Network Utilities
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.
|
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()
.
|
|
bool | emberDeepSleepTick (void) |
An application handler for deep sleep on sleepy end devices. This call is ignored for non-sleepy devices. The device may or may not sleep depending on the internal state.
|
|
void | emberDeepSleep (bool sleep) |
This function turns chip deep sleep on or off for sleepy end devices. This call is ignored on non-sleepy devices. The device may or may not sleep depending on the internal state.
|
|
void | emberDeepSleepReturn ( EmberStatus status) |
This function provides the result of a call to
emberDeepSleep()
.
|
|
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.
|
|
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 |
enum EmberIdleRadioState |
enum EmberResetCause |
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 emberDeepSleep | ( | bool |
sleep
|
) |
void emberDeepSleepCompleteHandler | ( | uint16_t |
sleepDuration
|
) |
void emberDeepSleepReturn | ( | EmberStatus |
status
|
) |
This function provides the result of a call to emberDeepSleep() .
bool emberDeepSleepTick | ( | void |
|
) |
- Returns
- true if going to deep sleep.
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
|
) |
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: - EMBER_SUCCESS - The poll message has been submitted for transmission
- EMBER_INVALID_CALL - The node is not a sleepy end device.
- EMBER_NOT_JOINED - The node is not part of a network.
This function provides the result of a call to emberPollForData() .
- Parameters
-
An
EmberStatus value: - EMBER_SUCCESS - The poll message has been submitted for transmission
- EMBER_INVALID_CALL - The node is not a sleepy end device.
- EMBER_NOT_JOINED - The node is not part of a network.
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 for instructions on how to set the MFG_PHY_CONFIG token appropriately. rt@e mber. com
- 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:
- EMBER_SUCCESS , the scan completed succesffully.
- EMBER_MAC_SCANNING , we are already scanning.
- EMBER_MAC_BAD_SCAN_DURATION , we have set a duration value that is not 0..14 inclusive.
- EMBER_MAC_INCORRECT_SCAN_TYPE , we have requested an undefined scanning type;
- EMBER_MAC_INVALID_CHANNEL_MASK , our channel mask did not specify any valid channels on the current platform.
- 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 |
|
) |