Data Structures

struct EmberEndpointDescription
Endpoint information (a ZigBee Simple Descriptor).
struct EmberEndpoint
Gives the endpoint information for a particular endpoint.

Macros

#define EMBER_MAJOR_VERSION 6
#define EMBER_MINOR_VERSION 7
#define EMBER_PATCH_VERSION 7
#define EMBER_SPECIAL_VERSION 0
#define EMBER_BUILD_NUMBER 347
#define EMBER_FULL_VERSION
#define EMBER_VERSION_TYPE EMBER_VERSION_TYPE_GA
#define SOFTWARE_VERSION EMBER_FULL_VERSION

Functions

void emberStackStatusHandler ( EmberStatus status)
A callback invoked when the status of the stack changes. If the status parameter equals EMBER_NETWORK_UP , the emberGetNetworkParameters() function can be called to get the new network parameters. If any of the parameters are stored in nonvolatile memory by the application, the stored values should be updated.
EmberNetworkStatus emberNetworkState (void)
Returns the current join status.
bool emberStackIsUp (void)
Indicates whether the stack is currently up.
EmberStatus emberWriteNodeData (bool erase)
Writes node data to stack token.
EmberEUI64 emberGetEui64 (void)
Returns the EUI64 ID of the local node.
bool emberIsLocalEui64 ( EmberEUI64 eui64)
Determines whether eui64 is the local node's EUI64 ID.
EmberNodeId emberGetNodeId (void)
Returns the 16-bit node ID of local node on the current logical network.
EmberNodeId emberRadioGetNodeId (void)
Returns the 16-bit node ID of local node on the network it is currently tuned on.
void emberSetManufacturerCode (uint16_t code)
Sets the manufacturer code to the specified value. The manufacturer code is one of the fields of the node descriptor.
void emberSetPowerDescriptor (uint16_t descriptor)
Sets the power descriptor to the specified value. The power descriptor is a dynamic value, therefore this function should be called whenever the value changes.
void emberSetMaximumIncomingTransferSize (uint16_t size)
Sets the maximum incoming transfer size to the specified value. The maximum incoming transfer size is one of the fields of the node descriptor.
void emberSetMaximumOutgoingTransferSize (uint16_t size)
Sets the maximum outgoing transfer size to the specified value. The maximum outgoing transfer size is one of the fields of the node descriptor.
void emberSetDescriptorCapability (uint8_t capability)
Sets the descriptor capability field of the node.
EmberStatus emberGetNetworkParameters ( EmberNetworkParameters *parameters)
Copies the current network parameters into the structure provided by the caller.
EmberStatus emberGetRadioParameters (uint8_t phyIndex, EmberMultiPhyRadioParameters *parameters)
Copies the current radio parameters into the structure provided by the caller.
EmberStatus emberGetNodeType ( EmberNodeType *resultLocation)
Copies the current node type into the location provided by the caller.
EmberStatus emberSetRadioChannel (uint8_t channel)
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.
EmberStatus emberSetLogicalAndRadioChannel (uint8_t channel)
Sets the current logical and physical channel.
uint8_t emberGetRadioChannel (void)
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.
EmberStatus emberSetRadioPower (int8_t power)
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 that using this API on a running network will directly impact the established link qualities which the neighboring nodes have with the node on which it is called. This can lead to disruption of existing routes and erratic network behavior. Note that, if the requested power level is not available on a given radio, this function will use the next higher available power level.
int8_t emberGetRadioPower (void)
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.
void * emberGetRailHandle (void)
Returns the RAIL level handle required to make RAIL API calls. Will return NULL if RAIL is not in use.
EmberPanId emberGetPanId (void)
Returns the local node's PAN ID of the current logical network.
EmberPanId emberRadioGetPanId (void)
Returns the local node's PAN ID of the current radio network.
void emberGetExtendedPanId (uint8_t *resultLocation)
Fetches a node's 8 byte Extended PAN identifier. If this is called when a device is not currently on a network (see emberNetworkState ), the Extended PAN ID returned will be an invalid value.
uint8_t emberGetEndpoint (uint8_t index)
Retrieves the endpoint number for the index'th endpoint. index must be less than the value of emberEndpointCount.
bool emberGetEndpointDescription (uint8_t endpoint, EmberEndpointDescription *result)
Retrieves the endpoint description for the given endpoint.
uint16_t emberGetEndpointCluster (uint8_t endpoint, EmberClusterListId listId, uint8_t listIndex)
Retrieves a cluster ID from one of the cluster lists associated with the given endpoint.
bool emberIsNodeIdValid ( EmberNodeId nodeId)
Determines whether nodeId is valid.
EmberNodeId emberLookupNodeIdByEui64 ( EmberEUI64 eui64)
Returns the node ID that corresponds to the specified EUI64. The node ID is found by searching through all stack tables for the specified EUI64.
EmberStatus emberLookupEui64ByNodeId ( EmberNodeId nodeId, EmberEUI64 eui64Return)
Returns the EUI64 that corresponds to the specified node ID. The EUI64 is found by searching through all stack tables for the specified node ID.
void emberCounterHandler ( EmberCounterType type, EmberCounterInfo info)
A callback invoked to inform the application of the occurrence of an event defined by EmberCounterType , for example, transmissions and receptions at different layers of the stack.
bool emberCounterRequiresPhyIndex ( EmberCounterType type)
bool emberCounterRequiresDestinationNodeId ( EmberCounterType type)
void emberStackTokenChangedHandler (uint16_t tokenAddress)
A callback invoked to inform the application that a stack token has changed.
bool emberRtosIdleHandler (uint32_t *idleTimeMs)
A callback to allow the application to manage idling the MCU.
void emberRtosStackWakeupIsrHandler (void)
A callback to request the application to wake up the stack task.
EmberStatus emberGetNeighbor (uint8_t index, EmberNeighborTableEntry *result)
Copies a neighbor table entry to the structure that result points to. Neighbor table entries are stored in ascending order by node ID, with all unused entries at the end of the table. The number of active neighbors can be obtained using emberNeighborCount() .
EmberStatus emberSetRoutingShortcutThreshold (uint8_t costThresh)
Sets the routing shortcut threshold to directly use a neighbor instead of performing routing.
uint8_t emberGetRoutingShortcutThreshold (void)
Gets the routing shortcut threshold used to separate between directly using a neighbor vs. performing routing.
EmberStatus emberSetInitialNeighborOutgoingCost (uint8_t cost)
Sets neighbor's initial outgoing link cost.
uint8_t emberGetInitialNeighborOutgoingCost (void)
Gets neighbor's initial outgoing link cost.
void emberResetRejoiningNeighborsFC (bool reset)
Indicates whether a rejoining neighbor's incoming FC should be reset.
bool emberIsResetRejoiningNeighborsFCEnabled (void)
Checks if resetting the incoming FC for a rejoining neighbor is enabled.
EmberStatus emberGetNeighborFrameCounter ( EmberEUI64 nodeEui64, uint32_t *returnFrameCounter)
This function gets the last received frame counter as found in the Network Auxiliary header for the specified neighbor or child.
EmberStatus emberGetRouteTableEntry (uint8_t index, EmberRouteTableEntry *result)
Copies a route table entry to the structure that the result points to. Unused route table entries have a destination of 0xFFFF. The route table size can be obtained via emberRouteTableSize() .
uint8_t emberStackProfile (void)
Returns the stack profile of the network which the node has joined.
uint8_t emberTreeDepth (void)
Returns the depth of the node in the network.
uint8_t emberNeighborCount (void)
Returns the number of active entries in the neighbor table.
uint8_t emberRouteTableSize (void)
Returns the size of the route table.
uint8_t emberNextZigbeeSequenceNumber (void)
Increments and returns the Zigbee sequence number.
uint8_t emberGetMaxNwkRetries (void)
Get max number of NWK retries.
EmberStatus emberGetBeaconClassificationParams ( EmberBeaconClassificationParams *param)
API used to get current beacon classification parameter settings.
EmberStatus emberSetBeaconClassificationParams ( EmberBeaconClassificationParams *param)
API used to set current beacon classification parameters.

