End Devices#

EmberZNet API relating to end device children.

See child.h for source code.

Power Management#

enum
@6 {
EMBER_OUTGOING_MESSAGES = 0x0001
EMBER_INCOMING_MESSAGES = 0x0002
EMBER_RADIO_IS_ON = 0x0004
EMBER_TRANSPORT_ACTIVE = 0x0008
EMBER_APS_LAYER_ACTIVE = 0x0010
EMBER_ASSOCIATING = 0x0020
EMBER_ZLL_TOUCH_LINKING = 0x0040
EMBER_NETWORK_TIMEOUT_REQUEST = 0x0200
EMBER_SEND_ORPHAN_NOTIFICATION = 0x0400
EMBER_MAC_DATA_POLL_SUPER_RETRY = 0x0800
}

Define tasks that are taken into account when dealing with sleep related behavior.

uint16_t

Return a bitmask indicating the stack's current tasks.

bool

Indicate whether the stack is currently in a state where there are no high-priority tasks, allowing the device to sleep.

bool

Indicate whether the parent token has been set by association.

bool

Indicate whether the stack currently has any tasks pending.

bool

Indicate whether the stack is currently in a state that does not require the application to periodically poll.

void

Immediately turn the radio power completely off.

void

Initialize the radio. Typically called coming out of deep sleep.

#define
EMBER_HIGH_PRIORITY_TASKS (EMBER_OUTGOING_MESSAGES | EMBER_INCOMING_MESSAGES | EMBER_RADIO_IS_ON)

A mask of the tasks that prevent a device from sleeping.

Functions#

int8_t
emberChildPower(uint8_t childIndex)

Return radio power value of the child from the given childIndex.

void
emberSetChildPower(uint8_t childIndex, int8_t newPower)

Set the radio power value for a given child index.

emberGetChildData(uint8_t index, EmberChildData *childData)

Get the EUI64 and node type of the child at the provided index. If there is no child at 'index', it returns EMBER_NOT_JOINED. Possible child indexes run from zero to emberMaxChildCount() - 1.

emberSetChildData(uint8_t index, EmberChildData *childData)

Sets the EUI64, node ID, and node type of the child at the provided index in nonvolatile memory. No other data from the childData argument is used or copied. The user is responsible for rebooting the device after calling this API in order to initialize RAM-based child data. Possible child indexes run from zero to emberMaxChildCount() - 1.

void
emberChildJoinHandler(uint8_t index, bool joining)

Called by the stack when a child joins or leaves. 'Joining' is true if the child is joining and false if leaving.

emberSetKeepAliveMode(EmberKeepAliveMode mode)

Request any pending data from the parent node. This function allows an end device to query its parent for any pending data.

void
emberSetMacPollFailureWaitTime(uint32_t waitBeforeRetryIntervalMs)
void
emberPollCompleteHandler(EmberStatus status)
emberSetMessageFlag(EmberNodeId childId)

Set a flag to indicate that a message is pending for a child. The next time that the child polls, it will be informed that it has a pending message. The message is sent from emberPollHandler, which is called when the child requests data.

emberClearMessageFlag(EmberNodeId childId)

Clear a flag to indicate that there are no more messages for a child. The next time the child polls, it will be informed that it does not have any pending messages.

void
emberPollHandler(EmberNodeId childId, bool transmitExpected)

Called to allow the application to send a message in response to a poll from a child.

emberAddChild(EmberNodeId shortId, EmberEUI64 longId, EmberNodeType nodeType)

Add a child to the child/neighbor table only on SoC, allowing direct manipulation of these tables by the application. This can affect the network functionality, and needs to be used wisely. If used appropriately, the application can maintain more than the maximum of children provided by the stack.

emberRemoveChild(EmberEUI64 childEui64)

Remove a node from child/neighbor table only on SoC, allowing direct manipulation of these tables by the application. This can affect the network functionality, and needs to be used wisely.

void
emberRemoveNeighbor(EmberNodeId shortId, EmberEUI64 longId)

Remove a neighbor from neighbor table only on SoC, allowing direct manipulation of neighbor table by the application. This can affect the network functionality, and needs to be used wisely.

uint8_t

Return the number of children the node currently has.

uint8_t

Return the number of router children that the node currently has.

uint8_t

Return the maximum number of children for this node. The return value is undefined for nodes that are not joined to a network.

uint8_t

Return the maximum number of router children for this node. The return value is undefined for nodes that are not joined to a network.

EmberNodeId

Return the parent's node ID. The return value is undefined for nodes without parents (coordinators and nodes that are not joined to a network).

EmberEUI64

Return the parent's EUI64. The return value is undefined for nodes without parents (coordinators and nodes that are not joined to a network).

Macros#

#define
emberChildId (childIndex)

Convert a child index to a node ID.

