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.

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.

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.

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.

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.

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.

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.

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.

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)

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) { ... }.

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) { ... }.

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.

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)

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.

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.

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.

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.

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.

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

Note

This function does not alter the MFG_PHY_CONFIG token. The MFG_PHY_CONFIG token must be properly configured to ensure optimal radio performance when the standalone bootloader runs in recovery mode. The MFG_PHY_CONFIG can only be set using external tools. IF YOUR PRODUCT USES BOOST MODE OR THE ALTERNATE TRANSMITTER OUTPUT AND THE STANDALONE BOOTLOADER YOU MUST SET THE PHY_CONFIG TOKEN INSTEAD OF USING THIS FUNCTION. Contact suppo.nosp@m.rt@e.nosp@m.mber..nosp@m.com for instructions on how to set the MFG_PHY_CONFIG token appropriately.

Parameters

txPowerMode

Specifies which of the transmit power mode options are to be activated. This parameter should be set to one of the literal values described in stack/include/ember-types.h. Any power option not specified in the txPowerMode parameter will be deactivated.

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.

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.