EmberZNet API relating to end device children.

Functions

EmberNodeId emberChildId (uint8_t childIndex)
 Converts a child index to a node ID.
 
int8_t emberChildPower (uint8_t childIndex)
 This function returns radio power value of the child from the given childIndex.
 
void emberSetChildPower (uint8_t childIndex, int8_t newPower)
 This function sets the radio power value for a given child index.
 
uint8_t emberChildIndex (EmberNodeId childId)
 Converts a node ID to a child index.
 
EmberStatus emberGetChildData (uint8_t index, EmberChildData *childData)
 Gets 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.
 
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.
 
EmberStatus emberSetKeepAliveMode (EmberKeepAliveMode mode)
 
EmberKeepAliveMode emberGetKeepAliveMode (void)
 
EmberStatus emberPollForData (void)
 Requests any pending data from the parent node. This function allows an end device to query its parent for any pending data.
 
void emberSetMacPollFailureWaitTime (uint8_t waitBeforeRetryIntervalSec)
 
void emberPollCompleteHandler (EmberStatus status)
 
EmberStatus emberSetMessageFlag (EmberNodeId childId)
 Sets a flag to indicate that there is a message 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.
 
EmberStatus emberClearMessageFlag (EmberNodeId childId)
 Clears 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.
 
uint8_t emberChildCount (void)
 Returns the number of children the node currently has.
 
uint8_t emberRouterChildCount (void)
 Returns the number of router children that the node currently has.
 
uint8_t emberMaxChildCount (void)
 Returns the maximum number of children for this node. The return value is undefined for nodes that are not joined to a network.
 
uint8_t emberMaxRouterChildCount (void)
 Returns the maximum number of router children for this node. The return value is undefined for nodes that are not joined to a network.
 
EmberNodeId emberGetParentNodeId (void)
 Returns 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 emberGetParentEui64 (void)
 Returns the parent's EUI64. The return value is undefined for nodes without parents (coordinators and nodes that are not joined to a network).

Power Management

enum  {
  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
}
 Defines tasks that are taken into account when dealing with sleep related behavior.
 
uint16_t emberCurrentStackTasks (void)
 Returns a bitmask indicating the stack's current tasks.
 
bool emberOkToNap (void)
 Indicates whether the stack is currently in a state where there are no high-priority tasks, allowing the device to sleep.
 
bool emberParentTokenSet (void)
 Indicates whether the parent token has been set by association.
 
bool emberOkToHibernate (void)
 Indicates whether the stack currently has any tasks pending.
 
bool emberOkToLongPoll (void)
 Indicates whether the stack is currently in a state that does not require the application to periodically poll.
 
void emberStackPowerDown (void)
 Immediately turns the radio power completely off.
 
void emberStackPowerUp (void)
 Initializes 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.

Detailed Description

EmberZNet API relating to end device children.

See child.h for source code.

Macro Definition Documentation

◆ EMBER_HIGH_PRIORITY_TASKS

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

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

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

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

Enumerator
EMBER_OUTGOING_MESSAGES 

There are messages waiting for transmission.

EMBER_INCOMING_MESSAGES 

One or more incoming messages 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 .

Function Documentation

◆ emberChildCount()

uint8_t emberChildCount ( void  )

Returns the number of children the node currently has.

Returns
The number of children.

◆ emberChildId()

EmberNodeId emberChildId ( uint8_t  childIndex)

Converts a child index to a node ID.

Parameters
childIndexThe index.
Returns
The node ID of the child or EMBER_NULL_NODE_ID if there isn't a child at the childIndex specified.

◆ emberChildIndex()

uint8_t emberChildIndex ( EmberNodeId  childId)

Converts a node ID to a child index.

Parameters
childIdThe node ID of the child.
Returns
The child index or 0xFF if the node ID does not belong to a child.

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

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

Parameters
indexThe index of the child of interest.
joiningTrue if the child is joining, false if the child is leaving.

◆ emberChildPower()

int8_t emberChildPower ( uint8_t  childIndex)

This function returns radio power value of the child from the given childIndex.

Parameters
childIndexThe 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.

◆ emberClearMessageFlag()