#define
emberChildIndex (childId)

Convert a node ID to a child index.

Power Management Documentation#

@6#

@6

Define tasks that are taken into account when dealing with sleep related behavior.

As opposed to its subset of EMBER_HIGH_PRIORITY_TASKS, these tasks do not necessarily prevent the device from going to sleep. However, they are taken into account when calculating how long we can sleep until the next event.

Enumerator
EMBER_OUTGOING_MESSAGES

Messages are waiting for transmission.

EMBER_INCOMING_MESSAGES

One or more incoming messages are being processed.

EMBER_RADIO_IS_ON

The radio is currently powered on. On sleepy devices, the radio is turned off when not in use. On non-sleepy devices (EMBER_COORDINATOR, EMBER_ROUTER, or EMBER_END_DEVICE), the radio is always on.

EMBER_TRANSPORT_ACTIVE

The transport layer has messages awaiting an ACK.

EMBER_APS_LAYER_ACTIVE

The ZigBee APS layer has messages awaiting an ACK.

EMBER_ASSOCIATING

The node is currently trying to associate with a ZigBee PRO network.

EMBER_ZLL_TOUCH_LINKING

The node is currently touch linking.

EMBER_NETWORK_TIMEOUT_REQUEST

Network Timeout Request Event.

EMBER_SEND_ORPHAN_NOTIFICATION

Sending Orphan Notification Event.

EMBER_MAC_DATA_POLL_SUPER_RETRY

MAC Data Poll Super Retry Event .


Definition at line 356 of file stack/include/child.h

emberCurrentStackTasks#

uint16_t emberCurrentStackTasks (void )

Return a bitmask indicating the stack's current tasks.

Parameters
N/A

The mask EMBER_HIGH_PRIORITY_TASKS defines which tasks are high priority. Devices should not sleep if any high priority tasks are active. Active tasks that are not high priority are waiting for messages to arrive from other devices. If there are active tasks, but no high priority ones, the device may sleep but should periodically wake up and call emberPollForData() in order to receive messages. Parents will hold messages for EMBER_INDIRECT_TRANSMISSION_TIMEOUT milliseconds before discarding them.

Returns

  • A bitmask of the stack's active tasks.


Definition at line 400 of file stack/include/child.h

emberOkToNap#

bool emberOkToNap (void )

Indicate whether the stack is currently in a state where there are no high-priority tasks, allowing the device to sleep.

Parameters
N/A

There may be tasks expecting incoming messages, in which case the device should periodically wake up and call emberPollForData() in order to receive messages. This function can only be called when the node type is EMBER_SLEEPY_END_DEVICE

Returns

  • True if the application may sleep but the stack may be expecting incoming messages.


Definition at line 414 of file stack/include/child.h

emberParentTokenSet#

bool emberParentTokenSet (void )

Indicate whether the parent token has been set by association.

Parameters
N/A

Returns

  • True if the parent token has been set.


Definition at line 424 of file stack/include/child.h

emberOkToHibernate#

bool emberOkToHibernate (void )

Indicate whether the stack currently has any tasks pending.

Parameters
N/A

If no tasks are pending, emberTick() does not need to be called until the next time a stack API function is called. This function can only be called when the node type is EMBER_SLEEPY_END_DEVICE or

Returns

  • True if the application may sleep for as long as it wishes.


Definition at line 435 of file stack/include/child.h

emberOkToLongPoll#

bool emberOkToLongPoll (void )

Indicate whether the stack is currently in a state that does not require the application to periodically poll.

Parameters
N/A

Returns

  • True if the application may stop polling periodically.


Definition at line 446 of file stack/include/child.h

emberStackPowerDown#

void emberStackPowerDown (void )

Immediately turn the radio power completely off.

Parameters
N/A

Calling this function will render all other stack functions except emberStackPowerUp() non-functional until the radio is powered back on.


Definition at line 456 of file stack/include/child.h

emberStackPowerUp#

void emberStackPowerUp (void )

Initialize the radio. Typically called coming out of deep sleep.

Parameters
N/A

For non-sleepy devices, also turns the radio on and leaves it in RX mode.


Definition at line 462 of file stack/include/child.h

EMBER_HIGH_PRIORITY_TASKS#

#define EMBER_HIGH_PRIORITY_TASKS
Value:
(EMBER_OUTGOING_MESSAGES | EMBER_INCOMING_MESSAGES | EMBER_RADIO_IS_ON)

A mask of the tasks that prevent a device from sleeping.


Definition at line 384 of file stack/include/child.h

Function Documentation#

emberChildPower#

int8_t emberChildPower (uint8_t childIndex)

Return radio power value of the child from the given childIndex.

Parameters
N/AchildIndex

The index.

Returns

  • The power of the child or maximum radio power, which is the power value provided by the user while forming/joining a network if there isn't a child at the childIndex specified.


