BLE can be switched off via POST /api/bluetooth?enabled=false or the web app (applied after a restart); the GATT server described here is then not started.
The ESP32 firmware exposes a GATT server over NimBLE-Arduino. It advertises under the name OpenPelletBridge and contains two services: the stove control service and an OTA firmware-update service.
| Parameter | Value |
|---|---|
| Device name | OpenPelletBridge |
| MTU | 185 bytes |
| TX power | +9 dBm |
| Advertising interval | 40 – 80 ms |
| Re-advertise after disconnect | 1 s backoff |
| Max simultaneous clients | 1 |
Every characteristic that supports notifications implements subscribe-push: the moment the client enables the CCCD (subscribes), the firmware immediately sends a notification with the current value. This means the client does not need to issue a separate readValue after subscribing — subscribing is sufficient to receive the initial state.
On the first connection the firmware waits until all characteristics have been subscribed (approximately 4 s) before issuing a bulk force-notify of every characteristic.
Values are refreshed every 2 s. Only characteristics whose underlying value has changed since the last cycle are notified.
Service UUID: A1B20001-1234-5678-ABCD-EF0123456789
Properties: R = Read, W = Write (with response), N = Notify, WNR = Write (no response).
| Field | Value |
|---|---|
| UUID | A1B20002-1234-5678-ABCD-EF0123456789 |
| Properties | R, N |
| Format | uint8 |
Read-only. Updated by the sensor task from the stove UART.
| Value | Meaning |
|---|---|
| 0 | Off |
| 1 | Starting |
| 2 | Pellet loading |
| 3 | Ignition |
| 4 | Working |
| 5 | Cleaning |
| 6 | Final cooling |
| 7 | Standby |
| 8 | Alarm |
| Field | Value |
|---|---|
| UUID | A1B20003-1234-5678-ABCD-EF0123456789 |
| Properties | R, W, N |
| Format | uint8 — 0 = off, 1 = on |
Write 1 to turn the stove on (only accepted when state is Off).
Write 0 to turn it off (accepted when Ignition, Working, or Alarm; sends a soft-off when Starting/Loading).
Writes are applied asynchronously from bleLoop() via the write queue. There is a 150 ms minimum gap between consecutive stove UART operations.
| Field | Value |
|---|---|
| UUID | A1B20004-1234-5678-ABCD-EF0123456789 |
| Properties | R, W, N |
| Format | uint8, range 7 – 30 (°C) |
Values outside 7 – 30 are silently rejected. Stored in stove EEPROM.
| Field | Value |
|---|---|
| UUID | A1B20005-1234-5678-ABCD-EF0123456789 |
| Properties | R, W, N |
| Format | uint8, range 0 – 3 |
| Value | Meaning |
|---|---|
| 0 | Off / auto |
| 1 | Low |
| 2 | Medium |
| 3 | High |
| Field | Value |
|---|---|
| UUID | A1B20006-1234-5678-ABCD-EF0123456789 |
| Properties | R, W, N |
| Format | uint8, range 1 – 4 |
Values outside 1 – 4 are rejected.
| Field | Value |
|---|---|
| UUID | A1B20007-1234-5678-ABCD-EF0123456789 |
| Properties | R, N |
| Format | int16 little-endian, value × 10 (e.g. 215 = 21.5 °C) |
Read-only sensor value.
| Field | Value |
|---|---|
| UUID | A1B20008-1234-5678-ABCD-EF0123456789 |
| Properties | R, N |
| Format | uint8 (°C) |
Read-only sensor value.
| Field | Value |
|---|---|
| UUID | A1B20009-1234-5678-ABCD-EF0123456789 |
| Properties | R, W, N |
| Format | uint8 — 0 = disabled, 1 = enabled |
Stored in stove EEPROM.
| Field | Value |
|---|---|
| UUID | A1B2000A-1234-5678-ABCD-EF0123456789 |
| Properties | R, N |
| Format | uint8 — 0 = OK, 1 = alarm |
Read-only.
| Field | Value |
|---|---|
| UUID | A1B2000B-1234-5678-ABCD-EF0123456789 |
| Properties | R, N |
| Format | uint16 little-endian |
Read-only sensor value.
| Field | Value |
|---|---|
| UUID | A1B2000C-1234-5678-ABCD-EF0123456789 |
| Properties | R, W, N |
| Format | uint8 raw stove register value |
| Raw | Adjustment |
|---|---|
| 2 | −3 |
| 3 | −2 |
| 4 | −1 |
| 5 | 0 (neutral) |
| 6 | +1 |
| 7 | +2 |
| 8 | +3 |
| 76 | +G (gas mode) |
| Field | Value |
|---|---|
| UUID | A1B2000D-1234-5678-ABCD-EF0123456789 |
| Properties | R, W, N |
| Format | uint8, range 0 – 10 |
| Raw | Adjustment |
|---|---|
| 0 | −5 |
| 1 | −4 |
| 2 | −3 |
| 3 | −2 |
| 4 | −1 |
| 5 | 0 (neutral) |
| 6 | +1 |
| 7 | +2 |
| 8 | +3 |
| 9 | +4 |
| 10 | +5 |
Stored in stove EEPROM.
| Field | Value |
|---|---|
| UUID | A1B2000E-1234-5678-ABCD-EF0123456789 |
| Properties | R, N |
| Format | UTF-8 dotted-decimal string, e.g. "192.168.1.42" |
Read-only. Notified when the IP changes.
| Field | Value |
|---|---|
| UUID | A1B2000F-1234-5678-ABCD-EF0123456789 |
| Properties | R, N |
| Format | 28-byte packed binary |
| Bytes | Type | Field |
|---|---|---|
| 0 – 10 | UTF-8, null-padded | Firmware version (max 11 bytes) |
| 11 – 12 | uint16 LE |
Total runtime (hours) |
| 13 – 14 | uint16 LE |
Number of starts |
| 15 – 19 | uint8[5] |
Previous error codes |
| 20 – 21 | uint16 LE |
Hours since last service |
| 22 – 23 | int16 LE |
Remote control temperature × 2 (INT16_MIN = not available) |
| 24 – 27 | uint32 LE |
Stove internal timestamp (Unix epoch) |
Notified whenever any of these fields changes.
| Field | Value |
|---|---|
| UUID | A1B20013-1234-5678-ABCD-EF0123456789 |
| Properties | R, N |
| Format | variable-length binary |
| Bytes | Type | Field |
|---|---|---|
| 0 | int8 |
WiFi RSSI (dBm). 0 = not connected |
| 1 … null | UTF-8 | IP address, null-terminated |
| after null | UTF-8 | SSID (no null terminator) |
Example for IP 192.168.1.42, SSID HomeNet, RSSI −55:
C9 31 39 32 2E 31 36 38 2E 31 2E 34 32 00 48 6F 6D 65 4E 65 74
^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^ ^^^^^^^^^^^^^^^^^^^
-55 "192.168.1.42" \0 "HomeNet"
Notified when RSSI, IP, or SSID changes.
| Field | Value |
|---|---|
| UUID | A1B20014-1234-5678-ABCD-EF0123456789 |
| Properties | R, W, N |
| Format | uint8 (interpret as int8), range −3 – 0 |
Hour offset applied to the energy-saving start time.
| Field | Value |
|---|---|
| UUID | A1B20015-1234-5678-ABCD-EF0123456789 |
| Properties | R, W, N |
| Format | uint8, range 0 – 3 |
Hour offset applied to the energy-saving stop time.
| Field | Value |
|---|---|
| UUID | A1B20016-1234-5678-ABCD-EF0123456789 |
| Properties | WNR (Write No Response) |
| Format | any single byte |
Write any value to trigger esp_restart(). The device reboots after 200 ms. No response is sent.
| Field | Value |
|---|---|
| UUID | A1B20017-1234-5678-ABCD-EF0123456789 |
| Properties | R, W, N |
| Format | UTF-8 string, max 32 printable ASCII characters |
The current hostname is returned on read. Writing a new value saves it to NVS (namespace net, key hostname). The updated value is echoed back via the characteristic so the client can confirm the save. Takes effect after restart.
Invalid characters (non-printable, non-ASCII) are stripped. If the result is empty the write is rejected.
| Field | Value |
|---|---|
| UUID | A1B20018-1234-5678-ABCD-EF0123456789 |
| Properties | R, W, N |
| Format | ASCII CSV string |
DHCP mode:
dhcp
Static IP mode:
static,<ip>,<gateway>,<subnet>,<dns>
Example:
static,192.168.1.100,192.168.1.1,255.255.255.0,8.8.8.8
The firmware validates all four IP addresses using IPAddress.fromString(). Malformed input is silently rejected. Saved to NVS key netcfg. Takes effect after restart.
| Timer | UUID |
|---|---|
| PR1 | A1B20020-1234-5678-ABCD-EF0123456789 |
| PR2 | A1B20021-1234-5678-ABCD-EF0123456789 |
| PR3 | A1B20022-1234-5678-ABCD-EF0123456789 |
| PR4 | A1B20023-1234-5678-ABCD-EF0123456789 |
| PR5 | A1B20024-1234-5678-ABCD-EF0123456789 |
| PR6 | A1B20025-1234-5678-ABCD-EF0123456789 |
Properties: R, W, N
Format: 7-byte packed binary
| Byte | Field | Notes |
|---|---|---|
| 0 | Enabled | 0 = disabled, 1 = enabled |
| 1 | On time (raw) | value × 10 = minutes since 00:00. 144 = disabled |
| 2 | Off time (raw) | Same encoding as on time |
| 3 | Setpoint (°C) | Temperature to hold when timer is active |
| 4 | Flame power | 1 – 4 |
| 5 | Fan speed | 0 – 3 |
| 6 | Day-of-week mask | Bitmask: Mon=1, Tue=2, Wed=4, Thu=8, Fri=16, Sat=32, Sun=64 |
Time encoding example: on time = 08:30 → 8 * 60 + 30 = 510 minutes → raw byte = 51 (510 ÷ 10).
Writes are applied to stove EEPROM asynchronously from bleLoop(). The in-memory cache is updated immediately so a read before the EEPROM write completes still returns the new value.
Service UUID: A1B20010-1234-5678-ABCD-EF0123456789
Used for over-the-air firmware updates over BLE.
| Field | Value |
|---|---|
| UUID | A1B20011-1234-5678-ABCD-EF0123456789 |
| Properties | R, W, N |
Commands written by the client:
| Byte 0 | Bytes 1 – 4 | Action |
|---|---|---|
0x01 |
uint32 LE — firmware size |
Begin OTA. Firmware size is optional (send 0 if unknown) |
0x02 |
— | Commit OTA. Device reboots into new firmware after 1 s |
0x03 |
— | Abort OTA |
Notifications sent by the device:
| Value | Meaning |
|---|---|
0x01 |
Ready — OTA session started successfully |
0x02 |
Success — firmware written, device rebooting |
0x03 |
Aborted |
0x50 <pct> |
Progress — 2-byte notification, byte 1 is completion percentage (0 – 100). Sent every 4 KB written |
0xFF |
Error |
| Field | Value |
|---|---|
| UUID | A1B20012-1234-5678-ABCD-EF0123456789 |
| Properties | W, WNR |
Stream raw firmware binary chunks here after receiving the 0x01 ready notification from OTA Control. Use Write No Response for maximum throughput. The firmware writes each chunk to the OTA partition via esp_ota_write().
All stove control writes (Power, Setpoint, Fan, Flame, Beep, Combustion, Pellet, Energy Saving) are handled via an internal queue (capacity 12 entries). The BLE callback thread only enqueues work; bleLoop() applies one operation per cycle with a 150 ms minimum gap between consecutive stove UART frames to prevent overlapping serial transactions.
Timer writes follow a separate path and are also applied asynchronously, with 20 ms delays between each of the 7 EEPROM fields. Writes with an out-of-range setpoint (7 – 30), flame power (1 – 4) or fan speed (0 – 3) are ignored.
Settings that survive restart are stored in ESP32 NVS under namespace net:
| Key | Default | Description |
|---|---|---|
hostname |
openpelletbridge |
mDNS / DHCP hostname |
netcfg |
dhcp |
IP configuration string (same format as Net Config characteristic) |