EmberStatus emberClearMessageFlag ( EmberNodeId  childId)

Clears 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
childIdThe 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.

◆ emberCurrentStackTasks()

uint16_t emberCurrentStackTasks ( void  )

Returns a bitmask indicating the stack's current tasks.

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.

◆ emberGetChildData()

EmberStatus emberGetChildData ( uint8_t  index,
EmberChildData childData 
)

Gets 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
indexThe index of the child of interest.
childDataThe child's data is copied here.
Returns
Returns EMBER_SUCCESS if a child is found at that index, EMBER_NOT_JOINED if not.

◆ emberGetKeepAliveMode()

EmberKeepAliveMode emberGetKeepAliveMode ( void  )

@ brief This function is useful to get the keep alive mode

Returns
mode could be one of the 4 configuration in EmberKeepAliveMode

◆ emberGetParentEui64()

EmberEUI64 emberGetParentEui64 ( void  )

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

Returns
The parent's EUI64.

◆ emberGetParentNodeId()

EmberNodeId emberGetParentNodeId ( void  )

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

Returns
The parent's node ID.

◆ emberMaxChildCount()

uint8_t emberMaxChildCount ( void  )

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

Returns
The maximum number of children.

◆ emberMaxRouterChildCount()

uint8_t emberMaxRouterChildCount ( void  )

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

Returns
The maximum number of router children.

◆ emberOkToHibernate()

bool emberOkToHibernate ( void  )

Indicates whether the stack currently has any tasks pending.

If there are no pending tasks, 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.

◆ emberOkToLongPoll()

bool emberOkToLongPoll ( void  )

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

Returns
True if the application may stop polling periodically.

◆ emberOkToNap()

bool emberOkToNap ( void  )

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

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.

◆ emberParentTokenSet()

bool emberParentTokenSet ( void  )

Indicates whether the parent token has been set by association.

Returns
True if the parent token has been set.

◆ emberPollCompleteHandler()

void emberPollCompleteHandler ( EmberStatus  status)

@ brief This is 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

Parameters
statusAn EmberStatus value:

◆ emberPollForData()

EmberStatus emberPollForData ( void  )

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

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
An EmberStatus value:

◆ emberPollHandler()

void emberPollHandler ( EmberNodeId  childId,
bool  transmitExpected 
)

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

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.

Parameters
childIdThe ID of the child that is requesting data.
transmitExpectedTrue if the child is expecting an application- supplied data message. False otherwise.

◆ emberRouterChildCount()

uint8_t emberRouterChildCount ( void  )

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

Returns
The number of router children.

◆ emberSetChildPower()

void emberSetChildPower ( uint8_t  childIndex,
int8_t  newPower 
)

This function sets the radio power value for a given child index.

Parameters
childIndexThe index.
newPowerThe new power value.

◆ emberSetKeepAliveMode()

EmberStatus emberSetKeepAliveMode ( EmberKeepAliveMode  mode)

@ brief This function is useful to set the keep alive mode

Parameters
modecould be one of the 4 configuration in EmberKeepAliveMode

◆ emberSetMacPollFailureWaitTime()

void emberSetMacPollFailureWaitTime ( uint8_t  waitBeforeRetryIntervalSec)

@ brief This function is useful to sleepy end devices. This function will set the retry interval (in seconds) for mac data poll. This interval is the time in seconds the device waits before retrying a data poll when a MAC level data poll fails for any reason.

Parameters
waitBeforeRetryIntervalSecTime in seconds the device waits before retrying a data poll when a MAC level data poll fails for any reason

◆ emberSetMessageFlag()

EmberStatus emberSetMessageFlag ( EmberNodeId  childId)

Sets a flag to indicate that there is a message 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
childIdThe ID of the child that just polled for data.
Returns
An EmberStatus value.
  • EMBER_SUCCESS - The next time that the child polls, it will be informed that it has pending data.
  • EMBER_NOT_JOINED - The child identified by childId is not our child.

◆ emberStackPowerDown()

void emberStackPowerDown ( void  )

Immediately turns the radio power completely off.

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

◆ emberStackPowerUp()

void emberStackPowerUp ( void  )

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

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