Stack Information

Connect API for accessing and modifying stack states and behaviors. More...

Macros

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

Handlers

void emberStackStatusHandler (EmberStatus status)
 A callback invoked when the status of the stack changes. More...
 
void emberChildJoinHandler (EmberNodeType nodeType, EmberNodeId nodeId)
 This handler is invoked at coordinator, range extender, or mac mode nodes when a new child has joined the device. More...
 
void emberStackIsrHandler (void)
 This handler is invoked in ISR context when certain stack-related ISR routines fire. More...
 
bool emberStackIdleHandler (uint32_t *idleTimeMs)
 A callback to allow the application to manage idling the MCU. More...
 
void emberRadioNeedsCalibratingHandler (void)
 The radio calibration callback function. More...
 

APIs

void emberStackPowerDown (void)
 Immediately turns the radio power completely off. More...
 
void emberStackPowerUp (void)
 Power up the radio. Typically called coming out of sleep. More...
 
EmberNetworkStatus emberNetworkState (void)
 Return the current join status. More...
 
bool emberStackIsUp (void)
 Indicate whether the stack is currently up. More...
 
EmberStatus emberSetSecurityKey (EmberKeyData *key)
 Set the security key. More...
 
EmberStatus emberGetCounter (EmberCounterType counterType, uint32_t *count)
 Retrieve the stack counter corresponding to the passed counter type. More...
 
EmberStatus emberSetRadioChannel (uint8_t channel)
 Set the channel to use for sending and receiving messages on the current network. The available channels depend on the radio config you use, and channels can differ more than the frequency if it's a multi-PHY config. More...
 
uint8_t emberGetRadioChannel (void)
 Get the radio channel, to which a node is set, on the current network. The available channels depend on the radio config you use, and channels can differ more than the frequency if it's a multi-PHY config. More...
 
void emberCalibrateCurrentChannel (void)
 Perform image rejection calibration on the current channel. The stack will notify the application of the need for channel calibration via the emberRadioNeedsCalibratingHandler() callback function during emberTick(). This function should only be called from within the context of the emberRadioNeedsCalibratingHandler() callback function. Note if this function is called when the radio is off, it will turn the radio on and leave it on. More...
 
EmberStatus emberSetRadioPower (int8_t power)
 Set the radio output power at which a node is to operate for the current network. The radio has a finite power resolution, so it will approximate the requested power with the closest possible value at or below the requested value. More...
 
int8_t emberGetRadioPower (void)
 Get the radio output power of the current network at which a node is operating. This might be different to what you set using emberSetRadioPower because the radio has a finite power resolution, and emberSetRadioPower must approximate to the closest possible value at or below the requested value. This API however returns with the actual setting. More...
 
EmberStatus emberSetRadioPowerMode (bool radioOn)
 Allow the application to turn the radio on/off. This API is intended for use with direct devices only. More...
 
EmberStatus emberSetMacParams (bool checkCca, uint8_t maxCcaAttempts, uint8_t minBackoffExp, uint8_t maxBackoffExp, uint8_t maxRetries)
 Sets the MAC layer transmission parameters. More...
 
EmberStatus emberMacGetParentAddress (EmberMacAddress *parentAddress)
 An API to retrieve the parent address. This API can be invoked only for nodes of EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE type. More...
 
uint32_t emberStackIdleTimeMs (uint16_t *currentStackTasks)
 Return the time in milliseconds the stack could idle for. More...
 
uint16_t emberCurrentStackTasks (void)
 Return a bitmask indicating the stack's current tasks. More...
 
bool emberOkToNap (void)
 Indicate whether the stack is currently in a state with no high-priority tasks and may sleep. More...
 
bool emberOkToHibernate (void)
 Indicate whether the stack currently has any pending tasks. More...
 
EmberEUI64 emberGetEui64 (void)
 Return the EUI64 ID of the local node. More...
 
bool emberIsLocalEui64 (EmberEUI64 eui64)
 Determines whether eui64 is the local node's EUI64 ID. EUI64 is accessible easily in SoC mode, but in Host-NCP, the address is stored on the NCP. This API can be used on the Host to compare a value with the locally stored one. More...
 
EmberNodeId emberGetNodeId (void)
 Return the 16-bit node ID of local node on the current network. More...
 
EmberPanId emberGetPanId (void)
 Return the local node's PAN ID of the current network. More...
 
EmberNodeType emberGetNodeType (void)
 Return an EmberNodeType value indicating the type of the node. More...
 
EmberNodeId emberGetParentId (void)
 Return the parent's node ID. More...
 

Detailed Description

Connect API for accessing and modifying stack states and behaviors.

See stack-info.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.

Definition at line 27 of file stack-info.h.

Function Documentation

◆ emberCalibrateCurrentChannel()

void emberCalibrateCurrentChannel ( void  )

Perform image rejection calibration on the current channel. The stack will notify the application of the need for channel calibration via the emberRadioNeedsCalibratingHandler() callback function during emberTick(). This function should only be called from within the context of the emberRadioNeedsCalibratingHandler() callback function. Note if this function is called when the radio is off, it will turn the radio on and leave it on.

