Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.researchanddesire.com/llms.txt

Use this file to discover all available pages before exploring further.

The OSSM exposes four GPIO pins that can be controlled via Bluetooth Low Energy (BLE). Use these pins to trigger external accessories, indicators, relays, or other hardware integrations.
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

PropertyValue
UUID522b443a-4f53-534d-4000-420badbabe69
PropertiesREAD, WRITE
Namespace0x4 (GPIO)
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:
Logical PinESP32 GPIOBoard Location
1GPIO 2Available on header
2GPIO 15Available on header
3GPIO 22Available on header
4GPIO 33Available on header
These GPIO pins are directly connected to the ESP32. They output 3.3V logic levels with limited current capacity (~12mA per pin). Use appropriate drivers for high-current loads.

​
Command format

​
Writing (setting pin state)

Send a string in the format: 
<pin_number>:<state>
Pin number: 1, 2, 3, or 4 State values:
  • high or 1 — Set pin HIGH (3.3V)
  • low or 0 — Set pin LOW (0V)
Examples:
CommandEffect
1:highSet pin 1 (GPIO 2) HIGH
2:lowSet pin 2 (GPIO 15) LOW
3:1Set pin 3 (GPIO 22) HIGH
4:0Set pin 4 (GPIO 33) LOW

​
Write responses

ResponseMeaning
ok:1:highPin 1 successfully set to HIGH
ok:2:lowPin 2 successfully set to LOW
error:invalid_formatCommand format not recognized
error:pin_out_of_rangePin number not 1-4

​
Reading (capabilities)

Reading the characteristic returns a capabilities hint: 
pins:[1,2,3,4]
This indicates which logical pins are available for control.

​
Example code

// Connect to OSSM (assumes already connected to service)
const gpioChar = await service.getCharacteristic(
  "522b443a-4f53-534d-4000-420badbabe69"
);

// Set pin 1 HIGH
await gpioChar.writeValue(new TextEncoder().encode("1:high"));

// Read the response
const response = await gpioChar.readValue();
console.log(new TextDecoder().decode(response));
// Output: "ok:1:high"

// Set pin 2 LOW
await gpioChar.writeValue(new TextEncoder().encode("2:low"));

// Read capabilities
const caps = await gpioChar.readValue();
console.log(new TextDecoder().decode(caps));
// Output: "pins:[1,2,3,4]"

​
Hardware integration

​
Basic LED indicator

Connect an LED with current-limiting resistor: 
GPIO Pin → 220Ω Resistor → LED Anode (+)
                           LED Cathode (-) → GND
Use a 220Ω to 470Ω resistor for standard LEDs. The ESP32’s 3.3V output provides plenty of voltage for most LEDs.

​
Relay control

For higher-current loads, use an optoisolated relay module: 
GPIO Pin → Relay Module Signal
3.3V     → Relay Module VCC
GND      → Relay Module GND
Most relay modules with optoisolation work with 3.3V logic. Check your module’s specifications.
Never connect mains voltage (120V/240V) directly to the OSSM. Always use properly rated relay modules with appropriate safety precautions.

​
Logic level conversion

If you need 5V logic output: 
GPIO Pin → Level Shifter 3.3V Side
5V       → Level Shifter 5V Side
GND      → Level Shifter GND
           Level Shifter 5V Output → Your 5V Device

​
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

  • 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
The command format wasn’t recognized. Valid formats:
  • 1:high, 1:low, 1:1, 1:0
  • 2:high, 2:low, 2:1, 2:0
  • etc.
Case doesn’t matter (HIGH and high both work).
Pin number must be 1, 2, 3, or 4. Check your command.
  • 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

BLE Protocol

Complete BLE protocol reference for OSSM control.

Configuration Reference

Pin definitions and hardware configuration.