NWK Configuration API

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

API Reference

Header File

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 extended PAN ID used by the Zigbee device for joining or forming a network.

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 extended PAN ID of Zigbee device.

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

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

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 arguments are invalid

uint8_t esp_zb_nwk_get_link_status_period(void)

Get the nwkLinkStatusPeriod attribute in NIB.

Returns:

The time in seconds between link status command frames.

esp_err_t esp_zb_nwk_set_link_status_period(uint8_t period)

Set the nwkLinkStatusPeriod attribute in NIB.

Parameters:

period – [in] The time in seconds between link status command frames.

Returns:

- ESP_OK on success, error code otherwise.

void esp_zb_nwk_set_extended_pan_id(esp_zb_ext_pan_id_t ext_pan_id)

Set the nwkExtendedPANID attribute in the NIB.

Parameters:

ext_pan_id – [in] A 64-bit extended PAN ID in little-endian format to be set in the NIB.

void esp_zb_nwk_get_extended_pan_id(esp_zb_ext_pan_id_t ext_pan_id)

Get the nwkExtendedPANID attribute from the NIB.

Parameters:

ext_pan_id – [out] A 64-bit extended PAN ID in little-endian format retrieved from the NIB, which represents the extended PAN ID of the network to which the device is joined. If the value is 0x0000000000000000, the device is not connected to any network.

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

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_command_status_t

Enumeration of Zigbee network command status code.

Values:

enumerator ESP_ZB_NWK_COMMAND_STATUS_NO_ROUTE_AVAILABLE

No route available

enumerator ESP_ZB_NWK_COMMAND_STATUS_TREE_LINK_FAILURE

Tree link failure

enumerator ESP_ZB_NWK_COMMAND_STATUS_NONE_TREE_LINK_FAILURE

None-tree link failure

enumerator ESP_ZB_NWK_COMMAND_STATUS_LOW_BATTERY_LEVEL

Low battery level

enumerator ESP_ZB_NWK_COMMAND_STATUS_NO_ROUTING_CAPACITY

No routing capacity

enumerator ESP_ZB_NWK_COMMAND_STATUS_NO_INDIRECT_CAPACITY

No indirect capacity

enumerator ESP_ZB_NWK_COMMAND_STATUS_INDIRECT_TRANSACTION_EXPIRY

Indirect transaction expiry

enumerator ESP_ZB_NWK_COMMAND_STATUS_TARGET_DEVICE_UNAVAILABLE

Target device unavailable

enumerator ESP_ZB_NWK_COMMAND_STATUS_TARGET_ADDRESS_UNALLOCATED

Target address unallocated

enumerator ESP_ZB_NWK_COMMAND_STATUS_PARENT_LINK_FAILURE

Parent link failure

enumerator ESP_ZB_NWK_COMMAND_STATUS_VALIDATE_ROUTE

Validate route

enumerator ESP_ZB_NWK_COMMAND_STATUS_SOURCE_ROUTE_FAILURE

Source route failure

enumerator ESP_ZB_NWK_COMMAND_STATUS_MANY_TO_ONE_ROUTE_FAILURE

Many-to-one route failure

enumerator ESP_ZB_NWK_COMMAND_STATUS_ADDRESS_CONFLICT

Address conflict

enumerator ESP_ZB_NWK_COMMAND_STATUS_VERIFY_ADDRESS

Verify address

enumerator ESP_ZB_NWK_COMMAND_STATUS_PAN_IDENTIFIER_UPDATE

Pan ID update

enumerator ESP_ZB_NWK_COMMAND_STATUS_NETWORK_ADDRESS_UPDATE

Network address update

enumerator ESP_ZB_NWK_COMMAND_STATUS_BAD_FRAME_COUNTER

Bad frame counter

enumerator ESP_ZB_NWK_COMMAND_STATUS_BAD_KEY_SEQUENCE_NUMBER

Bad key sequence number

enumerator ESP_ZB_NWK_COMMAND_STATUS_UNKNOWN_COMMAND

Command received is not known

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.