5.2.9. Network

This section provides the network layer data and management related APIs and defines of ESP Zigbee Core.

5.2.9.1. API Reference

5.2.9.1.1. Header File

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

5.2.9.1.2. Functions

ezb_err_t ezb_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:

EZB_ERR_NONE: On success
EZB_ERR_INV_STATE: Device is already on a network

uint8_t ezb_nwk_get_update_id(void)

Get the network update id.

Returns:: The network update id

ezb_err_t ezb_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:

EZB_ERR_NONE: On success
EZB_ERR_INV_STATE: Device is already on a network

uint32_t ezb_nwk_get_frame_counter(void)

Get the current network outgoing frame counter.

Returns:: The network outgoing frame counter

void ezb_nwk_set_rx_on_when_idle(bool rx_on)

Enable/Disable Rx when device is in IDLE state. .

Parameters:: rx_on -- [in] True - Rx remains on during idle periods, False - Rx is put to sleep during idle periods.

bool ezb_nwk_get_rx_on_when_idle(void)

Get the current state of RxOnWhenIdle. .

Returns:: The state of RxOnWhenIdle.

ezb_err_t ezb_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:

EZB_ERR_NONE: On success
EZB_ERR_NOT_SUPPORTED: for ZED.

uint8_t ezb_nwk_get_max_children(void)

Get the maximum number of children allowed.

Returns:

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

void ezb_nwk_set_extended_address(const ezb_extaddr_t *extaddr)

Set the IEEE (extended) address of the device. .

Note

Set this function AFTER ezb_core_init called, if user wants to set specific address which is different from the MAC address.

Parameters:: extaddr -- [in] The pointer to the 64-bit of IEEE address, in little-endian.

void ezb_nwk_get_extended_address(ezb_extaddr_t *extaddr)

Get the IEEE (extended) address of the device. .

Parameters:: extaddr -- [out] The pointer to the 64-bit of IEEE address, in little-endian.

void ezb_nwk_set_short_address(ezb_shortaddr_t short_addr)

Set the network (short) address of the device. .

Parameters:: short_addr -- [in] The 16-bit network (short) address.

ezb_shortaddr_t ezb_nwk_get_short_address(void)

Get the network (short) address of the device. .

Returns:: 16-bit Zigbee short address, in little-endian.

void ezb_nwk_set_extended_panid(const ezb_extpanid_t *extpanid)

Set the extended PAN ID of the network. .

Note

Please do not use this function to set the extended PAN ID, use ezb_set_use_extended_panid instead.

Parameters:: extpanid -- [in] The pointer to the 64-bit of extended PAN ID, in little-endian.

void ezb_nwk_get_extended_panid(ezb_extpanid_t *extpanid)

Get the extended PAN ID of the network. .

Parameters:: extpanid -- [out] The pointer to the 64-bit of extended PAN ID, in little-endian.

void ezb_nwk_set_panid(ezb_panid_t panid)

Set the PAN ID of the network. .

Note

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

Parameters:: panid -- [in] The 16-bit of PAN ID, in little-endian.

ezb_panid_t ezb_nwk_get_panid(void)

Get the PAN ID of the network. .

Returns:: 16-bit PAN ID, in little-endian.

uint8_t ezb_nwk_get_current_channel(void)

Get the currently used channel. .

Returns:: 8-bit Zigbee network channel number

void ezb_nwk_set_tx_power(int8_t power)

Set the tx power. .

Parameters:: power -- [in] The tx power in dBm.

void ezb_nwk_get_tx_power(int8_t *power)

Get the tx power. .

Parameters:: power -- [out] The tx power in dBm.

ezb_err_t ezb_address_short_by_extended(const ezb_extaddr_t *extaddr, ezb_shortaddr_t *shortaddr)

Get the short address by IEEE (extended) address.

Parameters:

extaddr -- [in] The 64-bit IEEE (extended) address of a known device.
shortaddr -- [out] The 16-bit short address of the device.

Returns:

EZB_ERR_NONE: on success
EZB_ERR_NOT_FOUND: The mapped short address is not found

ezb_err_t ezb_address_extended_by_short(ezb_shortaddr_t shortaddr, ezb_extaddr_t *extaddr)

Get the IEEE (extended) address by the short address.

Parameters:

shortaddr -- [in] The 16-bit short address of a known device.
extaddr -- [out] The 64-bit IEEE (extended) address of the device.

Returns:

EZB_ERR_NONE: on success
EZB_ERR_NOT_FOUND: The mapped IEEE (extended) address is not found

ezb_err_t ezb_nwk_set_device_type(ezb_nwk_device_type_t role)

Set the Zigbee network device role.

Parameters:

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

Returns:

EZB_ERR_NONE: On success
EZB_ERR_INV_STATE: Device is already on a network
EZB_ERR_INV_ARG: Invalid device role

