See Network Formation for documentation.

License#

Copyright 2018 Silicon Laboratories Inc. www.silabs.com

The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code.

/***************************************************************************/
#ifndef SILABS_NETWORK_INFORMATION_H
#define SILABS_NETWORK_INFORMATION_H

#include "stack/include/sl_zigbee_types.h"

sl_status_t sl_zigbee_init(void);

void sl_zigbee_tick(void);

sl_status_t sl_zigbee_network_init(sl_zigbee_network_init_struct_t* networkInitStruct);

sl_status_t sl_zigbee_form_network(sl_zigbee_network_parameters_t *parameters);

sl_status_t sl_zigbee_sleepy_to_sleepy_network_start(sl_zigbee_network_parameters_t *parameters, bool initiator);

sl_status_t sl_zigbee_permit_joining(uint8_t duration);

sl_status_t sl_zigbee_join_network(sl_zigbee_node_type_t nodeType,
                                   sl_zigbee_network_parameters_t *parameters);

sl_status_t sl_zigbee_join_network_directly(sl_zigbee_node_type_t localNodeType,
                                            sl_zigbee_beacon_data_t* beacon,
                                            int8_t radioTxPower,
                                            bool clearBeaconsAfterNetworkUp);

sl_status_t sl_zigbee_leave_network(sl_zigbee_leave_network_option_t options);

sl_status_t sl_zigbee_send_zigbee_leave(sl_802154_short_addr_t destination,
                                        sl_zigbee_leave_request_flags_t flags);

sl_status_t sl_zigbee_find_and_rejoin_network(bool haveCurrentNetworkKey,
                                              uint32_t channelMask,
                                              sl_zigbee_rejoin_reason_t reason,
                                              sl_zigbee_node_type_t nodeType);

sl_zigbee_rejoin_reason_t sl_zigbee_get_last_rejoin_reason(void);

sl_status_t sl_zigbee_start_scan(sl_zigbee_network_scan_type_t scanType, uint32_t channelMask, uint8_t duration);

typedef bool (*sl_zigbee_network_found_callback_t)(sl_zigbee_zigbee_network_t *network, sl_zigbee_beacon_data_t *beacon);

typedef bool (*sl_zigbee_scan_complete_callback_t)(uint8_t channel, sl_status_t status);

#ifndef EZSP_HOST

sl_status_t sl_zigbee_survey_beacons(bool useStandardBeacons,
                                     uint32_t channel_mask,
                                     sl_zigbee_network_found_callback_t networkFoundCallback,
                                     sl_zigbee_scan_complete_callback_t scanCompleteCallback);
#endif

sl_status_t sl_zigbee_find_unused_pan_id(uint32_t channelMask, uint8_t duration);

sl_status_t sl_zigbee_stop_scan(void);

void sl_zigbee_scan_complete_handler(uint8_t channel, sl_status_t status);

void sl_zigbee_energy_scan_result_handler(uint8_t channel, int8_t maxRssiValue);

void sl_zigbee_network_found_handler(sl_zigbee_zigbee_network_t *networkFound,
                                     uint8_t lqi,
                                     int8_t rssi);

void sl_zigbee_unused_pan_id_found_handler(sl_802154_pan_id_t panId, uint8_t channel);

void sl_zigbee_orphan_notification_handler(sl_802154_long_addr_t longId);

bool sl_zigbee_is_performing_rejoin(void);

sl_zigbee_leave_reason_t sl_zigbee_get_last_leave_reason(sl_802154_short_addr_t* returnNodeIdThatSentLeave);

bool sl_zigbee_get_permit_joining(void);

sl_status_t sl_zigbee_set_nwk_update_id(uint8_t nwkUpdateId, bool set_when_on_network);

sl_status_t sl_zigbee_set_beacon_jitter_duration(uint8_t beaconJitterDuration);

sl_status_t sl_zigbee_set_tc_rejoins_using_well_known_key_allowed(bool allow);

sl_status_t sl_zigbee_set_tc_rejoins_using_well_known_key_timeout_sec(uint16_t timeout_sec);

bool sl_zigbee_tc_rejoins_using_well_known_key_allowed(void);

/*
 * @brief Extend a joiner's timeout to wait for the network key
 * on the joiner default key timeout is 3 sec, and only values greater equal to 3 sec are accepted.
 *
 * @return SL_STATUS_INVALID_PARAMETER if the argument is invalid, else SL_STATUS_OK.
 */
sl_status_t sl_zigbee_setup_delayed_join(uint8_t networkKeyTimeoutS);

bool sl_zigbee_delayed_join_is_activated(void);

void sl_zigbee_delayed_join_activate(bool activated);

/*
 * @brief Return the value of network key timeout in seconds.
 *
 * @return value of network key timeout in seconds
 */
uint8_t sl_zigbee_get_network_key_timeout(void);

sl_status_t sl_zigbee_reschedule_link_status_msg(void);

void sl_zigbee_set_pending_network_update_pan_id(uint16_t panId);

/*
 * @brief Send an update PAN ID message with the new PanID and can be called
 *  within the context of sl_zigbee_internal_pan_id_conflict_handler,( the handler itself is called by the
 *  stack to report the number of conflict reports exceeds
 *  SL_ZIGBEE_PAN_ID_CONFLICT_REPORT_THRESHOLD within a period of 1 minute )
 *
 *  @param new PAN ID that we want to advertise
 *
 *  @returns true if sending an update was successful, false otherwise
 */
