130 lines
3.7 KiB
C
130 lines
3.7 KiB
C
/**
|
|
* @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. 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.
|
|
*
|
|
* 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"
|
|
#include "driver/spi_master.h"
|
|
#include "zh_nrf24_config.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** Max entries in the binding table (RAM and NVS). */
|
|
#define ZH_NRF_GATEWAY_MAX_BINDINGS 254
|
|
|
|
ESP_EVENT_DECLARE_BASE(ZH_NRF_GATEWAY_EVENTS);
|
|
|
|
typedef enum
|
|
{
|
|
/** Sensor telemetry received (data: zh_nrf24_sensor_transmitted_data_t) */
|
|
ZH_NRF_GATEWAY_EVENT_SENSOR_DATA,
|
|
} 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;
|
|
} zh_nrf_gateway_config_t;
|
|
|
|
/** 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 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);
|
|
|
|
/**
|
|
* @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
|
|
}
|
|
#endif |