ezb_nwk_device_type_t ezb_nwk_get_device_type(void)

Get the Zigbee network device type.

Returns:: device type ezb_nwk_device_type_t

void ezb_nwk_set_ed_timeout(ezb_nwk_ed_timeout_t timeout)

Set the End Device (ED) timeout.

Note

For ZC/ZR, the value indicates the duration of missing keepalive messages before aging out the end device. For ZED, the value indicates the duration of failed keepalive process before it is considered as lost links to its parent.

Parameters:: timeout -- [in] The End Device (ED) timeout value, ezb_nwk_ed_timeout_e

ezb_nwk_ed_timeout_t ezb_nwk_get_ed_timeout(void)

Get the End Device timeout value.

Returns:: The End Device timeout value, ezb_nwk_ed_timeout_e

void ezb_nwk_set_keepalive_interval(uint32_t interval)

Set the interval of keepalive process on End Device.

Note

This function is only available for End Device. By default, this is set to 1/4 of the ED timeout.

Parameters:: interval -- [in] The keepalive interval, in milliseconds.

uint32_t ezb_nwk_get_keepalive_interval(void)

Get the keepalive interval for the End Device.

Note

This function is only available for End Device.

Returns:: The keepalive interval, in milliseconds.

void ezb_nwk_set_fast_poll_interval(uint32_t interval)

Set the interval of fast poll process on Sleepy End Device (SED).

Note

This function is only available for End Device. By default, this is set to 200 milliseconds.

Parameters:: interval -- [in] The fast poll interval, in milliseconds.

uint32_t ezb_nwk_get_fast_poll_interval(void)

Get the fast poll interval for the Sleepy End Device (SED).

Note

This function is only available for Sleepy End Device (SED).

Returns:: The fast poll interval, in milliseconds.

