License#

Copyright 2018 Silicon Laboratories Inc. www.silabs.com

SPDX-License-Identifier: Zlib

The licensor of this software is Silicon Laboratories Inc.

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

  2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

  3. This notice may not be removed or altered from any source distribution.

/***************************************************************************/
#ifndef __NETWORK_FORMATION_H__
#define __NETWORK_FORMATION_H__

#define EMBER_MAC_MAX_APP_BEACON_PAYLOAD_LENGTH     16
#define EMBER_MAC_STACK_BEACON_PAYLOAD              "silabs-connect"
#define EMBER_MAC_STACK_BEACON_PAYLOAD_LENGTH       14

#define EMBER_MAC_MAX_BEACON_FIELDS_LENGTH          84

#define EMBER_CHILD_TABLE_AGING_DISABLED            0x20C400

#define EMBER_CHILD_TABLE_MAX_TIMEOUT_S   (EMBER_CHILD_TABLE_AGING_DISABLED - 1)

void emberIncomingBeaconHandler(EmberPanId panId,
                                EmberMacAddress *source,
                                int8_t rssi,
                                bool permitJoining,
                                uint8_t beaconFieldsLength,
                                uint8_t *beaconFields,
                                uint8_t beaconPayloadLength,
                                uint8_t *beaconPayload);

void emberActiveScanCompleteHandler(void);

void emberEnergyScanCompleteHandler(int8_t mean,
                                    int8_t min,
                                    int8_t max,
                                    uint16_t variance);

EmberStatus emberInit(void);

void emberTick(void);

EmberStatus emberNetworkInit(void);

EmberStatus emberStartActiveScan(uint16_t channel);

EmberStatus emberSetActiveScanDuration(uint16_t durationMs);

uint16_t emberGetActiveScanDuration(void);

EmberStatus emberStartEnergyScan(uint16_t channel, uint8_t samples);

EmberStatus emberSetApplicationBeaconPayload(uint8_t payloadLength,
                                             uint8_t *payload);

EmberStatus emberFormNetwork(EmberNetworkParameters *parameters);

EmberStatus emberJoinNetworkExtended(EmberNodeType nodeType,
                                     EmberNodeId nodeId,
                                     EmberNetworkParameters *parameters);

EmberStatus emberJoinNetwork(EmberNodeType nodeType,
                             EmberNetworkParameters *parameters);

EmberStatus emberPermitJoining(uint8_t duration);

EmberStatus emberJoinCommissioned(EmberNodeType nodeType,
                                  EmberNodeId nodeId,
                                  EmberNetworkParameters *parameters);

#define EMBER_MAX_SELECTIVE_JOIN_PAYLOAD_LENGTH           50

EmberStatus emberSetSelectiveJoinPayload(uint8_t payloadLength,
                                         uint8_t *payload);

EmberStatus emberClearSelectiveJoinPayload(void);

#define EMBER_MAX_AUXILIARY_ADDRESS_FILTERING_TABLE_LENGTH   2

EmberStatus emberSetAuxiliaryAddressFilteringEntry(EmberNodeId nodeId,
                                                   uint8_t entryIndex);

EmberNodeId emberGetAuxiliaryAddressFilteringEntry(uint8_t entryIndex);

void emberResetNetworkState(void);

EmberStatus emberMacFormNetwork(EmberNetworkParameters *parameters);

EmberStatus emberMacSetPanCoordinator(bool isCoordinator);

EmberStatus emberGetChildFlags(EmberMacAddress *address,
                               EmberChildFlags *flags);

EmberStatus emberGetChildInfo(EmberMacAddress *address,
                              EmberMacAddress *addressResp,
                              EmberChildFlags *flags);

EmberStatus emberRemoveChild(EmberMacAddress *address);

EmberStatus emberNetworkLeave(void);

EmberStatus emberMacAddShortToLongAddressMapping(EmberNodeId shortId,
                                                 EmberEUI64 longId);

EmberStatus emberMacClearShortToLongAddressMappings(void);

EmberStatus emberOfdmSetMcs(uint8_t mcs);

EmberStatus emberOfdmGetMcs(uint8_t *mcs);

//------------------------------------------------------------------------------
// Frequency Hopping

#define EMBER_FREQUENCY_HOPPING_ALWAYS_ON_CLIENT_SYNC_DISABLE_TIMEOUT 0xFFFF

EmberStatus emberFrequencyHoppingSetChannelMask(uint8_t channelMaskLength,
                                                uint8_t *channelMask);

EmberStatus emberFrequencyHoppingStartServer(void);

EmberStatus emberFrequencyHoppingStartClient(EmberNodeId serverNodeId,
                                             EmberPanId serverPanId);

