NWK Configuration API

NWK(Zigbee Network) configuration related APIs for ESP Zigbee SDK.

API Reference

Header File

components/esp-zigbee-lib/include/nwk/esp_zigbee_nwk.h

Functions

esp_err_t esp_zb_nwk_set_update_id(uint8_t id)

Set the network update id.

Parameters

id – [in] The network update id is expected to be set

Returns

ESP_OK: On success
ESP_ERR_INVALID_STATE: Device is already on a network

uint8_t esp_zb_nwk_get_update_id(void)

Get the network update id.

Returns: The network update id

esp_err_t esp_zb_nwk_set_frame_counter(uint32_t frame_counter)

Set the network outgoing frame counter.

Parameters

frame_counter – [in] The network frame counter value is expect to be set

Returns

ESP_OK: On success
ESP_ERR_INVALID_STATE: Device is already on a network

uint32_t esp_zb_nwk_get_frame_counter(void)

Get the current network outgoing frame counter.

Returns: The network outgoing frame counter

void esp_zb_set_rx_on_when_idle(bool rx_on)

Set zigbee rx on when idle.

Parameters: rx_on – [in] enable/disable rx on when idle.

bool esp_zb_get_rx_on_when_idle(void)

Get the current state of RX-ON-When-Idle.

Returns: The state of RX-ON-When-Idle

esp_err_t esp_zb_nwk_set_max_children(uint8_t max_children)

Set the maximum number of children allowed.

The function only takes effect on ZC/ZR.

Parameters

max_children – [in] Maximum number of children.

Returns

ESP_OK: On success
ESP_ERR_NOT_SUPPORTED: for ZED.

uint8_t esp_zb_nwk_get_max_children(void)

Get the maximum number of children allowed.

Returns

Maximum number of children, for ZC/ZR
0, for ZED

esp_err_t esp_zb_set_long_address(esp_zb_ieee_addr_t addr)

Set the Zigbee device long address.

Note

Set this function AFTER esp_zb_init called, if user wants to set specific address without reading MAC address from flash refer to tools/mfg_tool or eFUSE.

Parameters

addr – [in] An 64-bit of IEEE long address, which is presented in little-endian.

Returns

ESP_OK: On success
ESP_ERR_INVALID_STATE: Device is already on a network

void esp_zb_get_long_address(esp_zb_ieee_addr_t addr)

Get the Zigbee device long address.

Note

This function will return a pointer to 64-bit of ieee long address.

Parameters: addr – [out] An 64-bit of IEEE long address, which is presented in little-endian.

uint16_t esp_zb_get_short_address(void)

Get the Zigbee device short address.

Returns: 16-bit Zigbee short address

void esp_zb_set_extended_pan_id(const esp_zb_ieee_addr_t ext_pan_id)

Set the Zigbee network extended PAN ID.

Parameters: 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)

Get the Zigbee network extended PAN ID.

Note

This function will return back a pointer to 64-bit of extended PAN ID.

Parameters: ext_pan_id – [out] An 64-bit of extended PAN ID, which is presented in little-endian.

void esp_zb_set_pan_id(uint16_t pan_id)

Set the Zigbee network PAN ID.

Note

The PAN ID will be set from the network PIB to the IEEE802154 PIB

Parameters: pan_id – [in] 16-bit Zigbee network PAN ID

uint16_t esp_zb_get_pan_id(void)

Get the Zigbee network PAN ID.

Returns: 16-bit Zigbee network PAN ID

uint8_t esp_zb_get_current_channel(void)

Get the currently used channel.

Returns: 8-bit Zigbee network channel number

uint16_t esp_zb_address_short_by_ieee(esp_zb_ieee_addr_t address)

Get the network short address by the IEEE address.

Parameters: address – [in] An 64-bit for the IEEE address, which is presented in little-endian.
Returns: Network short address

esp_err_t esp_zb_ieee_address_by_short(uint16_t short_addr, uint8_t *ieee_addr)

Get the network IEEE address by the short address.

Parameters

short_addr – [in] The 2-byte address which will been used to search the mapped IEEE address
ieee_addr – [out] The 64-bit of address for Zigbee IEEE address, which is presented in little-endian.

Returns

ESP_OK: on success
ESP_ERR_NOT_FOUND: not found the IEEE address

esp_err_t esp_zb_set_network_device_role(esp_zb_nwk_device_type_t role)

Set the Zigbee network device role.

Parameters

role – [in] The network device role is expected to be set

Returns

ESP_OK: On success
ESP_ERR_INVALID_STATE: Device is already on a network
ESP_ERR_INVALID_ARG: Invalid device role

esp_zb_nwk_device_type_t esp_zb_get_network_device_role(void)

Get the Zigbee network device type.

Returns: device type esp_zb_nwk_device_type_t

esp_err_t esp_zb_nwk_get_next_neighbor(esp_zb_nwk_info_iterator_t *iterator, esp_zb_nwk_neighbor_info_t *nbr_info)

