Forming and Joining Networks#

sl_zigbee_scan_for_unused_pan_id#

sl_status_t sl_zigbee_scan_for_unused_pan_id (uint32_t channelMask, uint8_t duration)

Find an unused PAN ID.

Does an energy scan on the indicated channels and randomly chooses one from amongst those with the least average energy. Then picks a short PAN ID that does not appear during an active scan on the chosen channel. The chosen PAN ID and channel are returned via the sl_zigbee_unused_pan_id_found_handler() callback. If an error occurs, the application is informed via the sl_zigbee_scan_error_handler().

Returns

• SL_STATUS_NOT_AVAILABLE if the form and join library is not available.

sl_zigbee_scan_for_joinable_network#

sl_status_t sl_zigbee_scan_for_joinable_network (uint32_t channelMask, uint8_t * extendedPanId)

Find a joinable network.

Performs an active scan on the specified channels looking for networks that:

1. currently permit joining,

2. match the stack profile of the application,

3. match the extended PAN id argument if it is not NULL.

Upon finding a matching network, the application is notified via the sl_zigbee_joinable_network_found_handler() callback, and scanning stops. If an error occurs during the scanning process, the application is informed via the sl_zigbee_scan_error_handler(), and scanning stops.

If the application determines that the discovered network is not the correct one, it may call sl_zigbee_scan_for_next_joinable_network() to continue the scanning process where it was left off and find a different joinable network. If the next network is not the correct one, the application can continue to call sl_zigbee_scan_for_next_joinable_network(). Each call must occur within 30 seconds of the previous one, otherwise the state of the scan process is deleted to free up memory. Calling sl_zigbee_scan_for_joinable_network() causes any old state to be forgotten and starts scanning from the beginning.

Returns

• SL_STATUS_NOT_AVAILABLE if the form and join library is not available.

sl_zigbee_scan_for_next_joinable_network#

sl_status_t sl_zigbee_scan_for_next_joinable_network (void )

See sl_zigbee_scan_for_joinable_network().

sl_zigbee_form_and_join_is_scanning#

bool sl_zigbee_form_and_join_is_scanning (void )

Return true if and only if the form and join library is in the process of scanning and is therefore expecting scan results to be passed to it from the application.

sl_zigbee_form_and_join_can_continue_joinable_network_scan#

bool sl_zigbee_form_and_join_can_continue_joinable_network_scan (void )

Return true if and only if the application can continue a joinable network scan by calling sl_zigbee_scan_for_next_joinable_network(). See sl_zigbee_scan_for_joinable_network().

sl_zigbee_joinable_network_found_handler#

void sl_zigbee_joinable_network_found_handler (sl_zigbee_zigbee_network_t * networkFound, uint8_t lqi, int8_t rssi)

A callback the application needs to implement.

Notifies the application of the network found after a call to sl_zigbee_scan_for_joinable_network() or sl_zigbee_scan_for_next_joinable_network().

sl_zigbee_scan_error_handler#

void sl_zigbee_scan_error_handler (sl_status_t status)

A callback the application needs to implement.

If an error occurs while scanning, this function is called and the scan effort is aborted.

Possible return status values are:

• SL_STATUS_INVALID_STATE: if sl_zigbee_scan_for_next_joinable_network() is called more than 30 seconds after a previous call to sl_zigbee_scan_for_joinable_network() or sl_zigbee_scan_for_next_joinable_network().

• SL_STATUS_ALLOCATION_FAILED: if there is not enough memory to start a scan.

• SL_STATUS_NO_BEACONS: if no joinable beacons are found.

• SL_STATUS_MAC_SCANNING: if a scan is already in progress.

sl_zigbee_form_and_join_scan_complete_handler#

bool sl_zigbee_form_and_join_scan_complete_handler (uint8_t channel, sl_status_t status)

The application must call this function from within its sl_zigbee_scan_complete_handler() (on the node) or sl_zigbee_ezsp_scan_complete_handler() (on an EZSP host). Default callback implementations are provided in the form-and-join-*-callbacks.c files.

Returns

• true if the library made use of the call.

sl_zigbee_form_and_join_network_found_handler#

bool sl_zigbee_form_and_join_network_found_handler (sl_zigbee_zigbee_network_t * networkFound, uint8_t lqi, int8_t rssi)