EmberStatus emberFrequencyHoppingStop(void);

void emberFrequencyHoppingStartClientCompleteHandler(EmberStatus status);

#endif //__NETWORK_FORMATION_H__

Handlers#

void
emberIncomingBeaconHandler(EmberPanId panId, EmberMacAddress *source, int8_t rssi, bool permitJoining, uint8_t beaconFieldsLength, uint8_t *beaconFields, uint8_t beaconPayloadLength, uint8_t *beaconPayload)

Invoked if a beacon is received during the scanning procedure if the handler was initiated by the application with the emberStartActiveScan() stack APIs.

void

Invoked after the application calls the emberStartActiveScan() stack API to inform the application that the scanning procedure is complete.

void
emberEnergyScanCompleteHandler(int8_t mean, int8_t min, int8_t max, uint16_t variance)

Invoked after the application calls the emberStartEnergyScan() stack API to inform the application that the energy scan procedure is complete and to provide statistics.

Callbacks#

void

This stack handler is invoked after the application calls the emberFrequencyHoppingStartClient() stack API to inform the application that the synchronization process with the server is complete. See emberFrequencyHoppingStartClient() for details.

Macros#

#define

The maximum length in bytes of the application beacon payload.

#define
#define

The length in bytes of the stack beacon payload.

#define

The maximum length in bytes of the beacon fields (superframe, GTS, pending address) as per 802.15.4 specs.

#define

A special timeout value that disables aging of the child table.

#define
EMBER_CHILD_TABLE_MAX_TIMEOUT_S (EMBER_CHILD_TABLE_AGING_DISABLED - 1)

The maximum timeout in seconds after which a stale entry may be removed from the child table.

#define

The maximum length in bytes of the join payload.

#define

The maximum number of entries the auxiliary address filtering table can hold.

#define

A special value for the frequency hopping non sleepy client timeout that disables synchronization loss detection.

Functions#

emberInit(void)

Initialize the radio and the Ember stack.

void
emberTick(void)

A periodic tick routine that should be called in the main loop in the application.

Resume the network operation after a reboot.

emberStartActiveScan(uint16_t channel)

Start an active scan. EMBER_SUCCESS signals that the scan successfully started. Upon receiving a beacon, the emberIncomingBeaconHandler() stack handler is called. At the end of the scanning procedure, the emberActiveScanCompleteHandler() stack handler is called. Note that, while a scan can be initiated when the node is currently joined to a network, the node will generally be unable to communicate with its PAN during the scan period. In particular, time-sensitive network operations might be affected because a scan operation will prevent any network operation for the duration of the scan.

emberSetActiveScanDuration(uint16_t durationMs)

Set the time in milliseconds the node will spend listening for incoming beacons during an active scan. The default value is set based on the symbol time of the current PHY configuration according to the 802.15.4 specs.

uint16_t

Get the current active scan duration in milliseconds.

emberStartEnergyScan(uint16_t channel, uint8_t samples)

Start an energy scan. EMBER_SUCCESS signals that the scan successfully started. At the end of the scanning procedure, the emberEnergyScanCompleteHandler() stack handler is called. Note that, while a scan can be initiated when the node is currently joined to a network, the node is generally unable to communicate with its PAN during the scan period. In particular, time-sensitive network operations might be affected because a scan operation will prevent any network operation for the duration of the scan.

emberSetApplicationBeaconPayload(uint8_t payloadLength, uint8_t *payload)

Allow the application to set the application portion of the beacon payload. It's by default set to the empty string.

emberFormNetwork(EmberNetworkParameters *parameters)

Form a new network by becoming the coordinator. This API requires the parent-support library to be present.

