Skip to main content
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

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:
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: 1, 2, 3, or 4 State values:
  • high or 1 β€” Set pin HIGH (3.3V)
  • low or 0 β€” Set pin LOW (0V)
Examples:

Write responses

Reading (capabilities)

Reading the characteristic returns a capabilities hint:
This indicates which logical pins are available for control.

Example code

Hardware integration

Basic LED indicator

Connect an LED with current-limiting resistor:
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:
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:

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.