The application must call this function from within its sl_zigbee_network_found_handler() (on the node) or sl_zigbee_ezsp_network_found_handler() (on an EZSP host). Default callback implementations are provided in the form-and-join-*-callbacks.c files.

Returns

• true if the library made use of the call.

sl_zigbee_form_and_join_energy_scan_result_handler#

bool sl_zigbee_form_and_join_energy_scan_result_handler (uint8_t channel, int8_t maxRssiValue)

The application must call this function from within its sl_zigbee_energy_scan_result_handler() (on the node) or sl_zigbee_ezsp_energy_scan_result_handler() (on an EZSP host). Default callback implementations are provided in the form-and-join-*-callbacks.c files.

Returns

• true if the library made use of the call.

sl_zigbee_form_and_join_unused_pan_id_found_handler#

bool sl_zigbee_form_and_join_unused_pan_id_found_handler (sl_802154_pan_id_t panId, uint8_t channel)

The application must call this function from within its sl_zigbee_unused_pand_id_found_handler() (on the node) or sl_zigbee_ezsp_energy_scan_result_handler() (on an EZSP host). Default callback implementations are provided in the form-and-join-*-callbacks.c files.

sl_zigbee_form_and_join_tick#

void sl_zigbee_form_and_join_tick (void )

Used by the form and join code on the node to time out a joinable scan after 30 seconds of inactivity. The application must call sl_zigbee_form_and_join_tick() regularly. This function does not exist for the EZSP host library.

sl_zigbee_form_and_join_task_init#

void sl_zigbee_form_and_join_task_init (void )

When processor idling is desired on the SOC, this must be called to properly initialize the form and join library.

sl_zigbee_form_and_join_run_task#

void sl_zigbee_form_and_join_run_task (void )

When processor idling is desired on the SOC, this should be called regularly instead of sl_zigbee_form_and_join_tick()

sl_zigbee_form_and_join_cleanup#

void sl_zigbee_form_and_join_cleanup (sl_status_t status)

When form-and-join state is no longer needed, the application can call this routine to cleanup and free resources. On the SOC platforms this will free the allocated message buffer.

sl_zigbee_af_form_and_join_network_found_cb#

void sl_zigbee_af_form_and_join_network_found_cb (sl_zigbee_zigbee_network_t * networkFound, uint8_t lqi, int8_t rssi)

Network found.

This is called by the form-and-join library to notify the application of the network found after a call to sl_zigbee_scan_for_joinable_network() or sl_zigbee_scan_for_next_joinable_network(). See form-and-join documentation for more information.

sl_zigbee_af_form_and_join_unused_pan_id_found_cb#

void sl_zigbee_af_form_and_join_unused_pan_id_found_cb (sl_802154_pan_id_t panId, uint8_t channel)

Unused Pan ID found.

This function is called when the form-and-join library finds an unused PAN ID that can be used to form a new network on.

NETWORK_STORAGE_SIZE#

#define NETWORK_STORAGE_SIZE

16

Number of bytes required to store relevant info for a saved network.

This constant represents the minimum number of bytes required to store all members of the sli_zigbee_network_info_t struct used in the adapter code. Its value should not be changed unless the underlying adapter code is updated accordingly. Note that this constant's value may be different than sizeof(sli_zigbee_network_info_t) because some compilers pad the structs to align on word boundaries. Thus, the adapter code stores/retrieves these pieces of data individually (to be platform-agnostic) rather than as a struct.

For efficiency's sake, this number should be kept to a power of 2 and not and not exceed 32 (PACKET_BUFFER_SIZE).

NETWORK_STORAGE_SIZE_SHIFT#

#define NETWORK_STORAGE_SIZE_SHIFT

4

Log_base2 of NETWORK_STORAGE_SIZE.

FORM_AND_JOIN_MAX_NETWORKS#

#define FORM_AND_JOIN_MAX_NETWORKS

5

Number of joinable networks that can be remembered during the scan process.

Note for EZSP Host Platforms: In the host implementation of this library, the storage size for the detected networks buffer is controlled by ::EZSP_HOST_FORM_AND_JOIN_BUFFER_SIZE, so that limits the highest value that the host can set for FORM_AND_JOIN_MAX_NETWORKS.