◆ emberChildJoinHandler()

void emberChildJoinHandler ( EmberNodeType  nodeType,
EmberNodeId  nodeId 
)

This handler is invoked at coordinator, range extender, or mac mode nodes when a new child has joined the device.

Parameters
[in]nodeTypeThe role of the joining device (EMBER_STAR_RANGE_EXTENDER, EMBER_STAR_END_DEVICE, EMBER_STAR_SLEEPY_END_DEVICE, EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE).
[in]nodeIdThe node ID of the joining device.

◆ emberCurrentStackTasks()

uint16_t emberCurrentStackTasks ( void  )

Return 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() to receive messages. Parents will hold messages for EMBER_INDIRECT_TRANSMISSION_TIMEOUT_MS milliseconds before discarding them.

Returns
A bitmask of the stack's active tasks.

◆ emberGetCounter()

EmberStatus emberGetCounter ( EmberCounterType  counterType,
uint32_t *  count 
)

Retrieve the stack counter corresponding to the passed counter type.

Parameters
[in]counterTypeAn EmberCounterType value indicating the stack counter to be retrieved.
[out]countThe counter of the requested counterType is returned here
Returns
An EmberStatus value of EMBER_SUCCESS if the stack counter was successfully retrieved. An EmberStatus value of EMBER_INVALID_CALL if the passed counterType is invalid. An EmberStatus value of EMBER_LIBRARY_NOT_PRESENT if the stack counter library is not present.

◆ emberGetEui64()

EmberEUI64 emberGetEui64 ( void  )

Return the EUI64 ID of the local node.

Returns
The 64-bit ID.

◆ emberGetNodeId()

EmberNodeId emberGetNodeId ( void  )

Return the 16-bit node ID of local node on the current network.

Returns
The 16-bit ID. Byte order is little endian.

◆ emberGetNodeType()

EmberNodeType emberGetNodeType ( void  )

Return an EmberNodeType value indicating the type of the node.

Returns
The node type.

◆ emberGetPanId()

EmberPanId emberGetPanId ( void  )

Return the local node's PAN ID of the current network.

Returns
The PAN ID.

◆ emberGetParentId()

EmberNodeId emberGetParentId ( void  )

Return the parent's node ID.

Returns
The parent's node ID.

◆ emberGetRadioChannel()

uint8_t emberGetRadioChannel ( void  )

Get the radio channel, to which a node is set, on the current network. The available channels depend on the radio config you use, and channels can differ more than the frequency if it's a multi-PHY config.

Returns
The current radio channel.

◆ emberGetRadioPower()

int8_t emberGetRadioPower ( void  )

Get the radio output power of the current network at which a node is operating. This might be different to what you set using emberSetRadioPower because the radio has a finite power resolution, and emberSetRadioPower must approximate to the closest possible value at or below the requested value. This API however returns with the actual setting.

Returns
Current radio output power, in dBm.

◆ emberIsLocalEui64()

bool emberIsLocalEui64 ( EmberEUI64  eui64)

Determines whether eui64 is the local node's EUI64 ID. EUI64 is accessible easily in SoC mode, but in Host-NCP, the address is stored on the NCP. This API can be used on the Host to compare a value with the locally stored one.

Parameters
[in]eui64An EUI64 ID.
Returns
true if eui64 is the local node's ID, otherwise false.

◆ emberMacGetParentAddress()

EmberStatus emberMacGetParentAddress ( EmberMacAddress parentAddress)

An API to retrieve the parent address. This API can be invoked only for nodes of EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE type.

Returns
An EmberStatus value of EMBER_SUCCESS if the parent address was successfully retrieved, otherwise an EmberStatus value indicating the reason of failure.

◆ emberNetworkState()

EmberNetworkStatus emberNetworkState ( void  )

Return the current join status.

Returns a value indicating whether the node is joining, joined to, or leaving a network.

Returns
An EmberNetworkStatus value indicating the current join status.

◆ emberOkToHibernate()

bool emberOkToHibernate ( void  )

Indicate whether the stack currently has any pending tasks.

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

Returns
true if the application may sleep for as long as it wishes.

◆ emberOkToNap()

bool emberOkToNap ( void  )

Indicate whether the stack is currently in a state with no high-priority tasks and may sleep.

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

Returns
true if the application may sleep but the stack may be expecting incoming messages.

◆ emberRadioNeedsCalibratingHandler()

void emberRadioNeedsCalibratingHandler ( void  )

The radio calibration callback function.

This handler is invoked by the stack upon receiving a "calibration needed" event from the radio to inform the application that it should perform calibration of the current channel as soon as possible using the emberCalibrateCurrentChannel() API. While calibration only takes tens of microseconds, the application can failsafe any critical processes or peripherals before calling emberCalibrateCurrentChannel(). The application must call emberCalibrateCurrentChannel() in response to this callback to maintain expected radio performance.

◆ emberSetMacParams()

EmberStatus emberSetMacParams ( bool  checkCca,
uint8_t  maxCcaAttempts,
uint8_t  minBackoffExp,
uint8_t  maxBackoffExp,
uint8_t  maxRetries 
)

