Network Utilities
Thread Stack API Reference

Network Utilities.

Data Structures

struct EmberNetworkParameters
An application structure to hold useful network parameters.
struct EmberRipEntry
Structure that holds information about a routing table entry for use on the application. See emberGetRipEntry .
struct EmberChildEntry
struct EmberMacBeaconData
Structure to hold information about an 802.15.4 beacon for use on the application.
struct EmberSecurityParameters
Values of security parameters for use in forming or joining a network.

Macros

#define EMBER_HIGH_PRIORITY_TASKS ( EMBER_OUTGOING_MESSAGES | EMBER_INCOMING_MESSAGES | EMBER_RADIO_IS_ON )
A mask of the high priority tasks that prevent a device from sleeping. Devices should not sleep if any high priority tasks are active.
#define EMBER_CHILD_IS_SLEEPY_FLAG 0x0001
Flag values for EmberChildEntry .
#define EMBER_CHILD_IS_FULL_THREAD_DEVICE_FLAG 0x0002
#define ISLAND_ID_SIZE 5
Size of the island (aka network fragment) ID.
#define EMBER_NETWORK_KEY_OPTION BIT (0)
Define the various options for setting network parameters. Note: Only the EMBER_NETWORK_KEY_OPTION works at this time.
#define EMBER_PSK_JOINING_OPTION BIT (1)
#define EMBER_ECC_JOINING_OPTION BIT (2)

Typedefs

typedef uint8_t EmberTokenId
Read token values stored on the Ember chip.
typedef uint8_t EmberMfgTokenId
Token identifier used when reading and writing manufacturing tokens.

Enumerations

enum EmberIdleRadioState {
IDLE_WITH_RADIO_ON ,
IDLE_WITH_POLLING ,
IDLE_WITH_RADIO_OFF
}
Required radio state while stack is idle.
enum {
EMBER_OUTGOING_MESSAGES = 0x01,
EMBER_INCOMING_MESSAGES = 0x02,
EMBER_RADIO_IS_ON = 0x04
}
This function defines tasks that prevent the stack from sleeping.
enum {
EMBER_GET_CHILD_ENTRY_SUCCESS ,
EMBER_GET_CHILD_ENTRY_FAILURE
}
Status values passed to emberGetChildEntryReturn() .
enum EmberResetCause {
EMBER_RESET_UNKNOWN ,
EMBER_RESET_FIB ,
EMBER_RESET_BOOTLOADER ,
EMBER_RESET_EXTERNAL ,
EMBER_RESET_POWERON ,
EMBER_RESET_WATCHDOG ,
EMBER_RESET_SOFTWARE ,
EMBER_RESET_CRASH ,
EMBER_RESET_FLASH ,
EMBER_RESET_FATAL ,
EMBER_RESET_FAULT ,
EMBER_RESET_BROWNOUT
}
Enumerate the various chip reset causes.
enum { EMBER_CHANNEL_CAL_DATA_TOKEN }
Enumerate the various token values that can be retrieved by the application.
enum {
EMBER_CUSTOM_EUI_64_MFG_TOKEN ,
EMBER_EZSP_STORAGE_MFG_TOKEN ,
EMBER_CTUNE_MFG_TOKEN
}
Enumerate the various manufacturing token values that can be read or written by the application.

Functions

