/**
 * @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