Variables

const uint8_t emberStackProfileId []
The application must provide a definition for this variable.
uint8_t emberEndpointCount
The application must provide a definition for this variable.
EmberEndpoint emberEndpoints []
If emberEndpointCount is nonzero, the application must provide descriptions for each endpoint.

Radio-specific Functions

EmberStatus emberSetTxPowerMode (uint16_t txPowerMode)
Enables boost power mode and/or the alternate transmit path.
uint16_t emberGetTxPowerMode (void)
Returns the current configuration of boost power mode and alternate transmitter output.
EmberStatus emberSetNodeId ( EmberNodeId nodeId)
Sets the short node ID of the node. Notice that it can only be set if the stack is in the INITAL state.
uint8_t emberGetPhyInterfaceCount (void)
Returns the number of PHY interfaces present.
void emberRadioNeedsCalibratingHandler (void)
The radio calibration callback function.
void emberCalibrateCurrentChannel (void)
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. Calibration can take up to 150 ms. Note if this function is called when the radio is off, it will turn the radio on and leave it on.
void emberSetLongUpTime (bool hasLongUpTime)
sets the device uptime to be long or short the uptime is then advertised in the beacons
void emberSetHubConnectivity (bool connected)
sets the hub connectivity to be true or false the hub connectivity is then advertised in the beacons
bool emberIsUpTimeLong (void)
bool emberIsHubConnected (void)
EmberStatus emberRadioGetSchedulerPriorities ( EmberMultiprotocolPriorities *priorities)
API used to get the current scheduler priorities used for Zigbee multiprotocol operations.
EmberStatus emberRadioSetSchedulerPriorities (const EmberMultiprotocolPriorities *priorities)
API used to set the current scheduler priorities used for Zigbee multiprotocol operations.
EmberStatus emberRadioSetSchedulerSliptime (uint32_t slipTime)
Set the multiprotocol slip time.
EmberStatus emberRadioGetSchedulerSliptime (uint32_t *slipTime)
Get the multiprotocol slip time.