bool sl_zigbee_send_pan_id_update(sl_802154_pan_id_t newPan);

sl_status_t sl_zigbee_clear_stored_beacons(void);

/*
 * @brief Configure the number of beacons to store when issuing active scans
 *  for networks. For classical (Home Automation and Smart Energy) joining, the
 *  most prioritized beacon is chosen to join to. For network steering (Z3.0
 *  joining), all beacons are tried until a successful join.
 *  The existing join and rejoin APIs, such as sl_zigbee_join_network and the several
 *  sl_zigbee_find_and_rejoin_network APIs, set the maximum number of beacons to store
 *  to 1.
 *
 *  @param numBeacons The number of beacons to cache when scanning.
 *
 *  @returns SL_STATUS_INVALID_PARAMETER if numBeacons is greater than
 *   SL_ZIGBEE_MAX_BEACONS_TO_STORE, otherwise SL_STATUS_OK
 */
sl_status_t sl_zigbee_set_num_beacons_to_store(uint8_t numBeacons);

sl_status_t sl_zigbee_get_stored_beacon(uint8_t beacon_number, sl_zigbee_beacon_data_t* beacon);

uint8_t sl_zigbee_get_num_stored_beacons(void);

sl_status_t sl_zigbee_get_beacon_classification_params(sl_zigbee_beacon_classification_params_t* param);

sl_status_t sl_zigbee_set_beacon_classification_params(sl_zigbee_beacon_classification_params_t* param);

#endif // SILABS_NETWORK_INFORMATION_H

Typedefs#

typedef bool(*
sl_zigbee_network_found_callback_t)(sl_zigbee_zigbee_network_t *network, sl_zigbee_beacon_data_t *beacon)

Handle the reception of a beacon.

typedef bool(*
sl_zigbee_scan_complete_callback_t)(uint8_t channel, sl_status_t status)

Handle the conclusion of an active or energy scan.

Functions#

sl_status_t

Initialize the radio and the EmberZNet stack.

void

A periodic tick routine that should be called:

sl_status_t
sl_zigbee_network_init(sl_zigbee_network_init_struct_t *networkInitStruct)

Resume network operation after a reboot.

sl_status_t
sl_zigbee_form_network(sl_zigbee_network_parameters_t *parameters)

Form a new network by becoming the coordinator.

sl_status_t
sl_zigbee_sleepy_to_sleepy_network_start(sl_zigbee_network_parameters_t *parameters, bool initiator)

Form a new Sleepy-to-Sleepy network.

sl_status_t
sl_zigbee_permit_joining(uint8_t duration)

Tell the stack to allow other nodes to join the network with this node as their parent. Joining is initially disabled by default. This function may only be called after the node is part of a network and the stack is up.

sl_status_t
sl_zigbee_join_network(sl_zigbee_node_type_t nodeType, sl_zigbee_network_parameters_t *parameters)

Cause the stack to associate with the network using the specified network parameters. It can take several seconds for the stack to associate with the local network. Do not send messages until a call to the sl_zigbee_stack_status_handler() callback informs you that the stack is up.

sl_status_t
sl_zigbee_join_network_directly(sl_zigbee_node_type_t localNodeType, sl_zigbee_beacon_data_t *beacon, int8_t radioTxPower, bool clearBeaconsAfterNetworkUp)

Cause the stack to associate with the network using the specified network parameters in the beacon parameter. It can take several seconds for the stack to associate with the local network. Do not send messages until a call to the sl_zigbee_stack_status_handler() callback informs you that the stack is up. This function, unlike sl_zigbee_join_network(), does not issue an active scan before joining. Instead, this function will cause the local node to issue a MAC Association Request directly to the specified target node. It is assumed that the beacon parameter is an artifact after issuing an active scan (see sl_zigbee_get_stored_beacon() for more).

sl_status_t
sl_zigbee_leave_network(sl_zigbee_leave_network_option_t options)

Cause the stack to leave the current network. This generates a call to the sl_zigbee_stack_status_handler() callback to indicate that the network is down. The radio will not be used until after a later call to sl_zigbee_form_network() or sl_zigbee_join_network().

sl_status_t
sl_zigbee_send_zigbee_leave(sl_802154_short_addr_t destination, sl_zigbee_leave_request_flags_t flags)

Send a Zigbee NWK leave command to the specified destination.

sl_status_t
sl_zigbee_find_and_rejoin_network(bool haveCurrentNetworkKey, uint32_t channelMask, sl_zigbee_rejoin_reason_t reason, sl_zigbee_node_type_t nodeType)

Call this function when contact with the network has been lost. The most common use case is when an end device can no longer communicate with its parent and wishes to find a new one. Another case is when a device has missed a Network Key update and no longer has the current Network Key.

Return the enumeration for why a previous rejoin.

sl_status_t
sl_zigbee_start_scan(sl_zigbee_network_scan_type_t scanType, uint32_t channelMask, uint8_t duration)

Start a scan. ::SL_STATUS_OK signals that the scan successfully started. Note that although a scan can be initiated while the node is currently joined to a network, the node will generally be unable to communicate with its PAN during the scan period. Take care when performing scans of any significant duration while presently joined to an existing PAN.

