Merge pull request #2 from OpenEarable/codex/led-state-readback

Specify LED configuration readback and notifications

Author: TobiasRoeddiger

generated/c/include/led_protocol.h

@@ -5,9 +5,9 @@
 
 #define LED_BLE_SERVICE_UUID "81040a2e-4819-11ee-be56-0242ac120002"
 #define LED_BLE_RGB_CHARACTERISTIC_UUID "81040e7a-4819-11ee-be56-0242ac120002"
-#define LED_BLE_RGB_CHARACTERISTIC_PROPERTIES (PROTOCOL_BLE_PROPERTY_WRITE)
+#define LED_BLE_RGB_CHARACTERISTIC_PROPERTIES (PROTOCOL_BLE_PROPERTY_READ | PROTOCOL_BLE_PROPERTY_WRITE | PROTOCOL_BLE_PROPERTY_NOTIFY)
 #define LED_BLE_STATE_CHARACTERISTIC_UUID "81040e7b-4819-11ee-be56-0242ac120002"
-#define LED_BLE_STATE_CHARACTERISTIC_PROPERTIES (PROTOCOL_BLE_PROPERTY_WRITE)
+#define LED_BLE_STATE_CHARACTERISTIC_PROPERTIES (PROTOCOL_BLE_PROPERTY_READ | PROTOCOL_BLE_PROPERTY_WRITE | PROTOCOL_BLE_PROPERTY_NOTIFY)
 
 #ifdef __cplusplus
 extern "C" {

generated/c/include/zephyr/led_ble.h

@@ -8,9 +8,9 @@
 #define LED_ZEPHYR_SERVICE_UUID BT_UUID_DECLARE_128(BT_UUID_128_ENCODE(0x81040a2e, 0x4819, 0x11ee, 0xbe56, 0x0242ac120002))
 
 #define LED_ZEPHYR_RGB_CHARACTERISTIC_UUID BT_UUID_DECLARE_128(BT_UUID_128_ENCODE(0x81040e7a, 0x4819, 0x11ee, 0xbe56, 0x0242ac120002))
-#define LED_ZEPHYR_RGB_CHARACTERISTIC_PROPERTIES (BT_GATT_CHRC_WRITE)
-#define LED_ZEPHYR_RGB_CHARACTERISTIC_PERMISSIONS (BT_GATT_PERM_WRITE)
+#define LED_ZEPHYR_RGB_CHARACTERISTIC_PROPERTIES (BT_GATT_CHRC_READ | BT_GATT_CHRC_WRITE | BT_GATT_CHRC_NOTIFY)
+#define LED_ZEPHYR_RGB_CHARACTERISTIC_PERMISSIONS (BT_GATT_PERM_READ | BT_GATT_PERM_WRITE)
 
 #define LED_ZEPHYR_STATE_CHARACTERISTIC_UUID BT_UUID_DECLARE_128(BT_UUID_128_ENCODE(0x81040e7b, 0x4819, 0x11ee, 0xbe56, 0x0242ac120002))
-#define LED_ZEPHYR_STATE_CHARACTERISTIC_PROPERTIES (BT_GATT_CHRC_WRITE)
-#define LED_ZEPHYR_STATE_CHARACTERISTIC_PERMISSIONS (BT_GATT_PERM_WRITE)
+#define LED_ZEPHYR_STATE_CHARACTERISTIC_PROPERTIES (BT_GATT_CHRC_READ | BT_GATT_CHRC_WRITE | BT_GATT_CHRC_NOTIFY)
+#define LED_ZEPHYR_STATE_CHARACTERISTIC_PERMISSIONS (BT_GATT_PERM_READ | BT_GATT_PERM_WRITE)

generated/dart/lib/src/led_protocol.dart

@@ -16,7 +16,9 @@ abstract final class LedBleUuids {
         name: 'rgb',
         uuid: rgbCharacteristicUuid,
         properties: {
+          ProtocolBleCharacteristicProperty.read,
           ProtocolBleCharacteristicProperty.write,
+          ProtocolBleCharacteristicProperty.notify,
         },
       );
 
@@ -29,7 +31,9 @@ abstract final class LedBleUuids {
         name: 'state',
         uuid: stateCharacteristicUuid,
         properties: {
+          ProtocolBleCharacteristicProperty.read,
           ProtocolBleCharacteristicProperty.write,
+          ProtocolBleCharacteristicProperty.notify,
         },
       );
 

schemas/led/README.md

@@ -9,11 +9,13 @@ Service UUID: `81040a2e-4819-11ee-be56-0242ac120002`.
 
 | Characteristic | UUID | Operations | Payload size |
 |---|---|---|---|
-| RGB | `81040e7a-4819-11ee-be56-0242ac120002` | Write | 3 bytes |
-| State | `81040e7b-4819-11ee-be56-0242ac120002` | Write | 1 byte |
+| RGB | `81040e7a-4819-11ee-be56-0242ac120002` | Read, write, notify | 3 bytes |
+| State | `81040e7b-4819-11ee-be56-0242ac120002` | Read, write, notify | 1 byte |
 
 Send the payload directly to its characteristic, without a message ID, length
-prefix, or version byte. Neither characteristic supports reads or notifications.
+prefix, or version byte. Firmware 2.3.x adds reads and notifications using the
+same payloads and UUIDs. Older firmware is write-only: clients must check the
+discovered characteristic properties before reading or subscribing.
 
 ## RGB color
 
@@ -41,8 +43,9 @@ Write a single byte to State:
 | `00` | Automatic state indication; firmware chooses colors and animations |
 | `01` | Custom mode; display the stored RGB color |
 
-Use only these two values. The firmware callback currently does not reject
-other numeric values, but they have no defined protocol meaning.
+Use only these two values. The firmware callback does not reject
+other numeric values on older versions; firmware 2.3.x rejects them with
+ATT Value Not Allowed and preserves the current mode.
 
 To show blue:
 
@@ -58,6 +61,19 @@ that are not exactly three bytes, State payloads that are not exactly one byte,
 and writes with a nonzero offset. Successful writes have no separate response
 payload.
 
+## Readback and notifications
+
+Read RGB to retrieve the stored custom color, including while automatic mode
+is active. Read State to retrieve the configured indication mode. These are
+configuration values, not the instantaneous color of a pulse or a DFU override.
+At boot the custom color is black and the indication mode is automatic.
+
+Subscribe using each characteristic’s CCC descriptor, then read its current
+value. After a successful write, firmware notifies the accepted value to
+subscribers. Rejected writes leave the configuration unchanged and produce no
+notification. A successful write while unsubscribed remains valid. Settings
+are volatile and reset at reboot, as before.
+
 ## Generated bindings
 
 [`protocol.yml`](protocol.yml) defines both messages and their BLE metadata.

schemas/led/protocol.yml

@@ -8,10 +8,10 @@ transport:
     characteristics:
       - name: rgb
         uuid: 81040e7a-4819-11ee-be56-0242ac120002
-        properties: [write]
+        properties: [read, write, notify]
       - name: state
         uuid: 81040e7b-4819-11ee-be56-0242ac120002
-        properties: [write]
+        properties: [read, write, notify]
 
 messages:
   rgb: