network-management API 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 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 emberGetPtaPwmOptionsReturn (uint8_t request, uint8_t dutyCycle, uint8_t periodHalfMs)
 This function provides the result of a call to emberGetPtaPwmOptions.
 
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 emberSetPtaPwmOptionsReturn (EmberStatus status)
 This function provides the result of a call to emberSetPtaPwmOptions.
 
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 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
addressthe address
preferredLifetimethe preferred lifetime of the address (in seconds)
validLifetimethe valid lifetime of the address (in seconds)
addressFlagsaddress 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
sessionIdsessionId 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
flagsA 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)
commissionerNameThe name of the active commissioner, or NULL if there is none or the name is not known.
commissionerNameLengthThe 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
statusWhether 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
typeThe type of the event.
incrementSpecify 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
typeThe type of the event.
Returns
The counter's tally.
void emberCustomHostToNcpMessageHandler ( const uint8_t *  message,
uint16_t  messageLength 
)
Parameters
messagemessage received
messageLengthlength of message
void emberCustomNcpToHostMessageHandler ( const uint8_t *  message,
uint16_t  messageLength 
)
Parameters
messagemessage received
messageLengthlength of message
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
prefixdhcp server prefix
prefixLengthInBitslength in bits of the prefix
availablewhether 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
flags1 = server, 0 = client (possibly other info later)
sessionIdsessionId used for secure CoAP transport
localAddresslocal IPv6 address
remoteAddressremote IPv6 address
localPortlocal port
remotePortremote port
void emberEnergyScanHandler ( uint8_t  channel,
int8_t  maxRssiValue 
)

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

Parameters
channelThe 802.15.4 channel on which the RSSI value was measured.
maxRssiValueThe maximum RSSI value measured (in units of dBm).
void emberEventDelayUpdatedFromIsrHandler ( Event event)
Parameters
eventThe 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
prefixexternal route prefix
prefixLengthInBitslength in bits of the prefix
availablewhether 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
statusAn EmberStatus value indicating success or the reason for failure.
modethe 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
tuneThe current CTUNE value.
statusAn 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
addressIPv6 global address
preferredLifetimePreferred lifetime (in seconds)
validLifetimeValid lifetime (in seconds)
addressFlagsAddress 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
flagsPlease ignore this param, it is currently unused. (returns 0)
isStableStable or temporary prefix
prefixBorder router prefix
prefixLengthInBitsPrefix length in bits
domainIdProvisioning domain ID
preferredLifetimePreferred lifetime (in seconds)
validLifetimeValid 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
tokenIdWhich manufacturing token read.
statusAn EmberStatus value indicating success or the
tokenDataThe manufacturing token data.
tokenDataLengthThe 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
networkDatalocation of the Network Data
dataLengthlength 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
typethe type of TLV returned. This is the same value as the value specified in the emberGetNetworkDataTlv() call.
indexthe instance number of the TLV. This is the same value as the value specified in the emberGetNetworkDataTlv() call.
versionNumberthe network data version
tlvthe TLV corresponding to type or NULL.
tlvLengthlength of tlv
void emberGetPtaEnableReturn ( bool  enabled)

This function provides the result of a call to emberGetPtaEnable.

Parameters
enabledWhen 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
indicatespacket 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 emberGetPtaPwmOptionsReturn ( uint8_t  request,
uint8_t  dutyCycle,
uint8_t  periodHalfMs 
)
Parameters
requestPTA PWM bit field Field Bit Position Size(bits) Request enabled 0 1 Priority enabled 1 1
dutyCyclePTA PWM duty cycle percentage(0-100)
periodHalfMsPTA PWM request period in half milliseconds
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
rlocThe Routing Locator as a full IPv6 address.
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
versionBOOTLOADER_INVALID_VERSION if the standalone bootloader is not present, or the version of the installed standalone bootloader.
platformIdThe value of PLAT on the node.
microIdThe value of MICRO on the node.
phyIdThe 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
parametersCurrent network parameters
localEui64The EUI64 of the Ember chip
macExtendedIdThe extended MAC ID of the Ember chip
networkStatusThe 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
statusAn EmberStatus value indicating success or the reason for failure.
void emberLeaderDataHandler ( const uint8_t *  leaderData)
Parameters
leaderDatathe 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
macHeaderA 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
headerThe 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
macHeaderA 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
currentRssiThe 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
networkDatathe Network Data
lengthlength 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
resulterror 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)
remoteAddressIPv6 address of the server
localPortlocal port
remotePortremote port
void emberPollForDataReturn ( EmberStatus  status)

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

Parameters
AnEmberStatus 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
statusAn 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.
rnthe 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
statusStatus of DHCP Address Request
prefixPrefix requested in emberRequestDhcpAddress
prefixLengthInBitsPrefix 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
statusStatus of SLAAC Address Request
prefixPrefix requested in emberRequestSlaacAddress
prefixLengthInBitsPrefix 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
typeThe 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
addressIP address, 16 bytes
void emberSetAntennaModeReturn ( EmberStatus  status)

This function provides the result of a call to emberSetAntennaMode.

Parameters
EMBER_SUCCESSif 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
statusAn 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
tokenIdWhich manufacturing token set.
statusAn 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
pskcPSKc: 16 bytes in length
void emberSetPtaEnableReturn ( EmberStatus  status)

This function provides the result of a call to emberSetPtaEnable.

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

This function provides the result of a call to emberSetPtaOptions.

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

This function provides the result of a call to emberSetRadioHoldOff.

Parameters
statusAn 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
prefixSLAAC prefix
prefixLengthInBitslength in bits of the prefix
availablewhether 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
addressparent IP address, 16 bytes
void emberStateReturn ( const EmberNetworkParameters parameters,
const EmberEui64 localEui64,
const EmberEui64 macExtendedId,
EmberNetworkStatus  networkStatus 
)
Parameters
parametersCurrent network parameters
localEui64The EUI64 of the Ember chip
macExtendedIdThe extended MAC ID of the Ember chip
networkStatusThe 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().