network-management API Callbacks
Application Framework API Reference > Callbacks

Functions

void emberActiveScanHandler (const EmberMacBeaconData *beaconData)
Reports an incoming beacon during an active scan.
void emberAddressConfigurationChangeHandler (const EmberIpv6Address *address, uint32_t preferredLifetime, uint32_t validLifetime, uint8_t addressFlags)
This is called when a new address is configured on the application.
void emberAttachToNetworkReturn ( EmberStatus status)
A callback that indicates whether the attach process was successfully initiated via a prior call to emberAttachToNetwork() . The status argument is either EMBER_SUCCESS, or EMBER_INVALID_CALL if attach was called when the network status was not EMBER_JOINED_NETWORK_NO_PARENT, or while an attach was underway.
void emberBecomeCommissionerReturn ( EmberStatus status)
Return call for emberBecomeCommissioner() . The status is EMBER_SUCCESS if a petition was sent or EMBER_ERR_FATAL if some temporary resource shortage prevented doing so.
void emberChangeNodeTypeReturn ( EmberStatus status)
Provides the result of a call to emberChangeNodeType() : either EMBER_SUCCESS, or EMBER_INVALID_CALL.
void emberAllowNativeCommissionerReturn ( EmberStatus status)
Provides the result of a call to emberAllowNativeCommissioner() : either EMBER_SUCCESS or EMBER_INVALID_CALL.
void emberSetCommissionerKeyReturn ( EmberStatus status)
Provides the result of a call to emberSetCommissionerKey() : either EMBER_SUCCESS or EMBER_INVALID_CALL.
void emberSetPskcHandler (const uint8_t *pskc)
Handler to let application know that a PSKc TLV was successfully set.
void emberSetJoinKeyReturn ( EmberStatus status)
Provides the result of a call to emberSetJoinKey() : either EMBER_SUCCESS or EMBER_BAD_ARGUMENT.
void emberCommissionNetworkReturn ( EmberStatus status)
Provides the result of a call to emberCommissionNetwork.
void emberCommissionerStatusHandler (uint16_t flags, const uint8_t *commissionerName, uint8_t commissionerNameLength)
Reports on the current commissioner state.
void emberConfigureGatewayReturn ( EmberStatus status)
Provides the result of a call to emberConfigureGateway .
void emberSetNdDataReturn ( EmberStatus status, uint16_t length)
Provides the result of a call to emberSetNdData .
void emberSetLocalNetworkDataReturn ( EmberStatus status, uint16_t length)
Provides the result of a call to emberSetLocalNetworkData .
void emberConfigureExternalRouteReturn ( EmberStatus status)
Provides the result of a call to emberConfigureExternalRoute .
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.
void emberCustomHostToNcpMessageHandler (const uint8_t *message, uint16_t messageLength)
NCP handler called to process a custom message from the Host.
void emberCustomNcpToHostMessageHandler (const uint8_t *message, uint16_t messageLength)
Host handler called to process a custom message from the NCP.
void emberDeepSleepCompleteHandler (uint16_t sleepDuration)
For a sleepy end device, report how long the chip went to deep sleep. In a NCP + host setup, the stack reports this to the host app.
void emberDeepSleepReturn ( EmberStatus status)
Provides the result of a call to emberDeepSleep() .
void emberDhcpServerChangeHandler (const uint8_t *prefix, uint8_t prefixLengthInBits, bool available)
This is called when the stack knows about a new dhcp server or if a dhcp server has become unavailable.
void emberEnergyScanHandler (uint8_t channel, int8_t maxRssiValue)
Reports the maximum RSSI value measured on the channel.
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 emberExternalRouteChangeHandler (const uint8_t *prefix, uint8_t prefixLengthInBits, bool available)
This is called when the stack knows about a border router that has an external route to a prefix.
void emberFormNetworkReturn ( EmberStatus status)
A callback that indicates whether a prior call to emberFormNetwork() successfully initiated the form process. The status argument is either EMBER_SUCCSS, or EMBER_INVALID_CALL if resume was called when the network status was not EMBER_NO_NETWORK, or a scan was underway.
void emberGetAntennaModeReturn ( EmberStatus status, uint8_t mode)
Provides the result of a call to emberGetAntennaMode .
void emberGetCcaThresholdReturn (int8_t threshold)
Provides the result of a call to emberGetCcaThreshold() .
void emberGetChannelCalDataTokenReturn (uint8_t lna, int8_t tempAtLna, uint8_t modDac, int8_t tempAtModDac)
Gets the token information for tokenId = EMBER_CHANNEL_CAL_DATA_TOKEN.
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 emberGetCounterReturn ( EmberCounterType type, uint16_t value)
Provides the result of a call to emberGetCounter() .
void emberGetCtuneReturn (uint16_t tune, EmberStatus status)
Provides the result of a call to emberGetCtune .
void emberGetGlobalAddressReturn (const EmberIpv6Address *address, uint32_t preferredLifetime, uint32_t validLifetime, uint8_t addressFlags)
Provides the result of a call to emberGetGlobalAddresses .
void emberGetGlobalPrefixReturn (uint8_t flags, bool isStable, const uint8_t *prefix, uint8_t prefixLengthInBits, uint8_t domainId, uint32_t preferredLifetime, uint32_t validLifetime)
Provides the result of a call to ::emberGetGlobalPrefix.
void emberGetMfgTokenReturn ( EmberMfgTokenId tokenId, EmberStatus status, const uint8_t *tokenData, uint8_t tokenDataLength)
Provides the result of a call to emberGetMfgToken .
void emberGetNetworkDataReturn ( EmberStatus status, uint8_t *networkData, uint16_t bufferLength)
Provides the result of a call to emberGetNetworkData .
void emberGetNetworkDataTlvReturn (uint8_t typeByte, uint8_t index, uint8_t versionNumber, const uint8_t *tlv, uint8_t tlvLength)
Provides the result of a call to emberGetNetworkDataTlv() .
void emberGetPtaEnableReturn (bool enabled)
Provides the result of a call to emberGetPtaEnable .
void emberGetPtaOptionsReturn (uint32_t options)
Provides the result of a call to emberGetPtaOptions .
void emberGetRadioPowerReturn (int8_t power)
Provides the result of a call to emberGetRadioPower() on the host.
void emberGetRipEntryReturn (uint8_t index, const EmberRipEntry *entry)
Provides the result of a call to emberGetRipEntry() .
void emberGetRoutingLocatorReturn (const EmberIpv6Address *rloc)
Provides the result of a call to emberGetRoutingLocator .
void emberGetStandaloneBootloaderInfoReturn (uint16_t version, uint8_t platformId, uint8_t microId, uint8_t phyId)
Provides the result of a call to emberGetStandaloneBootloaderInfo .
void emberGetTxPowerModeReturn (uint16_t txPowerMode)
Provides the result of a call to emberGetTxPowerMode() on the host.
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 emberSetAddressHandler (const uint8_t *address)
In a host/NCP setup, notifies the host to set the new mesh local address.
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 emberInitReturn ( EmberStatus status)
Provides the result of a call to emberInit() .
void emberJoinNetworkReturn ( EmberStatus status)
A callback that indicates whether the join process was successfully initiated via a prior call to emberJoinNetwork() or emberJoinCommissioned() . The possible EmberStatus values are: EMBER_SUCCESS, EMBER_BAD_ARGUMENT, or EMBER_INVALID_CALL (if join was called when the network status was something other than EMBER_NO_NETWORK).
void emberLaunchStandaloneBootloaderReturn ( EmberStatus status)
Provides the result of a call to emberLaunchStandaloneBootloader .
void emberLeaderDataHandler (const uint8_t *leaderData)
A callback invoked when the leader data changes.
bool emberMacPassthroughFilterHandler (uint8_t *macHeader)
Application handler to define "passthrough" packets.
void emberMacPassthroughMessageHandler ( PacketHeader header)
Application handler to intercept "passthrough" packets and handle them at the application.
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 emberNetworkDataChangeHandler (const uint8_t *networkData, uint16_t length)
This is called when the stack receives new Thread Network Data.
void emberNetworkStatusHandler ( EmberNetworkStatus newNetworkStatus, EmberNetworkStatus oldNetworkStatus, EmberJoinFailureReason reason)
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 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 emberPollForDataReturn ( EmberStatus status)
Provides the result of a call to emberPollForData() .
void emberRadioGetRandomNumbersReturn ( EmberStatus status, const uint16_t *rn, uint8_t count)
Provides the result of a call to emberRadioGetRandomNumbers .
void emberRequestDhcpAddressReturn ( EmberStatus status, const uint8_t *prefix, uint8_t prefixLengthInBits)
Provides the result of a call to emberRequestDhcpAddress .
void emberRequestSlaacAddressReturn ( EmberStatus status, const uint8_t *prefix, uint8_t prefixLengthInBits)
Provides the result of a call to emberRequestSlaacAddress .
void emberResetMicroHandler ( EmberResetCause cause)
Notifies the application of a reset on the Ember chip due to the indicated cause.
void emberResetNetworkStateReturn ( EmberStatus status)
Provides the result of a call to emberResetNetworkState() .
void emberResignGlobalAddressReturn ( EmberStatus status)
Provides the result of a call to emberResignGlobalAddress() .
void emberResumeNetworkReturn ( EmberStatus status)
A callback that indicates whether a prior call to emberResumeNetwork() successfully initiated the resume process. The status argument is either EMBER_SUCCESS, or EMBER_INVALID_CALL if resume was called when the network status was not EMBER_SAVED_NETWORK, or while a scan was underway.
void emberScanReturn ( EmberStatus status)
Provides the status upon completion of a scan.
void emberSendSteeringDataReturn ( EmberStatus status)
Provides the result of a call to emberSendSteeringData() .
void emberSetAntennaModeReturn ( EmberStatus status)
Provides the result of a call to emberSetAntennaMode .
void emberSetCcaThresholdReturn ( EmberStatus status)
Provides the result of a call to emberSetCcaThreshold() .
void emberSetCtuneReturn ( EmberStatus status)
Provides the result of a call to emberSetCtune .
void emberSetMfgTokenReturn ( EmberMfgTokenId tokenId, EmberStatus status)
Provides the result of a call to emberSetMfgToken .
void emberSetPtaEnableReturn ( EmberStatus status)
Provides the result of a call to emberSetPtaEnable .
void emberSetPtaOptionsReturn ( EmberStatus status)
Provides the result of a call to emberSetPtaOptions .
void emberSetRadioHoldOffReturn ( EmberStatus status)
Provides the result of a call to emberSetRadioHoldOff .
void emberSetRadioPowerReturn ( EmberStatus status)
Provides the result of a call to emberSetRadioPower() on the host.
void emberSetSecurityParametersReturn ( EmberStatus status)
Provides the result of a call to emberSetSecurityParameters() .
void emberSetTxPowerModeReturn ( EmberStatus status)
Provides the result of a call to emberSetTxPowerMode() on the host.
void emberSlaacServerChangeHandler (const uint8_t *prefix, uint8_t prefixLengthInBits, bool available)
This is called when the stack knows about a new SLAAC prefix or if a SLAAC server has become unavailable.
void emberStackPollForDataReturn ( EmberStatus status)
Provides the result of a call to emberStackPollForData() .
void emberStartHostJoinClientHandler (const uint8_t *parentAddress)
Callback to tell the host to start security commissioning.
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 emberSwitchToNextNetworkKeyHandler ( EmberStatus status)
This 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)
Provides the result of a call to emberSwitchToNextNetworkKey() .
void emberSetDtlsDeviceCertificateReturn (uint32_t result)
Provides the result of a call to emberSetDtlsDeviceCertificate() .
void emberSetDtlsPresharedKeyReturn ( EmberStatus status)
Provides the result of a call to emberSetDtlsPresharedKey() .
void emberOpenDtlsConnectionReturn (uint32_t result, const EmberIpv6Address *remoteAddress, uint16_t localPort, uint16_t remotePort)
Provides the result of a call to emberOpenDtlsConnection() .
void emberDtlsSecureSessionEstablished (uint8_t flags, uint8_t sessionId, const EmberIpv6Address *localAddress, const EmberIpv6Address *remoteAddress, uint16_t localPort, uint16_t remotePort)
Indicates to the application that a secure connection was successfully established.
void emberGetSecureDtlsSessionIdReturn (uint8_t sessionId, const EmberIpv6Address *remoteAddress, uint16_t localPort, uint16_t remotePort)
Provides the result of a call to emberGetSecureDtlsSessionId() .
void emberCloseDtlsConnectionReturn (uint8_t sessionId, EmberStatus status)
Provides the result of a call to emberCloseDtlsConnection() , or indicates that the connection was closed on the other end.
void emberProcessCoap (const uint8_t *message, uint16_t messageLength, EmberCoapRequestInfo *info)
Process a CoAP message received over an alternate transport.
void emberMicroBusyHandler (bool busy)
Callback informing the application running on the micro of interruptions to normal processing. If ::busy is true, the micro will be busy processing and unavailable for an indefinite period of time. If ::busy is false, the micro has resumed normal operation. The main use case is jpake crypto on EM3xx processors. This gives the application a chance to prepare for the pause in regular processing.