void emberInit (void)
This function initializes the Ember stack.
void emberInitReturn ( EmberStatus status)
This function provides the result of a call to emberInit() .
void emberTick (void)
A periodic tick routine that must be called in the application's main event loop.
void emberResetNetworkState (void)
This function erases the network state stored in nonvolatile memory after which the network status will be EMBER_NO_NETWORK. This function should not be called to rejoin a former network; use emberResumeNetwork() instead. There may be difficulties joining a former network after resetting the network state, due to security considerations.
void emberResetNetworkStateReturn ( EmberStatus status)
This function provides the result of a call to emberResetNetworkState() .
uint32_t emberStackIdleTimeMs ( EmberIdleRadioState *radioStateResult)
This function returns the time the stack will be idle, in milliseconds. Also sets radioStateResult to the required radio state while the stack is idle.
bool emberOkToNap (void)
This function indicates whether the stack is currently in a state where there are no high priority tasks and may sleep.
void emberOkToNapReturn (uint8_t stateMask)
If implementing event-driven sleep on an NCP host, this method will return the bitmask indicating the stack's current tasks. (see enum above)
void emberEventDelayUpdatedFromIsrHandler ( Event *event)
This method is called any time an event is scheduled from within an ISR context. It can be used to determine when to stop a long running sleep to see what application or stack events now need to be processed.
void emberStackPrepareForPowerDown (void)
This function gets the stack ready for power down, or deep sleep. Purges the MAC indirect queue, and empties the phy-to-mac and mac-to-network queues.
bool emberStackPreparingForPowerDown (void)
This function returns true if the stack is currently emptying any message queues or false if the MAC queue is currently not empty.
void emberStackPowerDown (void)
Immediately turns the radio power completely off.
void emberStackPowerUp (void)
This function initializes the radio. Typically called coming out of deep sleep.
void emberStackPollForData (uint32_t pollMs)
For sleepy hosts, use this call to have the stack manage polling for sleepy end devices. In a host/NCP setup, this means that the NCP app will take care of periodic data polling.
void emberStackPollForDataReturn ( EmberStatus status)
This function provides the result of a call to emberStackPollForData() .
void emberPollForData (void)
Use this call if setting up polling for sleepy end devices on the application.
void emberPollForDataReturn ( EmberStatus status)
This function provides the result of a call to emberPollForData() .
const EmberEui64 * emberEui64 (void)
This function returns the EUI64 of the Ember chip.
EmberNetworkStatus emberNetworkStatus (void)
This function returns the current status of the network. Prior to calling emberInitNetwork(), the status is EMBER_NETWORK_UNINITIALIZED.
void emberNetworkStatusHandler ( EmberNetworkStatus newNetworkStatus, EmberNetworkStatus oldNetworkStatus, EmberJoinFailureReason reason)
This function reports a change to the network status. For example, the network status changes while going through the joining process, or while reattaching to the network, which can happen for a variety of reasons. In particular, after issuing a form, join, resume, or attach command, the application knows that the device is on the network and ready to communicate when this handler is called with a newNetworkStatus of EMBER_JOINED_NETWORK_ATTACHED.
void emberGetNetworkParameters ( EmberNetworkParameters *parameters)
This function fetches the current network parameters into the supplied pointer.
EmberPanId emberGetPanId (void)
This function returns the pan id of the network.
void emberGetRipEntry (uint8_t index)
This function gets the EmberRipEntry at the specified index of the RIP table. The result is returned to the application via the emberGetRipEntryReturn() callback.
void emberGetRipEntryReturn (uint8_t index, const EmberRipEntry *entry)
This function provides the result of a call to emberGetRipEntry() .
void emberGetChildEntry (uint8_t index)
Get the next valid EmberChildEntry whose index is no lower than the supplied index. The result is returned to the application via the emberGetChildEntryReturn() callback.
void emberGetChildEntryReturn (uint8_t status, uint8_t index, uint8_t childTableSize, const EmberChildEntry *entry, const EmberIpv6Address *addresses, uint8_t addressCount)
This callback returns the results of a call to emberGetChildEntry() . A status of EMBER_GET_CHILD_ENTRY_SUCCESS indicates a valid entry is being returned in the EmberChildEntry argument, located at the supplied index in the child table of size childTableSize. Note that the index returned is the smallest index not less than the index that was supplied to emberGetChildEntry() , which contains a valid child entry.
void emberGetCounter ( EmberCounterType type)
This function gets the value for the specified counter. The result is returned to the application via emberGetCounterReturn() .
void emberGetCounterReturn ( EmberCounterType type, uint16_t value)
This function provides the result of a call to emberGetCounter() .
void emberClearCounters (void)
This function resets all counter values to 0.
void emberCounterHandler ( EmberCounterType type, uint16_t increment)
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.
uint16_t emberCounterValueHandler ( EmberCounterType type)
A callback invoked to query the application for the countervalue of an event defined by EmberCounterType.
void emberResetCounterHandler ( EmberCounterType type)
A callback invoked to the application to reset the countervalue of an event defined by EmberCounterType.
bool emberForwardIpv6Packet (const uint8_t *packet, const uint16_t packetLength)
This API provides a means to forward a raw IPv6 packet on the mesh.
void emberStartScan ( EmberNetworkScanType scanType, uint32_t channelMask, uint8_t duration)
This function starts a scan. Note that while a scan can be initiated while the node is currently joined to a network, the node will generally be unable to communicate with its PAN during the scan period, so care should be taken when performing scans of any significant duration while presently joined to an existing PAN.
void emberEnergyScanHandler (uint8_t channel, int8_t maxRssiValue)
This function reports the maximum RSSI value measured on the channel.
void emberActiveScanHandler (const EmberMacBeaconData *beaconData)
This function reports an incoming beacon during an active scan.
void emberScanReturn ( EmberStatus status)
This function provides the status upon completion of a scan.
void emberStopScan (void)
This function terminates a scan in progress.
void emberResetMicro (void)
This function resets the Ember chip.
void emberResetMicroHandler ( EmberResetCause cause)
This function notifies the application of a reset on the Ember chip due to the indicated cause.
void emberGetStandaloneBootloaderInfo (void)
This function detects if the standalone bootloder is installed, and if so returns the installed version and info about the platform, micro and phy. If not version will be set to 0xffff. A returned version of 0x1234 would indicate version 1.2 build 34.
void emberGetStandaloneBootloaderInfoReturn (uint16_t version, uint8_t platformId, uint8_t microId, uint8_t phyId)
This function provides the result of a call to emberGetStandaloneBootloaderInfo .
void emberLaunchStandaloneBootloader (uint8_t mode)
This function launches the standalone bootloader (if installed). The function returns an error if the standalone bootloader is not present.
void emberLaunchStandaloneBootloaderReturn ( EmberStatus status)
This function provides the result of a call to emberLaunchStandaloneBootloader .
void emberInitHost (void)
In a host/NCP setup, inform the NCP to send the network state and version information.
void emberState (void)
In a host/NCP setup, get the network parameters, the network status and eui64 all at once.
void emberStateReturn (const EmberNetworkParameters *parameters, const EmberEui64 *localEui64, const EmberEui64 *macExtendedId, EmberNetworkStatus networkStatus)
In a host/NCP setup, provides the result of a call to emberState() on the host.
void emberHostStateHandler (const EmberNetworkParameters *parameters, const EmberEui64 *localEui64, const EmberEui64 *macExtendedId, EmberNetworkStatus networkStatus)
In a host/NCP setup, notifies the host to changes in the network parameters.
void emberSetRadioPower (int8_t power)
This function sets the radio output power at which a node is to operate. 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, as it will directly impact 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 will use the next higher available power level.
void emberSetRadioPowerReturn ( EmberStatus status)
This function provides the result of a call to emberSetRadioPower() on the host.
void emberGetRadioPower (void)
This function gets the radio output power 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 emberGetRadioPowerReturn (int8_t power)
This function provides the result of a call to emberGetRadioPower() on the host.
EmberStatus emberSetTxPowerMode (uint16_t txPowerMode)
This function enables boost power mode and/or the alternate transmit path.
void emberSetTxPowerModeReturn ( EmberStatus status)
This function provides the result of a call to emberSetTxPowerMode() on the host.
void emberGetTxPowerMode (void)
This function requests the current configuration of boost power mode and alternate transmitter output.
void emberGetTxPowerModeReturn (uint16_t txPowerMode)
This function provides the result of a call to emberGetTxPowerMode() on the host.
void emberSetSecurityParameters (const EmberSecurityParameters *parameters, uint16_t options)
This function is called before forming or joining. Fails if already formed or joined or if the arguments are inconsistent with the stack (i.e. if ECC is wanted and we have no ECC).
void emberSetSecurityParametersReturn ( EmberStatus status)
This function provides the result of a call to emberSetSecurityParameters() .
void emberSwitchToNextNetworkKey (void)
This function changes MAC encryption over to the next key. Fails if there is no next network key.
void emberSwitchToNextNetworkKeyReturn ( EmberStatus status)
This function provides the result of a call to emberSwitchToNextNetworkKey() .
void emberSwitchToNextNetworkKeyHandler ( EmberStatus status)
This function can be stubbed out on the SoC and host app. It is used by the NCP to update security on the driver when it is instructed to switch the network key by an over the air update.
void emberGetVersions (void)
This function gets various versions: The stack version name (versionName) The management version number (managementVersionNumber, if applicable, otherwise set to 0xFFFF) The stack version number (stackVersionNumber) The stack build number (stackBuildNumber) The version type (versionType) The date / time of the build (buildTimestamp)
void emberGetVersionsReturn (const uint8_t *versionName, uint16_t managementVersionNumber, uint16_t stackVersionNumber, uint16_t stackBuildNumber, EmberVersionType versionType, const uint8_t *buildTimestamp)
Provides the result of a call to emberGetVersions() .
void emberSetCcaThreshold (int8_t threshold)
This function sets the CCA threshold level - the noise floor above which the channel is normally considered busy. The threshold parameter is expected to be a signed 2's complement value, in dBm.
void emberSetCcaThresholdReturn ( EmberStatus status)
This function provides the result of a call to emberSetCcaThreshold() .
void emberGetCcaThreshold (void)
This function gets the current CCA threshold level.
void emberGetCcaThresholdReturn (int8_t threshold)
This function provides the result of a call to emberGetCcaThreshold() .
void emberMacPassthroughMessageHandler ( PacketHeader header)
Application handler to intercept "passthrough" packets and handle them at the application.
bool emberMacPassthroughFilterHandler (uint8_t *macHeader)
Application handler to define "passthrough" packets.
bool emberMacRssiFilterHandler (uint8_t *macHeader)
Application handler to filter 802.15.4 packets to be observed for signal strength.
void emberMacRssiHandler (int8_t currentRssi)
Gets the received signal strength indication (RSSI) for the last 802.15.4 packet received by the stack.
void emberGetIndexedToken ( EmberTokenId tokenId, uint8_t index)
This function gets the indexed token stored in non-volatile memory on the Ember chip. The result is returned depending on the tokenId provided (see enum above) to the appropriate Return() API.
void emberGetChannelCalDataTokenReturn (uint8_t lna, int8_t tempAtLna, uint8_t modDac, int8_t tempAtModDac)
This function gets the token information for tokenId = EMBER_CHANNEL_CAL_DATA_TOKEN.
void emberGetMfgToken ( EmberMfgTokenId tokenId)
This function gets the manufacturer token stored in non-volatile memory on the Ember chip.
void emberGetMfgTokenReturn ( EmberMfgTokenId tokenId, EmberStatus status, const uint8_t *tokenData, uint8_t tokenDataLength)
This function provides the result of a call to emberGetMfgToken .
void emberSetMfgToken ( EmberMfgTokenId tokenId, const uint8_t *tokenData, uint8_t tokenDataLength)
This function sets the manufacturer token stored in non-volatile memory on the Ember chip.
void emberSetMfgTokenReturn ( EmberMfgTokenId tokenId, EmberStatus status)
This function provides the result of a call to emberSetMfgToken .
void emberGetCtune (void)
This function gets the CTUNE value. (Only valid on EFR32)
void emberGetCtuneReturn (uint16_t tune, EmberStatus status)
This function provides the result of a call to emberGetCtune .
void emberSetCtune (uint16_t tune)
This function changes the CTUNE value. Involves switching to HFRCO and turning off the HFXO temporarily. (Only valid on EFR32)
void emberSetCtuneReturn ( EmberStatus status)
This function provides the result of a call to emberSetCtune .
void emberRegisterDropIncomingMessageCallback (bool(*drop)( PacketHeader header, Ipv6Header *ipHeader))
This function registers a callback function so that the application can define rules to drop incoming packets. The callback function MUST be of the form: bool func_name(PacketHeader header, Ipv6Header *ipHeader) { ... }.
void emberRegisterSerialTransmitCallback (void(*serialTransmit)(uint8_t type, PacketHeader header))
This function registers a callback function so that the application can define serial transmit logic. This should only be used for NCPs, and will have no effect for SoCs. The callback function MUST be of the form: void uartTransmit(uint8_t type, Buffer b) { ... }.