sl_status_t
sl_zigbee_survey_beacons(bool useStandardBeacons, uint32_t channel_mask, sl_zigbee_network_found_callback_t networkFoundCallback, sl_zigbee_scan_complete_callback_t scanCompleteCallback)

Kick off a procedure to scan for beacons, filter results, and provide a response ZCL frame including the best eligible parents. This procedure uses the sl_zigbee_start_scan() API.

sl_status_t
sl_zigbee_find_unused_pan_id(uint32_t channelMask, uint8_t duration)

Kick off a procedure to find an unused panId on a low-activity channel that is included in the passed-in channel mask. This procedure uses the sl_zigbee_start_scan() API.

sl_status_t

Terminate a scan in progress.

void
sl_zigbee_scan_complete_handler(uint8_t channel, sl_status_t status)

Indicate the status of the current scan. When the scan has completed, the stack will call this function with status set to ::SL_STATUS_OK. Prior to the scan completing, the stack may call this function with other status values. Non-SL_STATUS_OK status values indicate that the scan failed to start successfully on the channel indicated by the channel parameter. The current scan is ongoing until the stack calls this function with status set to ::SL_STATUS_OK.

void
sl_zigbee_energy_scan_result_handler(uint8_t channel, int8_t maxRssiValue)

Report the maximum RSSI value measured on the channel.

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

Report that a network was found and gives the network parameters used for deciding which network to join.

void
sl_zigbee_unused_pan_id_found_handler(sl_802154_pan_id_t panId, uint8_t channel)

Return an unused panID and channel pair found via the find unused panId scan procedure.

void
sl_zigbee_orphan_notification_handler(sl_802154_long_addr_t longId)

Handle the orphan notification for a Zigbee network.

bool

Indicate whether the stack is in the process of performing a rejoin.

sl_zigbee_get_last_leave_reason(sl_802154_short_addr_t *returnNodeIdThatSentLeave)

Indicate the reason why the device left the network (if any). This also will return the device that sent the leave message, if the leave was due to an over-the-air message.

bool

Indicate the state of the permit joining in the MAC.

sl_status_t
sl_zigbee_set_nwk_update_id(uint8_t nwkUpdateId, bool set_when_on_network)

Set the Network Update ID to the desired value. If this function is called when the node is not part of a network, the desired Network Update ID is saved and will be aplied to the newly formed network when calling sl_zigbee_form_network. If this function is called in case the node is part of a network, the node's Network Update ID will only be updated in case set_even_if_on_network is set to TRUE.

sl_status_t
sl_zigbee_set_beacon_jitter_duration(uint8_t beaconJitterDuration)

Set the duration of a beacon jitter, in the units used by the 15.4 scan parameter (((1 << duration) + 1) * 15 ms), when responding to a beacon request.

sl_status_t

Set the policy decision for Trust Center (insecure) rejoins for devices using the well-known link key. If rejoining using the well-known key is allowed, it is disabled again after sli_zigbee_allow_tc_rejoins_using_well_known_key_timeout_sec seconds.

sl_status_t

Set the timeout in seconds for Trust Center (insecure) rejoins for devices using the well-known link key. If rejoining using the well-known key is allowed, it is disabled again after this timeout.

bool

Get the policy decision for Trust Center (insecure) rejoins for devices using the well-known link key.

sl_status_t
sl_zigbee_setup_delayed_join(uint8_t networkKeyTimeoutS)
bool

Return true if the TC is delaying in sending the network key to newly joining devices. The delay amount is configured via the Delayed Join component.

void

Set the activation state of Delayed Join. If Delayed Join is activated, the TC will delay in sending network key to newly joining devices.

sl_status_t

Reschedule sending link status message, first one being sent immediately.

void

Set the short PAN ID the device will accept in a NLME Network Update command.

bool
sl_zigbee_send_pan_id_update(sl_802154_pan_id_t newPan)
sl_status_t

Clear all cached beacons that have been collected from an active scan.

sl_status_t
sl_status_t
sl_zigbee_get_stored_beacon(uint8_t beacon_number, sl_zigbee_beacon_data_t *beacon)

Fetches the specified beacon in the cache. User should first issue an active scan to populate the beacon cache, then users may call sl_zigbee_get_num_stored_beacons to identify how many beacons have been stored in cache. Following that, users may retrieve beacons based on the number of cached beacons.

uint8_t

Return the number of cached beacons that have been collected from a scan.

sl_status_t
sl_zigbee_get_beacon_classification_params(sl_zigbee_beacon_classification_params_t *param)

Get current beacon classification parameter settings. The parameters related to beacon prioritization, could be all accessed with this function. The values returned in beaconClassificationMask must be decoded by using sl_zigbee_beacon_classification_flags_t.

sl_status_t
sl_zigbee_set_beacon_classification_params(sl_zigbee_beacon_classification_params_t *param)

Set current beacon classification parameters. The parameters related to beacon prioritization, could be all set with this function. The values in beaconClassificationMask must be encoded by using sl_zigbee_beacon_classification_flags_t.

Typedef Documentation#

sl_zigbee_network_found_callback_t#