Detailed Description

These callbacks were contributed by the network-management API.

Function Documentation

void emberActiveScanHandler ( const EmberMacBeaconData * beaconData )

This function reports an incoming beacon during an active scan.

void emberAddressConfigurationChangeHandler ( const EmberIpv6Address * address,
uint32_t preferredLifetime,
uint32_t validLifetime,
uint8_t addressFlags
)

This function is called when a new address is configured on the application.

If addressFlags is EMBER_LOCAL_ADDRESS, it means that the address configured is a Thread-local address.

Otherwise, it means that the address assigned is a global address (DHCP or SLAAC).

In either case, if the valid lifetime is zero, then the address is no longer available.

Parameters
address the address
preferredLifetime the preferred lifetime of the address (in seconds)
validLifetime the valid lifetime of the address (in seconds)
addressFlags address configuration flags (see LocalServerFlag_e)
void emberAllowNativeCommissionerReturn ( EmberStatus status )

This function provides the result of a call to emberAllowNativeCommissioner() : either EMBER_SUCCESS or EMBER_INVALID_CALL.

void emberAttachToNetworkReturn ( EmberStatus status )
void emberBecomeCommissionerReturn ( EmberStatus status )
void emberChangeNodeTypeReturn ( EmberStatus status )

This function provides the result of a call to emberChangeNodeType() : either EMBER_SUCCESS, or EMBER_INVALID_CALL.