Detailed Description

See network-management.h for source code.

Macro Definition Documentation

#define EMBER_CHILD_IS_FULL_THREAD_DEVICE_FLAG   0x0002
#define EMBER_CHILD_IS_SLEEPY_FLAG   0x0001
#define EMBER_ECC_JOINING_OPTION BIT (2)
#define EMBER_HIGH_PRIORITY_TASKS   ( EMBER_OUTGOING_MESSAGES | EMBER_INCOMING_MESSAGES | EMBER_RADIO_IS_ON )
#define EMBER_NETWORK_KEY_OPTION BIT (0)
#define EMBER_PSK_JOINING_OPTION BIT (1)
#define ISLAND_ID_SIZE   5

Typedef Documentation

typedef uint8_t EmberMfgTokenId
typedef uint8_t EmberTokenId

Enumeration Type Documentation

anonymous enum
Enumerator
EMBER_OUTGOING_MESSAGES

There are messages 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_ROUTER or EMBER_END_DEVICE ) the radio is always on.

anonymous enum
Enumerator
EMBER_GET_CHILD_ENTRY_SUCCESS
EMBER_GET_CHILD_ENTRY_FAILURE
anonymous enum
Enumerator
EMBER_CHANNEL_CAL_DATA_TOKEN
anonymous enum
Enumerator
EMBER_CUSTOM_EUI_64_MFG_TOKEN
EMBER_EZSP_STORAGE_MFG_TOKEN
EMBER_CTUNE_MFG_TOKEN
enum EmberIdleRadioState
Enumerator
IDLE_WITH_RADIO_ON

