wip:

include/zh_nrf24_gateway.h

@@ -9,9 +9,12 @@
  * 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
+ *  - ZH_NRF_GATEWAY_EVENT_SENSOR_DATA       — sensor telemetry
+ *  - ZH_NRF_GATEWAY_EVENT_SENSOR_PAIRED     — pairing completed (gateway
+ *    assigned a new id and the ACK was delivered)
+ *  - ZH_NRF_GATEWAY_EVENT_SENSOR_REGISTERED — data packet arrived from a
+ *    {id, type} that was missing from the binding table; it was added
+ *    on the fly (covers gateway replacement / NVS wipe without re-pairing)
  *
  * Binding table semantics:
  *  - each binding is a pair {id, type};
@@ -43,32 +46,29 @@ ESP_EVENT_DECLARE_BASE(ZH_NRF_GATEWAY_EVENTS);
 
 typedef enum
 {
-    /**
-     * Sensor telemetry received.
-     * Event data: zh_nrf24_sensor_transmitted_data_t
-     */
+    /** Sensor telemetry (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
-     */
+    /** Pairing completed (data: zh_nrf_gateway_binding_t) */
     ZH_NRF_GATEWAY_EVENT_SENSOR_PAIRED,
+
+    /** Unknown {id, type} seen in a data packet, auto-added to bindings
+     *  (data: zh_nrf_gateway_binding_t) */
+    ZH_NRF_GATEWAY_EVENT_SENSOR_REGISTERED,
 } zh_nrf_gateway_event_t;
 
 typedef struct
 {
-    spi_host_device_t spi_host;
-    int pin_sck;
-    int pin_miso;
-    int pin_mosi;
-    int pin_csn;
-    int pin_ce;
-    int pin_irq;
-    uint8_t channel;
-    uint32_t address;
-    uint32_t spi_clock_hz;
+    spi_host_device_t spi_host;   /*!< SPI host (SPI2_HOST / SPI3_HOST) */
+    int pin_sck;                  /*!< SCK  GPIO */
+    int pin_miso;                 /*!< MISO GPIO */
+    int pin_mosi;                 /*!< MOSI GPIO */
+    int pin_csn;                  /*!< CSN  GPIO (chip select, active low) */
+    int pin_ce;                   /*!< CE   GPIO (chip enable, active high) */
+    int pin_irq;                  /*!< IRQ  GPIO (open-drain, active low) */
+    uint8_t channel;              /*!< RF channel (0..125) */
+    uint32_t address;             /*!< 24-bit pipe address, transmitted as LE bytes */
+    uint32_t spi_clock_hz;        /*!< SPI clock, 0 → default 4 MHz */
 } zh_nrf_gateway_config_t;
 
 /** A single {id, type} binding. */
@@ -78,14 +78,61 @@ typedef struct
     uint8_t type;  /**< zh_nrf24_sensor_type_t */
 } zh_nrf_gateway_binding_t;
 
+/**
+ * @brief Initialize the gateway.
+ *
+ * Configures SPI, the IRQ GPIO with falling-edge interrupt, the nRF24L01+
+ * transceiver (DPL enabled, RX mode) and prepares NVS and the default
+ * event loop if they are not already initialized.
+ *
+ * @param[in] config  Gateway configuration (must not be NULL)
+ *
+ * @return ESP_OK on success, or an ESP-IDF error code
+ */
 esp_err_t zh_nrf_gateway_init(const zh_nrf_gateway_config_t *config);
+
+/**
+ * @brief Start the receiver task.
+ *
+ * The task blocks on the IRQ semaphore (or polls the FIFO as a fallback
+ * once per second) and dispatches received packets.
+ *
+ * @return ESP_OK on success
+ */
 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).
+ */
 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);
-bool   zh_nrf_gateway_binding_exists(uint8_t id, uint8_t type);
+
+/**
+ * @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);
+
+/**
+ * @brief Auto-register {id, type} if not present.
+ *
+ * Validates both fields, then adds the pair to the table and persists
+ * to NVS if it is not already there. The id is taken from the packet
+ * as-is (unlike pairing, which assigns a new id).
+ *
+ * @return  1        binding was newly added
+ * @return  0        binding already existed
+ * @return negative  ESP error (invalid arg, NVS failure, etc.)
+ */
+int zh_nrf_gateway_binding_auto_register(uint8_t id, uint8_t type);
 
 /**
  * @brief Delete a {id, type} binding.