void emberCloseDtlsConnectionReturn ( uint8_t sessionId,
EmberStatus status
)
Parameters
sessionId sessionId used for secure CoAP transport.
status
void emberCommissionerStatusHandler ( uint16_t flags,
const uint8_t * commissionerName,
uint8_t commissionerNameLength
)

This function reports on the current commissioner state.

Parameters
flags A combination of zero or more of the following:
  • EMBER_HAVE_COMMISSIONER a commissioner is active in the network
  • EMBER_AM_COMMISSIONER this device is the active commissioner if emberStopCommissioning is called, then this flag is not returned as we are open to commissioner petitions
  • EMBER_JOINING_ENABLED joining is enabled
  • EMBER_JOINING_WITH_EUI_STEERING steering data restricts which devices can join. if not set, no restriction, any device can join (significant only when EMBER_JOINING_ENABLED is set)
commissionerName The name of the active commissioner, or NULL if there is none or the name is not known.
commissionerNameLength The length of commissonerName.
void emberCommissionNetworkReturn ( EmberStatus status )

This function provides the result of a call to emberCommissionNetwork.

Returns EMBER_SUCCESS if successful EMBER_BAD_ARGUMENT if any of the options are wrong EMBER_INVALID_CALL if the node is already on a network

Parameters
status Whether the call to emberCommissionNetwork was successful
void emberConfigureExternalRouteReturn ( EmberStatus status )

