Network Management#

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.

emberActiveScanCompleteHandler#

void emberActiveScanCompleteHandler (void )

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

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.

emberInit#

EmberStatus emberInit (void )

Initialize the radio and the Ember stack.

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.

emberTick#

void emberTick (void )

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

emberNetworkInit#

EmberStatus emberNetworkInit (void )

Resume the network operation after a reboot.

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.

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.

Possible error responses and their meanings:

• EMBER_INVALID_CALL, the node is currently frequency hopping.

• EMBER_MAC_SCANNING, indicates an ongoing scan.

• EMBER_PHY_INVALID_CHANNEL, the specified channel is not a valid channel on the current platform.

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.

Returns

• an EmberStatus value of EMBER_SUCCESS if the active scan duration was successfully set, otherwise an EmberStatus value indicating the reason of failure.

emberGetActiveScanDuration#

uint16_t emberGetActiveScanDuration (void )

Get the current active scan duration in milliseconds.

Returns

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

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.

Possible error responses and their meanings:

• EMBER_INVALID_CALL, the node is currently frequency hopping.

• EMBER_BAD_ARGUMENT, the samples parameter is invalid.

• EMBER_MAC_SCANNING, indicates an ongoing scan.

• EMBER_PHY_INVALID_CHANNEL, the specified channel is not a valid channel on the current platform.

• EMBER_NO_BUFFERS, the stack doesn't have enough memory at the moment to perform the requested scan.

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.

Returns

• an EmberStatus value of EMBER_SUCCESS if the application beacon payload was successfully set, otherwise an EmberStatus value indicating the reason of failure.

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.

Returns

• An EmberStatus value that indicates either:

  • that the association process began successfully or

  • the reason for failure.

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.

Returns

• An EmberStatus value that indicates either:

  • that the association process began successfully or

  • the reason for failure.

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.

Returns

• an EmberStatus value of EMBER_SUCCESS if the permit joining was successfully set, otherwise an EmberStatus value indicating the reason of failure.

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.

Returns

• An EmberStatus value that indicates either:

  • that the node successfully commissioned the passed network parameters

  • the reason for failure.

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.

Returns

• An EmberStatus value that indicates either:

  • that the node successfully set the join payload.

  • the reason for failure.

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.

Returns

• An EmberStatus value that indicates either:

  • that the node successfully cleared the join payload.

  • the reason for failure.

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.

Returns

• An EmberStatus value of EMBER_SUCCESS if auxiliary address filtering table entry was successfully set. An EmberStatus value of EMBER_INVALID_CALL if the passed entry index is invalid.

emberGetAuxiliaryAddressFilteringEntry#

EmberNodeId emberGetAuxiliaryAddressFilteringEntry (uint8_t entryIndex)

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

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.

emberResetNetworkState#

void emberResetNetworkState (void )

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

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.

Returns

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

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.

Returns

• An EmberStatus value of EMBER_SUCCESS if the coordinator flag was successfully set, or another EmberStatus value indicating the reason of failure.

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.

Returns

• An EmberStatus value of EMBER_SUCCESS if the node successfully initiated the network leave procedure, or another EmberStatus value indicating the reason of failure.

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.

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

• an EmberStatus value of:

  • EMBER_SUCCESS if the mapping was successfully added to the table.

  • EMBER_INVALID_CALL if the node is not running as EMBER_MAC_MODE_DEVICE or as EMBER_MAC_MODE_SLEEPY_DEVICE.

  • EMBER_TABLE_FULL if the table is currently full.

  • EMBER_NO_BUFFERS if the heap does not currently have enough space for the new entry. The size of the table is controlled by the EMBER_SECURITY_SHORT_TO_LONG_MAPPING_TABLE_SIZE.

emberMacClearShortToLongAddressMappings#

EmberStatus emberMacClearShortToLongAddressMappings (void )

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

Returns

• an EmberStatus value of EMBER_SUCCESS if table was cleared, or another EmberStatus value indicating the reason of failure.

emberOfdmSetMcs#

EmberStatus emberOfdmSetMcs (uint8_t mcs)

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

Returns

• an EmberStatus value of EMBER_SUCCESS if the MCS is valid, an EmberStatus value of EMBER_INVALID_CALL if the current PHY is not OFDM or an EmberStatus value of EMBER_BAD_ARGUMENT if the MCS value is not valid.

emberOfdmGetMcs#

EmberStatus emberOfdmGetMcs (uint8_t * mcs)

Get the MCS in case of an OFDM PHY.

Returns

• an EmberStatus value of EMBER_INVALID_CALL if the current PHY is not OFDM or an EmberStatus value of EMBER_SUCCESS if the current PHY is OFDM.

EMBER_MAC_MAX_APP_BEACON_PAYLOAD_LENGTH#

#define EMBER_MAC_MAX_APP_BEACON_PAYLOAD_LENGTH

16

The maximum length in bytes of the application beacon payload.

EMBER_MAC_STACK_BEACON_PAYLOAD#

#define EMBER_MAC_STACK_BEACON_PAYLOAD

"silabs-connect"

EMBER_MAC_STACK_BEACON_PAYLOAD_LENGTH#

#define EMBER_MAC_STACK_BEACON_PAYLOAD_LENGTH

14

The length in bytes of the stack beacon payload.

EMBER_MAC_MAX_BEACON_FIELDS_LENGTH#

#define EMBER_MAC_MAX_BEACON_FIELDS_LENGTH

84

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

EMBER_CHILD_TABLE_AGING_DISABLED#

#define EMBER_CHILD_TABLE_AGING_DISABLED

0x20C400

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

EMBER_CHILD_TABLE_MAX_TIMEOUT_S#

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

EMBER_MAX_SELECTIVE_JOIN_PAYLOAD_LENGTH#

#define EMBER_MAX_SELECTIVE_JOIN_PAYLOAD_LENGTH

50

The maximum length in bytes of the join payload.

EMBER_MAX_AUXILIARY_ADDRESS_FILTERING_TABLE_LENGTH#

#define EMBER_MAX_AUXILIARY_ADDRESS_FILTERING_TABLE_LENGTH

2

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