BLE Command Channel
Overview
The command characteristic carries a request/response interface for device control operations. Write a JSON command, then read back the response as a notification on the same characteristic.
| Characteristic | UUID | Access |
|---|---|---|
command |
00000102-c1ec-46e2-ac97-7d4c7b4bb930 |
Write / Notify |
Power-on self test and initialization test reports are read from their own report characteristic; see telemetry_messages.md.
Request format
{ "command": "<operation>", "<field>": <value>, ... }
Fields are flat at the top level alongside "command" — the same layout as CoAP commands.
Response format
{ "command": "<operation>", "ok": true, "data": null, "error": null }
ok is false and error is a string when the operation fails. data carries op-specific payload for read operations.
Operations
identify
Blinks the onboard LEDs for a configurable duration to locate a device physically.
{ "command": "identify", "duration_sec": 5 }
| Field | Type | Default | Range |
|---|---|---|---|
duration_sec |
int | 5 | 1–30 |
reboot
Reboots the device. Response is sent before the reset occurs.
{ "command": "reboot" }
factory_reset
Clears OpenThread dataset and reboots. Requires explicit confirmation.
{ "command": "factory_reset", "confirm": true }
setDamper
Commands a stepper-actuated damper to a target position in degrees.
{ "command": "setDamper", "index": 0, "position": 45.0 }
| Field | Type | Notes |
|---|---|---|
index |
int | 0 = supply damper, 1 = exhaust damper |
position |
float | Position in degrees (0–90) |
setDamperPct
Commands a damper to a position expressed as percent open. Equivalent to setDamper with degrees computed as percent / 100 × 90.
{ "command": "setDamperPct", "index": 0, "percent": 50 }
| Field | Type | Notes |
|---|---|---|
index |
int | 0 = supply damper, 1 = exhaust damper |
percent |
number | Percent open, 0–100 (clamped) |
getDamperPct
Reads the current tracked position of one damper as percent open.
{ "command": "getDamperPct", "index": 0 }
Response data:
{ "percent": 50.0, "homed": true }
homed is false (and percent is -1) if the damper has not been homed since boot.
homeDamper
Runs the homing sequence for one damper. The stepper drives to the hard stop to establish the zero reference.
{ "command": "homeDamper", "index": 0 }
| Field | Type | Notes |
|---|---|---|
index |
int | 0 = supply, 1 = exhaust |
getDamper
Reads the current tracked position of one damper.
{ "command": "getDamper", "index": 0 }
Response data:
{ "position": 45.0, "homed": true }
homed is false (and position is -1) if the damper has not been homed since boot.
testDamper
Enables or disables the stepper demo mode. In demo mode the firmware drives both dampers through a continuous sweep pattern for visual verification.
{ "command": "testDamper", "enable": true }
{ "command": "testDamper", "enable": false }
Python test script (src/ble_test_stepper_demo.py)
Scans for the nearest Vibrant BLE device and sends a testDamper command. Requires bleak (pip install bleak).
Enable stepper demo mode:
python src/ble_test_stepper_demo.py --enable
Disable stepper demo mode:
python src/ble_test_stepper_demo.py --disable
The script subscribes to command notifications, writes the command, waits up to 10 seconds for the device response, and exits non-zero if the command fails or times out.