This function provides the result of a call to emberConfigureExternalRoute .

void emberConfigureGatewayReturn ( EmberStatus status )

This function provides the result of a call to emberConfigureGateway .

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 emberCustomHostToNcpMessageHandler ( const uint8_t * message,
uint16_t messageLength
)
Parameters
message message received
messageLength length of message
void emberCustomNcpToHostMessageHandler ( const uint8_t * message,
uint16_t messageLength
)
Parameters
message message received
messageLength length of message
void emberDeepSleepCompleteHandler ( uint16_t sleepDuration )
void emberDeepSleepReturn ( EmberStatus status )

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

void emberDhcpServerChangeHandler ( const uint8_t * prefix,
uint8_t prefixLengthInBits,
bool available
)

This function is called when the stack knows about a new dhcp server or if a dhcp server has become unavailable.

"available" means the DHCP server can offer us an address if requested.

Parameters
prefix dhcp server prefix
prefixLengthInBits length in bits of the prefix
available whether this dhcp server is available
void emberDtlsSecureSessionEstablished ( uint8_t flags,
uint8_t sessionId,
const EmberIpv6Address * localAddress,
const EmberIpv6Address * remoteAddress,
uint16_t localPort,
uint16_t remotePort
)
Parameters
flags 1 = server, 0 = client (possibly other info later)
sessionId sessionId used for secure CoAP transport
localAddress local IPv6 address
remoteAddress remote IPv6 address
localPort local port
remotePort remote port
void emberEnergyScanHandler ( uint8_t channel,
int8_t maxRssiValue
)

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).
void emberEventDelayUpdatedFromIsrHandler ( Event * event )
Parameters
event The event that was scheduled by the ISR.
void emberExternalRouteChangeHandler ( const uint8_t * prefix,
uint8_t prefixLengthInBits,
bool available
)