Detailed Description

See stack-info.h for source code.

See also config.h .

This documentation was produced from the following software release and build.

SOFTWARE_VERSION 0x4700 High byte = release number, low byte = patch number

Macro Definition Documentation

EMBER_BUILD_NUMBER

#define EMBER_BUILD_NUMBER   347

EMBER_FULL_VERSION

#define EMBER_FULL_VERSION
Value:
( ((uint16_t) EMBER_MAJOR_VERSION << 12) \
| ((uint16_t) EMBER_MINOR_VERSION << 8) \
| ((uint16_t) EMBER_PATCH_VERSION << 4) \
| ((uint16_t) EMBER_SPECIAL_VERSION ))
#define EMBER_SPECIAL_VERSION
Definition: config.h:37
#define EMBER_MAJOR_VERSION
Definition: config.h:34
#define EMBER_MINOR_VERSION
Definition: config.h:35
#define EMBER_PATCH_VERSION
Definition: config.h:36

EMBER_MAJOR_VERSION

#define EMBER_MAJOR_VERSION   6

EMBER_MINOR_VERSION

#define EMBER_MINOR_VERSION   7

EMBER_PATCH_VERSION

#define EMBER_PATCH_VERSION   7

EMBER_SPECIAL_VERSION

#define EMBER_SPECIAL_VERSION   0

EMBER_VERSION_TYPE

#define EMBER_VERSION_TYPE EMBER_VERSION_TYPE_GA

SOFTWARE_VERSION

#define SOFTWARE_VERSION EMBER_FULL_VERSION

Software version. High byte = release number, low byte = patch number.

Function Documentation

emberCalibrateCurrentChannel()

void emberCalibrateCurrentChannel ( void )

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. Calibration can take up to 150 ms. Note if this function is called when the radio is off, it will turn the radio on and leave it on.

emberCounterHandler()

void emberCounterHandler ( EmberCounterType type,
EmberCounterInfo info
)

A callback invoked to inform the application of the occurrence of an event defined by EmberCounterType , for example, transmissions and receptions at different layers of the stack.

The application must define ::EMBER_APPLICATION_HAS_COUNTER_HANDLER in its CONFIGURATION_HEADER to use this. This function may be called in ISR context, so processing should be kept to a minimum.

Parameters
type Type of the event.
info could map to:
  1. data: For transmission events, the number of retries used. For most other events, this parameter is unused and is set to zero.
  2. phyIndex: use for mac specific counters specifying if they belong to sub-Ghz or 2.4 GHz.
  3. destinationNodeId: identifying which connection/destinationId a specific counter refers to.
  4. Any combination of the parameters above.

emberCounterRequiresDestinationNodeId()

bool emberCounterRequiresDestinationNodeId ( EmberCounterType type )

emberCounterRequiresPhyIndex()

bool emberCounterRequiresPhyIndex ( EmberCounterType type )

emberGetBeaconClassificationParams()

EmberStatus emberGetBeaconClassificationParams ( EmberBeaconClassificationParams * param )

API used to get current beacon classification parameter settings.

emberGetEndpoint()

uint8_t emberGetEndpoint ( uint8_t index )

Retrieves the endpoint number for the index'th endpoint. index must be less than the value of emberEndpointCount.

This function is provided by the stack, using the data from emberEndpoints, unless the application defines EMBER_APPLICATION_HAS_GET_ENDPOINT in its CONFIGURATION_HEADER.

Parameters
index The index of an endpoint (as distinct from its endpoint number). This must be less than the value of emberEndpointCount.
Returns
The endpoint number for the index'th endpoint.

emberGetEndpointCluster()

uint16_t emberGetEndpointCluster ( uint8_t endpoint,
EmberClusterListId listId,
uint8_t listIndex
)

Retrieves a cluster ID from one of the cluster lists associated with the given endpoint.

This function is provided by the stack, using the data from emberEndpoints, unless the application defines ::EMBER_APPLICATION_HAS_GET_ENDPOINT in its CONFIGURATION_HEADER.

Parameters
endpoint The endpoint from which the cluster ID is to be read.
listId The list from which the cluster ID is to be read.
listIndex The index of the desired cluster ID in the list. This value must be less than the length of the list. The length can be found in the EmberEndpointDescription for this endpoint.
Returns
The cluster ID at position listIndex in the specified endpoint cluster list.

emberGetEndpointDescription()

bool emberGetEndpointDescription ( uint8_t endpoint,
EmberEndpointDescription * result
)

Retrieves the endpoint description for the given endpoint.

This function is provided by the stack, using the data from emberEndpoints, unless the application defines ::EMBER_APPLICATION_HAS_GET_ENDPOINT in its ::CONFIGURATION_HEADER.

Parameters
endpoint The endpoint whose description is to be returned.
result A pointer to the location to which to copy the endpoint description.
Returns
True if the description was copied to result, or false if the endpoint is not active.

emberGetEui64()

EmberEUI64 emberGetEui64 ( void )

Returns the EUI64 ID of the local node.

Returns
The 64-bit ID.

emberGetExtendedPanId()

void emberGetExtendedPanId ( uint8_t * resultLocation )

Fetches a node's 8 byte Extended PAN identifier. If this is called when a device is not currently on a network (see emberNetworkState ), the Extended PAN ID returned will be an invalid value.

emberGetInitialNeighborOutgoingCost()

uint8_t emberGetInitialNeighborOutgoingCost ( void )

Gets neighbor's initial outgoing link cost.

Returns
The default cost associated with new neighbor's outgoing links. NOTE: There is no EZSP version of this function yet.

emberGetMaxNwkRetries()

uint8_t emberGetMaxNwkRetries ( void )

Get max number of NWK retries.

Returns the maximum number of NWK retries that will be attempted

Returns
uint8_t Max NWK retries

emberGetNeighbor()

EmberStatus emberGetNeighbor ( uint8_t index,
EmberNeighborTableEntry * result
)

Copies a neighbor table entry to the structure that result points to. Neighbor table entries are stored in ascending order by node ID, with all unused entries at the end of the table. The number of active neighbors can be obtained using emberNeighborCount() .

Parameters
index The index of a neighbor table entry.
result A pointer to the location to which to copy the neighbor table entry.
Returns
EMBER_ERR_FATAL if the index is greater or equal to the number of active neighbors, or if the device is an end device. Returns EMBER_SUCCESS otherwise.

emberGetNeighborFrameCounter()

EmberStatus emberGetNeighborFrameCounter ( EmberEUI64 nodeEui64,
uint32_t * returnFrameCounter
)

This function gets the last received frame counter as found in the Network Auxiliary header for the specified neighbor or child.

Parameters
nodeEui64 The neighbor or child EUI to search.
returnFrameCounter The frame counter variable to fill in.
Returns
EmberStatus depending on whether the frame counter is found in the neighbor or child table.

emberGetNetworkParameters()

EmberStatus emberGetNetworkParameters ( EmberNetworkParameters * parameters )

Copies the current network parameters into the structure provided by the caller.

Parameters
parameters A pointer to an EmberNetworkParameters value into which the current network parameters will be copied.
Returns
An EmberStatus value indicating the success or failure of the command.

emberGetNodeId()

EmberNodeId emberGetNodeId ( void )

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

Returns
The 16-bit ID.

emberGetNodeType()

EmberStatus emberGetNodeType ( EmberNodeType * resultLocation )

Copies the current node type into the location provided by the caller.

Parameters
resultLocation A pointer to an EmberNodeType value into which the current node type will be copied.
Returns
An EmberStatus value that indicates the success or failure of the command.

emberGetPanId()

EmberPanId emberGetPanId ( void )

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

Returns
A PAN ID.

emberGetPhyInterfaceCount()

uint8_t emberGetPhyInterfaceCount ( void )

Returns the number of PHY interfaces present.

Returns
The number of PHY interface(s).

emberGetRadioChannel()

uint8_t emberGetRadioChannel ( void )

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.

emberGetRadioParameters()

EmberStatus emberGetRadioParameters ( uint8_t phyIndex,
EmberMultiPhyRadioParameters * parameters
)

Copies the current radio parameters into the structure provided by the caller.

Parameters
phyIndex The index of the PHY interface for radio parameters.
  • For 2.4 or Subghz only (switched) device, index will be ignored.
  • For simultaneous dual radio, returns radio parameters based on the provided PHY index. parameters A pointer to an EmberMultiPhyRadioParameters value into which the current radio parameters will be copied.
Returns
An EmberStatus value indicating the success or failure of the command.

emberGetRadioPower()

int8_t emberGetRadioPower ( void )

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
The current radio output power, in dBm.

emberGetRailHandle()

void* emberGetRailHandle ( void )

Returns the RAIL level handle required to make RAIL API calls. Will return NULL if RAIL is not in use.

Returns
A RAIL handle

emberGetRouteTableEntry()

EmberStatus emberGetRouteTableEntry ( uint8_t index,
EmberRouteTableEntry * result
)

Copies a route table entry to the structure that the result points to. Unused route table entries have a destination of 0xFFFF. The route table size can be obtained via emberRouteTableSize() .

Parameters
index The index of a route table entry.
result A pointer to the location to which to copy the route table entry.
Returns
EMBER_ERR_FATAL if the index is out of range or the device is an end device, and EMBER_SUCCESS otherwise.

emberGetRoutingShortcutThreshold()

uint8_t emberGetRoutingShortcutThreshold ( void )

Gets the routing shortcut threshold used to separate between directly using a neighbor vs. performing routing.

Returns
the routingShortcutThresh which takes one of the following values: 1, 3, 5, or 7.

emberGetTxPowerMode()

uint16_t emberGetTxPowerMode ( void )

Returns the current configuration of boost power mode and alternate transmitter output.

Returns
The current TX power mode.

emberIsHubConnected()

bool emberIsHubConnected ( void )
Returns
true if there is hub connectivity, false otherwise

emberIsLocalEui64()

bool emberIsLocalEui64 ( EmberEUI64 eui64 )

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.

emberIsNodeIdValid()

bool emberIsNodeIdValid ( EmberNodeId nodeId )

Determines whether nodeId is valid.

Parameters
nodeId A node ID.
Returns
True if nodeId is valid, false otherwise.

emberIsResetRejoiningNeighborsFCEnabled()

bool emberIsResetRejoiningNeighborsFCEnabled ( void )

Checks if resetting the incoming FC for a rejoining neighbor is enabled.

Parameters
void
Returns
::True or False. NOTE: There is no EZSP version of this function yet.

emberIsUpTimeLong()

bool emberIsUpTimeLong ( void )
Returns
true if device uptime is long, false otherwise

emberLookupEui64ByNodeId()