Incoming messages are expected and the radio must be left on.

IDLE_WITH_POLLING

Incoming messages are expected and must be polled for.

IDLE_WITH_RADIO_OFF

No messages are expected and the radio may be left off.

enum EmberResetCause
Enumerator
EMBER_RESET_UNKNOWN
EMBER_RESET_FIB
EMBER_RESET_BOOTLOADER
EMBER_RESET_EXTERNAL
EMBER_RESET_POWERON
EMBER_RESET_WATCHDOG
EMBER_RESET_SOFTWARE
EMBER_RESET_CRASH
EMBER_RESET_FLASH
EMBER_RESET_FATAL
EMBER_RESET_FAULT
EMBER_RESET_BROWNOUT

Function Documentation

void emberActiveScanHandler ( const EmberMacBeaconData * beaconData )

This function reports an incoming beacon during an active scan.

void emberClearCounters ( void )
void emberCounterHandler ( EmberCounterType type,
uint16_t increment
)

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 The type of the event.
increment Specify the increase in the counter's tally.
uint16_t emberCounterValueHandler ( EmberCounterType type )

The application must define EMBER_APPLICATION_HAS_COUNTER_VALUE_HANDLER in its CONFIGURATION_HEADER to use this.

Parameters
type The type of the event.
Returns
The counter's tally.
void emberEnergyScanHandler ( uint8_t channel,
int8_t maxRssiValue
)
Parameters
channel The 802.15.4 channel on which the RSSI value was measured.
maxRssiValue The maximum RSSI value measured (in units of dBm).