Definition at line 47 of file stack/include/child.h

emberSetChildPower#

void emberSetChildPower (uint8_t childIndex, int8_t newPower)

Set the radio power value for a given child index.

Parameters
N/AchildIndex

The index.

N/AnewPower

The new power value.


Definition at line 54 of file stack/include/child.h

emberGetChildData#

EmberStatus emberGetChildData (uint8_t index, EmberChildData * childData)

Get the EUI64 and node type of the child at the provided index. If there is no child at 'index', it returns EMBER_NOT_JOINED. Possible child indexes run from zero to emberMaxChildCount() - 1.

Parameters
N/Aindex

The index of the child of interest.

N/AchildData

The child's data is copied here.

Returns


Definition at line 75 of file stack/include/child.h

emberSetChildData#

EmberStatus emberSetChildData (uint8_t index, EmberChildData * childData)

Sets the EUI64, node ID, and node type of the child at the provided index in nonvolatile memory. No other data from the childData argument is used or copied. The user is responsible for rebooting the device after calling this API in order to initialize RAM-based child data. Possible child indexes run from zero to emberMaxChildCount() - 1.

Parameters
N/Aindex

The index of the child.

N/AchildData

The child's data.

Returns

Note

  • This API only sets the child data to nonvolatile memory. A reboot is required after calling this API to read the nonvolatile child data and set it to RAM structures. This API does not set other child RAM data, such as power and timeout values.


Definition at line 96 of file stack/include/child.h

emberChildJoinHandler#

void emberChildJoinHandler (uint8_t index, bool joining)

Called by the stack when a child joins or leaves. 'Joining' is true if the child is joining and false if leaving.

Parameters
N/Aindex

The index of the child of interest.

N/Ajoining

True if the child is joining, false if the child is leaving.

The index is the same as the value that should be passed to emberGetChildData() to get this child's data. Note that if the child is leaving, emberGetChildData() will return EMBER_NOT_JOINED if called with this index. If the application includes emberChildJoinHandler(), it must define EMBER_APPLICATION_HAS_CHILD_JOIN_HANDLER in its CONFIGURATION_HEADER


Definition at line 114 of file stack/include/child.h

emberSetKeepAliveMode#

EmberStatus emberSetKeepAliveMode (EmberKeepAliveMode mode)
Parameters
N/Amode

One of the four configurations in the EmberKeepAliveMode.

@ brief Set the keep alive mode.


Definition at line 122 of file stack/include/child.h

emberGetKeepAliveMode#

EmberKeepAliveMode emberGetKeepAliveMode (void )
Parameters
N/A

@ brief Get the keep alive mode.

Returns

  • mode One of the four configurations in the EmberKeepAliveMode.


Definition at line 130 of file stack/include/child.h

emberPollForData#

EmberStatus emberPollForData (void )

Request any pending data from the parent node. This function allows an end device to query its parent for any pending data.

Parameters
N/A

End devices must call this function periodically to maintain contact with their parent. The parent will remove a child if it has not received a poll from it within the configured timeout.

If the end device has lost contact with its parent, emberPollForData() calls ::emberRejoinNetwork(true) and returns EMBER_ERR_FATAL.

The default values for the timeouts are set in config/ember-configuration-defaults.h and can be overridden in the application's configuration header.

Returns


Definition at line 157 of file stack/include/child.h

emberSetMacPollFailureWaitTime#

void emberSetMacPollFailureWaitTime (uint32_t waitBeforeRetryIntervalMs)
Parameters
N/AwaitBeforeRetryIntervalMs

Time in milliseconds the device waits before retrying a data poll when a MAC level data poll fails for any reason. The retry feature can be disabled by setting this value to zero.

@ brief Set the retry interval (in milliseconds) for mac data poll. This function is useful for sleepy end devices. The retry interval is the time in milliseconds the device waits before retrying a data poll when a MAC level data poll fails for any reason. The retry feature can be disabled by setting the retry interval to zero.


Definition at line 173 of file stack/include/child.h

emberPollCompleteHandler#

void emberPollCompleteHandler (EmberStatus status)
Parameters
N/Astatus

An EmberStatus value:

@ brief Called by the stack when a data poll to the parent is complete.

If the application includes emberPollCompleteHandler(), it must define EMBER_APPLICATION_HAS_POLL_COMPLETE_HANDLER within its CONFIGURATION_HEADER


Definition at line 190 of file stack/include/child.h

emberSetMessageFlag#

EmberStatus emberSetMessageFlag (EmberNodeId childId)

Set a flag to indicate that a message is pending for a child. The next time that the child polls, it will be informed that it has a pending message. The message is sent from emberPollHandler, which is called when the child requests data.

Parameters
N/AchildId

The ID of the child that just polled for data.

Returns