EmberStatus emberLookupEui64ByNodeId ( EmberNodeId nodeId,
EmberEUI64 eui64Return
)

Returns the EUI64 that corresponds to the specified node ID. The EUI64 is found by searching through all stack tables for the specified node ID.

Parameters
nodeId The short ID of the node to look up.
eui64Return The EUI64 of the node is copied here if it is known.
Returns
An EmberStatus value:

emberLookupNodeIdByEui64()

EmberNodeId emberLookupNodeIdByEui64 ( EmberEUI64 eui64 )

Returns the node ID that corresponds to the specified EUI64. The node ID is found by searching through all stack tables for the specified EUI64.

Parameters
eui64 The EUI64 of the node to look up.
Returns
The short ID of the node or EMBER_NULL_NODE_ID if the short ID is not known.

emberNeighborCount()

uint8_t emberNeighborCount ( void )

Returns the number of active entries in the neighbor table.

Returns
The number of active entries in the neighbor table.

emberNetworkState()

EmberNetworkStatus emberNetworkState ( void )

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.

emberNextZigbeeSequenceNumber()

uint8_t emberNextZigbeeSequenceNumber ( void )

Increments and returns the Zigbee sequence number.

Returns
The next Zigbee sequence number.

emberRadioGetNodeId()

EmberNodeId emberRadioGetNodeId ( void )

Returns the 16-bit node ID of local node on the network it is currently tuned on.

Returns
The 16-bit ID.

emberRadioGetPanId()

EmberPanId emberRadioGetPanId ( void )

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

Returns
A PAN ID.

emberRadioGetSchedulerPriorities()

EmberStatus emberRadioGetSchedulerPriorities ( EmberMultiprotocolPriorities * priorities )

API used to get the current scheduler priorities used for Zigbee multiprotocol operations.

Parameters
priorities A pointer to a structure to store the current priorities in. This must not be NULL.
Returns
EMBER_SUCCESS if called in a multiprotocol app and EMBER_INVALID_CALL otherwise.

For more details on what these priorities are and how to use them see UG305, the Dynamic Multiprotocol User Guide.

emberRadioGetSchedulerSliptime()

EmberStatus emberRadioGetSchedulerSliptime ( uint32_t * slipTime )

Get the multiprotocol slip time.

Parameters
slipTime A pointer to the place to store the current slip time
Returns
EMBER_SUCCESS if called in a multiprotocol app and EMBER_INVALID_CALL otherwise.

Use this to get the current value of the multiprotocol slip time used for each transmit at the PHY layer. For more details on slip time see UG305.

emberRadioNeedsCalibratingHandler()

void emberRadioNeedsCalibratingHandler ( void )

The radio calibration callback function.

The Voltage Controlled Oscillator (VCO) can drift with temperature changes. During every call to emberTick() , the stack will check to see if the VCO has drifted. If the VCO has drifted, the stack will call emberRadioNeedsCalibratingHandler() to inform the application that it should perform calibration of the current channel as soon as possible. Calibration can take up to 150 ms. The default callback function implementation provided here performs the calibration immediately. The application can define its own callback by defining ::EMBER_APPLICATION_HAS_CUSTOM_RADIO_CALIBRATION_CALLBACK in its CONFIGURATION_HEADER. It can then failsafe any critical processes or peripherals before calling emberCalibrateCurrentChannel() . The application must call emberCalibrateCurrentChannel() in response to this callback to maintain expected radio performance.

emberRadioSetSchedulerPriorities()

EmberStatus emberRadioSetSchedulerPriorities ( const EmberMultiprotocolPriorities * priorities )

API used to set the current scheduler priorities used for Zigbee multiprotocol operations.

Parameters
priorities A pointer to a structure of the new priorities to use. This must not be NULL.
Returns
EMBER_SUCCESS if called in a multiprotocol app and EMBER_INVALID_CALL otherwise.

For more details on what these priorities are and how to use them see UG305, the Dynamic Multiprotocol User Guide.

emberRadioSetSchedulerSliptime()

EmberStatus emberRadioSetSchedulerSliptime ( uint32_t slipTime )

Set the multiprotocol slip time.

Parameters
slipTime The value to set the slip time to for each transmit.
Returns
EMBER_SUCCESS if called in a multiprotocol app and EMBER_INVALID_CALL otherwise.