This function reports the maximum RSSI value measured on the channel.

Parameters
channel The 802.15.4 channel on which the RSSI value was measured.
maxRssiValue The maximum RSSI value measured (in units of dBm).
const EmberEui64 * emberEui64 ( void )
void emberEventDelayUpdatedFromIsrHandler ( Event * event )
Parameters
event The event that was scheduled by the ISR.
bool emberForwardIpv6Packet ( const uint8_t * packet,
const uint16_t packetLength
)
Parameters
packet Raw bytes of the IPv6 packet
packetLength Length of the packet
void emberGetCcaThreshold ( void )
void emberGetCcaThresholdReturn ( int8_t threshold )

This function provides the result of a call to emberGetCcaThreshold() .

void emberGetChannelCalDataTokenReturn ( uint8_t lna,
int8_t tempAtLna,
uint8_t modDac,
int8_t tempAtModDac
)
Parameters
lna [msb: cal needed? | bit 0-5: lna tune value]
tempAtLna [the temp (degC) when the LNA was calibrated]
modDac [msb: cal needed? | bit 0-5: modulation DAC tune value]
tempAtModDac [the temp (degC) when the mod DAC was calibrated]

This function gets the token information for tokenId = EMBER_CHANNEL_CAL_DATA_TOKEN.

Parameters
lna [msb: cal needed? | bit 0-5: lna tune value]
tempAtLna [the temp (degC) when the LNA was calibrated] #param modDac [msb: cal needed? | bit 0-5: modulation DAC tune value]
tempAtModDac [the temp (degC) when the mod DAC was calibrated]
void emberGetChildEntry ( uint8_t index )

The index is between 0 and the size of the child table (which is returned in the callback). The valid child entries may be located at any index in the table. If there is no valid entry at our above the supplied index, the callback returns a status of EMBER_GET_CHILD_ENTRY_FAILURE.

The caller can pass an index of 0xFF to retrieve all valid entries with one call. The emberGetChildEntryReturn() callback will then be invoked once for each valid entry, followed by a final invocation with status EMBER_GET_CHILD_ENTRY_FAILURE to indicate completion.

void emberGetChildEntryReturn ( uint8_t status,
uint8_t index,
uint8_t childTableSize,
const EmberChildEntry * entry,
const EmberIpv6Address * addresses,
uint8_t addressCount
)

If the child is not a Full Thread Device (as indicated in the EmberChildEntry flags field), the parent stores the child's ipv6 addresses, which are then returned by this callback as well.

A status of EMBER_GET_CHILD_ENTRY_FAILURE indicates that no valid child entry was found at or above the requested index.

void emberGetCounter ( EmberCounterType type )
void emberGetCounterReturn ( EmberCounterType type,
uint16_t value
)

This function provides the result of a call to emberGetCounter() .

void emberGetCtune ( void )
void emberGetCtuneReturn ( uint16_t tune,
EmberStatus status
)
Parameters
tune The current CTUNE value.
status An EmberStatus value indicating success or the reason for failure.

This function provides the result of a call to emberGetCtune .

Parameters
tune The current CTUNE value.
status An EmberStatus value indicating success or the reason for failure.
void emberGetIndexedToken ( EmberTokenId tokenId,
uint8_t index
)
void emberGetMfgToken ( EmberMfgTokenId tokenId )
Parameters
tokenId Which manufacturing token to read.
void emberGetMfgTokenReturn ( EmberMfgTokenId tokenId,
EmberStatus status,
const uint8_t * tokenData,
uint8_t tokenDataLength
)
Parameters
tokenId Which manufacturing token read.
status An EmberStatus value indicating success or the reason for failure.
tokenData The manufacturing token data.
tokenDataLength The length of the tokenData parameter in bytes.

This function provides the result of a call to emberGetMfgToken .

Parameters
tokenId Which manufacturing token read.
status An EmberStatus value indicating success or the
tokenData The manufacturing token data.
tokenDataLength The length of the tokenData parameter in bytes.
void emberGetNetworkParameters ( EmberNetworkParameters * parameters )

Note: The network master key is sensitive network information and therefore not public. The masterKey value in the result is zeroed out.

EmberPanId emberGetPanId ( void )
void emberGetRadioPower ( void )
Returns
Current radio output power, in dBm.
void emberGetRadioPowerReturn ( int8_t power )

This function provides the result of a call to emberGetRadioPower() on the host.

void emberGetRipEntry ( uint8_t index )

The index is between 0 and 31 inclusive, but there may be fewer than 32 valid entries depending on the number of routers in the network.