ezb_err_t ezb_nwk_get_next_neighbor(ezb_nwk_info_iterator_t *iterator, ezb_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 ezb_nwk_info_iterator_t
nbr_info -- [out] next neighbor information, ezb_nwk_neighbor_info_s

Returns:

- EZB_ERR_NONE on success

EZB_ERR_NOT_FOUND on finish iteration
EZB_ERR_INV_ARG if arguments are invalid

ezb_err_t ezb_nwk_get_next_route(ezb_nwk_info_iterator_t *iterator, ezb_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 ezb_nwk_info_iterator_t
route_info -- [out] next route entry information, ezb_nwk_route_info_s

Returns:

- EZB_ERR_NONE on success

EZB_ERR_NOT_FOUND on finish iteration
EZB_ERR_INV_ARG if arguments are invalid

ezb_err_t ezb_nwk_get_next_route_record(ezb_nwk_info_iterator_t *iterator, ezb_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 ezb_nwk_info_iterator_t
route_record_info -- [out] next route record entry information, ezb_nwk_route_record_info_s

Returns:

- EZB_ERR_NONE on success

EZB_ERR_NOT_FOUND on finish iteration
EZB_ERR_INV_ARG if arguments are invalid

uint8_t ezb_nwk_get_link_status_period(void)

Get the nwkLinkStatusPeriod attribute in NIB.

Returns:: The time in seconds between link status command frames.

ezb_err_t ezb_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:: - EZB_ERR_NONE on success, error code otherwise.

uint8_t ezb_nwk_get_min_join_lqi(void)

Get the minimum LQI value for device joining the network.

Returns:: The minimum LQI value

void ezb_nwk_set_min_join_lqi(uint8_t lqi)

Set the minimum LQI value for device joining the network.

Parameters:: lqi -- [in] The minimum LQI value

const char *ezb_nwk_network_status_to_string(ezb_nwk_network_status_t status)

Convert the network status to string.

Parameters:: status -- [in] The network status to convert, ezb_nwk_network_status_t
Returns:: The string representation of the network status

ezb_err_t ezb_nwk_scan(const ezb_nwk_scan_req_t *req)

Request for network scan.

Parameters:: req -- [in] The network scan request, ezb_nwk_scan_req_s
Returns:: - EZB_ERR_NONE on success, error code otherwise.

5.2.9.1.3. Structures

struct ezb_nwk_neighbor_info_s

Information of network neighbor table entry.

Public Members

ezb_extaddr_t ieee_addr: Long address (EUI64) of the device.

ezb_shortaddr_t short_addr: Short address (network address) of the device.

uint8_t device_type: Neighbor device type, refer to ezb_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 ezb_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 ezb_nwk_route_info_s

Information of network routing table entry.

Public Members

ezb_shortaddr_t dest_addr: 16-bit network address of the destination.

ezb_shortaddr_t next_hop_addr: 16-bit network address of the next hop on the way to the destination.

uint8_t expiry: Expiration time.

uint8_t status: The status of the route, bit 0 - 2, refer to ezb_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

Deprecated:

uint8_t __pad0__: Reserved, bit 7

struct ezb_nwk_route_info_s flags: Flags in the routing table entry

struct ezb_nwk_route_record_info_s

Information of network route record table entry.

Public Members

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

ezb_shortaddr_t path[EZB_NWK_MAX_SOURCE_ROUTE]: The set of network addresses that represent the route in order from the concentrator to the destination.

struct ezb_nwk_active_scan_result_s

Information of active scan result (beacon)

Public Members

ezb_shortaddr_t shortaddr: Short address of the router

ezb_panid_t panid: PAN ID of the network

ezb_extpanid_t extpanid: Extended PAN ID of the network

uint8_t channel_page: Channel page of the network

uint8_t channel_number: Channel number of the network

uint8_t nwk_update_id: Network update ID

uint8_t stack_profile: Stack profile

uint8_t protocol_version: Protocol version

bool permit_join: Indicate if it permits joining

bool router_capacity: Indicate if it is capable to accept router's joining request

bool enddev_capacity: Indicate if it is capable to accept end device's joining request

struct ezb_nwk_ed_scan_result_s

Information of energy detection scan result.

Public Members

uint8_t channel_page: Channel page of the scanned channel

uint8_t channel_number: Channel number of the scanned channel

int8_t max_rssi: Maximum RSSI value, the detected energy

struct ezb_nwk_scan_req_s

Request for network scan.

Public Members

ezb_nwk_scan_type_t scan_type: Scan type, ezb_nwk_scan_type_t

uint8_t scan_duration: Scan duration, time spent scanning each channel, (2^n + 1) * BeaconInterval(15.36 ms).

uint32_t scan_channels: Scan channels, bitmask of the channels to scan

ezb_nwk_active_scan_callback_t active_scan_cb: Callback function for active scan.

ezb_nwk_ed_scan_callback_t ed_scan_cb: Callback function for energy detection scan.

void *user_ctx: The user context for the callback functions.

5.2.9.1.4. Macros

ESP_ZIGBEE_NWK_H

EZB_NWK_ADDR_UNKNOWN: Unknown address

EZB_NWK_INFO_ITERATOR_INIT: Initializer for ezb_neighbor_info_iterator_t.

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

EZB_NWK_MAX_SOURCE_ROUTE

5.2.9.1.5. Type Definitions

typedef uint8_t ezb_nwk_ed_timeout_t: Represent the End Device (ED) timeout value, ezb_nwk_ed_timeout_e.

typedef void *ezb_nwk_info_iterator_t: Iterator used to iterate through the tables of network information.

typedef struct ezb_nwk_neighbor_info_s ezb_nwk_neighbor_info_t: Information of network neighbor table entry.

typedef struct ezb_nwk_route_info_s ezb_nwk_route_info_t: Information of network routing table entry.

typedef struct ezb_nwk_route_record_info_s ezb_nwk_route_record_info_t: Information of network route record table entry.

typedef uint8_t ezb_nwk_scan_type_t: Represent the network scan type.

typedef struct ezb_nwk_active_scan_result_s ezb_nwk_active_scan_result_t: Information of active scan result (beacon)

typedef struct ezb_nwk_ed_scan_result_s ezb_nwk_ed_scan_result_t: Information of energy detection scan result.

typedef void (*ezb_nwk_active_scan_callback_t)(ezb_nwk_active_scan_result_t *result, void *user_ctx)

Callback function for active scan.

Note

It will be called when a active scan result is available (beacon is received) or the scan is finished.

Param result:: [in] The active scan result, ezb_nwk_active_scan_result_s, or NULL if the scan is finished.
Param user_ctx:: [in] The user context

typedef void (*ezb_nwk_ed_scan_callback_t)(ezb_nwk_ed_scan_result_t *result, void *user_ctx)

Callback function for energy detection scan.

Note

It will be called when a energy detection scan result is available (ED finished on channel) or the scan is finished.

Param result:: [in] The energy detection scan result, ezb_nwk_ed_scan_result_s, or NULL if the scan is finished.
Param user_ctx:: [in] The user context

typedef struct ezb_nwk_scan_req_s ezb_nwk_scan_req_t: Request for network scan.

5.2.9.1.6. Enumerations

enum ezb_nwk_device_type_t

Enum of the Zigbee network device type .

Values:

enumerator EZB_NWK_DEVICE_TYPE_COORDINATOR: Device - Coordinator

enumerator EZB_NWK_DEVICE_TYPE_ROUTER: Device - Router

enumerator EZB_NWK_DEVICE_TYPE_END_DEVICE: Device - End device

enumerator EZB_NWK_DEVICE_TYPE_NONE: Unknown device type

enum ezb_nwk_network_status_t

Enumeration of Zigbee network command status code .

Values:

enumerator EZB_NWK_NETWORK_STATUS_LEGACY_NO_ROUTE_AVAILABLE: No route available

enumerator EZB_NWK_NETWORK_STATUS_LEGACY_LINK_FAILURE: Tree link failure

enumerator EZB_NWK_NETWORK_STATUS_LINK_FAILURE: None-tree link failure

enumerator EZB_NWK_NETWORK_STATUS_LOW_BATTERY_LEVEL: Low battery level

enumerator EZB_NWK_NETWORK_STATUS_NO_ROUTING_CAPACITY: No routing capacity

enumerator EZB_NWK_NETWORK_STATUS_NO_INDIRECT_CAPACITY: No indirect capacity

enumerator EZB_NWK_NETWORK_STATUS_INDIRECT_TRANSACTION_EXPIRY: Indirect transaction expiry

enumerator EZB_NWK_NETWORK_STATUS_TARGET_DEVICE_UNAVAILABLE: Target device unavailable

enumerator EZB_NWK_NETWORK_STATUS_TARGET_ADDRESS_UNALLOCATED: Target address unallocated

enumerator EZB_NWK_NETWORK_STATUS_PARENT_LINK_FAILURE: Parent link failure

enumerator EZB_NWK_NETWORK_STATUS_VALIDATE_ROUTE: Validate route

enumerator EZB_NWK_NETWORK_STATUS_SOURCE_ROUTE_FAILURE: Source route failure

enumerator EZB_NWK_NETWORK_STATUS_MANY_TO_ONE_ROUTE_FAILURE: Many-to-one route failure

enumerator EZB_NWK_NETWORK_STATUS_ADDRESS_CONFLICT: Address conflict

enumerator EZB_NWK_NETWORK_STATUS_VERIFY_ADDRESS: Verify address

enumerator EZB_NWK_NETWORK_STATUS_PAN_IDENTIFIER_UPDATE: Pan ID update

enumerator EZB_NWK_NETWORK_STATUS_NETWORK_ADDRESS_UPDATE: Network address update

enumerator EZB_NWK_NETWORK_STATUS_BAD_FRAME_COUNTER: Bad frame counter

enumerator EZB_NWK_NETWORK_STATUS_BAD_KEY_SEQUENCE_NUMBER: Bad key sequence number

enumerator EZB_NWK_NETWORK_STATUS_UNKNOWN_COMMAND: Command received is not known

enumerator EZB_NWK_NETWORK_STATUS_PANID_CONFLICT: PAN ID conflict

enum ezb_nwk_ed_timeout_e

End Device (ED) timeout request .

Values:

enumerator EZB_NWK_ED_TIMEOUT_10SEC: 10 seconds

enumerator EZB_NWK_ED_TIMEOUT_2MIN: 2 minutes

enumerator EZB_NWK_ED_TIMEOUT_4MIN: 4 minutes

enumerator EZB_NWK_ED_TIMEOUT_8MIN: 8 minutes

enumerator EZB_NWK_ED_TIMEOUT_16MIN: 16 minutes

enumerator EZB_NWK_ED_TIMEOUT_32MIN: 32 minutes

enumerator EZB_NWK_ED_TIMEOUT_64MIN: 64 minutes

enumerator EZB_NWK_ED_TIMEOUT_128MIN: 128 minutes

enumerator EZB_NWK_ED_TIMEOUT_256MIN: 256 minutes

enumerator EZB_NWK_ED_TIMEOUT_512MIN: 512 minutes

enumerator EZB_NWK_ED_TIMEOUT_1024MIN: 1024 minutes

enumerator EZB_NWK_ED_TIMEOUT_2048MIN: 2048 minutes

enumerator EZB_NWK_ED_TIMEOUT_4096MIN: 4096 minutes

enumerator EZB_NWK_ED_TIMEOUT_8192MIN: 8192 minutes

enumerator EZB_NWK_ED_TIMEOUT_16384MIN: 16384 minutes

enum ezb_nwk_relationship_t

Relationship of network neighbor .

Values:

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

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

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

enumerator EZB_NWK_RELATIONSHIP_NONE_OF_THE_ABOVE: The relationship is none of above.

enum ezb_nwk_route_state_t

State of the network route .

Values:

enumerator EZB_NWK_ROUTE_STATE_ACTIVE: The route is active.

enumerator EZB_NWK_ROUTE_STATE_DISCOVERY_UNDERWAY: The route is under discovery process.

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

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

enum ezb_nwk_scan_type_e

Enumeration of network scan types .

Values:

enumerator EZB_NWK_SCAN_TYPE_ED: Energy detection

enumerator EZB_NWK_SCAN_TYPE_ACTIVE: Active scan

enumerator EZB_NWK_SCAN_TYPE_MAX_NR: Maximum number of scan types