Use this to update the slip time passed to the radio scheduler for each transmit from the PHY layer. The smaller this is set the lower the potential multi-protocol induced latency is, but it makes packets more likely to fail to be transmitted. For more details on slip time see UG305.

emberResetRejoiningNeighborsFC()

void emberResetRejoiningNeighborsFC ( bool reset )

Indicates whether a rejoining neighbor's incoming FC should be reset.

Parameters
reset True or False.
Returns
::void NOTE: There is no EZSP version of this function yet.

emberRouteTableSize()

uint8_t emberRouteTableSize ( void )

Returns the size of the route table.

Returns
The size of the route table.

emberRtosIdleHandler()

bool emberRtosIdleHandler ( uint32_t * idleTimeMs )

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

Parameters
idleTimeMs The time in millisecond the stack is allowed to idle.
Returns
True if the application is managing idling the MCU, false otherwise. If this function returns false, the stack will manage idling the MCU.

emberRtosStackWakeupIsrHandler()

void emberRtosStackWakeupIsrHandler ( void )

A callback to request the application to wake up the stack task.

emberSetBeaconClassificationParams()

EmberStatus emberSetBeaconClassificationParams ( EmberBeaconClassificationParams * param )

API used to set current beacon classification parameters.

emberSetDescriptorCapability()

void emberSetDescriptorCapability ( uint8_t capability )

Sets the descriptor capability field of the node.

Parameters
capability The descriptor capability of the local node.

emberSetHubConnectivity()

void emberSetHubConnectivity ( bool connected )

sets the hub connectivity to be true or false the hub connectivity is then advertised in the beacons

emberSetInitialNeighborOutgoingCost()

EmberStatus emberSetInitialNeighborOutgoingCost ( uint8_t cost )

Sets neighbor's initial outgoing link cost.

Parameters
cost The new default cost.
Returns
EMBER_BAD_ARGUMENT if the cost is not any of 0, 1, 3, 5, or 7. Returns EMBER_SUCCESS otherwise NOTE: There is no EZSP version of this function yet.

emberSetLogicalAndRadioChannel()

EmberStatus emberSetLogicalAndRadioChannel ( uint8_t channel )

Sets the current logical and physical channel.

emberSetLongUpTime()

void emberSetLongUpTime ( bool hasLongUpTime )

sets the device uptime to be long or short the uptime is then advertised in the beacons

emberSetManufacturerCode()

void emberSetManufacturerCode ( uint16_t code )

Sets the manufacturer code to the specified value. The manufacturer code is one of the fields of the node descriptor.

Parameters
code The manufacturer code for the local node.

emberSetMaximumIncomingTransferSize()

void emberSetMaximumIncomingTransferSize ( uint16_t size )

Sets the maximum incoming transfer size to the specified value. The maximum incoming transfer size is one of the fields of the node descriptor.

Parameters
size The maximum incoming transfer size for the local node.

emberSetMaximumOutgoingTransferSize()

void emberSetMaximumOutgoingTransferSize ( uint16_t size )

Sets the maximum outgoing transfer size to the specified value. The maximum outgoing transfer size is one of the fields of the node descriptor.

Parameters
size The maximum outgoing transfer size for the local node.

emberSetNodeId()

EmberStatus emberSetNodeId ( EmberNodeId nodeId )

Sets the short node ID of the node. Notice that it can only be set if the stack is in the INITAL state.

Parameters
nodeId Specifies the short ID to be assigned to the node.
Returns
EMBER_SUCCESS if successful; an error code otherwise.

emberSetPowerDescriptor()

void emberSetPowerDescriptor ( uint16_t descriptor )

Sets the power descriptor to the specified value. The power descriptor is a dynamic value, therefore this function should be called whenever the value changes.

Parameters
descriptor The new power descriptor for the local node.

emberSetRadioChannel()

EmberStatus emberSetRadioChannel ( uint8_t channel )

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: When using this API, all devices on a network must use the same channel.

Parameters
channel The desired radio channel.
Returns
An EmberStatus value indicating the success or failure of the command.

emberSetRadioPower()