The caller can pass in a 0xFF index to request all valid RIP table entries. Note that the stack will ONLY return valid entries when 0xFF is passed. Once all valid entries have been returned by this method, an extra zeroed-out entry is returned to indicate completion.

When the application requests an EmberRipEntry at a certain index, it can check for the validity of the returned EmberRipEntry by checking whether it is zeroed out. For example, the 'type' parameter should never be zero. (it should be a valid node type: EMBER_ROUTER)

void emberGetRipEntryReturn ( uint8_t index,
const EmberRipEntry * entry
)

This function provides the result of a call to emberGetRipEntry() .

void emberGetStandaloneBootloaderInfo ( void )
void emberGetStandaloneBootloaderInfoReturn ( uint16_t version,
uint8_t platformId,
uint8_t microId,
uint8_t phyId
)
Parameters
version BOOTLOADER_INVALID_VERSION if the standalone bootloader is not present, or the version of the installed standalone bootloader.
nodePlat The value of PLAT on the node.
nodeMicro The value of MICRO on the node.
nodePhy The value of PHY on the node.

This function provides the result of a call to emberGetStandaloneBootloaderInfo .

Parameters
version BOOTLOADER_INVALID_VERSION if the standalone bootloader is not present, or the version of the installed standalone bootloader.
platformId The value of PLAT on the node.
microId The value of MICRO on the node.
phyId The value of PHY on the node.
void emberGetTxPowerMode ( void )
void emberGetTxPowerModeReturn ( uint16_t txPowerMode )
Returns
the current tx power mode.

This function provides the result of a call to emberGetTxPowerMode() on the host.

Returns
the current tx power mode.
void emberGetVersions ( void )
void emberGetVersionsReturn ( const uint8_t * versionName,
uint16_t managementVersionNumber,
uint16_t stackVersionNumber,
uint16_t stackBuildNumber,
EmberVersionType versionType,
const uint8_t * buildTimestamp
)
void emberHostStateHandler ( const EmberNetworkParameters * parameters,
const EmberEui64 * localEui64,
const EmberEui64 * macExtendedId,
EmberNetworkStatus networkStatus
)
Parameters
parameters Current network parameters
localEui64 The EUI64 of the Ember chip
macExtendedId The extended MAC ID of the Ember chip
networkStatus The current status of the network
void emberInit ( void )
void emberInitHost ( void )
void emberInitReturn ( EmberStatus status )

This function provides the result of a call to emberInit() .

void emberLaunchStandaloneBootloader ( uint8_t mode )
Parameters
mode Controls the mode in which the standalone bootloader will run. See the app. note for full details. Options are: STANDALONE_BOOTLOADER_NORMAL_MODE: Will listen for an over-the-air image transfer on the current channel with current power settings. STANDALONE_BOOTLOADER_RECOVERY_MODE: Will listen for an over-the-air image transfer on the default channel with default power settings. Both modes also allow an image transfer to begin with XMODEM over the serial protocol's Bootloader Frame.
void emberLaunchStandaloneBootloaderReturn ( EmberStatus status )
Parameters
status An EmberStatus value indicating success or the reason for failure.

This function provides the result of a call to emberLaunchStandaloneBootloader .

Parameters
status An EmberStatus value indicating success or the reason for failure.
bool emberMacPassthroughFilterHandler ( uint8_t * macHeader )
Note
This API is for SoCs only.
The application must define EMBER_APPLICATION_HAS_MAC_PASSTHROUGH_FILTER_HANDLER
Parameters
macHeader A pointer to the initial portion of the incoming MAC header, in the standard 802.15.4 format. The first two bytes comprise the frame control, which dictates source / destination PAN and addressing formats. (See the MAC sublayer definition in the standards definition 802.15.4e/2012)

The relevant bytes of the header are:

| octets: | 2 | 1 | 0/2 | 0/2/8 | 0/2 | 0/2/8 |

| | ctl | seq | dst.pan | dst.addr | src.pan | src.addr | ...

Note that subsequent MAC fields, and the MAC payload, may not yet be present at this point.

Returns
true if the message is an application MAC passthrough message.
void emberMacPassthroughMessageHandler ( PacketHeader header )
Note
This API is for SoCs only.
The application must define EMBER_APPLICATION_HAS_MAC_PASSTHROUGH_MESSAGE_HANDLER
Parameters
header The message buffer pointing to the full 802.15.4 frame to be handled by the application.
bool emberMacRssiFilterHandler ( uint8_t * macHeader )
Note
This API is for SoCs only.
The application must define EMBER_APPLICATION_HAS_RSSI_FILTER_HANDLER
Parameters
macHeader A pointer to the initial portion of the incoming MAC header, in the standard 802.15.4 format. The first two bytes comprise the frame control, which dictates source / destination PAN and addressing formats. (See the MAC sublayer definition in the standards definition 802.15.4e/2012)

The relevant bytes of the header are:

