Forming and Joining Utilities.

Macros

#define EMBER_USE_DEFAULTS   0
 The following denotes which network parameters to use when forming or joining a network. Construct an uint16_t "options" flag for use in various network formation calls.
 
#define EMBER_NETWORK_ID_OPTION   BIT(0)
 
#define EMBER_ULA_PREFIX_OPTION   BIT(1)
 
#define EMBER_EXTENDED_PAN_ID_OPTION   BIT(2)
 
#define EMBER_PAN_ID_OPTION   BIT(3)
 
#define EMBER_NODE_TYPE_OPTION   BIT(4)
 
#define EMBER_TX_POWER_OPTION   BIT(5)
 
#define EMBER_MASTER_KEY_OPTION   BIT(6)
 
#define EMBER_JOIN_KEY_OPTION   BIT(8)

Functions

void emberConfigureNetwork (const EmberNetworkParameters *parameters, uint16_t options)
 This function configures network parameters.
 
void emberFormNetwork (const EmberNetworkParameters *parameters, uint16_t options, uint32_t channelMask)
 This function forms a new network.
 
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 emberJoinNetwork (const EmberNetworkParameters *parameters, uint16_t options, uint32_t channelMask)
 This function joins an existing network.
 
void emberJoinCommissioned (int8_t radioTxPower, EmberNodeType nodeType, bool requireConnectivity)
 This function joins an already-commissioned network.
 
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 emberResumeNetwork (void)
 This function resumes network operation after a reboot of the Ember micro.
 
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 emberAttachToNetwork (void)
 On an end device, this initiates an attach with any available router-eligible devices in the network. This call must only be made if the network materials have been pre-commissioned on this device, or if previously completed obtaining the commissioning materials from another device.
 
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 emberSetParentPriority (int8_t parentPriority)
 A function to set the parent priority value.
 
void emberSetParentPriorityReturn (EmberStatus status)
 A callback to indicate if the call to emberSetParentPriority() was successful.
 
void emberGetParentPriority (void)
 A function to get the parent priority value.
 
void emberGetParentPriorityReturn (const int8_t parentPriority)
 In a host/NCP setup, provides the result of a call to emberGetParentPriority() on the host.
 
void emberSetAddressHandler (const uint8_t *address)
 A callback that is generated when the host's address changes.
 
void emberSetDriverAddressHandler (const uint8_t *address)
 A callback to the IP driver to tell it to change its address.
 
void emberStartHostJoinClientHandler (const uint8_t *parentAddress)
 A callback to tell the host to start security commissioning.
 
void emberSetNetworkKeysHandler (uint32_t sequence, const uint8_t *masterKey, uint32_t sequence2, const uint8_t *masterKey2)
 A callback to the IP driver to tell it the network keys.
 
void emberSetCommProxyAppParametersHandler (const uint8_t *extendedPanId, const uint8_t *networkId, const uint8_t *ulaPrefix, uint16_t panId, uint8_t channel, const EmberEui64 *eui64, const EmberEui64 *macExtendedId, EmberNetworkStatus networkStatus)
 A callback to provide the commission-proxy-app on the host with the requisite network parameters.
 
void emberSetCommProxyAppSecurityHandler (const uint8_t *masterKey, uint32_t sequenceNumber)
 A callback to provide the commission-proxy-app on the host with the requisite security material.
 
void emberSetCommProxyAppAddressHandler (const uint8_t *address)
 A callback to provide the commission-proxy-app on the host with our mesh local address.
 
void emberSetCommProxyAppPskcHandler (const uint8_t *pskc)
 A callback to provide the commission-proxy-app on the host with the pskc.
 
void emberSetCommProxyAppJoinKey (const EmberEui64 *eui64, const uint8_t *key, uint8_t keyLength)
 A callback to provide the commission-proxy-app on the host with an [EUI, join passphrase] pair.
 
void emberChangeNodeType (EmberNodeType newType)
 This function changes the node type of a joined device.
 
void emberChangeNodeTypeReturn (EmberStatus status)
 This function provides the result of a call to emberChangeNodeType(): either EMBER_SUCCESS, or EMBER_INVALID_CALL.

Detailed Description

See network-management.h for source code.

