GPIO control is a developer/maker feature. It requires a BLE client application to send commandsβthereβs no on-device interface for GPIO control.
Overview
The GPIO characteristic allows you to:- Set any of 4 pins to HIGH or LOW
- Read current capabilities
- Integrate external hardware with your OSSM
Use cases
- LED indicators β Signal device state to external lighting
- Relay control β Trigger external devices on/off
- Accessory sync β Coordinate with other hardware
- Custom integrations β Build your own control systems
BLE characteristic
The GPIO characteristic is part of the main OSSM BLE service (
522b443a-4f53-534d-0001-420badbabe69). Connect to the service first, then access this characteristic.Pin mapping
The firmware exposes 4 logical pins that map to ESP32 GPIO numbers:Command format
Writing (setting pin state)
Send a string in the format:1, 2, 3, or 4
State values:
highor1β Set pin HIGH (3.3V)lowor0β Set pin LOW (0V)
Write responses
Reading (capabilities)
Reading the characteristic returns a capabilities hint:Example code
Hardware integration
Basic LED indicator
Connect an LED with current-limiting resistor:Relay control
For higher-current loads, use an optoisolated relay module:Logic level conversion
If you need 5V logic output:Limitations
- No PWM support β Pins are digital HIGH/LOW only
- No input reading β GPIO is output-only via this interface
- No persistence β Pin states reset to LOW on device restart
- No interrupts β Cannot trigger based on external signals
- Current limits β ESP32 GPIO maximum ~12mA per pin, 40mA total
Troubleshooting
Pin doesn't respond
Pin doesn't respond
- Verify the BLE connection is active
- Check the command format exactly matches
<pin>:<state> - Ensure pin number is 1-4
- Verify with a multimeter that voltage changes
error:invalid_format response
error:invalid_format response
The command format wasnβt recognized. Valid formats:
1:high,1:low,1:1,1:02:high,2:low,2:1,2:0- etc.
HIGH and high both work).error:pin_out_of_range response
error:pin_out_of_range response
Pin number must be 1, 2, 3, or 4. Check your command.
Connected device doesn't work
Connected device doesn't work
- Verify voltage with a multimeter (should be 0V or ~3.3V)
- Check current requirementsβESP32 GPIO limited to ~12mA
- Ensure common ground between OSSM and your device
- Consider using a transistor or relay for higher current loads
Related pages
BLE Protocol
Complete BLE protocol reference for OSSM control.
Configuration Reference
Pin definitions and hardware configuration.

