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

EmberStatus emberInit(void);

void emberTick(void);

EmberStatus emberNetworkInit(EmberNetworkInitStruct* networkInitStruct);

EmberStatus emberFormNetwork(EmberNetworkParameters *parameters);

EmberStatus emberWireFreeNetworkStart(EmberNetworkParameters *parameters, bool initiator);

EmberStatus emberPermitJoining(uint8_t duration);

EmberStatus emberJoinNetwork(EmberNodeType nodeType,
                             EmberNetworkParameters *parameters);

EmberStatus emberJoinNetworkDirectly(EmberNodeType localNodeType,
                                     EmberBeaconData* beacon,
                                     int8_t radioTxPower,
                                     bool clearBeaconsAfterNetworkUp);

EmberStatus emberLeaveNetwork(void);

EmberStatus emberSendZigbeeLeave(EmberNodeId destination,
                                 EmberLeaveRequestFlags flags);

EmberStatus emberFindAndRejoinNetworkWithReason(bool haveCurrentNetworkKey,
                                                uint32_t channelMask,
                                                EmberRejoinReason reason);

EmberStatus emberFindAndRejoinNetwork(bool haveCurrentNetworkKey,
                                      uint32_t channelMask);

EmberStatus emberFindAndRejoinNetworkWithNodeType(bool haveCurrentNetworkKey,
                                                  uint32_t channelMask,
                                                  EmberNodeType nodeType);

EmberRejoinReason emberGetLastRejoinReason(void);

#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberStatus emberRejoinNetwork(bool haveCurrentNetworkKey);

#else
#define emberRejoinNetwork(haveKey) emberFindAndRejoinNetwork((haveKey), 0)
#endif

EmberStatus emberStartScan(EmberNetworkScanType scanType, uint32_t channelMask, uint8_t duration);

typedef bool (*EmberNetworkFoundCallback)(EmberZigbeeNetwork *network, uint8_t rssi, int8_t lqi, uint16_t senderNodeId, uint8_t parentPriority);

typedef bool (*EmberScanCompleteCallback)(uint8_t channel, EmberStatus status);

#ifndef EZSP_HOST

EmberStatus emberSurveyBeacons(bool useStandardBeacons,
                               EmberNetworkFoundCallback networkFoundCallback,
                               EmberScanCompleteCallback scanCompleteCallback);
#endif

EmberStatus emberFindUnusedPanId(uint32_t channelMask, uint8_t duration);

EmberStatus emberStopScan(void);

bool emberIsRadioOffScanActivated(void);

void emberScanCompleteHandler(uint8_t channel, EmberStatus status);

void emberEnergyScanResultHandler(uint8_t channel, int8_t maxRssiValue);

void emberNetworkFoundHandler(EmberZigbeeNetwork *networkFound,
                              uint8_t lqi,
                              int8_t rssi);

void emberUnusedPanIdFoundHandler(EmberPanId panId, uint8_t channel);

bool emberStackIsPerformingRejoin(void);

EmberLeaveReason emberGetLastLeaveReason(EmberNodeId* returnNodeIdThatSentLeave);

bool emberGetPermitJoining(void);

EmberStatus emberSetNwkUpdateId(uint8_t nwkUpdateId);

EmberStatus emberSetBeaconJitterDuration(uint8_t beaconJitterDuration);

void emberSetTcRejoinsUsingWellKnownKeyAllowed(bool allow);