Iterate through the neighbor table and get information about active neighbor.

Parameters

iterator – [in] iterator used to iterate through neighbor table, refer to esp_zb_nwk_info_iterator_t
nbr_info – [out] next neighbor information, esp_zb_nwk_neighbor_info_s

Returns

- ESP_OK on success

ESP_ERR_NOT_FOUND on finish iteration
ESP_ERR_INVALID_ARG if arguements 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)

Iterate through the routing table and get the information in the entry.

Parameters

iterator – [in] iterator used to iterate through routing table, refer to esp_zb_nwk_info_iterator_t
route_info – [out] next route entry information, esp_zb_nwk_route_info_s

Returns

- ESP_OK on success

ESP_ERR_NOT_FOUND on finish iteration
ESP_ERR_INVALID_ARG if arguements 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)

Iterate through the route record table (a.k.a source route table) and get the information in the entry.

Parameters

iterator – [in] iterator used to iterate through routing table, refer to esp_zb_nwk_info_iterator_t
route_record_info – [out] next route record entry information, esp_zb_nwk_route_record_info_s

Returns

- ESP_OK on success

ESP_ERR_NOT_FOUND on finish iteration
ESP_ERR_INVALID_ARG if arguements are invalid

Structures

struct esp_zb_nwk_neighbor_info_s

Information of network neighbor table entry.

Public Members

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 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 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.

struct esp_zb_nwk_route_info_s

Information of network routing table entry.

Public Members

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.

uint8_t status: The status of the route, bit 0 - 2, refer to esp_zb_nwk_route_state_t

uint8_t no_route_cache: Dest does not store source routes, bit 3

uint8_t many_to_one: Dest is the concentrator and many-to-one request was used, bit 4

uint8_t route_record_required: Route record command frame should be sent to the dest prior to the next data packet, bit 5

uint8_t group_id: Indicates that dest_addr is a Group ID, bit 6

uint8_t __pad0__: Reserved, bit 7

struct esp_zb_nwk_route_info_s::[anonymous] flags: Flags in the routing table entry

uint8_t expiry: Expiration time.

struct esp_zb_nwk_route_record_info_s

Information of network route record table entry.

Public Members

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.

Macros

ESP_ZB_NWK_INFO_ITERATOR_INIT: Initializer for esp_zb_neighbor_info_iterator_t.

ESP_ZB_NWK_INFO_ITERATOR_EOT: Indicate the iterator reach the End of Table.

ESP_ZB_NWK_MAX_SOURCE_ROUTE

Type Definitions

typedef uint16_t esp_zb_nwk_info_iterator_t: Iterator used to iterate through the tables of network informations.

typedef struct esp_zb_nwk_neighbor_info_s esp_zb_nwk_neighbor_info_t: Information of network neighbor table entry.

typedef struct esp_zb_nwk_route_info_s esp_zb_nwk_route_info_t: Information of network routing table entry.

typedef struct esp_zb_nwk_route_record_info_s esp_zb_nwk_route_record_info_t: Information of network route record table entry.

Enumerations

enum esp_zb_nwk_device_type_t

Enum of the Zigbee network device type

Values:

enumerator ESP_ZB_DEVICE_TYPE_COORDINATOR: Device - Coordinator

enumerator ESP_ZB_DEVICE_TYPE_ROUTER: Device - Router

enumerator ESP_ZB_DEVICE_TYPE_ED: Device - End device

enumerator ESP_ZB_DEVICE_TYPE_NONE: Unknown Device

enum esp_zb_nwk_relationship_t

Relationship of network neighbor.

Values:

enumerator ESP_ZB_NWK_RELATIONSHIP_PARENT: The peer device is the parent of current device.

enumerator ESP_ZB_NWK_RELATIONSHIP_CHILD: The peer device is the child of current device.

enumerator ESP_ZB_NWK_RELATIONSHIP_SIBLING: The peer device is the sibling of current device.

enumerator ESP_ZB_NWK_RELATIONSHIP_NONE_OF_THE_ABOVE: 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.

enumerator ESP_ZB_NWK_RELATIONSHIP_PREVIOUS_CHILD: The peer device is the previous child of current device, meaning it has been confirmed to have left the network

enumerator ESP_ZB_NWK_RELATIONSHIP_UNAUTHENTICATED_CHILD: 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.

enum esp_zb_nwk_route_state_t

State of the network route.

Values:

enumerator ESP_ZB_NWK_ROUTE_STATE_ACTIVE: The route is active.

enumerator ESP_ZB_NWK_ROUTE_STATE_DISCOVERY_UNDERWAY: The route is under discovery process.

enumerator ESP_ZB_NWK_ROUTE_STATE_DISCOVERY_FAILED: The discovery process failed of this route.

enumerator ESP_ZB_NWK_ROUTE_STATE_INACTIVE: The route is inactive and under validation.