typedef bool(* sl_zigbee_network_found_callback_t) (sl_zigbee_zigbee_network_t *network, sl_zigbee_beacon_data_t *beacon) )(sl_zigbee_zigbee_network_t *network, sl_zigbee_beacon_data_t *beacon)

Handle the reception of a beacon.

NOTE: SoC only


Definition at line 307 of file stack/include/network-formation.h

sl_zigbee_scan_complete_callback_t#

typedef bool(* sl_zigbee_scan_complete_callback_t) (uint8_t channel, sl_status_t status) )(uint8_t channel, sl_status_t status)

Handle the conclusion of an active or energy scan.

NOTE: SoC only


Definition at line 314 of file stack/include/network-formation.h

Function Documentation#

sl_zigbee_init#

sl_status_t sl_zigbee_init (void )

Initialize the radio and the EmberZNet stack.

Parameters
N/A

Device configuration functions must be called before sl_zigbee_init() is called.

Note

  • The application must check the return value of this function. If the initialization fails, normal messaging functions will not be available. Some failure modes are not fatal, but the application must follow certain procedures to permit recovery. Ignoring the return code will result in unpredictable radio and API behavior. (In particular, problems with association will occur.)

Returns

  • An ::sl_status_t value indicating successful initialization or the reason for failure.


Definition at line 47 of file stack/include/network-formation.h

sl_zigbee_tick#

void sl_zigbee_tick (void )

A periodic tick routine that should be called:

Parameters
N/A
  • in the application's main event loop,

  • as soon as possible after any radio interrupts, and

  • after sl_zigbee_init().


Definition at line 54 of file stack/include/network-formation.h

sl_zigbee_network_init#

sl_status_t sl_zigbee_network_init (sl_zigbee_network_init_struct_t * networkInitStruct)

Resume network operation after a reboot.

Parameters
N/AnetworkInitStruct

Defines whether an orphan scan/rejoin request/or neither is performed during network initialization.

Call this function on boot prior to any network operations. It will initialize the networking system and attempt to resume the previous network identity and configuration. If the node was not previously joined, this routine should still be called.

If the node was previously joined to a network, it will retain its original type (e.g., coordinator, router, end device, and so on.)

::SL_STATUS_NOT_JOINED is returned if the node is not part of a network.

. This function has encapsulated the old behavior of emberNetworkInitExtended().

Returns

  • An ::sl_status_t value that indicates one of the following:

    • successful initialization,

    • ::SL_STATUS_NOT_JOINED if the node is not part of a network, or

    • the reason for failure.


Definition at line 82 of file stack/include/network-formation.h

sl_zigbee_form_network#

sl_status_t sl_zigbee_form_network (sl_zigbee_network_parameters_t * parameters)

Form a new network by becoming the coordinator.

Parameters
N/Aparameters

Specification of the new network.

Note

  • If using security, the application must call sl_zigbee_set_initial_security_state() prior to joining the network. This also applies when a device leaves a network and wants to form another one.

Returns

  • An ::sl_status_t value that indicates either the successful formation of the new network, or the reason that the network formation failed.


Definition at line 95 of file stack/include/network-formation.h

sl_zigbee_sleepy_to_sleepy_network_start#

sl_status_t sl_zigbee_sleepy_to_sleepy_network_start (sl_zigbee_network_parameters_t * parameters, bool initiator)

Form a new Sleepy-to-Sleepy network.

Parameters
N/Aparameters

Specification of the new network.

N/Ainitiator

Indicates if the device is a initiator or a joiner.

Note

  • If using security, the application must call sl_zigbee_set_initial_security_state() prior to joining the network. This also applies when a device leaves a network and wants to form another one.

Returns

  • An ::sl_status_t value that indicates either the successful formation of the new network, or the reason that the network formation failed.


Definition at line 109 of file stack/include/network-formation.h

sl_zigbee_permit_joining#

sl_status_t sl_zigbee_permit_joining (uint8_t duration)

Tell the stack to allow other nodes to join the network with this node as their parent. Joining is initially disabled by default. This function may only be called after the node is part of a network and the stack is up.

Parameters
N/Aduration

A value of 0x00 disables joining. A value of 0xFF enables joining. Any other value enables joining for that number of seconds.


Definition at line 120 of file stack/include/network-formation.h

sl_zigbee_join_network#

sl_status_t sl_zigbee_join_network (sl_zigbee_node_type_t nodeType, sl_zigbee_network_parameters_t * parameters)

Cause the stack to associate with the network using the specified network parameters. It can take several seconds for the stack to associate with the local network. Do not send messages until a call to the sl_zigbee_stack_status_handler() callback informs you that the stack is up.

Parameters
N/AnodeType

Specification of the role that this node will have in the network. This role must not be SL_ZIGBEE_COORDINATOR. To be a coordinator, call sl_zigbee_form_network().

N/Aparameters

Specification of the network with which the node should associate.

Note

  • If using security, the application must call sl_zigbee_set_initial_security_state() prior to joining the network. This also applies when a device leaves a network and wants to join another one.

Returns

  • An ::sl_status_t value that indicates either:

    • that the association process began successfully, or

    • the reason for failure.


Definition at line 142 of file stack/include/network-formation.h

sl_zigbee_join_network_directly#

sl_status_t sl_zigbee_join_network_directly (sl_zigbee_node_type_t localNodeType, sl_zigbee_beacon_data_t * beacon, int8_t radioTxPower, bool clearBeaconsAfterNetworkUp)

