wip:

include/zh_nrf24_gateway.h

@@ -6,7 +6,12 @@
  * Receives RF sensor telemetry and posts it as events on the default
  * ESP event loop. Pairing is fully internal: the gateway allocates
  * per-type device IDs, persists the binding table in NVS and sends
- * ACK packets. No pairing event reaches the event loop.
+ * ACK packets.
+ *
+ * Events emitted:
+ *  - ZH_NRF_GATEWAY_EVENT_SENSOR_DATA   — sensor telemetry
+ *  - ZH_NRF_GATEWAY_EVENT_SENSOR_PAIRED — a new {id, type} binding was
+ *    created and the ACK was successfully delivered to the sensor
  *
  * Binding table semantics:
  *  - each binding is a pair {id, type};
@@ -38,8 +43,18 @@ ESP_EVENT_DECLARE_BASE(ZH_NRF_GATEWAY_EVENTS);
 
 typedef enum
 {
-    /** Sensor telemetry received (data: zh_nrf24_sensor_transmitted_data_t) */
+    /**
+     * Sensor telemetry received.
+     * Event data: zh_nrf24_sensor_transmitted_data_t
+     */
     ZH_NRF_GATEWAY_EVENT_SENSOR_DATA,
+
+    /**
+     * A new {id, type} binding was created (pairing succeeded and the
+     * ACK was delivered to the sensor).
+     * Event data: zh_nrf_gateway_binding_t
+     */
+    ZH_NRF_GATEWAY_EVENT_SENSOR_PAIRED,
 } zh_nrf_gateway_event_t;
 
 typedef struct
@@ -68,61 +83,27 @@ esp_err_t zh_nrf_gateway_start(void);
 
 /* ===================== BINDING TABLE API ===================== */
 
-/**
- * @brief Copy current bindings into @p buf.
- *
- * Thread-safe. Returns number of entries copied (≤ max_count and ≤
- * current table size). Use with zh_nrf_gateway_bindings_count() to
- * decide buffer size.
- */
 size_t zh_nrf_gateway_bindings_get(zh_nrf_gateway_binding_t *buf, size_t max_count);
-
-/** @brief Current number of bindings in the table. */
 size_t zh_nrf_gateway_bindings_count(void);
-
-/**
- * @brief Check whether a {id, type} binding exists.
- *
- * @return true if the binding is present in the table
- */
-bool zh_nrf_gateway_binding_exists(uint8_t id, uint8_t type);
+bool   zh_nrf_gateway_binding_exists(uint8_t id, uint8_t type);
 
 /**
  * @brief Delete a {id, type} binding.
  *
- * Composite key: both @p id AND @p type must match an existing entry.
- * If only one of them matches, nothing is deleted and ESP_ERR_NOT_FOUND
- * is returned. The id becomes immediately available for the next
- * pairing request of the same type. The change is persisted to NVS.
+ * Composite key: both @p id AND @p type must match. If only one matches,
+ * nothing is deleted and ESP_ERR_NOT_FOUND is returned.
  *
- * @return ESP_OK             on success
- * @return ESP_ERR_NOT_FOUND  no such {id, type} pair in the table
- * @return ESP_ERR_INVALID_ARG  id out of 1..254, or unknown type
- * @return ESP_ERR_INVALID_STATE  gateway not initialized
- * @return other              NVS error
+ * @return ESP_OK / ESP_ERR_NOT_FOUND / ESP_ERR_INVALID_ARG / ESP_ERR_INVALID_STATE / NVS error
  */
 esp_err_t zh_nrf_gateway_binding_delete(uint8_t id, uint8_t type);
 
-/**
- * @brief Delete every binding whose id equals @p id (any type).
- *
- * Use when the same physical device changed its type and the old
- * binding must be dropped regardless of the type field.
- *
- * @return Number of bindings deleted (≥ 0), or negative ESP error code
- */
+/** Delete every binding whose id equals @p id (any type). Returns count, or -err. */
 int zh_nrf_gateway_bindings_delete_by_id(uint8_t id);
 
-/**
- * @brief Delete every binding whose type equals @p type (any id).
- *
- * Use for mass-forget of one sensor category.
- *
- * @return Number of bindings deleted (≥ 0), or negative ESP error code
- */
+/** Delete every binding whose type equals @p type (any id). Returns count, or -err. */
 int zh_nrf_gateway_bindings_delete_by_type(uint8_t type);
 
-/** @brief Remove all bindings (persisted). */
+/** Remove all bindings (persisted). */
 esp_err_t zh_nrf_gateway_binding_clear_all(void);
 
 #ifdef __cplusplus