| octets: | 2 | 1 | 0/2 | 0/2/8 | 0/2 | 0/2/8 |

| | ctl | seq | dst.pan | dst.addr | src.pan | src.addr | ...

Note that subsequent MAC fields, and the MAC payload, may not yet be present at this point.

Returns
true if the application wants to peek at the RSSI for this message.
void emberMacRssiHandler ( int8_t currentRssi )
Note
This is called on the application for all packets that match the rule defined in emberMacRssiFilterHandler()

The quantity referenced by currentRssi will contain the energy level (in units of dBm) observed during the last 802.15.4 packet received in that handler.

Note
This API is for SoCs only.
The application must define EMBER_APPLICATION_HAS_RSSI_FILTER_HANDLER
This functionality is not available for packets such as 802.15.4 data requests or acknowledgements. Data requests must be handled quickly due to strict 15.4 timing requirements, and so the RSSI information is not recorded. Similarly, 802.15.4 ACKs are handled by the hardware and the information does not make it up to the stack.
Parameters
currentRssi The RSSI for the last incoming message processed.
EmberNetworkStatus emberNetworkStatus ( void )
void emberNetworkStatusHandler ( EmberNetworkStatus newNetworkStatus,
EmberNetworkStatus oldNetworkStatus,
EmberJoinFailureReason reason
)

If the status handler is reporting a join failure, then the newNetworkStatus argument will have a value of EMBER_NO_NETWORK and the reason argument will contain an appropriate value. For other network status reports, the reason argument does not apply and is set to EMBER_JOIN_FAILURE_REASON_NONE.

This function reports a change to the network status. For example, the network status changes while going through the joining process, or while reattaching to the network, which can happen for a variety of reasons. In particular, after issuing a form, join, resume, or attach command, the application knows that the device is on the network and ready to communicate when this handler is called with a newNetworkStatus of EMBER_JOINED_NETWORK_ATTACHED.

If the status handler is reporting a join failure, then the newNetworkStatus argument will have a value of EMBER_NO_NETWORK and the reason argument will contain an appropriate value. For other network status reports, the reason argument does not apply and is set to EMBER_JOIN_FAILURE_REASON_NONE.

bool emberOkToNap ( void )

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 for sleepy end devices.

void emberOkToNapReturn ( uint8_t stateMask )

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 (in quarter seconds) before discarding them.

Returns
A bitmask of the stack's active tasks.
void emberPollForData ( void )

This function allows a sleepy end device to query its parent for any pending data.

Sleepy end devices must call this function periodically to maintain contact with their parent. The parent will remove a sleepy end device from its child table if it has not received a poll from it within the last EMBER_SLEEPY_CHILD_POLL_TIMEOUT seconds.

If the sleepy end device has lost contact with its parent, it re-joins then network using another router.

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

void emberPollForDataReturn ( EmberStatus status )
Parameters
An EmberStatus value:

This function provides the result of a call to emberPollForData() .

Parameters
An EmberStatus value:
void emberRegisterDropIncomingMessageCallback ( bool(*)( PacketHeader header, Ipv6Header *ipHeader) drop )
void emberRegisterSerialTransmitCallback ( void(*)(uint8_t type, PacketHeader header) serialTransmit )
void emberResetCounterHandler ( EmberCounterType type )

The application must define EMBER_APPLICATION_HAS_COUNTER_VALUE_HANDLER in its CONFIGURATION_HEADER to use this.

Parameters
type The type of the event.
void emberResetMicro ( void )
void emberResetMicroHandler ( EmberResetCause cause )

This function notifies the application of a reset on the Ember chip due to the indicated cause.

void emberResetNetworkState ( void )
void emberResetNetworkStateReturn ( EmberStatus status )

This function provides the result of a call to emberResetNetworkState() .

void emberScanReturn ( EmberStatus status )

This function provides the status upon completion of a scan.

void emberSetCcaThreshold ( int8_t threshold )
void emberSetCcaThresholdReturn ( EmberStatus status )

This function provides the result of a call to emberSetCcaThreshold() .

void emberSetCtune ( uint16_t tune )
Parameters
tune Value to set CTUNE to.
void emberSetCtuneReturn ( EmberStatus status )
Parameters
status An EmberStatus value indicating success or the reason for failure.

This function provides the result of a call to emberSetCtune .

Parameters
status An EmberStatus value indicating success or the reason for failure.
void emberSetMfgToken ( EmberMfgTokenId tokenId,
const uint8_t * tokenData,
uint8_t tokenDataLength
)
Parameters
tokenId Which manufacturing token to set.
tokenData The manufacturing token data.
tokenDataLength The length of the tokenData parameter in bytes.
void emberSetMfgTokenReturn ( EmberMfgTokenId tokenId,
EmberStatus status
)
Parameters
tokenId Which manufacturing token set.
status An EmberStatus value indicating success or the reason for failure.