Cause the stack to associate with the network using the specified network parameters in the beacon parameter. It can take several seconds for the stack to associate with the local network. Do not send messages until a call to the sl_zigbee_stack_status_handler() callback informs you that the stack is up. This function, unlike sl_zigbee_join_network(), does not issue an active scan before joining. Instead, this function will cause the local node to issue a MAC Association Request directly to the specified target node. It is assumed that the beacon parameter is an artifact after issuing an active scan (see sl_zigbee_get_stored_beacon() for more).

Parameters
N/AlocalNodeType

Specification of the role that this node will have in the network. This role must not be SL_ZIGBEE_COORDINATOR. To be a coordinator, call sl_zigbee_form_network().

N/Abeacon

Specification of the network with which the node should associate.

N/AradioTxPower

The radio transmit power to use, specified in dBm.

N/AclearBeaconsAfterNetworkUp

If true, clear beacons in cache upon join success. Do nothing for join failure.

Note

  • If using security, the application must call sl_zigbee_set_initial_security_state() prior to joining the network. This also applies when a device leaves a network and wants to join another one.

Returns

  • An ::sl_status_t value that indicates either:

    • that the association process began successfully, or

    • the reason for failure.


Definition at line 176 of file stack/include/network-formation.h

sl_zigbee_leave_network#

sl_status_t sl_zigbee_leave_network (sl_zigbee_leave_network_option_t options)

Cause the stack to leave the current network. This generates a call to the sl_zigbee_stack_status_handler() callback to indicate that the network is down. The radio will not be used until after a later call to sl_zigbee_form_network() or sl_zigbee_join_network().

Parameters
N/Aoptions

gives options when leave network. See sl_zigbee_leave_network_option_t enumeration for more information.

Returns

  • An ::sl_status_t value indicating success or reason for failure. A status of ::SL_STATUS_INVALID_STATE indicates that the node is either not joined to a network or is already in the process of leaving.


Definition at line 193 of file stack/include/network-formation.h

sl_zigbee_send_zigbee_leave#

sl_status_t sl_zigbee_send_zigbee_leave (sl_802154_short_addr_t destination, sl_zigbee_leave_request_flags_t flags)

Send a Zigbee NWK leave command to the specified destination.

Parameters
N/Adestination

is the node ID of the device that is being told to leave.

N/Aflags

is a bitmask indicating additional considerations for the leave request. See the sl_zigbee_leave_request_flags_t enumeration for more information. Multiple bits may be set.

Returns

  • An ::sl_status_t value indicating success or reason for failure. A status of ::SL_STATUS_INVALID_STATE indicates that the node not currently joined to the network, or the destination is the local node. To tell the local device to leave, use the sl_zigbee_leave_network() API.


Definition at line 209 of file stack/include/network-formation.h

sl_zigbee_find_and_rejoin_network#

sl_status_t sl_zigbee_find_and_rejoin_network (bool haveCurrentNetworkKey, uint32_t channelMask, sl_zigbee_rejoin_reason_t reason, sl_zigbee_node_type_t nodeType)

Call this function when contact with the network has been lost. The most common use case is when an end device can no longer communicate with its parent and wishes to find a new one. Another case is when a device has missed a Network Key update and no longer has the current Network Key.

Parameters
N/AhaveCurrentNetworkKey

This parameter determines whether the request to rejoin the Network is sent encrypted (true) or unencrypted (false). The application should first try to use encryption. If that fails, the application should call this function again and use no encryption. If the unencrypted rejoin is successful then device will be in the joined but unauthenticated state. The Trust Center will be notified of the rejoin and send an updated Network encrypted using the device's Link Key. Sending the rejoin unencrypted is only supported on networks using Standard Security with link keys (i.e., ZigBee 2006 networks do not support it).

N/AchannelMask

A mask indicating the channels to be scanned. See sl_zigbee_start_scan() for format details.

N/Areason

An enumeration indicating why the rejoin occurred. The stack will set the reason based on the sl_zigbee_rejoin_reason_t. An application should use one of the APP_EVENT rejoin reasons. The stack will never use these. Only if the function return code is SL_STATUS_OK will the rejoin reason be set.

N/AnodeType

An enumeration indicating the device type to rejoin as. For this to be effective the stack only accepts SL_ZIGBEE_END_DEVICE and SL_ZIGBEE_SLEEPY_END_DEVICE. This value could be set to 0 or SL_ZIGBEE_DEVICE_TYPE_UNCHANGED if not needed.

Note that a call to sl_zigbee_poll_for_data() on an end device that has lost contact with its parent will automatically call ::emberRejoinNetwork(true).

The stack will call sl_zigbee_stack_status_handler() to indicate that the network is down, then try to re-establish contact with the network by performing an active scan, choosing a network with matching extended pan ID, and sending a Zigbee network rejoin request. A second call to the sl_zigbee_stack_status_handler() callback indicates either the success or the failure of the attempt. The process takes approximately 150 milliseconds per channel to complete.

This call replaces the ::emberMobileNodeHasMoved() API from EmberZNet 2.x, which used MAC association and consequently took half a second longer to complete.

Returns

  • An ::sl_status_t value indicating success or reason for failure.