emberJoinNetworkExtended(EmberNodeType nodeType, EmberNodeId nodeId, 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. Notice that forming a network causes the node's security frame counter to be reset.

emberJoinNetwork(EmberNodeType nodeType, EmberNetworkParameters *parameters)

Cause the stack to associate with the network using the specified network parameters. The network ID is assigned by the network coordinator. 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. Notice that joining a network causes the node's security frame counter to be reset.

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.

emberJoinCommissioned(EmberNodeType nodeType, EmberNodeId nodeId, EmberNetworkParameters *parameters)

Cause the stack to go up with the passed network parameters without performing any over-the-air message exchange. Notice that commissioning a network causes the node's security frame counter to be reset.

emberSetSelectiveJoinPayload(uint8_t payloadLength, uint8_t *payload)

When invoked at a EMBER_STAR_COORDINATOR or a EMBER_STAR_RANGE_EXTENDER, it causes the stack to only accept subsequent joining nodes with matching joining payload. When invoked at a node that has not yet joined a network, it sets the joining payload that will be included in the joining process. Notice, the join payload is included in a non-standard 802.15.4 command, therefore this feature is not available for nodes operating as EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE.

Clear the join payload previously set with the emberSetSelectiveJoinPayload() API. When invoked at an EMBER_STAR_COORDINATOR or an EMBER_STAR_RANGE_EXTENDER it causes the stack to accept joining nodes with any join payload pattern. When invoked at a node that has not yet joined a network, it clears the join payload. Subsequent joining attempts will not include any join payload in the over-the-air joining handshake.

emberSetAuxiliaryAddressFilteringEntry(EmberNodeId nodeId, uint8_t entryIndex)

Set an entry in the auxiliary address filtering table at a given address. Nodes of EMBER_DIRECT_DEVICE device type can receive incoming messages destined to any of the node IDs in the auxiliary address filtering table (while also receiving messages destined to actual node ID). If the passed node ID is EMBER_NULL_NODE_ID, the entry is cleared.

Retrieve the content of the auxiliary address filtering table at a given address. See emberSetAuxiliaryAddressFilteringEntry() for details.

void

Forget the current network and reverts to a network status of EMBER_NO_NETWORK.

emberMacFormNetwork(EmberNetworkParameters *parameters)

Form a new network as an EMBER_MAC_MODE_DEVICE by becoming the coordinator. This API should be used to form a compliant 802.15.4 PAN and to inter-operate with other 802.15.4 devices. Notice that forming a network causes the node's security frame counter to be reset.

emberMacSetPanCoordinator(bool isCoordinator)

Configure a EMBER_MAC_MODE_DEVICE node to be a PAN coordinator. Note, this only applies to nodes that have been commissioned as EMBER_MAC_MODE_DEVICE.

emberGetChildFlags(EmberMacAddress *address, EmberChildFlags *flags)

Return an EmberChildFlags bitmask indicating the child flags of the child corresponding to the passed MAC address.

emberGetChildInfo(EmberMacAddress *address, EmberMacAddress *addressResp, EmberChildFlags *flags)

Return info on the child corresponding to the passed MAC address.

emberRemoveChild(EmberMacAddress *address)

Remove the node corresponding to the passed MAC address from the child table.

Allow a star topology node that previously joined a network to leave the network. The node will notify the parent node and eventually leave the network. The application is notified that the leave procedure completed via the emberStackStatusHandler() handler.

emberMacAddShortToLongAddressMapping(EmberNodeId shortId, EmberEUI64 longId)

Populate the short-to-long address mapping table at the MAC layer. The table is meaningful only when running as EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE. The standard 802.15.4 encryption and authentication process requires the security nonce to be populated with the source node long ID. A receiver must do the same to decrypt a secured incoming message. This short-to-long mapping table is used to decrypt a secured incoming packet from a node using short source addressing. If no entry is found in this table, the incoming message will be dropped. This table is also used to encrypt secured outgoing messages with short source addressing in case the node is sending out a secured message with a short source address other than its own.

Clear the short-to-long address mapping table at the MAC layer.

emberOfdmSetMcs(uint8_t mcs)

Set the MCS in case of an OFDM PHY. MCS can range from 0 to 6.

emberOfdmGetMcs(uint8_t *mcs)

Get the MCS in case of an OFDM PHY.

emberFrequencyHoppingSetChannelMask(uint8_t channelMaskLength, uint8_t *channelMask)

Set the channel mask for frequency hopping. This API can only be invoked when the node is not frequency hopping.

Start the device operating as a frequency hopping server. This API can only be invoked when the node is joined to a network. Notice that the server upon starting hopping shall perform an initial advertisement across the entire channel hopping sequence. This is done to resynchronize clients in case the server was started as result of a reboot.

emberFrequencyHoppingStartClient(EmberNodeId serverNodeId, EmberPanId serverPanId)

Start operating as a frequency hopping client and synchronize with the specified server. This API can be invoked on nodes that are already joined to a network (with the exception of nodes started as EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE) and nodes that are not joined to a network yet. If the node is already performing frequency hopping, this API returns EMBER_INVALID_CALL. If this API returns EMBER_SUCCESS, the emberFrequencyHoppingStartClientCompleteHandler() is invoked asynchronously to inform the application whether the node successfully synchronized with the specified server or to inform the application of the reason of failure. After the client is synced to a server, it may seamlessly perform the resynchronization process if needed. Sleepy devices in particular periodically perform the resynchronization process. If the client fails a resynchronization process, it informs the application by invoking the emberStackStatusHandler() handler with EMBER_MAC_SYNC_TIMEOUT status. When this occurs, the client will no longer be synced to the server. The application may elect to attempt a new synchronization process by invoking this API again.

Stop frequency hopping. This API can only be invoked when the node is frequency hopping. Applicable for both server and client.

Handlers Documentation#

emberIncomingBeaconHandler#

void emberIncomingBeaconHandler (EmberPanId panId, EmberMacAddress * source, int8_t rssi, bool permitJoining, uint8_t beaconFieldsLength, uint8_t * beaconFields, uint8_t beaconPayloadLength, uint8_t * beaconPayload)

Invoked if a beacon is received during the scanning procedure if the handler was initiated by the application with the emberStartActiveScan() stack APIs.

Parameters
[in]panId

The source pan ID of the received beacon.

[in]source

The source node address of the received beacon.

[in]rssi

The RSSI the beacon was received with.

[in]permitJoining

The permit joining flag in the received beacon.

[in]beaconFieldsLength

The length in bytes of the beacon fields defined as per 802.15.4 specs (superframe, GTS fields and pending address fields) of the received beacon.

[in]beaconFields

A pointer to the beacon fields defined as per 802.15.4 specs (superframe, GTS fields and pending address fields) of the received beacon.

[in]beaconPayloadLength

The length in bytes of the application beacon payload of the received beacon.

[in]beaconPayload

A pointer to the application beacon payload of the received beacon.


Definition at line 94 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberActiveScanCompleteHandler#

void emberActiveScanCompleteHandler (void )

Invoked after the application calls the emberStartActiveScan() stack API to inform the application that the scanning procedure is complete.

Parameters
N/A

Definition at line 106 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberEnergyScanCompleteHandler#

void emberEnergyScanCompleteHandler (int8_t mean, int8_t min, int8_t max, uint16_t variance)

Invoked after the application calls the emberStartEnergyScan() stack API to inform the application that the energy scan procedure is complete and to provide statistics.

Parameters
[in]mean

The average energy detected in dBm.

[in]min

The minimum energy detected in dBm.

[in]max

The maximum energy detected in dBm.

[in]variance

The variance of the energy detected in dBm.


Definition at line 117 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

Callbacks Documentation#

emberFrequencyHoppingStartClientCompleteHandler#

void emberFrequencyHoppingStartClientCompleteHandler (EmberStatus status)

This stack handler is invoked after the application calls the emberFrequencyHoppingStartClient() stack API to inform the application that the synchronization process with the server is complete. See emberFrequencyHoppingStartClient() for details.

Parameters
[in]status

An EmberStatus value indicating whether the synchronization process with the server was completed successfully or the reason for failure.


Definition at line 733 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

Macro Definition Documentation#

EMBER_MAC_MAX_APP_BEACON_PAYLOAD_LENGTH#

#define EMBER_MAC_MAX_APP_BEACON_PAYLOAD_LENGTH
Value:
16

The maximum length in bytes of the application beacon payload.


Definition at line 44 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

EMBER_MAC_STACK_BEACON_PAYLOAD#

#define EMBER_MAC_STACK_BEACON_PAYLOAD
Value:
"silabs-connect"

Definition at line 45 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

EMBER_MAC_STACK_BEACON_PAYLOAD_LENGTH#

#define EMBER_MAC_STACK_BEACON_PAYLOAD_LENGTH
Value:
14

The length in bytes of the stack beacon payload.


Definition at line 48 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

EMBER_MAC_MAX_BEACON_FIELDS_LENGTH#

#define EMBER_MAC_MAX_BEACON_FIELDS_LENGTH
Value:
84

The maximum length in bytes of the beacon fields (superframe, GTS, pending address) as per 802.15.4 specs.


Definition at line 53 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

EMBER_CHILD_TABLE_AGING_DISABLED#

#define EMBER_CHILD_TABLE_AGING_DISABLED
Value:
0x20C400

A special timeout value that disables aging of the child table.


Definition at line 57 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

EMBER_CHILD_TABLE_MAX_TIMEOUT_S#

#define EMBER_CHILD_TABLE_MAX_TIMEOUT_S
Value:
(EMBER_CHILD_TABLE_AGING_DISABLED - 1)

The maximum timeout in seconds after which a stale entry may be removed from the child table.


Definition at line 62 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

EMBER_MAX_SELECTIVE_JOIN_PAYLOAD_LENGTH#

#define EMBER_MAX_SELECTIVE_JOIN_PAYLOAD_LENGTH
Value:
50

The maximum length in bytes of the join payload.


Definition at line 370 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

EMBER_MAX_AUXILIARY_ADDRESS_FILTERING_TABLE_LENGTH#

#define EMBER_MAX_AUXILIARY_ADDRESS_FILTERING_TABLE_LENGTH
Value:
2

The maximum number of entries the auxiliary address filtering table can hold.


Definition at line 409 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

EMBER_FREQUENCY_HOPPING_ALWAYS_ON_CLIENT_SYNC_DISABLE_TIMEOUT#

#define EMBER_FREQUENCY_HOPPING_ALWAYS_ON_CLIENT_SYNC_DISABLE_TIMEOUT
Value:
0xFFFF

A special value for the frequency hopping non sleepy client timeout that disables synchronization loss detection.


Definition at line 629 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

Function Documentation#

emberInit#

EmberStatus emberInit (void )

Initialize the radio and the Ember 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 are not available. Some failure modes are not fatal, but the application must follow certain procedures to permit recovery. Ignoring the return code results 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 141 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberTick#

void emberTick (void )

A periodic tick routine that should be called in the main loop in the application.

Parameters
N/A

Definition at line 146 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberNetworkInit#

EmberStatus emberNetworkInit (void )

Resume the network operation after a reboot.

Parameters
N/A

This API must be called on boot prior to ANY network operations. It initializes the networking system and attempts 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.

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 165 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberStartActiveScan#

EmberStatus emberStartActiveScan (uint16_t channel)

Start an active scan. EMBER_SUCCESS signals that the scan successfully started. Upon receiving a beacon, the emberIncomingBeaconHandler() stack handler is called. At the end of the scanning procedure, the emberActiveScanCompleteHandler() stack handler is called. Note that, while a scan can be initiated when the node is currently joined to a network, the node will generally be unable to communicate with its PAN during the scan period. In particular, time-sensitive network operations might be affected because a scan operation will prevent any network operation for the duration of the scan.

Parameters
[in]channel

The channel to scan.

Possible error responses and their meanings:


Definition at line 186 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberSetActiveScanDuration#

EmberStatus emberSetActiveScanDuration (uint16_t durationMs)

Set the time in milliseconds the node will spend listening for incoming beacons during an active scan. The default value is set based on the symbol time of the current PHY configuration according to the 802.15.4 specs.

Parameters
[in]durationMs

The active scan duration in milliseconds. A value of 0xFFFF restores the default value.

Returns


Definition at line 199 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberGetActiveScanDuration#

uint16_t emberGetActiveScanDuration (void )

Get the current active scan duration in milliseconds.

Parameters
N/A

Returns

  • a 16-bit integer indicating the current duration in millisecond of the active scan.


Definition at line 206 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberStartEnergyScan#

EmberStatus emberStartEnergyScan (uint16_t channel, uint8_t samples)

Start an energy scan. EMBER_SUCCESS signals that the scan successfully started. At the end of the scanning procedure, the emberEnergyScanCompleteHandler() stack handler is called. Note that, while a scan can be initiated when the node is currently joined to a network, the node is generally unable to communicate with its PAN during the scan period. In particular, time-sensitive network operations might be affected because a scan operation will prevent any network operation for the duration of the scan.

Parameters
[in]channel

The channel to scan.

[in]samples

The number of energy samples to be produced. Each sample is performed averaging the detected energy over X symbols time, whereas X depends on the selected PHY configuration and set by default to 8. The symbol time duration also depends on the selected PHY configuration.

Possible error responses and their meanings:


Definition at line 233 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberSetApplicationBeaconPayload#

EmberStatus emberSetApplicationBeaconPayload (uint8_t payloadLength, uint8_t * payload)

Allow the application to set the application portion of the beacon payload. It's by default set to the empty string.

Parameters
[in]payloadLength

The length in bytes of the application beacon payload to be set. This value can not exceed EMBER_MAC_MAX_APP_BEACON_PAYLOAD_LENGTH.

[out]payload

A pointer to the application beacon payload to be set.

Returns


Definition at line 248 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberFormNetwork#

EmberStatus emberFormNetwork (EmberNetworkParameters * parameters)

Form a new network by becoming the coordinator. This API requires the parent-support library to be present.

Parameters
[in]parameters

An EmberNetworkParameters value that specifies the network parameters of the network to be formed.

Returns

  • An EmberStatus value that indicates either the successful formation of the new network or an EmberStatus value indicating the reason of failure.


Definition at line 263 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberJoinNetworkExtended#

EmberStatus emberJoinNetworkExtended (EmberNodeType nodeType, EmberNodeId nodeId, 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. Notice that forming a network causes the node's security frame counter to be reset.

Parameters
[in]nodeType

Specification of the role that this node will have in the network. This role can be EMBER_STAR_RANGE_EXTENDER, EMBER_STAR_END_DEVICE, EMBER_STAR_SLEEPY_END_DEVICE, EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE. If the node is frequency hopping, the role can not be EMBER_STAR_RANGE_EXTENDER.

[in]nodeId

An EmberNodeId value indicating the short ID the node intends to use for addressing purposes. If this value is EMBER_NULL_NODE_ID, the network coordinator will allocate a new short address. Addresses should be allocated by the coordinator unless there is a specific need to join a network with a specific ID. If a specific ID is used, uniqueness should be guaranteed across the entire network by the application, via some out of band means. Notice that nodes of EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE require this parameter to be set to EMBER_NULL_NODE_ID.

[in]parameters

An EmberNetworkParameters value that specifies the network parameters of the network with which the node should associate.

Returns

  • An EmberStatus value that indicates either:

    • that the association process began successfully or

    • the reason for failure.


Definition at line 295 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberJoinNetwork#

EmberStatus emberJoinNetwork (EmberNodeType nodeType, EmberNetworkParameters * parameters)

Cause the stack to associate with the network using the specified network parameters. The network ID is assigned by the network coordinator. 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. Notice that joining a network causes the node's security frame counter to be reset.

Parameters
[in]nodeType

Specification of the role that this node will have in the network. This role can be EMBER_STAR_RANGE_EXTENDER, EMBER_STAR_END_DEVICE, EMBER_STAR_SLEEPY_END_DEVICE, EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE. If the node is frequency hopping, the role can not be EMBER_STAR_RANGE_EXTENDER.

[in]parameters

An EmberNetworkParameters value that specifies the network parameters of the network with which the node should associate.

Returns

  • An EmberStatus value that indicates either:

    • that the association process began successfully or

    • the reason for failure.


Definition at line 321 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.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
[in]duration

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

Returns


Definition at line 337 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberJoinCommissioned#

EmberStatus emberJoinCommissioned (EmberNodeType nodeType, EmberNodeId nodeId, EmberNetworkParameters * parameters)

Cause the stack to go up with the passed network parameters without performing any over-the-air message exchange. Notice that commissioning a network causes the node's security frame counter to be reset.

Parameters
[in]nodeType

Specifies the role that this node will have in the network. The only device types allowed in the commissioning API are EMBER_DIRECT_DEVICE, EMBER_MAC_MODE_DEVICE and EMBER_MAC_MODE_SLEEPY_DEVICE.

[in]nodeId

An EmberNodeId value that specifies the short ID the node will have. The passed node ID must be a valid short address (any value other than EMBER_NULL_NODE_ID or EMBER_BROADCAST_ADDRESS). A value of EMBER_USE_LONG_ADDRESS is allowed only when commissioning the node as EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE and will cause the node to send MAC level control messages such as data polls or beacons using long source addressing.

[in]parameters

An EmberNetworkParameters value that specifies the network parameters of the network the node should participate in.

Returns

  • An EmberStatus value that indicates either:

    • that the node successfully commissioned the passed network parameters

    • the reason for failure.


Definition at line 364 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberSetSelectiveJoinPayload#

EmberStatus emberSetSelectiveJoinPayload (uint8_t payloadLength, uint8_t * payload)

When invoked at a EMBER_STAR_COORDINATOR or a EMBER_STAR_RANGE_EXTENDER, it causes the stack to only accept subsequent joining nodes with matching joining payload. When invoked at a node that has not yet joined a network, it sets the joining payload that will be included in the joining process. Notice, the join payload is included in a non-standard 802.15.4 command, therefore this feature is not available for nodes operating as EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE.

Parameters
[in]payloadLength

The length in bytes of the passed joining payload. This can not exceed EMBER_MAX_SELECTIVE_JOIN_PAYLOAD_LENGTH.

[in]payload

A pointer to the payload to be set.

Returns

  • An EmberStatus value that indicates either:

    • that the node successfully set the join payload.

    • the reason for failure.


Definition at line 389 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberClearSelectiveJoinPayload#

EmberStatus emberClearSelectiveJoinPayload (void )

Clear the join payload previously set with the emberSetSelectiveJoinPayload() API. When invoked at an EMBER_STAR_COORDINATOR or an EMBER_STAR_RANGE_EXTENDER it causes the stack to accept joining nodes with any join payload pattern. When invoked at a node that has not yet joined a network, it clears the join payload. Subsequent joining attempts will not include any join payload in the over-the-air joining handshake.

Parameters
N/A

Returns

  • An EmberStatus value that indicates either:

    • that the node successfully cleared the join payload.

    • the reason for failure.


Definition at line 404 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberSetAuxiliaryAddressFilteringEntry#

EmberStatus emberSetAuxiliaryAddressFilteringEntry (EmberNodeId nodeId, uint8_t entryIndex)

Set an entry in the auxiliary address filtering table at a given address. Nodes of EMBER_DIRECT_DEVICE device type can receive incoming messages destined to any of the node IDs in the auxiliary address filtering table (while also receiving messages destined to actual node ID). If the passed node ID is EMBER_NULL_NODE_ID, the entry is cleared.

Parameters
[in]nodeId

An EmberNodeId value to be added to the auxiliary address filtering table at the passed entry index.

[in]entryIndex

The index of the auxiliary address filtering table entry to be set.

Returns


Definition at line 427 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberGetAuxiliaryAddressFilteringEntry#

EmberNodeId emberGetAuxiliaryAddressFilteringEntry (uint8_t entryIndex)

Retrieve the content of the auxiliary address filtering table at a given address. See emberSetAuxiliaryAddressFilteringEntry() for details.

Parameters
[in]entryIndex

The index in the auxiliary address filtering table entry to be retrieved.

Returns

  • An EmberNodeId value of EMBER_NULL_NODE_ID if the passed entry index is invalid or if the passed entry index refers to an unused entry. Otherwise, it returns the content of the auxiliary address filtering table entry corresponding to the passed entry index.


Definition at line 442 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberResetNetworkState#

void emberResetNetworkState (void )

Forget the current network and reverts to a network status of EMBER_NO_NETWORK.

Parameters
N/A

Definition at line 447 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberMacFormNetwork#

EmberStatus emberMacFormNetwork (EmberNetworkParameters * parameters)

Form a new network as an EMBER_MAC_MODE_DEVICE by becoming the coordinator. This API should be used to form a compliant 802.15.4 PAN and to inter-operate with other 802.15.4 devices. Notice that forming a network causes the node's security frame counter to be reset.

Parameters
[in]parameters

An EmberNetworkParameters value that specifies the network parameters of the network to be formed.

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 461 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberMacSetPanCoordinator#

EmberStatus emberMacSetPanCoordinator (bool isCoordinator)

Configure a EMBER_MAC_MODE_DEVICE node to be a PAN coordinator. Note, this only applies to nodes that have been commissioned as EMBER_MAC_MODE_DEVICE.

Parameters
[in]isCoordinator

If set to true, the node will identify itself as the PAN coordinator.

Returns


Definition at line 474 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberGetChildFlags#

EmberStatus emberGetChildFlags (EmberMacAddress * address, EmberChildFlags * flags)

Return an EmberChildFlags bitmask indicating the child flags of the child corresponding to the passed MAC address.

Parameters
[in]address

A pointer to an EmberMacAddress that specifies the MAC address of the child.

[out]flags

A pointer to an EmberChildFlags containing the child flags of the child corresponding to the passed MAC address.

Note

  • Deprecated, use emberGetChildInfo instead

Returns


Definition at line 493 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberGetChildInfo#

EmberStatus emberGetChildInfo (EmberMacAddress * address, EmberMacAddress * addressResp, EmberChildFlags * flags)

Return info on the child corresponding to the passed MAC address.

Parameters
[in]address

A pointer to an EmberMacAddress that specifies the MAC address of the child (short or long).

[out]addressResp

A pointer to an EmberMacAddress that returns the other address (respectively long or short).

[out]flags

A pointer to an EmberChildFlags containing the child flags of the child corresponding to the passed MAC address.

Note

  • For star coordinators, if the input address is short, the corresponding child will also be searched in the list of devices connected through range extender. Long address and additional flags for these devices are not available to the coordinator.

Note

  • Both out parameters are optional. If set to NULL, the API will at least indicate if the child was found in the network.

Returns


Definition at line 521 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberRemoveChild#

EmberStatus emberRemoveChild (EmberMacAddress * address)

Remove the node corresponding to the passed MAC address from the child table.

Parameters
[in]address

A pointer to an EmberMacAddress that specifies the MAC address of the child to be removed.

Returns


Definition at line 537 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberNetworkLeave#

EmberStatus emberNetworkLeave (void )

Allow a star topology node that previously joined a network to leave the network. The node will notify the parent node and eventually leave the network. The application is notified that the leave procedure completed via the emberStackStatusHandler() handler.

Parameters
N/A

Returns


Definition at line 548 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberMacAddShortToLongAddressMapping#

EmberStatus emberMacAddShortToLongAddressMapping (EmberNodeId shortId, EmberEUI64 longId)

Populate the short-to-long address mapping table at the MAC layer. The table is meaningful only when running as EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE. The standard 802.15.4 encryption and authentication process requires the security nonce to be populated with the source node long ID. A receiver must do the same to decrypt a secured incoming message. This short-to-long mapping table is used to decrypt a secured incoming packet from a node using short source addressing. If no entry is found in this table, the incoming message will be dropped. This table is also used to encrypt secured outgoing messages with short source addressing in case the node is sending out a secured message with a short source address other than its own.

Parameters
[in]shortId

The short address of the [short, long] entry to be added to the table.

[in]longId

The long address of the [short, long] entry to be added to the table.

Note

  • Because the table is stored in RAM, the application should ensure it gets correctly re-populated upon reboot.

  • Adding a new entry will cause the removal of existing entries matching the passed short ID or long ID.

Returns


Definition at line 584 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberMacClearShortToLongAddressMappings#

EmberStatus emberMacClearShortToLongAddressMappings (void )

Clear the short-to-long address mapping table at the MAC layer.

Parameters
N/A

Returns


Definition at line 593 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberOfdmSetMcs#

EmberStatus emberOfdmSetMcs (uint8_t mcs)

Set the MCS in case of an OFDM PHY. MCS can range from 0 to 6.

Parameters
[in]mcs

The MCS value to set.

Returns


Definition at line 605 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberOfdmGetMcs#

EmberStatus emberOfdmGetMcs (uint8_t * mcs)

Get the MCS in case of an OFDM PHY.

Parameters
[out]mcs

A pointer to the uint8_t that should hold the current MCS value.

Returns


Definition at line 617 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberFrequencyHoppingSetChannelMask#

EmberStatus emberFrequencyHoppingSetChannelMask (uint8_t channelMaskLength, uint8_t * channelMask)

Set the channel mask for frequency hopping. This API can only be invoked when the node is not frequency hopping.

Parameters
[in]channelMaskLength

Length of the bitmap in bytes

[in]channelMask

A pointer to a bitmap representing allowed channels for frequency hopping.

Note

  • The application is responsible for applying this setting to both the server and clients.

Note

  • The bitmap size needs to be at least (EMBER_FREQUENCY_HOPPING_END_CHANNEL + 8) >> 3 or an error is thrown.

  • The bitmap needs to be set again after stopping frequency hopping.

Returns


Definition at line 661 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberFrequencyHoppingStartServer#

EmberStatus emberFrequencyHoppingStartServer (void )

Start the device operating as a frequency hopping server. This API can only be invoked when the node is joined to a network. Notice that the server upon starting hopping shall perform an initial advertisement across the entire channel hopping sequence. This is done to resynchronize clients in case the server was started as result of a reboot.

Parameters
N/A

Returns


Definition at line 675 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberFrequencyHoppingStartClient#

EmberStatus emberFrequencyHoppingStartClient (EmberNodeId serverNodeId, EmberPanId serverPanId)

Start operating as a frequency hopping client and synchronize with the specified server. This API can be invoked on nodes that are already joined to a network (with the exception of nodes started as EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE) and nodes that are not joined to a network yet. If the node is already performing frequency hopping, this API returns EMBER_INVALID_CALL. If this API returns EMBER_SUCCESS, the emberFrequencyHoppingStartClientCompleteHandler() is invoked asynchronously to inform the application whether the node successfully synchronized with the specified server or to inform the application of the reason of failure. After the client is synced to a server, it may seamlessly perform the resynchronization process if needed. Sleepy devices in particular periodically perform the resynchronization process. If the client fails a resynchronization process, it informs the application by invoking the emberStackStatusHandler() handler with EMBER_MAC_SYNC_TIMEOUT status. When this occurs, the client will no longer be synced to the server. The application may elect to attempt a new synchronization process by invoking this API again.

Parameters
[in]serverNodeId

An EmberNodeId value indicating the node ID of the server to synchronize with.

[in]serverPanId

An EmberPanId value indicating the PAN ID of the server to synchronize with. Note that this parameter is meaningful only if the node is not currently joined to any network.

Returns

  • An EmberStatus value of EMBER_SUCCESS indicating that the node successfully initiated the synchronization process with the server, otherwise an EmberStatus value indicating the reason of failure.


Definition at line 708 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h

emberFrequencyHoppingStop#

EmberStatus emberFrequencyHoppingStop (void )

Stop frequency hopping. This API can only be invoked when the node is frequency hopping. Applicable for both server and client.

Parameters
N/A

Returns


Definition at line 718 of file /mnt/raid/workspaces/ws.2dqDELv9z/overlay/gsdk/protocol/flex/stack/include/network-management.h