GPIO Control

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.

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

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:

<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:

Write responses

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]"

import asyncio
from bleak import BleakClient

GPIO_UUID = "522b443a-4f53-534d-4000-420badbabe69"

async def control_gpio():
    async with BleakClient("OSSM") as client:
        # Set pin 1 HIGH
        await client.write_gatt_char(GPIO_UUID, b"1:high")

        # Read response
        response = await client.read_gatt_char(GPIO_UUID)
        print(response.decode())  # "ok:1:high"

        # Set pin 2 LOW
        await client.write_gatt_char(GPIO_UUID, b"2:low")

        # Set multiple pins
        await client.write_gatt_char(GPIO_UUID, b"3:high")
        await client.write_gatt_char(GPIO_UUID, b"4:low")

asyncio.run(control_gpio())

Hardware integration

Basic LED indicator

Connect an LED with current-limiting resistor:

GPIO Pin → 220Ω Resistor → LED Anode (+)
                           LED Cathode (-) → GND

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.

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

Related pages