EmberStatus emberSetRadioPower ( int8_t power )

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 that using this API on a running network will directly impact the established link qualities which the neighboring nodes have with the node on which it is called. This can lead to disruption of existing routes and erratic network behavior. Note that, if the requested power level is not available on a given radio, this function will use the next higher available power level.

Parameters
power A 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.

emberSetRoutingShortcutThreshold()

EmberStatus emberSetRoutingShortcutThreshold ( uint8_t costThresh )

Sets the routing shortcut threshold to directly use a neighbor instead of performing routing.

Parameters
costThresh the routing shortcut value that should be used to directly use a neighbor instead of performing routing.
Returns
::return EMBER_BAD_ARGUMENT if the costThresh is not 1, 3, 5, 7 Returns EMBER_SUCCESS otherwise.

emberSetTxPowerMode()

EmberStatus emberSetTxPowerMode ( uint16_t txPowerMode )

Enables boost power mode and/or the alternate transmit path.

Boost power mode is a high-performance radio mode, which offers increased transmit power and receive sensitivity at the cost of an increase in power consumption. emberInit() calls this function using the power mode and transmitter output settings as specified in the MFG_PHY_CONFIG token (with each bit inverted so that the default token value of 0xffff corresponds to normal power mode and bi-directional RF transmitter output). The application only needs to call emberSetTxPowerMode() to use a power mode or transmitter output setting different than specified in the MFG_PHY_CONFIG token. After the initial call to emberSetTxPowerMode() , the stack will automatically maintain the specified power mode configuration across sleep/wake cycles.

Parameters
txPowerMode Specifies which transmit power mode options should be activated. This parameter should be set to one of the literal values described in stack/include/ember-types.h . Any power option not specified in the txPowerMode parameter will be deactivated.
Returns
EMBER_SUCCESS if successful; an error code otherwise.

emberStackIsUp()

bool emberStackIsUp ( void )

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; it does not indicate whether other nodes are able to communicate with this node.

Returns
True if the stack is up, false otherwise.

emberStackProfile()

uint8_t emberStackProfile ( void )

Returns the stack profile of the network which the node has joined.

Returns
The stack profile.

emberStackStatusHandler()

void emberStackStatusHandler ( EmberStatus status )

A callback invoked when the status of the stack changes. If the status parameter equals EMBER_NETWORK_UP , the emberGetNetworkParameters() function can be called to get the new network parameters. If any of the parameters are stored in nonvolatile memory by the application, the stored values should be updated.

The application is free to begin messaging after it receives the EMBER_NETWORK_UP status. However, routes discovered immediately after the stack comes up may be suboptimal because the routes are based on the neighbor table's information about two-way links with neighboring nodes, which is obtained from periodic ZigBee Link Status messages. It can take two or three link status exchange periods (of 16 seconds each) before the neighbor table has a good estimate of link quality to neighboring nodes. Therefore, the application may improve the quality of initially discovered routes by waiting after startup to give the neighbor table time to be populated.

Parameters
status Stack status. One of the following:

emberStackTokenChangedHandler()

void emberStackTokenChangedHandler ( uint16_t tokenAddress )

A callback invoked to inform the application that a stack token has changed.

Parameters
tokenAddress The address of the stack token that has changed.

emberTreeDepth()

uint8_t emberTreeDepth ( void )

Returns the depth of the node in the network.

Returns
The current depth.

emberWriteNodeData()

EmberStatus emberWriteNodeData ( bool erase )

Writes node data to stack token.

Parameters
bool Indicates whether the node type should be erased.
Returns
The status of the operation and an error code if unsuccessful.

Variable Documentation

emberEndpointCount

uint8_t emberEndpointCount

The application must provide a definition for this variable.

emberEndpoints

EmberEndpoint emberEndpoints[]

If emberEndpointCount is nonzero, the application must provide descriptions for each endpoint.

This can be done either by providing a definition of emberEndpoints or by providing definitions of emberGetEndpoint() , emberGetEndpointDescription() and emberGetEndpointCluster() . Using the array is often simpler, but consumes large amounts of memory if emberEndpointCount is large.

If the application provides definitions for the three functions, it must define EMBER_APPLICATION_HAS_GET_ENDPOINT in its CONFIGURATION_HEADER.

emberStackProfileId

const uint8_t emberStackProfileId[]

The application must provide a definition for this variable.