Definition at line 204 of file stack/include/child.h

emberClearMessageFlag#

EmberStatus emberClearMessageFlag (EmberNodeId childId)

Clear a flag to indicate that there are no more messages for a child. The next time the child polls, it will be informed that it does not have any pending messages.

Parameters
N/AchildId

The ID of the child that no longer has pending messages.

Returns

  • An EmberStatus value.

    • EMBER_SUCCESS - The next time that the child polls, it will be informed that it does not have any pending messages.

    • EMBER_NOT_JOINED - The child identified by childId is not our child.


Definition at line 217 of file stack/include/child.h

emberPollHandler#

void emberPollHandler (EmberNodeId childId, bool transmitExpected)

Called to allow the application to send a message in response to a poll from a child.

Parameters
N/AchildId

The ID of the child that is requesting data.

N/AtransmitExpected

True if the child is expecting an application- supplied data message. False otherwise.

This function is called when a child polls, provided that the pending message flag is set for that child (see emberSetMessageFlag(). The message should be sent to the child using emberSendUnicast() with the EMBER_APS_OPTION_POLL_RESPONSE option.

If the application includes ::emberPollHanlder(), it must define EMBER_APPLICATION_HAS_POLL_HANDLER in its CONFIGURATION_HEADER.


Definition at line 236 of file stack/include/child.h

emberAddChild#

EmberStatus emberAddChild (EmberNodeId shortId, EmberEUI64 longId, EmberNodeType nodeType)

Add a child to the child/neighbor table only on SoC, allowing direct manipulation of these tables by the application. This can affect the network functionality, and needs to be used wisely. If used appropriately, the application can maintain more than the maximum of children provided by the stack.

Parameters
N/AshortId

The preferred short ID of the node.

N/AlongId

The long ID of the node.

N/AnodeType

The nodetype e.g., EMBER_ROUTER defining, if this would be added to the child table or neighbor table.

Returns


Definition at line 255 of file stack/include/child.h

emberRemoveChild#

EmberStatus emberRemoveChild (EmberEUI64 childEui64)

Remove a node from child/neighbor table only on SoC, allowing direct manipulation of these tables by the application. This can affect the network functionality, and needs to be used wisely.

Parameters
N/AchildEui64

The long ID of the node.

Returns


Definition at line 269 of file stack/include/child.h

emberRemoveNeighbor#

void emberRemoveNeighbor (EmberNodeId shortId, EmberEUI64 longId)

Remove a neighbor from neighbor table only on SoC, allowing direct manipulation of neighbor table by the application. This can affect the network functionality, and needs to be used wisely.

Parameters
N/AshortId

The short ID of the neighbor.

N/AlongId

The long ID of the neighbor.


Definition at line 280 of file stack/include/child.h

emberChildCount#

uint8_t emberChildCount (void )

Return the number of children the node currently has.

Parameters
N/A

Returns

  • The number of children.


Definition at line 288 of file stack/include/child.h

emberRouterChildCount#

uint8_t emberRouterChildCount (void )

Return the number of router children that the node currently has.

Parameters
N/A

Returns

  • The number of router children.


Definition at line 295 of file stack/include/child.h

emberMaxChildCount#

uint8_t emberMaxChildCount (void )

Return the maximum number of children for this node. The return value is undefined for nodes that are not joined to a network.

Parameters
N/A

Returns

  • The maximum number of children.


Definition at line 302 of file stack/include/child.h

emberMaxRouterChildCount#

uint8_t emberMaxRouterChildCount (void )

Return the maximum number of router children for this node. The return value is undefined for nodes that are not joined to a network.

Parameters
N/A

Returns

  • The maximum number of router children.


Definition at line 309 of file stack/include/child.h

emberGetParentNodeId#

EmberNodeId emberGetParentNodeId (void )

Return the parent's node ID. The return value is undefined for nodes without parents (coordinators and nodes that are not joined to a network).

Parameters
N/A

Returns

  • The parent's node ID.


Definition at line 317 of file stack/include/child.h

emberGetParentEui64#

EmberEUI64 emberGetParentEui64 (void )

Return the parent's EUI64. The return value is undefined for nodes without parents (coordinators and nodes that are not joined to a network).

Parameters
N/A

Returns

  • The parent's EUI64.


Definition at line 325 of file stack/include/child.h

Macro Definition Documentation#

emberChildId#

#define emberChildId
Value:
(childIndex)

Convert a child index to a node ID.

Returns

  • The node ID of the child or EMBER_NULL_NODE_ID if there isn't a child at the childIndex specified.


Definition at line 37 of file stack/include/child.h

emberChildIndex#

#define emberChildIndex
Value:
(childId)

Convert a node ID to a child index.

Returns

  • The child index or 0xFF if the node ID does not belong to a child.


Definition at line 62 of file stack/include/child.h