Macro Definition Documentation

#define EMBER_EXTENDED_PAN_ID_OPTION   BIT(2)
#define EMBER_JOIN_KEY_OPTION   BIT(8)
#define EMBER_MASTER_KEY_OPTION   BIT(6)
#define EMBER_NETWORK_ID_OPTION   BIT(0)
#define EMBER_NODE_TYPE_OPTION   BIT(4)
#define EMBER_PAN_ID_OPTION   BIT(3)
#define EMBER_TX_POWER_OPTION   BIT(5)
#define EMBER_ULA_PREFIX_OPTION   BIT(1)
#define EMBER_USE_DEFAULTS   0

Function Documentation

void emberAttachToNetwork ( void  )

The status of whether the attach process was initiated is reported to the application via emberAttachToNetworkReturn(). Changes to the network status resulting from the attach process are reported to the application via emberNetworkStatusHandler().

This function may only be called when the network status is EMBER_JOINED_NETWORK_NO_PARENT and an attach is not already underway.

void emberAttachToNetworkReturn ( EmberStatus  status)
void emberChangeNodeType ( EmberNodeType  newType)

The device must be joined to a network prior to making this call.

Parameters
newTypeThe node type to change to.
void emberChangeNodeTypeReturn ( EmberStatus  status)

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

void emberConfigureNetwork ( const EmberNetworkParameters parameters,
uint16_t  options 
)

This function assigns the network configuration values that will be used when the device forms or joins a network.

This function may only be called when the network status is EMBER_NO_NETWORK. If the node was previously part of a network, use emberResumeNetwork() to recover after a reboot. To forget the network and return to a status of EMBER_NO_NETWORK, please read cautions for emberResetNetworkState().

Parameters
parametersSome parameters may be supplied by the caller.
optionsA bitmask indicating which network parameters are being supplied by the caller. The following list enumerates the options that can be set.
  • EMBER_NETWORK_ID_OPTION
  • EMBER_EXTENDED_PAN_ID_OPTION
  • EMBER_ULA_PREFIX_OPTION
  • EMBER_MASTER_KEY_OPTION
  • EMBER_PAN_ID_OPTION
void emberFormNetwork ( const EmberNetworkParameters parameters,
uint16_t  options,
uint32_t  channelMask 
)

The forming node chooses a random extended pan ID, network ULA prefix, and pan ID for the new network. It peforms an energy scan of the channels indicated by the channelMask argument and selects the one with lowest detected energy. It performs an active scan on that channel to ensure there is no pan ID conflict. emberFormNetworkReturn() indicates whether the form process was initiated. Changes to the network status resulting from the form process are reported to the application via emberNetworkStatusHandler().

This function may only be called when the network status is EMBER_NO_NETWORK, and when a scan is not underway. If the node was previously part of a network, use emberResumeNetwork() to recover after a reboot. To forget the network and return to a status of EMBER_NO_NETWORK, read cautions for emberResetNetworkState().

Parameters
parametersSome parameters may be supplied by the caller.
optionsA bitmask indicating which network parameters are being supplied by the caller. The following list enumerates the allowed options and the default value used if the option is not specified:
  • EMBER_NETWORK_ID_OPTION default: ember
  • EMBER_ULA_PREFIX_OPTION default: random
  • EMBER_NODE_TYPE_OPTION default: EMBER_ROUTER
  • EMBER_TX_POWER_OPTION default: 3
channelMaskA mask indicating the channels to be scanned. See emberStartScan() for format details.
void emberFormNetworkReturn ( EmberStatus  status)
void emberGetParentPriority ( void  )

Note: If this value is not set by the application, the stack returns 0 (default value) & -1 (if the node has less that 1/3 child capacity remaining)

void emberGetParentPriorityReturn ( const int8_t  parentPriority)
Parameters
parentPriorityParent Priority value.

In a host/NCP setup, provides the result of a call to emberGetParentPriority() on the host.

Parameters
parentPriorityParent Priority
void emberJoinCommissioned ( int8_t  radioTxPower,
EmberNodeType  nodeType,
bool  requireConnectivity 
)

This function assumes that commissioning data has already been cached via a call to emberConfigureNetwork().

Parameters
radioTxPowerDesired radio output power, in dBm.
nodeTypeType of device.
requireConnectivityIf commissioned join fails, specify whether this node should start a new fragment. Note: The short PAN ID MUST be commissioned if this is true.
void emberJoinNetwork ( const EmberNetworkParameters parameters,
uint16_t  options,
uint32_t  channelMask 
)

The joining node performs an active scan of the channels indicated by the channelMask argument. It looks for networks matching the criteria specified via the supplied parameters, and which currently allow joining. The status of whether the join process was initiated is reported to the application via emberResumeNetworkReturn(). Changes to the network status resulting from the join process are reported to the application via emberNetworkStatusHandler().

This function may only be called when the network status is EMBER_NO_NETWORK, and when a scan is not underway. If the node was previously part of a network, use emberResumeNetwork() to recover after a reboot. To forget the network and return to a status of EMBER_NO_NETWORK, please read cautions for emberResetNetworkState().

Parameters
parametersSome parameters may be supplied by the caller.
optionsA bitmask indicating which network parameters are being supplied by the caller. The following list enumerates the allowed options and the default value used if the option is not specified:
  • EMBER_NETWORK_ID_OPTION default: looks for any network id
  • EMBER_EXTENDED_PAN_ID_OPTION default: looks for any extended pan id
  • EMBER_PAN_ID_OPTION default: looks for any pan id
  • EMBER_NODE_TYPE_OPTION default: EMBER_ROUTER
  • EMBER_TX_POWER_OPTION default: 3
  • EMBER_JOIN_KEY_OPTION default: empty
channelMaskA mask indicating the channels to be scanned. See emberStartScan() for format details.
void emberJoinNetworkReturn ( EmberStatus  status)
void emberResumeNetwork ( void  )

If the device was previously part of a network, it will recover its former network parameters including pan id, extended pan id, node type, etc. and resume participation in the network. The status of whether the resume process was initiated is reported to the application via emberResumeNetworkReturn(). Changes to the network status resulting from the resume process are reported to the application via emberNetworkStatusHandler().

This function may only be called when the network status is EMBER_SAVED_NETWORK and when a scan is not underway.

void emberResumeNetworkReturn ( EmberStatus  status)
void emberSetAddressHandler ( const uint8_t *  address)
Parameters
addressIP address, 16 bytes

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

Parameters
addressIP address, 16 bytes
void emberSetCommProxyAppAddressHandler ( const uint8_t *  address)
void emberSetCommProxyAppJoinKey ( const EmberEui64 eui64,
const uint8_t *  key,
uint8_t  keyLength 
)
void emberSetCommProxyAppParametersHandler ( const uint8_t *  extendedPanId,
const uint8_t *  networkId,
const uint8_t *  ulaPrefix,
uint16_t  panId,
uint8_t  channel,
const EmberEui64 eui64,
const EmberEui64 macExtendedId,
EmberNetworkStatus  networkStatus 
)
void emberSetCommProxyAppPskcHandler ( const uint8_t *  pskc)
void emberSetCommProxyAppSecurityHandler ( const uint8_t *  masterKey,
uint32_t  sequenceNumber 
)
void emberSetDriverAddressHandler ( const uint8_t *  address)
Parameters
addressIP address, 16 bytes
void emberSetNetworkKeysHandler ( uint32_t  sequence,
const uint8_t *  masterKey,
uint32_t  sequence2,
const uint8_t *  masterKey2 
)
Parameters
sequencesequence number
masterKeymaster key, 16 bytes
sequence2second sequence number
masterKey2NotUsedsecond key, 16 bytes
void emberSetParentPriority ( int8_t  parentPriority)
Parameters
parentPriorityParent priority. Valid Inputs are: 1, 0 (default) & -1

Note: If this value is not set, the stack uses 0 (as default) & -1 (if the node has less that 1/3 child capacity remaining)

void emberSetParentPriorityReturn ( EmberStatus  status)

A callback to indicate if the call to emberSetParentPriority() was successful.

void emberStartHostJoinClientHandler ( const uint8_t *  parentAddress)
Parameters
addressparent IP address, 16 bytes

A callback to tell the host to start security commissioning.

Parameters
addressparent IP address, 16 bytes