Definition at line 258 of file stack/include/network-formation.h

sl_zigbee_get_last_rejoin_reason#

sl_zigbee_rejoin_reason_t sl_zigbee_get_last_rejoin_reason (void )

Return the enumeration for why a previous rejoin.

Parameters
N/A

Definition at line 265 of file stack/include/network-formation.h

sl_zigbee_start_scan#

sl_status_t sl_zigbee_start_scan (sl_zigbee_network_scan_type_t scanType, uint32_t channelMask, uint8_t duration)

Start a scan. ::SL_STATUS_OK signals that the scan successfully started. Note that although a scan can be initiated while the node is currently joined to a network, the node will generally be unable to communicate with its PAN during the scan period. Take care when performing scans of any significant duration while presently joined to an existing PAN.

Parameters
N/AscanType

Indicates the type of scan to be performed. Possible values: SL_ZIGBEE_ENERGY_SCAN, SL_ZIGBEE_ACTIVE_SCAN.

N/AchannelMask

Bits set as 1 indicate that this particular channel should be scanned. Bits set to 0 indicate that this particular channel should not be scanned. For example, a channelMask value of 0x00000001 indicates that only channel 0 should be scanned. Valid channels range from 11 to 26 inclusive. This translates to a channel mask value of 0x07 FF F8 00. As a convenience, a channelMask of 0 is reinterpreted as the mask for the current channel.

N/Aduration

Sets the exponent of the number of scan periods, where a scan period is 960 symbols, and a symbol is 16 microseconds. The scan will occur for ((2^duration) + 1) scan periods. The value of duration must be less than 15. The time corresponding to the first few values is as follows: 0 = 31 msec, 1 = 46 msec, 2 = 77 msec, 3 = 138 msec, 4 = 261 msec, 5 = 507 msec, 6 = 998 msec.

Possible error responses and their meanings:

  • ::SL_STATUS_MAC_SCANNING, already scanning.

  • ::SL_STATUS_BAD_SCAN_DURATION, a duration value that is not 0..14 inclusive is set.

  • ::SL_STATUS_MAC_INCORRECT_SCAN_TYPE, an undefined scanning type is requested;

  • ::SL_STATUS_INVALID_CHANNEL_MASK, the channel mask did not specify any valid channels on the current platform.


Definition at line 301 of file stack/include/network-formation.h

sl_zigbee_survey_beacons#

sl_status_t sl_zigbee_survey_beacons (bool useStandardBeacons, uint32_t channel_mask, sl_zigbee_network_found_callback_t networkFoundCallback, sl_zigbee_scan_complete_callback_t scanCompleteCallback)

Kick off a procedure to scan for beacons, filter results, and provide a response ZCL frame including the best eligible parents. This procedure uses the sl_zigbee_start_scan() API.

Parameters
N/AuseStandardBeacons

If true, the surveyBeacon procedure will use standard beacons. If false, the surveyBeacon procedure will use enhanced beacons.

N/Achannel_mask

The function pointer that is called after the reception of a beacon.

N/AnetworkFoundCallback

The function pointer that is called after the beacon collection phase of the surveyBeacon procedure is over.

N/AscanCompleteCallback

NOTE: SoC only


Definition at line 334 of file stack/include/network-formation.h

sl_zigbee_find_unused_pan_id#

sl_status_t sl_zigbee_find_unused_pan_id (uint32_t channelMask, uint8_t duration)

Kick off a procedure to find an unused panId on a low-activity channel that is included in the passed-in channel mask. This procedure uses the sl_zigbee_start_scan() API.

Parameters
N/AchannelMask

The set of channels that will be scanned to find an available panId.

N/Aduration

The length of time that will be spent scanning for an available panId.


Definition at line 350 of file stack/include/network-formation.h

sl_zigbee_stop_scan#

sl_status_t sl_zigbee_stop_scan (void )

Terminate a scan in progress.

Parameters
N/A

Returns

  • Returns ::SL_STATUS_OK if successful.


Definition at line 356 of file stack/include/network-formation.h

sl_zigbee_scan_complete_handler#

void sl_zigbee_scan_complete_handler (uint8_t channel, sl_status_t status)

Indicate the status of the current scan. When the scan has completed, the stack will call this function with status set to ::SL_STATUS_OK. Prior to the scan completing, the stack may call this function with other status values. Non-SL_STATUS_OK status values indicate that the scan failed to start successfully on the channel indicated by the channel parameter. The current scan is ongoing until the stack calls this function with status set to ::SL_STATUS_OK.

Parameters
N/Achannel

The channel on which the current error occurred. Undefined for the case of ::SL_STATUS_OK.

N/Astatus

The error condition that occurred on the current channel. Value will be ::SL_STATUS_OK when the scan has completed.


Definition at line 372 of file stack/include/network-formation.h

sl_zigbee_energy_scan_result_handler#

void sl_zigbee_energy_scan_result_handler (uint8_t channel, int8_t maxRssiValue)

Report the maximum RSSI value measured on the channel.

Parameters
N/Achannel

The 802.15.4 channel number on which the RSSI value. was measured.

N/AmaxRssiValue

The maximum RSSI value measured (in units of dBm).


Definition at line 382 of file stack/include/network-formation.h

sl_zigbee_network_found_handler#

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

