wip:

include/zh_nrf24_gateway.h

@@ -0,0 +1,91 @@
+/**
+ * @file zh_nrf24_gateway.h
+ *
+ * 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).
+ *
+ * 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.
+ */
+#pragma once
+
+#include <stdint.h>
+
+#include "esp_err.h"
+#include "esp_event.h"
+#include "driver/spi_master.h"
+#include "zh_nrf24_config.h"
+
+#ifdef __cplusplus
+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.
+ */
+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 */
+} 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
+ */
+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. 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
+ */
+esp_err_t zh_nrf_gateway_start(void);
+
+#ifdef __cplusplus
+}
+#endif