Sets the MAC layer transmission parameters.

Parameters
[in]checkCcaIf set to true, the node performs a clear channel assessment prior to transmit a packet. If the channel is not clear, a random backoff is performed. If this is set to false, no clear channel assessment is performed and the packet is transmitted immediately. This parameter is by default set to true.
[in]maxCcaAttemptsThe maximum number of clear channel assessment attempts that are performed prior to fail to transmit a packet with EMBER_PHY_TX_CCA_FAIL status. This parameter is set by default to 4. Note: this is meaningful only if the checkCca parameter is set to true.
[in]minBackoffExpThe backoff exponent used if the initial channel clear assessment fails. This parameter is set by default to 3. Note: this is meaningful only if the checkCca parameter is set to true.
[in]maxBackoffExpThe backoff exponent used if the final channel clear assessment fails. This parameter is set by default to 5. Note: this is meaningful only if the checkCca parameter is set to true.
[in]maxRetriesThe number of transmission retries that is performed if no acknowledgment was received. This parameter is set by default to 3 (which means that a total of 4 transmission attempts will be performed).
Note
The CSMA/CA (CCA) values are directly used in RAIL's RAIL_CsmaConfig_t and further information can be found in the RAIL API documentation.
Returns
An EmberStatus value indicating whether the MAC parameters were successfully set or the reason of failure.

◆ emberSetRadioChannel()

EmberStatus emberSetRadioChannel ( uint8_t  channel)

Set the channel to use for sending and receiving messages on the current network. The available channels depend on the radio config you use, and channels can differ more than the frequency if it's a multi-PHY config.

Note
Care should be taken when using this API. All devices on a network must use the same channel. Each call triggers a token write. Excessive usage might cause flash to wear-out.
Parameters
[in]channelA desired radio channel.
Returns
An EmberStatus value of:

◆ emberSetRadioPower()

EmberStatus emberSetRadioPower ( int8_t  power)

Set the radio output power at which a node is to operate for the current network. The radio has a finite power resolution, so it will approximate the requested power with the closest possible value at or below the requested value.

Note
Care should be taken when using this API on a running network, because it directly impacts the established link qualities neighboring nodes have with the node on which it is called. This can lead to disruption of existing routes and erratic network behavior.
Parameters
[in]powerDesired radio output power, in dBm.
Returns
An EmberStatus value indicating the success or failure of the command. Failure indicates that the requested power level is out of range.

◆ emberSetRadioPowerMode()

EmberStatus emberSetRadioPowerMode ( bool  radioOn)

Allow the application to turn the radio on/off. This API is intended for use with direct devices only.

Parameters
[in]radioOnIf this parameter is true, the radio is turned on, otherwise it's turned off.
Returns
An EmberStatus value indicating the success or failure of the command. Failure indicates that the node type is a type other than EMBER_DIRECT_DEVICE.

◆ emberSetSecurityKey()

EmberStatus emberSetSecurityKey ( EmberKeyData key)

Set the security key.

Parameters
[out]keyAn EmberKeyData value containing the security key to be set.
Returns
An EmberStatus value of EMBER_SUCCESS if the key was successfully set. Otherwise, it returns an EmberStatus value of EMBER_INVALID_CALL.

◆ emberStackIdleHandler()

bool emberStackIdleHandler ( uint32_t *  idleTimeMs)

A callback to allow the application to manage idling the MCU.

Parameters
[in,out]idleTimeMsA pointer to the time in millisecond the stack is allowed to idle. If the application decides to manage idling the MCU, it should update the passed value with the actual time the MCU was idled.
Returns
true if the application is managing idling the MCU, false otherwise. If this function returns false, the stack will manage idling the MCU.

◆ emberStackIdleTimeMs()

uint32_t emberStackIdleTimeMs ( uint16_t *  currentStackTasks)

Return the time in milliseconds the stack could idle for.

Parameters
[in]currentStackTasksA pointer to an integer that is written with the active stack tasks at the time of the API call.
Returns
Allowed idle time in milliseconds.

◆ emberStackIsrHandler()

void emberStackIsrHandler ( void  )

This handler is invoked in ISR context when certain stack-related ISR routines fire.

◆ emberStackIsUp()

bool emberStackIsUp ( void  )

Indicate whether the stack is currently up.

Returns true if the stack is joined to a network and ready to send and receive messages. This reflects only the state of the local node and does not indicate whether or not other nodes are able to communicate with this node.

Returns
true if the stack is up, false otherwise.

◆ emberStackPowerDown()

void emberStackPowerDown ( void  )

Immediately turns the radio power completely off.

After calling this function, do not call any other stack function except emberStackPowerUp() because all other stack functions require that the radio is powered to operate properly.

◆ emberStackPowerUp()

void emberStackPowerUp ( void  )

Power up the radio. Typically called coming out of sleep.

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

◆ emberStackStatusHandler()

void emberStackStatusHandler ( EmberStatus  status)

A callback invoked when the status of the stack changes.

The application is free to begin messaging once it receives the EMBER_NETWORK_UP status.

Parameters
[in]statusStack status. One of the following: