384 lines
15 KiB
C
384 lines
15 KiB
C
/*
|
|
* SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
#pragma once
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#include "esp_err.h"
|
|
#include "esp_zigbee_type.h"
|
|
|
|
/** Enum of the Zigbee network device type
|
|
* @anchor esp_zb_nwk_device_type_t
|
|
*/
|
|
typedef enum {
|
|
ESP_ZB_DEVICE_TYPE_COORDINATOR = 0x0, /*!< Device - Coordinator */
|
|
ESP_ZB_DEVICE_TYPE_ROUTER = 0x1, /*!< Device - Router */
|
|
ESP_ZB_DEVICE_TYPE_ED = 0x2, /*!< Device - End device */
|
|
ESP_ZB_DEVICE_TYPE_NONE = 0x3, /*!< Unknown Device */
|
|
} esp_zb_nwk_device_type_t;
|
|
|
|
/**
|
|
* @brief Enumeration of Zigbee network command status code
|
|
*
|
|
*/
|
|
typedef enum {
|
|
ESP_ZB_NWK_COMMAND_STATUS_NO_ROUTE_AVAILABLE = 0x00U, /*!< No route available */
|
|
ESP_ZB_NWK_COMMAND_STATUS_TREE_LINK_FAILURE = 0x01U, /*!< Tree link failure */
|
|
ESP_ZB_NWK_COMMAND_STATUS_NONE_TREE_LINK_FAILURE = 0x02U, /*!< None-tree link failure */
|
|
ESP_ZB_NWK_COMMAND_STATUS_LOW_BATTERY_LEVEL = 0x03U, /*!< Low battery level */
|
|
ESP_ZB_NWK_COMMAND_STATUS_NO_ROUTING_CAPACITY = 0x04U, /*!< No routing capacity */
|
|
ESP_ZB_NWK_COMMAND_STATUS_NO_INDIRECT_CAPACITY = 0x05U, /*!< No indirect capacity */
|
|
ESP_ZB_NWK_COMMAND_STATUS_INDIRECT_TRANSACTION_EXPIRY = 0x06U, /*!< Indirect transaction expiry */
|
|
ESP_ZB_NWK_COMMAND_STATUS_TARGET_DEVICE_UNAVAILABLE = 0x07U, /*!< Target device unavailable */
|
|
ESP_ZB_NWK_COMMAND_STATUS_TARGET_ADDRESS_UNALLOCATED = 0x08U, /*!< Target address unallocated */
|
|
ESP_ZB_NWK_COMMAND_STATUS_PARENT_LINK_FAILURE = 0x09U, /*!< Parent link failure */
|
|
ESP_ZB_NWK_COMMAND_STATUS_VALIDATE_ROUTE = 0x0aU, /*!< Validate route */
|
|
ESP_ZB_NWK_COMMAND_STATUS_SOURCE_ROUTE_FAILURE = 0x0bU, /*!< Source route failure */
|
|
ESP_ZB_NWK_COMMAND_STATUS_MANY_TO_ONE_ROUTE_FAILURE = 0x0cU, /*!< Many-to-one route failure */
|
|
ESP_ZB_NWK_COMMAND_STATUS_ADDRESS_CONFLICT = 0x0dU, /*!< Address conflict */
|
|
ESP_ZB_NWK_COMMAND_STATUS_VERIFY_ADDRESS = 0x0eU, /*!< Verify address */
|
|
ESP_ZB_NWK_COMMAND_STATUS_PAN_IDENTIFIER_UPDATE = 0x0fU, /*!< Pan ID update */
|
|
ESP_ZB_NWK_COMMAND_STATUS_NETWORK_ADDRESS_UPDATE = 0x10U, /*!< Network address update */
|
|
ESP_ZB_NWK_COMMAND_STATUS_BAD_FRAME_COUNTER = 0x11U, /*!< Bad frame counter */
|
|
ESP_ZB_NWK_COMMAND_STATUS_BAD_KEY_SEQUENCE_NUMBER = 0x12U, /*!< Bad key sequence number */
|
|
ESP_ZB_NWK_COMMAND_STATUS_UNKNOWN_COMMAND = 0x13U, /*!< Command received is not known */
|
|
} esp_zb_nwk_command_status_t;
|
|
|
|
#define ESP_ZB_NWK_INFO_ITERATOR_INIT 0 /*!< Initializer for esp_zb_neighbor_info_iterator_t. */
|
|
#define ESP_ZB_NWK_INFO_ITERATOR_EOT 0xFFFF /*!< Indicate the iterator reach the End of Table. */
|
|
|
|
#define ESP_ZB_NWK_MAX_SOURCE_ROUTE 5
|
|
|
|
/**
|
|
* @brief Iterator used to iterate through the tables of network information.
|
|
*
|
|
*/
|
|
typedef uint16_t esp_zb_nwk_info_iterator_t;
|
|
|
|
/**
|
|
* @brief Relationship of network neighbor
|
|
* @anchor esp_zb_nwk_relationship_t
|
|
*/
|
|
typedef enum {
|
|
ESP_ZB_NWK_RELATIONSHIP_PARENT = 0U, /*!< The peer device is the parent of current device. */
|
|
ESP_ZB_NWK_RELATIONSHIP_CHILD = 1U, /*!< The peer device is the child of current device. */
|
|
ESP_ZB_NWK_RELATIONSHIP_SIBLING = 2U, /*!< The peer device is the sibling of current device. */
|
|
ESP_ZB_NWK_RELATIONSHIP_NONE_OF_THE_ABOVE = 3U, /*!< The relationship is none of above, means that the peer device is
|
|
currently unknown, and its relationship with the network is in
|
|
the process of being established. */
|
|
ESP_ZB_NWK_RELATIONSHIP_PREVIOUS_CHILD = 4U, /*!< The peer device is the previous child of current device, meaning it
|
|
has been confirmed to have left the network */
|
|
ESP_ZB_NWK_RELATIONSHIP_UNAUTHENTICATED_CHILD = 5U, /*!< The peer device is the unauthenticated child of current device,
|
|
meaning it is in the process of joining the network but has not yet
|
|
been authenticated. */
|
|
} esp_zb_nwk_relationship_t;
|
|
|
|
/**
|
|
* @brief Information of network neighbor table entry
|
|
*
|
|
*/
|
|
typedef struct esp_zb_nwk_neighbor_info_s {
|
|
esp_zb_ieee_addr_t ieee_addr; /*!< Long address (EUI64) of the device. */
|
|
uint16_t short_addr; /*!< Short address (network address) of the device. */
|
|
uint8_t device_type; /*!< Neighbor device type, refer to @ref esp_zb_nwk_device_type_t */
|
|
uint8_t depth; /*!< The network depth of this device.*/
|
|
uint8_t rx_on_when_idle; /*!< Indicates if neighbour receiver enabled during idle periods:*/
|
|
uint8_t relationship; /*!< The relationship between the neighbour and current device, refer to @ref esp_zb_nwk_relationship_t */
|
|
uint8_t lqi; /*!< Link quality. Also used to calculate incoming cost */
|
|
int8_t rssi; /*!< Received signal strength indicator */
|
|
uint8_t outgoing_cost; /*!< The cost of an outgoing link. Got from link status. */
|
|
uint8_t age; /*!< Counter value for router aging. The number of nwkLinkStatusPeriod
|
|
* intervals since a link status command was received. */
|
|
uint32_t device_timeout; /*!< Configured end device timeout, in seconds. */
|
|
uint32_t timeout_counter; /*!< Timeout value ED aging, in milliseconds. */
|
|
} esp_zb_nwk_neighbor_info_t;
|
|
|
|
/**
|
|
* @brief State of the network route
|
|
* @anchor esp_zb_nwk_route_state_t
|
|
*/
|
|
typedef enum {
|
|
ESP_ZB_NWK_ROUTE_STATE_ACTIVE = 0U, /*!< The route is active. */
|
|
ESP_ZB_NWK_ROUTE_STATE_DISCOVERY_UNDERWAY = 1U, /*!< The route is under discovery process. */
|
|
ESP_ZB_NWK_ROUTE_STATE_DISCOVERY_FAILED = 2U, /*!< The discovery process failed of this route. */
|
|
ESP_ZB_NWK_ROUTE_STATE_INACTIVE = 3U, /*!< The route is inactive and under validation. */
|
|
} esp_zb_nwk_route_state_t;
|
|
|
|
/**
|
|
* @brief Information of network routing table entry
|
|
*
|
|
*/
|
|
typedef struct esp_zb_nwk_route_info_s {
|
|
uint16_t dest_addr; /*!< 16-bit network address of the destination. */
|
|
uint16_t next_hop_addr; /*!< 16-bit network address of the next hop on the way to the destination. */
|
|
struct {
|
|
uint8_t status : 3; /*!< The status of the route, bit 0 - 2, refer to esp_zb_nwk_route_state_t */
|
|
uint8_t no_route_cache : 1; /*!< Dest does not store source routes, bit 3 */
|
|
uint8_t many_to_one : 1; /*!< Dest is the concentrator and many-to-one request was used, bit 4 */
|
|
uint8_t route_record_required : 1; /*!< Route record command frame should be sent
|
|
* to the dest prior to the next data packet, bit 5 */
|
|
uint8_t group_id : 1; /*!< Indicates that dest_addr is a Group ID, bit 6 */
|
|
uint8_t /* reserved */ : 2; /*!< Reserved, bit 7 */
|
|
} flags; /*!< Flags in the routing table entry */
|
|
uint8_t expiry; /*!< Expiration time. */
|
|
} esp_zb_nwk_route_info_t;
|
|
|
|
/**
|
|
* @brief Information of network route record table entry
|
|
*
|
|
*/
|
|
typedef struct esp_zb_nwk_route_record_info_s {
|
|
uint16_t dest_address; /*!< Destination network address of this route record. */
|
|
uint8_t expiry; /*!< Expiration time. */
|
|
uint8_t relay_count; /*!< The count of relay nodes from concentrator to the destination. */
|
|
uint16_t path[ESP_ZB_NWK_MAX_SOURCE_ROUTE]; /*!< The set of network addresses that represent the route
|
|
* in order from the concentrator to the destination.*/
|
|
} esp_zb_nwk_route_record_info_t;
|
|
|
|
/**
|
|
* @brief Set the network update id
|
|
*
|
|
* @param[in] id The network update id is expected to be set
|
|
* @return
|
|
* - ESP_OK: On success
|
|
* - ESP_ERR_INVALID_STATE: Device is already on a network
|
|
*/
|
|
esp_err_t esp_zb_nwk_set_update_id(uint8_t id);
|
|
|
|
/**
|
|
* @brief Get the network update id
|
|
*
|
|
* @return The network update id
|
|
*/
|
|
uint8_t esp_zb_nwk_get_update_id(void);
|
|
|
|
/**
|
|
* @brief Set the network outgoing frame counter
|
|
*
|
|
* @param[in] frame_counter The network frame counter value is expect to be set
|
|
* @return
|
|
* - ESP_OK: On success
|
|
* - ESP_ERR_INVALID_STATE: Device is already on a network
|
|
*/
|
|
esp_err_t esp_zb_nwk_set_frame_counter(uint32_t frame_counter);
|
|
|
|
/**
|
|
* @brief Get the current network outgoing frame counter
|
|
*
|
|
* @return The network outgoing frame counter
|
|
*/
|
|
uint32_t esp_zb_nwk_get_frame_counter(void);
|
|
|
|
/**
|
|
* @brief Set zigbee rx on when idle.
|
|
*
|
|
* @param[in] rx_on enable/disable rx on when idle.
|
|
*
|
|
*/
|
|
void esp_zb_set_rx_on_when_idle(bool rx_on);
|
|
|
|
/**
|
|
* @brief Get the current state of RX-ON-When-Idle
|
|
*
|
|
* @return The state of RX-ON-When-Idle
|
|
*/
|
|
bool esp_zb_get_rx_on_when_idle(void);
|
|
|
|
/**
|
|
* @brief Set the maximum number of children allowed.
|
|
*
|
|
* The function only takes effect on ZC/ZR.
|
|
*
|
|
* @param[in] max_children Maximum number of children.
|
|
*
|
|
* @return
|
|
* - ESP_OK: On success
|
|
* - ESP_ERR_NOT_SUPPORTED: for ZED.
|
|
*
|
|
*/
|
|
esp_err_t esp_zb_nwk_set_max_children(uint8_t max_children);
|
|
|
|
/**
|
|
* @brief Get the maximum number of children allowed.
|
|
*
|
|
* @return
|
|
* - Maximum number of children, for ZC/ZR
|
|
* - 0, for ZED
|
|
*
|
|
*/
|
|
uint8_t esp_zb_nwk_get_max_children(void);
|
|
|
|
/**
|
|
* @brief Set the Zigbee device long address.
|
|
*
|
|
* @note Set this function AFTER @ref esp_zb_init called, if user wants to set specific address
|
|
* without reading MAC address from flash refer to tools/mfg_tool or eFUSE.
|
|
*
|
|
* @param[in] addr An 64-bit of IEEE long address, which is presented in little-endian.
|
|
* @return
|
|
* - ESP_OK: On success
|
|
* - ESP_ERR_INVALID_STATE: Device is already on a network
|
|
*/
|
|
esp_err_t esp_zb_set_long_address(esp_zb_ieee_addr_t addr);
|
|
|
|
/**
|
|
* @brief Get the Zigbee device long address.
|
|
*
|
|
* @note This function will return a pointer to 64-bit of ieee long address.
|
|
*
|
|
* @param[out] addr An 64-bit of IEEE long address, which is presented in little-endian.
|
|
*
|
|
*/
|
|
void esp_zb_get_long_address(esp_zb_ieee_addr_t addr);
|
|
|
|
/**
|
|
* @brief Get the Zigbee device short address.
|
|
*
|
|
* @return 16-bit Zigbee short address
|
|
*
|
|
*/
|
|
uint16_t esp_zb_get_short_address(void);
|
|
|
|
/**
|
|
* @brief Set the Zigbee network extended PAN ID.
|
|
*
|
|
* @param ext_pan_id An 64-bit of extended PAN ID, which is presented in little-endian.
|
|
*/
|
|
void esp_zb_set_extended_pan_id(const esp_zb_ieee_addr_t ext_pan_id);
|
|
|
|
/**
|
|
* @brief Get the Zigbee network extended PAN ID.
|
|
*
|
|
* @note This function will return back a pointer to 64-bit of extended PAN ID.
|
|
*
|
|
* @param[out] ext_pan_id An 64-bit of extended PAN ID, which is presented in little-endian.
|
|
*
|
|
*/
|
|
void esp_zb_get_extended_pan_id(esp_zb_ieee_addr_t ext_pan_id);
|
|
|
|
/**
|
|
* @brief Set the Zigbee network PAN ID.
|
|
*
|
|
* @note The PAN ID will be set from the network PIB to the IEEE802154 PIB
|
|
* @param[in] pan_id 16-bit Zigbee network PAN ID
|
|
*
|
|
*/
|
|
void esp_zb_set_pan_id(uint16_t pan_id);
|
|
|
|
/**
|
|
* @brief Get the Zigbee network PAN ID.
|
|
*
|
|
* @return 16-bit Zigbee network PAN ID
|
|
*
|
|
*/
|
|
uint16_t esp_zb_get_pan_id(void);
|
|
|
|
/**
|
|
* @brief Get the currently used channel.
|
|
* @return 8-bit Zigbee network channel number
|
|
*/
|
|
uint8_t esp_zb_get_current_channel(void);
|
|
|
|
/**
|
|
* @brief Get the network short address by the IEEE address
|
|
*
|
|
* @param[in] address An 64-bit for the IEEE address, which is presented in little-endian.
|
|
* @return Network short address
|
|
*
|
|
*/
|
|
uint16_t esp_zb_address_short_by_ieee(esp_zb_ieee_addr_t address);
|
|
|
|
/**
|
|
* @brief Get the network IEEE address by the short address
|
|
*
|
|
* @param[in] short_addr The 2-byte address which will been used to search the mapped IEEE address
|
|
* @param[out] ieee_addr The 64-bit of address for Zigbee IEEE address, which is presented in little-endian.
|
|
* @return
|
|
* - ESP_OK: on success
|
|
* - ESP_ERR_NOT_FOUND: not found the IEEE address
|
|
*/
|
|
esp_err_t esp_zb_ieee_address_by_short(uint16_t short_addr, uint8_t *ieee_addr);
|
|
|
|
/**
|
|
* @brief Set the Zigbee network device role
|
|
*
|
|
* @param[in] role The network device role is expected to be set
|
|
* @return
|
|
* - ESP_OK: On success
|
|
* - ESP_ERR_INVALID_STATE: Device is already on a network
|
|
* - ESP_ERR_INVALID_ARG: Invalid device role
|
|
*/
|
|
esp_err_t esp_zb_set_network_device_role(esp_zb_nwk_device_type_t role);
|
|
|
|
/**
|
|
* @brief Get the Zigbee network device type.
|
|
*
|
|
* @return device type @ref esp_zb_nwk_device_type_t
|
|
*
|
|
*/
|
|
esp_zb_nwk_device_type_t esp_zb_get_network_device_role(void);
|
|
|
|
/**
|
|
* @brief Iterate through the neighbor table and get information about active neighbor
|
|
*
|
|
* @param[in] iterator iterator used to iterate through neighbor table, refer to esp_zb_nwk_info_iterator_t
|
|
* @param[out] nbr_info next neighbor information, @ref esp_zb_nwk_neighbor_info_s
|
|
*
|
|
* @return - ESP_OK on success
|
|
* - ESP_ERR_NOT_FOUND on finish iteration
|
|
* - ESP_ERR_INVALID_ARG if arguments are invalid
|
|
*
|
|
*/
|
|
esp_err_t esp_zb_nwk_get_next_neighbor(esp_zb_nwk_info_iterator_t *iterator, esp_zb_nwk_neighbor_info_t *nbr_info);
|
|
|
|
/**
|
|
* @brief Iterate through the routing table and get the information in the entry
|
|
*
|
|
* @param[in] iterator iterator used to iterate through routing table, refer to esp_zb_nwk_info_iterator_t
|
|
* @param[out] route_info next route entry information, @ref esp_zb_nwk_route_info_s
|
|
*
|
|
* @return - ESP_OK on success
|
|
* - ESP_ERR_NOT_FOUND on finish iteration
|
|
* - ESP_ERR_INVALID_ARG if arguments are invalid
|
|
*
|
|
*/
|
|
esp_err_t esp_zb_nwk_get_next_route(esp_zb_nwk_info_iterator_t *iterator, esp_zb_nwk_route_info_t *route_info);
|
|
|
|
/**
|
|
* @brief Iterate through the route record table (a.k.a source route table) and get the information in the entry
|
|
*
|
|
* @param[in] iterator iterator used to iterate through routing table, refer to esp_zb_nwk_info_iterator_t
|
|
* @param[out] route_record_info next route record entry information, @ref esp_zb_nwk_route_record_info_s
|
|
*
|
|
* @return - ESP_OK on success
|
|
* - ESP_ERR_NOT_FOUND on finish iteration
|
|
* - ESP_ERR_INVALID_ARG if arguments are invalid
|
|
*
|
|
*/
|
|
esp_err_t esp_zb_nwk_get_next_route_record(esp_zb_nwk_info_iterator_t *iterator, esp_zb_nwk_route_record_info_t *route_record_info);
|
|
|
|
/**
|
|
* @brief Get the nwkLinkStatusPeriod attribute in NIB
|
|
*
|
|
* @return The time in seconds between link status command frames.
|
|
*
|
|
*/
|
|
uint8_t esp_zb_nwk_get_link_status_period(void);
|
|
|
|
/**
|
|
* @brief Set the nwkLinkStatusPeriod attribute in NIB
|
|
*
|
|
* @param[in] period The time in seconds between link status command frames.
|
|
*
|
|
* @return - ESP_OK on success, error code otherwise.
|
|
*
|
|
*/
|
|
esp_err_t esp_zb_nwk_set_link_status_period(uint8_t period);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|