This function is called when the stack knows about a border router that has an external route to a prefix.

Parameters
prefix external route prefix
prefixLengthInBits length in bits of the prefix
available whether this external route is available.
void emberFormNetworkReturn ( EmberStatus status )
void emberGetAntennaModeReturn ( EmberStatus status,
uint8_t mode
)

This function provides the result of a call to emberGetAntennaMode .

Parameters
status An EmberStatus value indicating success or the reason for failure.
mode the current antenna mode, 0-primary, 1-secondary, 2-toggle on tx ack fail
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
)

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 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 emberGetCounterReturn ( EmberCounterType type,
uint16_t value
)

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

void emberGetCtuneReturn ( uint16_t tune,
EmberStatus status
)

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 emberGetGlobalAddressReturn ( const EmberIpv6Address * address,
uint32_t preferredLifetime,
uint32_t validLifetime,
uint8_t addressFlags
)

This function provides the result of a call to emberGetGlobalAddresses .

Parameters
address IPv6 global address
preferredLifetime Preferred lifetime (in seconds)
validLifetime Valid lifetime (in seconds)
addressFlags Address configuration flags (EMBER_GLOBAL_ADDRESS_*)
void emberGetGlobalPrefixReturn ( uint8_t flags,
bool isStable,
const uint8_t * prefix,
uint8_t prefixLengthInBits,
uint8_t domainId,
uint32_t preferredLifetime,
uint32_t validLifetime
)

This function provides the result of a call to ::emberGetGlobalPrefix.

Parameters
flags Please ignore this param, it is currently unused. (returns 0)
isStable Stable or temporary prefix
prefix Border router prefix
prefixLengthInBits Prefix length in bits
domainId Provisioning domain ID
preferredLifetime Preferred lifetime (in seconds)
validLifetime Valid lifetime (in seconds)
void emberGetMfgTokenReturn ( EmberMfgTokenId tokenId,
EmberStatus status,
const uint8_t * tokenData,
uint8_t tokenDataLength
)

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 emberGetNetworkDataReturn ( EmberStatus status,
uint8_t * networkData,
uint16_t bufferLength
)

This function provides the result of a call to emberGetNetworkData .

The status value is one of:

  • EMBER_SUCCESS
  • EMBER_NETWORK_DOWN
  • EMBER_BAD_ARGUMENT (the supplied buffer was too small)
Parameters
status
networkData location of the Network Data
dataLength length in bytes of the Network Data
void emberGetNetworkDataTlvReturn ( uint8_t typeByte,
uint8_t index,
uint8_t versionNumber,
const uint8_t * tlv,
uint8_t tlvLength
)

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

Parameters
type the type of TLV returned. This is the same value as the value specified in the emberGetNetworkDataTlv() call.
index the instance number of the TLV. This is the same value as the value specified in the emberGetNetworkDataTlv() call.
versionNumber the network data version
tlv the TLV corresponding to type or NULL.
tlvLength length of tlv
void emberGetPtaEnableReturn ( bool enabled )

This function provides the result of a call to emberGetPtaEnable .

Parameters
enabled When true, indicates packet traffic arbitration is enabed. When false, indicates packet traffic arbitration is disabled.
void emberGetPtaOptionsReturn ( uint32_t options )

This function provides the result of a call to emberGetPtaOptions .

