wip:

include/zh_nrf24_gateway.h

@@ -4,15 +4,23 @@
  * nRF24L01+ gateway for ESP-IDF.
  *
  * Receives RF sensor telemetry and posts it as events on the default
- * ESP event loop (base ZH_NRF_GATEWAY_EVENTS, id ZH_NRF_GATEWAY_EVENT_SENSOR_DATA).
+ * 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.
  *
- * Pairing is fully internal to the component: it allocates device IDs,
- * persists the next-id counter in NVS and sends ACK packets. No pairing
- * event is posted to the event loop.
+ * Binding table semantics:
+ *  - each binding is a pair {id, type};
+ *  - the same id may be reused across different types;
+ *  - on pairing, the gateway allocates the smallest free id in 1..254
+ *    for the requested type;
+ *  - deleting a binding makes its id available to the next pairing
+ *    request of the same type.
  */
 #pragma once
 
 #include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
 
 #include "esp_err.h"
 #include "esp_event.h"
@@ -23,68 +31,99 @@
 extern "C" {
 #endif
 
-/**
- * @brief Event base for gateway events.
- *
- * Event data for ZH_NRF_GATEWAY_EVENT_SENSOR_DATA is a copy of
- * zh_nrf24_sensor_transmitted_data_t.
- */
+/** Max entries in the binding table (RAM and NVS). */
+#define ZH_NRF_GATEWAY_MAX_BINDINGS 254
+
 ESP_EVENT_DECLARE_BASE(ZH_NRF_GATEWAY_EVENTS);
 
-/**
- * @brief Gateway event IDs.
- */
 typedef enum
 {
     /** Sensor telemetry received (data: zh_nrf24_sensor_transmitted_data_t) */
     ZH_NRF_GATEWAY_EVENT_SENSOR_DATA,
 } zh_nrf_gateway_event_t;
 
-/**
- * @brief Gateway configuration.
- *
- * Filled by the application before calling zh_nrf_gateway_init(). All pins
- * refer to the ESP32 GPIO numbers; the nRF24L01+ module is connected over
- * the selected SPI host. CE, CSN and IRQ are managed by the component.
- */
 typedef struct
 {
-    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 */
+    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;
 } zh_nrf_gateway_config_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
- */
+/** A single {id, type} binding. */
+typedef struct
+{
+    uint8_t id;    /**< 1..254, 0xFF = unassigned */
+    uint8_t type;  /**< zh_nrf24_sensor_type_t */
+} zh_nrf_gateway_binding_t;
+
 esp_err_t zh_nrf_gateway_init(const zh_nrf_gateway_config_t *config);
+esp_err_t zh_nrf_gateway_start(void);
+
+/* ===================== BINDING TABLE API ===================== */
 
 /**
- * @brief Start the receiver task.
+ * @brief Copy current bindings into @p buf.
  *
- * The task blocks on the IRQ semaphore (or polls the FIFO as a fallback
- * once per second) and dispatches received packets. Sensor telemetry is
- * posted to the default event loop as ZH_NRF_GATEWAY_EVENT_SENSOR_DATA.
- * Pairing packets are handled internally and never reach the event loop.
- *
- * @return ESP_OK on success
+ * Thread-safe. Returns number of entries copied (≤ max_count and ≤
+ * current table size). Use with zh_nrf_gateway_bindings_count() to
+ * decide buffer size.
  */
-esp_err_t zh_nrf_gateway_start(void);
+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);
+
+/**
+ * @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.
+ *
+ * @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
+ */
+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
+ */
+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
+ */
+int zh_nrf_gateway_bindings_delete_by_type(uint8_t type);
+
+/** @brief Remove all bindings (persisted). */
+esp_err_t zh_nrf_gateway_binding_clear_all(void);
 
 #ifdef __cplusplus
 }