bool emberTcRejoinsUsingWellKnownKeyAllowed(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 EMBER_BAD_ARGUMENT if the argument is invalid, else EMBER_SUCCESS.
 */
EmberStatus emberSetupDelayedJoin(uint8_t networkKeyTimeoutS);

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

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

void emberRescheduleLinkStatusMsg(void);

void emberSetMinRSSI(int8_t minRSSI);

void emberSetParentClassificationEnabled(bool enabled);

bool emberGetParentClassificationEnabled(void);

void emberSetPendingNetworkUpdatePanId(uint16_t panId);

/*
 * @brief Get the last LQI/RSSI values for neighbors in a specific debug mode.
 *
 *  @param nodeId id of the node for which we are looking for LQI and RSSI
 *
 *  @returns EMBER_SUCESS if the specific defines exist, otherwise returns EMBER_FATAL_ERR
 *  also returns the last LQI and RSSI for the specified node, if they exist
 */
EmberStatus emberGetNeighborLastLqiRssi(EmberNodeId nodeId, uint8_t *lqi, int8_t *rssi);

/*
 * @brief Send an update PAN ID message with the new PanID and can be called
 *  within the context of emberPanIdConflictHandler,( the handler itself is called by the
 *  stack to report the number of conflict reports exceeds
 *  EMBER_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 emberSendPanIdUpdate(EmberPanId newPan);

void emberClearStoredBeacons(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 emberJoinNetwork and the several
 *  emberFindAndRejoinNetwork APIs, set the maximum number of beacons to store
 *  to 1.
 *
 *  @param numBeacons The number of beacons to cache when scanning.
 *
 *  @returns EMBER_BAD_ARGUMENT if numBeacons is greater than
 *   EMBER_MAX_BEACONS_TO_STORE, otherwise EMBER_SUCCESS
 */
EmberStatus emberSetNumBeaconsToStore(uint8_t numBeacons);

/*
 * @brief Return the first beacon in the cache. Beacons are stored in cache
 *  after issuing an active scan.
 *
 *  @param beaconIterator The iterator to use when returning the first beacon.
 *   This argument must not be NULL.
 *
 *  @returns EMBER_SUCCESS if first beacon found, EMBER_BAD_ARGUMENT if input
 *   parameters are invalid, EMBER_INVALID_CALL if no beacons stored,
 *   EMBER_ERR_FATAL if no first beacon found.
 */
EmberStatus emberGetFirstBeacon(EmberBeaconIterator* beaconIterator);

/*
 * @brief Return the next beacon in the cache. Beacons are stored in cache
 *  after issuing an active scan.
 *
 *  @param beacon The next beacon retrieved. It is assumed that
 *   ::emberGetFirstBeacon has been called first. This argument must not be
 *   NULL.
 *
 *  @returns EMBER_SUCCESS if next beacon found, EMBER_BAD_ARGUMENT if input
 *   parameters are invalid, EMBER_ERR_FATAL if no next beacon found.
 */
EmberStatus emberGetNextBeacon(EmberBeaconData* beacon);

uint8_t emberGetNumStoredBeacons(void);

#endif // SILABS_NETWORK_INFORMATION_H

Typedefs#

typedef bool(*
EmberNetworkFoundCallback)(EmberZigbeeNetwork *network, uint8_t rssi, int8_t lqi, uint16_t senderNodeId, uint8_t parentPriority)

Handle the reception of a beacon.

typedef bool(*
EmberScanCompleteCallback)(uint8_t channel, EmberStatus status)

Handle the conclusion of an active or energy scan.

Functions#

emberInit(void)

Initialize the radio and the EmberZNet stack.

void
emberTick(void)

A periodic tick routine that should be called:

emberNetworkInit(EmberNetworkInitStruct *networkInitStruct)

Resume network operation after a reboot.

emberFormNetwork(EmberNetworkParameters *parameters)

Form a new network by becoming the coordinator.

emberWireFreeNetworkStart(EmberNetworkParameters *parameters, bool initiator)

Form a new Wirefree network.

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

emberJoinNetwork(EmberNodeType nodeType, EmberNetworkParameters *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 emberStackStatusHandler() callback informs you that the stack is up.

emberJoinNetworkDirectly(EmberNodeType localNodeType, EmberBeaconData *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 emberStackStatusHandler() callback informs you that the stack is up. This function, unlike emberJoinNetwork(), 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 ::emberGetBestBeacon() and emberGetNextBeacon() for more).

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

emberSendZigbeeLeave(EmberNodeId destination, EmberLeaveRequestFlags flags)

Send a Zigbee NWK leave command to the specified destination.

emberFindAndRejoinNetworkWithReason(bool haveCurrentNetworkKey, uint32_t channelMask, EmberRejoinReason reason)

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.

emberFindAndRejoinNetwork(bool haveCurrentNetworkKey, uint32_t channelMask)

This call is the same emberFindAndRejoinNetworkWithReason(). However, the reason is assumed to be ::EMBER_REJOIN_REASON_APP_EVENT_1.

emberFindAndRejoinNetworkWithNodeType(bool haveCurrentNetworkKey, uint32_t channelMask, EmberNodeType nodeType)

Attempt to rejoin the network with a different device type.

Return the enumeration for why a previous rejoin.

emberRejoinNetwork(bool haveCurrentNetworkKey)

A convenience function which calls emberFindAndRejoinNetwork() with a channel mask value for scanning only the current channel. Included for back-compatibility.

emberStartScan(EmberNetworkScanType scanType, uint32_t channelMask, uint8_t duration)

Start a scan. EMBER_SUCCESS 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.

emberSurveyBeacons(bool useStandardBeacons, EmberNetworkFoundCallback networkFoundCallback, EmberScanCompleteCallback 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 emberStartScan() API.

emberFindUnusedPanId(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 emberStartScan() API.

Terminate a scan in progress.

bool

Check if radio_off scan mode is activated and radio has shut down as a result.

void
emberScanCompleteHandler(uint8_t channel, EmberStatus status)

Indicate the status of the current scan. When the scan has completed, the stack will call this function with status set to EMBER_SUCCESS. Prior to the scan completing, the stack may call this function with other status values. Non-EMBER_SUCCESS 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 EMBER_SUCCESS.

void
emberEnergyScanResultHandler(uint8_t channel, int8_t maxRssiValue)

Report the maximum RSSI value measured on the channel.

void
emberNetworkFoundHandler(EmberZigbeeNetwork *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
emberUnusedPanIdFoundHandler(EmberPanId panId, uint8_t channel)

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

bool

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

emberGetLastLeaveReason(EmberNodeId *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.

emberSetNwkUpdateId(uint8_t nwkUpdateId)

Set the Network Update ID to the desired value. The Network Update ID value cannot be manually changed after a network is joined, so this function must be called before calling emberFormNetwork.

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

void

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

bool

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

emberSetupDelayedJoin(uint8_t networkKeyTimeoutS)
void
emberSetMinRSSI(int8_t minRSSI)

Configure the minimum RSSI for receiving packets.

void

Enable/disable the parent classification algorithm on the stack side. Parent classification considers whether a received beacon indicates trust center connectivity and long uptime on the network. This is left here for backward compatibility. You can achieve the same with emberSetBeaconClassificationParams.

bool

Get the enable state the parent classification algorithm. This is left here for backward compatibility. You can achieve the same with emberGetBeaconClassificationParams.

void

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

emberGetNeighborLastLqiRssi(EmberNodeId nodeId, uint8_t *lqi, int8_t *rssi)
bool
emberSendPanIdUpdate(EmberPanId newPan)
void

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

emberGetFirstBeacon(EmberBeaconIterator *beaconIterator)
emberGetNextBeacon(EmberBeaconData *beacon)
uint8_t

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

Typedef Documentation#

EmberNetworkFoundCallback#

typedef bool(* EmberNetworkFoundCallback) (EmberZigbeeNetwork *network, uint8_t rssi, int8_t lqi, uint16_t senderNodeId, uint8_t parentPriority) )(EmberZigbeeNetwork *network, uint8_t rssi, int8_t lqi, uint16_t senderNodeId, uint8_t parentPriority)

Handle the reception of a beacon.

NOTE: SoC only


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

EmberScanCompleteCallback#

typedef bool(* EmberScanCompleteCallback) (uint8_t channel, EmberStatus status) )(uint8_t channel, EmberStatus status)

Handle the conclusion of an active or energy scan.

NOTE: SoC only


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

Function Documentation#

emberInit#

EmberStatus emberInit (void )

Initialize the radio and the EmberZNet stack.

Parameters
N/A

Device configuration functions must be called before emberInit() 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 EmberStatus value indicating successful initialization or the reason for failure.


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

emberTick#

void emberTick (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 emberInit().


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

emberNetworkInit#

EmberStatus emberNetworkInit (EmberNetworkInitStruct * 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.)

EMBER_NOT_JOINED is returned if the node is not part of a network.

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

Returns

  • An EmberStatus value that indicates one of the following:

    • successful initialization,

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

    • the reason for failure.


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

emberFormNetwork#

EmberStatus emberFormNetwork (EmberNetworkParameters * 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 emberSetInitialSecurityState() prior to joining the network. This also applies when a device leaves a network and wants to form another one.

Returns

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


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

emberWireFreeNetworkStart#

EmberStatus emberWireFreeNetworkStart (EmberNetworkParameters * parameters, bool initiator)

Form a new Wirefree 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 emberSetInitialSecurityState() prior to joining the network. This also applies when a device leaves a network and wants to form another one.

Returns

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


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

emberPermitJoining#

EmberStatus emberPermitJoining (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 115 of file stack/include/network-formation.h

emberJoinNetwork#

EmberStatus emberJoinNetwork (EmberNodeType nodeType, EmberNetworkParameters * 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 emberStackStatusHandler() 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 EMBER_COORDINATOR. To be a coordinator, call emberFormNetwork().

N/Aparameters

Specification of the network with which the node should associate.

Note

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

Returns

  • An EmberStatus value that indicates either:

    • that the association process began successfully, or

    • the reason for failure.


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

emberJoinNetworkDirectly#

EmberStatus emberJoinNetworkDirectly (EmberNodeType localNodeType, EmberBeaconData * 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 emberStackStatusHandler() callback informs you that the stack is up. This function, unlike emberJoinNetwork(), 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 ::emberGetBestBeacon() and emberGetNextBeacon() for more).

Parameters
N/AlocalNodeType

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

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 emberSetInitialSecurityState() prior to joining the network. This also applies when a device leaves a network and wants to join another one.

Returns

  • An EmberStatus value that indicates either:

    • that the association process began successfully, or

    • the reason for failure.


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

emberLeaveNetwork#

EmberStatus emberLeaveNetwork (void )

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

Parameters
N/A

Returns

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


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

emberSendZigbeeLeave#

EmberStatus emberSendZigbeeLeave (EmberNodeId destination, EmberLeaveRequestFlags 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 EmberLeaveRequestFlags enumeration for more information. Multiple bits may be set.

Returns

  • An EmberStatus value indicating success or reason for failure. A status of EMBER_INVALID_CALL 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 emberLeaveNetwork() API.


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

emberFindAndRejoinNetworkWithReason#

EmberStatus emberFindAndRejoinNetworkWithReason (bool haveCurrentNetworkKey, uint32_t channelMask, EmberRejoinReason reason)

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 emberStartScan() for format details.

N/Areason

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

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

The stack will call emberStackStatusHandler() 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 emberStackStatusHandler() 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 EmberStatus value indicating success or reason for failure.


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

emberFindAndRejoinNetwork#

EmberStatus emberFindAndRejoinNetwork (bool haveCurrentNetworkKey, uint32_t channelMask)

This call is the same emberFindAndRejoinNetworkWithReason(). However, the reason is assumed to be ::EMBER_REJOIN_REASON_APP_EVENT_1.

Parameters
N/AhaveCurrentNetworkKey
N/AchannelMask

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

emberFindAndRejoinNetworkWithNodeType#

EmberStatus emberFindAndRejoinNetworkWithNodeType (bool haveCurrentNetworkKey, uint32_t channelMask, EmberNodeType nodeType)

Attempt to rejoin the network with a different device type.

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 emberStartScan() for format details.

N/AnodeType

An enumeration indicating the device type to rejoin as. The stack only accepts EMBER_END_DEVICE and EMBER_SLEEPY_END_DEVICE.


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

emberGetLastRejoinReason#

EmberRejoinReason emberGetLastRejoinReason (void )

Return the enumeration for why a previous rejoin.

Parameters
N/A

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

emberRejoinNetwork#

EmberStatus emberRejoinNetwork (bool haveCurrentNetworkKey)

A convenience function which calls emberFindAndRejoinNetwork() with a channel mask value for scanning only the current channel. Included for back-compatibility.

Parameters
N/AhaveCurrentNetworkKey

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

emberStartScan#

EmberStatus emberStartScan (EmberNetworkScanType scanType, uint32_t channelMask, uint8_t duration)

Start a scan. EMBER_SUCCESS 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: EMBER_ENERGY_SCAN, EMBER_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:


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

emberSurveyBeacons#

EmberStatus emberSurveyBeacons (bool useStandardBeacons, EmberNetworkFoundCallback networkFoundCallback, EmberScanCompleteCallback 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 emberStartScan() API.

Parameters
N/AuseStandardBeacons

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

N/AnetworkFoundCallback

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

N/AscanCompleteCallback

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

NOTE: SoC only


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

emberFindUnusedPanId#

EmberStatus emberFindUnusedPanId (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 emberStartScan() 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 375 of file stack/include/network-formation.h

emberStopScan#

EmberStatus emberStopScan (void )

Terminate a scan in progress.

Parameters
N/A

Returns


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

emberIsRadioOffScanActivated#

bool emberIsRadioOffScanActivated (void )

Check if radio_off scan mode is activated and radio has shut down as a result.

Parameters
N/A

Returns

  • Returns ::true if radio has shut down successfully. There is no EZSP/NCP implementation for this.


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

emberScanCompleteHandler#

void emberScanCompleteHandler (uint8_t channel, EmberStatus status)

Indicate the status of the current scan. When the scan has completed, the stack will call this function with status set to EMBER_SUCCESS. Prior to the scan completing, the stack may call this function with other status values. Non-EMBER_SUCCESS 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 EMBER_SUCCESS.

Parameters
N/Achannel

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

N/Astatus

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


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

emberEnergyScanResultHandler#

void emberEnergyScanResultHandler (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 413 of file stack/include/network-formation.h

emberNetworkFoundHandler#

void emberNetworkFoundHandler (EmberZigbeeNetwork * 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 EmberZigbeeNetwork 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 425 of file stack/include/network-formation.h

emberUnusedPanIdFoundHandler#

void emberUnusedPanIdFoundHandler (EmberPanId 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 436 of file stack/include/network-formation.h

emberStackIsPerformingRejoin#

bool emberStackIsPerformingRejoin (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 444 of file stack/include/network-formation.h

emberGetLastLeaveReason#

EmberLeaveReason emberGetLastLeaveReason (EmberNodeId * 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), EMBER_UNKNOWN_NODE_ID is returned.

Returns

  • Returns EmberLeaveReason enumeration, or EMBER_LEAVE_REASON_NONE if the device has not left the network.


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

emberGetPermitJoining#

bool emberGetPermitJoining (void )

Indicate the state of the permit joining in the MAC.

Parameters
N/A

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

emberSetNwkUpdateId#

EmberStatus emberSetNwkUpdateId (uint8_t nwkUpdateId)

Set the Network Update ID to the desired value. The Network Update ID value cannot be manually changed after a network is joined, so this function must be called before calling emberFormNetwork.

Parameters
N/AnwkUpdateId

Note

  • This Network Update ID should not normally be changed, as it is used by the stack to track changes in the network.

Returns

  • EMBER_SUCCESS if called when not on network, else EMBER_INVALID_CALL.


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

emberSetBeaconJitterDuration#

EmberStatus emberSetBeaconJitterDuration (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

  • EMBER_BAD_ARGUMENT if the argument is invalid, else EMBER_SUCCESS.


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

emberSetTcRejoinsUsingWellKnownKeyAllowed#

void emberSetTcRejoinsUsingWellKnownKeyAllowed (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 emAllowTcRejoinsUsingWellKnownKeyTimeoutSec seconds.

Parameters
N/Aallow

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

emberTcRejoinsUsingWellKnownKeyAllowed#

bool emberTcRejoinsUsingWellKnownKeyAllowed (void )

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

Parameters
N/A

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

emberSetupDelayedJoin#

EmberStatus emberSetupDelayedJoin (uint8_t networkKeyTimeoutS)
Parameters
N/AnetworkKeyTimeoutS

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

emberGetNetworkKeyTimeout#

uint8_t emberGetNetworkKeyTimeout (void )
Parameters
N/A

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

emberRescheduleLinkStatusMsg#

void emberRescheduleLinkStatusMsg (void )
Parameters
N/A

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

emberSetMinRSSI#

void emberSetMinRSSI (int8_t minRSSI)

Configure the minimum RSSI for receiving packets.

Parameters
N/AminRSSI

The minimum RSSI is used to classify good/bad parent signal strengths. Any packet in the range of minimum RSSI + 30 db is considered to be "bad". By default, this value is set to -100. Currently, there is no EZSP support. This is left here for backward compatibility. You can achieve the same EZSP applicable setting with emberSetBeaconClassificationParams


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

emberSetParentClassificationEnabled#

void emberSetParentClassificationEnabled (bool enabled)

Enable/disable the parent classification algorithm on the stack side. Parent classification considers whether a received beacon indicates trust center connectivity and long uptime on the network. This is left here for backward compatibility. You can achieve the same with emberSetBeaconClassificationParams.

Parameters
N/Aenabled

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

emberGetParentClassificationEnabled#

bool emberGetParentClassificationEnabled (void )

Get the enable state the parent classification algorithm. This is left here for backward compatibility. You can achieve the same with emberGetBeaconClassificationParams.

Parameters
N/A

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

emberSetPendingNetworkUpdatePanId#

void emberSetPendingNetworkUpdatePanId (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 559 of file stack/include/network-formation.h

emberGetNeighborLastLqiRssi#

EmberStatus emberGetNeighborLastLqiRssi (EmberNodeId nodeId, uint8_t * lqi, int8_t * rssi)
Parameters
N/AnodeId
N/Alqi
N/Arssi

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

emberSendPanIdUpdate#

bool emberSendPanIdUpdate (EmberPanId newPan)
Parameters
N/AnewPan

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

emberClearStoredBeacons#

void emberClearStoredBeacons (void )

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

Parameters
N/A

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

emberSetNumBeaconsToStore#

EmberStatus emberSetNumBeaconsToStore (uint8_t numBeacons)
Parameters
N/AnumBeacons

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

emberGetFirstBeacon#

EmberStatus emberGetFirstBeacon (EmberBeaconIterator * beaconIterator)
Parameters
N/AbeaconIterator

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

emberGetNextBeacon#

EmberStatus emberGetNextBeacon (EmberBeaconData * beacon)
Parameters
N/Abeacon

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

emberGetNumStoredBeacons#

uint8_t emberGetNumStoredBeacons (void )

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

Parameters
N/A

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