Parameters
indicates packet traffic arbitration options bit field. Field Bit Position Size(bits) RX retry timeout ms 0 8 Enable ack radio holdoff 8 1 Abort mid TX if grant is lost 9 1 TX request is high priority 10 1 RX request is high prioirity 11 1 RX retry request is high priority 12 1 RX retry request is enabled 13 1 Radio holdoff is enabled 14 1 Toggle request on mac retransmit 15 1 Reserved 16 15 Hold request across CCA failures 31 1
void emberGetRadioPowerReturn ( int8_t power )

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

void emberGetRipEntryReturn ( uint8_t index,
const EmberRipEntry * entry
)

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

void emberGetRoutingLocatorReturn ( const EmberIpv6Address * rloc )

This function provides the result of a call to emberGetRoutingLocator .

Parameters
rloc The Routing Locator as a full IPv6 address.
void emberGetSecureDtlsSessionIdReturn ( uint8_t sessionId,
const EmberIpv6Address * remoteAddress,
uint16_t localPort,
uint16_t remotePort
)
Parameters
sessionId sessionId used for secure CoAP transport
remoteAddress remote IPv6 address
localPort local port
remotePort remote port
void emberGetStandaloneBootloaderInfoReturn ( uint16_t version,
uint8_t platformId,
uint8_t microId,
uint8_t phyId
)

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 emberGetTxPowerModeReturn ( uint16_t txPowerMode )

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

Returns
the current tx power mode.
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 emberInitReturn ( EmberStatus status )

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

void emberJoinNetworkReturn ( EmberStatus status )
void emberLaunchStandaloneBootloaderReturn ( EmberStatus status )

This function provides the result of a call to emberLaunchStandaloneBootloader .

Parameters
status An EmberStatus value indicating success or the reason for failure.
void emberLeaderDataHandler ( const uint8_t * leaderData )
Parameters
leaderData the leader data
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.
void emberMicroBusyHandler ( bool busy )

This callback is not available on a host processor. Note that if ::busy is true, the micro may become busy as soon as this handler exits. In a host/ncp setup, one solution for informing the host is to implement this handler in your own xNCP image and use it to toggle the serial CTS line.

void emberNetworkDataChangeHandler ( const uint8_t * networkData,
uint16_t length
)

This function is called when the stack receives new Thread Network Data. The networkData argument may be NULL, in which case emberGetNetworkData can be used to obtain the new Thread Network Data.

Parameters
networkData the Network Data
length length in bytes of the Network Data
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.

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.

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 emberOpenDtlsConnectionReturn ( uint32_t result,
const EmberIpv6Address * remoteAddress,
uint16_t localPort,
uint16_t remotePort
)
Parameters
result error code
  • an EmberStatus value if using Silicon Labs TLS
  • an mbed TLS error code if using mbed TLS library (see mbedtls:include/mbedtls/ssl.h)
remoteAddress IPv6 address of the server
localPort local port
remotePort remote port
void emberPollForDataReturn ( EmberStatus status )

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

Parameters
An EmberStatus value:
void emberProcessCoap ( const uint8_t * message,
uint16_t messageLength,
EmberCoapRequestInfo * info
)

This function processes a CoAP message received over an alternate transport.

Called to process a CoAP message that arrived via DTLS or other alternative transport. Only the address, port and transmit handler fields of info are used. The token and ackData fields are ignored.

void emberRadioGetRandomNumbersReturn ( EmberStatus status,
const uint16_t * rn,
uint8_t count
)

This function provides the result of a call to emberRadioGetRandomNumbers .

Parameters
status An EmberStatus value indicating success or the reason for failure. When EMBER_SUCCESS is returned ::rn and ::count will contain valid data. ::rn and ::count are undefined when EMBER_SUCCESS is not returned.
rn the uint16_t random values
count - the count of uint16_t values located at ::rn
void emberRequestDhcpAddressReturn ( EmberStatus status,
const uint8_t * prefix,
uint8_t prefixLengthInBits
)

This function provides the result of a call to emberRequestDhcpAddress .

This call only indicates the status of the request (EMBER_ERR_FATAL if no DHCP server is found, and EMBER_SUCCESS otherwise). The assigned IPv6 address is returned via emberAddressConfigurationChangeHandler

Parameters
status Status of DHCP Address Request
prefix Prefix requested in emberRequestDhcpAddress
prefixLengthInBits Prefix length in bits requested in emberRequestDhcpAddress
void emberRequestSlaacAddressReturn ( EmberStatus status,
const uint8_t * prefix,
uint8_t prefixLengthInBits
)

