Stack Information

Silicon Labs Connect Stack API Reference

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

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

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

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

Parameters

nodeType	The 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 ).
nodeId	The node ID of the joining device.

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() 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.

Retrieves the stack counter corresponding to the passed counter type.

Parameters

counterType

An EmberCounterType value indicating the stack counter to be retrieved.

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.

Returns the EUI64 ID of the local node.

Returns

The 64-bit ID.

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

Returns

The 16-bit ID.

Returns an EmberNodeType value indicating the type of the node.

Returns

A PAN ID.

Returns the local node's PAN ID of the current logical network.

Returns

A PAN ID.

Returns the parent's node ID.

Returns

The parent's node ID.

Gets the radio channel, to which a node is set, on the current logical network. The possible return values depend on the radio in use. For a list of available radio channels, see the technical specification for the RF communication module in your Developer Kit.

Returns

The current radio channel.

Gets the radio output power of the current logical network at which a node is operating. Ember radios have discrete power settings. For a list of available power settings, see the technical specification for the RF communication module in your Developer Kit.

Returns

Current radio output power, in dBm.

Determines whether eui64 is the local node's EUI64 ID.

Parameters

eui64

An EUI64 ID.

Returns

TRUE if eui64 is the local node's ID, otherwise FALSE.

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

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

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

There may be tasks 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.

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.

Sets the MAC layer transmission parameters.

Parameters

checkCca	If 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.
maxCcaAttempts	The 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.
minBackoffExp	The 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.
maxBackoffExp	The 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.
maxRetries	The number of transmission retries that is performed if no acknowledgement was received. This parameter is set by default to 3 (which means that a total of 4 transmission attempts will be performed).

Returns

An EmberStatus value indicating whether the MAC parameters were successfully set or the reason of failure.

Sets the channel to use for sending and receiving messages on the current logical network. For a list of available radio channels, see the technical specification for the RF communication module in your Developer Kit.

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

channel

A desired radio channel.

Returns

An EmberStatus value of:

• EMBER_SUCCESS if the stack accepted the channel change.
• EMBER_INVALID_CALL if the node is currently performing frequency hopping.
• EMBER_PHY_INVALID_CHANNEL if the passed channel is invalid.
• EMBER_MAC_BUSY if the MAC is currently performing a high priority task.

Sets the radio output power at which a node is to operate for the current logical network. Ember radios have discrete power settings. For a list of available power settings, see the technical specification for the RF communication module in your Developer Kit. 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. Note: If the requested power level is not available on a given radio, this function uses the next higher available power level.

Parameters

power

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

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

Parameters

radioOn

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

Sets the security key.

Parameters

key	An 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 .

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

Parameters

idleTimeMs

A 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 otherise. If this function returns false, the stack will manage idling the MCU.

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

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

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.

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

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

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

status

Stack status. One of the following: EMBER_NETWORK_UP EMBER_NETWORK_DOWN EMBER_NO_VALID_BEACONS EMBER_JOIN_SCAN_FAILED EMBER_JOIN_FAILED EMBER_JOIN_DENIED EMBER_JOIN_TIMEOUT EMBER_MAC_SYNC_TIMEOUT