Report that a network was found and gives the network parameters used for deciding which network to join.

Parameters
N/AnetworkFound

A pointer to a sl_zigbee_zigbee_network_t structure that contains the discovered network and its associated parameters.

N/Alqi

The link quality indication of the network found.

N/Arssi

The received signal strength indication of the network found.


Definition at line 394 of file stack/include/network-formation.h

sl_zigbee_unused_pan_id_found_handler#

void sl_zigbee_unused_pan_id_found_handler (sl_802154_pan_id_t panId, uint8_t channel)

Return an unused panID and channel pair found via the find unused panId scan procedure.

Parameters
N/ApanId

The unused panID.

N/Achannel

The channel which the unused panId was found on.


Definition at line 405 of file stack/include/network-formation.h

sl_zigbee_orphan_notification_handler#

void sl_zigbee_orphan_notification_handler (sl_802154_long_addr_t longId)

Handle the orphan notification for a Zigbee network.

Parameters
N/AlongId

The long address of the orphaned device.

This function is called when an orphan notification is received for a Zigbee network. The function takes the long address of the orphaned device as a parameter.


Definition at line 415 of file stack/include/network-formation.h

sl_zigbee_is_performing_rejoin#

bool sl_zigbee_is_performing_rejoin (void )

Indicate whether the stack is in the process of performing a rejoin.

Parameters
N/A

Returns

  • Returns true if the device is in the process of performing a rejoin. Returns false otherwise.


Definition at line 423 of file stack/include/network-formation.h

sl_zigbee_get_last_leave_reason#

sl_zigbee_leave_reason_t sl_zigbee_get_last_leave_reason (sl_802154_short_addr_t * returnNodeIdThatSentLeave)

Indicate the reason why the device left the network (if any). This also will return the device that sent the leave message, if the leave was due to an over-the-air message.

Parameters
N/AreturnNodeIdThatSentLeave

If returnNodeIdThatSentLeave is a non-NULL pointer, the node ID of the device that sent the leave message will be written to the value indicated by the pointer. If the leave was not due to an over-the-air message (but an internal API call instead), SL_ZIGBEE_UNKNOWN_NODE_ID is returned.

Returns

  • Returns sl_zigbee_leave_reason_t enumeration, or SL_ZIGBEE_LEAVE_REASON_NONE if the device has not left the network.


Definition at line 440 of file stack/include/network-formation.h

sl_zigbee_get_permit_joining#

bool sl_zigbee_get_permit_joining (void )

Indicate the state of the permit joining in the MAC.

Parameters
N/A

Returns

  • Returns true if permit, else returns false.


Definition at line 446 of file stack/include/network-formation.h

sl_zigbee_set_nwk_update_id#

sl_status_t sl_zigbee_set_nwk_update_id (uint8_t nwkUpdateId, bool set_when_on_network)

Set the Network Update ID to the desired value. If this function is called when the node is not part of a network, the desired Network Update ID is saved and will be aplied to the newly formed network when calling sl_zigbee_form_network. If this function is called in case the node is part of a network, the node's Network Update ID will only be updated in case set_even_if_on_network is set to TRUE.

Parameters
N/AnwkUpdateId

The Network Update ID.

N/Aset_when_on_network

set to TRUE if Network Update ID is to be applied even when on network.

Note

  • When on a network, the Network Update ID should not normally be changed, as it is used by the stack to track changes in the network. Unless specifically required set_even_if_on_network should always be set to FALSE

Returns

  • SL_STATUS_OK if update was successful, else SL_STATUS_INVALID_STATE.


Definition at line 463 of file stack/include/network-formation.h

sl_zigbee_set_beacon_jitter_duration#

sl_status_t sl_zigbee_set_beacon_jitter_duration (uint8_t beaconJitterDuration)

Set the duration of a beacon jitter, in the units used by the 15.4 scan parameter (((1 << duration) + 1) * 15 ms), when responding to a beacon request.

Parameters
N/AbeaconJitterDuration

Note

  • Because the recommended scan duration of a joining device is 3 for 2.4 GHz devices, any value passed in to this function greater than 3 will be rejected.

Returns

  • SL_STATUS_INVALID_PARAMETER if the argument is invalid, else SL_STATUS_OK.


Definition at line 475 of file stack/include/network-formation.h

sl_zigbee_set_tc_rejoins_using_well_known_key_allowed#

sl_status_t sl_zigbee_set_tc_rejoins_using_well_known_key_allowed (bool allow)

Set the policy decision for Trust Center (insecure) rejoins for devices using the well-known link key. If rejoining using the well-known key is allowed, it is disabled again after sli_zigbee_allow_tc_rejoins_using_well_known_key_timeout_sec seconds.

Parameters
N/Aallow

Returns

  • A valid error code.


Definition at line 485 of file stack/include/network-formation.h

sl_zigbee_set_tc_rejoins_using_well_known_key_timeout_sec#

sl_status_t sl_zigbee_set_tc_rejoins_using_well_known_key_timeout_sec (uint16_t timeout_sec)

Set the timeout in seconds for Trust Center (insecure) rejoins for devices using the well-known link key. If rejoining using the well-known key is allowed, it is disabled again after this timeout.

Parameters
N/Atimeout_sec

Returns

  • A valid error code.


Definition at line 494 of file stack/include/network-formation.h