This function provides the result of a call to emberRequestSlaacAddress .

This call only indicates the status of the request (EMBER_ERR_FATAL if no SLAAC server is found, and EMBER_SUCCESS otherwise). The assigned IPv6 address is returned via emberAddressConfigurationChangeHandler

Parameters
status Status of SLAAC Address Request
prefix Prefix requested in emberRequestSlaacAddress
prefixLengthInBits Prefix length in bits requested in emberRequestSlaacAddress
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 emberResetMicroHandler ( EmberResetCause cause )

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

void emberResetNetworkStateReturn ( EmberStatus status )

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

void emberResignGlobalAddressReturn ( EmberStatus status )

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

void emberResumeNetworkReturn ( EmberStatus status )
void emberScanReturn ( EmberStatus status )

This function provides the status upon completion of a scan.

void emberSendSteeringDataReturn ( EmberStatus status )

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

void emberSetAddressHandler ( const uint8_t * address )

A callback that is generated when the host's address changes.

Parameters
address IP address, 16 bytes
void emberSetAntennaModeReturn ( EmberStatus status )

This function provides the result of a call to emberSetAntennaMode .

Parameters
EMBER_SUCCESS if antenna mode is configured as desired or EMBER_BAD_ARGUMENT if antenna mode is not supported.
void emberSetCcaThresholdReturn ( EmberStatus status )

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

void emberSetCommissionerKeyReturn ( EmberStatus status )

This function provides the result of a call to emberSetCommissionerKey() : either EMBER_SUCCESS or EMBER_INVALID_CALL.

void emberSetCtuneReturn ( EmberStatus status )

This function provides the result of a call to emberSetCtune .

Parameters
status An EmberStatus value indicating success or the reason for failure.
void emberSetDtlsDeviceCertificateReturn ( uint32_t result )
Parameters
result
  • ::0 The certificate was set successfully.
  • ::result error code
    • an EmberStatus value if using Silicon Labs TLS
    • an mbed TLS error code if using mbed TLS library (see mbedtls:include/mbedtls/ssl.h)
void emberSetDtlsPresharedKeyReturn ( EmberStatus status )
Parameters
result
  • ::status An EmberStatus value
void emberSetJoinKeyReturn ( EmberStatus status )

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

void emberSetLocalNetworkDataReturn ( EmberStatus status,
uint16_t length
)

Provides the result of a call to ::emberSetServerNetworkData.

void emberSetMfgTokenReturn ( EmberMfgTokenId tokenId,
EmberStatus status
)

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 emberSetNdDataReturn ( EmberStatus status,
uint16_t length
)

This function provides the result of a call to emberSetNdData .

void emberSetPskcHandler ( const uint8_t * pskc )
Parameters
pskc PSKc: 16 bytes in length
void emberSetPtaEnableReturn ( EmberStatus status )

This function provides the result of a call to emberSetPtaEnable .

Parameters
status An EmberStatus value indicating success or the reason for failure.
void emberSetPtaOptionsReturn ( EmberStatus status )

This function provides the result of a call to emberSetPtaOptions .

Parameters
status An EmberStatus value indicating success or the reason for failure.
void emberSetRadioHoldOffReturn ( EmberStatus status )

This function provides the result of a call to emberSetRadioHoldOff .

Parameters
status An EmberStatus value indicating success or the reason for failure. EMBER_SUCCESS if Radio HoldOff was configured as desired or EMBER_BAD_ARGUMENT if requesting it be enabled but RHO has not been configured by the BOARD_HEADER.
void emberSetRadioPowerReturn ( EmberStatus status )

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

void emberSetSecurityParametersReturn ( EmberStatus status )

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

void emberSetTxPowerModeReturn ( EmberStatus status )

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

void emberSlaacServerChangeHandler ( const uint8_t * prefix,
uint8_t prefixLengthInBits,
bool available
)

This function is called when the stack knows about a new SLAAC prefix or if a SLAAC server has become unavailable.

"available" means we can configure a SLAAC address.

Parameters
prefix SLAAC prefix
prefixLengthInBits length in bits of the prefix
available whether we can configure an address
void emberStackPollForDataReturn ( EmberStatus status )

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

void emberStartHostJoinClientHandler ( const uint8_t * parentAddress )

A callback to tell the host to start security commissioning.

Parameters
address parent IP address, 16 bytes
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 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() .