This function provides the result of a call to emberSetMfgToken .

Parameters
tokenId Which manufacturing token set.
status An EmberStatus value indicating success or the reason for failure.
void emberSetRadioPower ( int8_t power )
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.
void emberSetRadioPowerReturn ( EmberStatus status )

This function provides the result of a call to emberSetRadioPower() on the host.

void emberSetSecurityParameters ( const EmberSecurityParameters * parameters,
uint16_t options
)

*** Only the EMBER_NETWORK_KEY_OPTION works at this time. ***

void emberSetSecurityParametersReturn ( EmberStatus status )

This function provides the result of a call to emberSetSecurityParameters() .

EmberStatus emberSetTxPowerMode ( uint16_t txPowerMode )

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. The alternate transmit output path allows for simplified connection to an external power amplifier via the RF_TX_ALT_P and RF_TX_ALT_N pins on the em250. 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() if it wishes to use a power mode or transmitter output setting different from that specified in the MFG_PHY_CONFIG token. After this initial call to emberSetTxPowerMode() , the stack will automatically maintain the specified power mode configuration across sleep/wake cycles.

Note
This function does not alter the MFG_PHY_CONFIG token. The MFG_PHY_CONFIG token must be properly configured to ensure optimal radio performance when the standalone bootloader runs in recovery mode. The MFG_PHY_CONFIG can only be set using external tools. IF YOUR PRODUCT USES BOOST MODE OR THE ALTERNATE TRANSMITTER OUTPUT AND THE STANDALONE BOOTLOADER YOU MUST SET THE PHY_CONFIG TOKEN INSTEAD OF USING THIS FUNCTION. Contact suppo .nosp@m. rt@e .nosp@m. mber. .nosp@m. com for instructions on how to set the MFG_PHY_CONFIG token appropriately.
Parameters
txPowerMode Specifies which of the transmit power mode options are to 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.
void emberSetTxPowerModeReturn ( EmberStatus status )

This function provides the result of a call to emberSetTxPowerMode() on the host.

uint32_t emberStackIdleTimeMs ( EmberIdleRadioState * radioStateResult )

This function returns directly, rather than having a ...Return() callback, because it is only available on SOCs.

Parameters
radioStateResult Used to return the required radio state while the stack is idle.
Returns
The number of milliseonds for which the stack will be idle.
void emberStackPollForData ( uint32_t pollMs )
void emberStackPollForDataReturn ( EmberStatus status )

This function provides the result of a call to emberStackPollForData() .

void emberStackPowerDown ( void )

After calling this function, you must not call any other stack function except emberStackPowerUp() . This is because all other stack functions require that the radio is powered on for their proper operation.

Referenced by usbSuspendDsr() .

void emberStackPowerUp ( void )

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

void emberStackPrepareForPowerDown ( void )
bool emberStackPreparingForPowerDown ( void )
void emberStartScan ( EmberNetworkScanType scanType,
uint32_t channelMask,
uint8_t duration
)

Upon completion of the scan, a status is returned via emberScanReturn() . Possible EmberStatus values and their meanings:

Parameters
scanType Indicates the type of scan to be performed. Possible values: EMBER_ENERGY_SCAN , EMBER_ACTIVE_SCAN .
channelMask Bits set as 1 indicate that this particular channel should be scanned. Bits set to 0 indicate that this particular channel should not be scanned. For example, a channelMask value of 0x00000001 would indicate that only channel 0 should be scanned. Valid channels range from 11 to 26 inclusive. This translates to a channel mask value of 0x07 FF F8 00. As a convenience, a channelMask of 0 is reinterpreted as the mask for the current channel.
duration Sets the exponent of the number of scan periods, where a scan period is 960 symbols, and a symbol is 16 microseconds. The scan will occur for ((2^duration) + 1) scan periods. The value of duration must be less than 15. The time corresponding to the first few values are as follows: 0 = 31 msec, 1 = 46 msec, 2 = 77 msec, 3 = 138 msec, 4 = 261 msec, 5 = 507 msec, 6 = 998 msec.
void emberState ( void )
void emberStateReturn ( const EmberNetworkParameters * parameters,
const EmberEui64 * localEui64,
const EmberEui64 * macExtendedId,
EmberNetworkStatus networkStatus
)
Parameters
parameters Current network parameters
localEui64 The EUI64 of the Ember chip
macExtendedId The extended MAC ID of the Ember chip
networkStatus The current status of the network
void emberStopScan ( void )
void emberSwitchToNextNetworkKey ( void )
void emberSwitchToNextNetworkKeyHandler ( EmberStatus status )

This function can be stubbed out on the SoC and host app. It is used by the NCP to update security on the driver when it is instructed to switch the network key by an over the air update.

void emberSwitchToNextNetworkKeyReturn ( EmberStatus status )

This function provides the result of a call to emberSwitchToNextNetworkKey() .

void emberTick ( void )