sl_zigbee_tc_rejoins_using_well_known_key_allowed#

bool sl_zigbee_tc_rejoins_using_well_known_key_allowed (void )

Get the policy decision for Trust Center (insecure) rejoins for devices using the well-known link key.

Parameters
N/A

Returns

  • Return true if allowed, else false.


Definition at line 502 of file stack/include/network-formation.h

sl_zigbee_setup_delayed_join#

sl_status_t sl_zigbee_setup_delayed_join (uint8_t networkKeyTimeoutS)
Parameters
N/AnetworkKeyTimeoutS

Definition at line 510 of file stack/include/network-formation.h

sl_zigbee_delayed_join_is_activated#

bool sl_zigbee_delayed_join_is_activated (void )

Return true if the TC is delaying in sending the network key to newly joining devices. The delay amount is configured via the Delayed Join component.

Parameters
N/A

Definition at line 515 of file stack/include/network-formation.h

sl_zigbee_delayed_join_activate#

void sl_zigbee_delayed_join_activate (bool activated)

Set the activation state of Delayed Join. If Delayed Join is activated, the TC will delay in sending network key to newly joining devices.

Parameters
N/Aactivated

Definition at line 520 of file stack/include/network-formation.h

sl_zigbee_get_network_key_timeout#

uint8_t sl_zigbee_get_network_key_timeout (void )
Parameters
N/A

Definition at line 527 of file stack/include/network-formation.h

sl_zigbee_reschedule_link_status_msg#

sl_status_t sl_zigbee_reschedule_link_status_msg (void )

Reschedule sending link status message, first one being sent immediately.

Parameters
N/A

Returns

  • A valid error code.


Definition at line 534 of file stack/include/network-formation.h

sl_zigbee_set_pending_network_update_pan_id#

void sl_zigbee_set_pending_network_update_pan_id (uint16_t panId)

Set the short PAN ID the device will accept in a NLME Network Update command.

Parameters
N/ApanId

A pending network update short PAN ID.

If a NLME Network Update command is received by the device specifying a short PAN ID that does not match with the given PAN ID, then the NLME Network Update message will be ignored by the device. A value of 0xFFFF indicates that any short PAN ID received in a NLME Network Update command will be accepted which is also the default value set by the stack.


Definition at line 546 of file stack/include/network-formation.h

sl_zigbee_send_pan_id_update#

bool sl_zigbee_send_pan_id_update (sl_802154_pan_id_t newPan)
Parameters
N/AnewPan

Definition at line 558 of file stack/include/network-formation.h

sl_zigbee_clear_stored_beacons#

sl_status_t sl_zigbee_clear_stored_beacons (void )

Clear all cached beacons that have been collected from an active scan.

Parameters
N/A

Returns

  • An appropriate error code.


Definition at line 564 of file stack/include/network-formation.h

sl_zigbee_set_num_beacons_to_store#

sl_status_t sl_zigbee_set_num_beacons_to_store (uint8_t numBeacons)
Parameters
N/AnumBeacons

Definition at line 580 of file stack/include/network-formation.h

sl_zigbee_get_stored_beacon#

sl_status_t sl_zigbee_get_stored_beacon (uint8_t beacon_number, sl_zigbee_beacon_data_t * beacon)

Fetches the specified beacon in the cache. User should first issue an active scan to populate the beacon cache, then users may call sl_zigbee_get_num_stored_beacons to identify how many beacons have been stored in cache. Following that, users may retrieve beacons based on the number of cached beacons.

Parameters
N/Abeacon_number

The beacon index to fetch. Valid values range from 0 to sl_zigbee_get_num_stored_beacons-1.

N/Abeacon

The beacon to populate upon success.

Returns

  • An appropriate sl_status_t status code.


Definition at line 598 of file stack/include/network-formation.h

sl_zigbee_get_num_stored_beacons#

uint8_t sl_zigbee_get_num_stored_beacons (void )

Return the number of cached beacons that have been collected from a scan.

Parameters
N/A

Definition at line 602 of file stack/include/network-formation.h

sl_zigbee_get_beacon_classification_params#

sl_status_t sl_zigbee_get_beacon_classification_params (sl_zigbee_beacon_classification_params_t * param)

Get current beacon classification parameter settings. The parameters related to beacon prioritization, could be all accessed with this function. The values returned in beaconClassificationMask must be decoded by using sl_zigbee_beacon_classification_flags_t.

Parameters
N/Aparam

could be used to get all possible priorities, e.g. (beaconClassificationMask | TC_CONNECTIVITY)

Returns

  • SL_STATUS_OK if successful, and error code otherwise.


Definition at line 615 of file stack/include/network-formation.h

sl_zigbee_set_beacon_classification_params#

sl_status_t sl_zigbee_set_beacon_classification_params (sl_zigbee_beacon_classification_params_t * param)

Set current beacon classification parameters. The parameters related to beacon prioritization, could be all set with this function. The values in beaconClassificationMask must be encoded by using sl_zigbee_beacon_classification_flags_t.

Parameters
N/Aparam

could be used to set all possible priorities, e.g. beaconClassificationMask &= ~TC_CONNECTIVITY

Returns

  • SL_STATUS_OK if successful, and error code otherwise.


Definition at line 626 of file stack/include/network-formation.h