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	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

newType The 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

`parameters`	Some parameters may be supplied by the caller.
`options`	A 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

`parameters`	Some parameters may be supplied by the caller.
`options`	A 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
`channelMask`	A 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

parentPriority Parent Priority value.

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

Parameters

parentPriority Parent 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

`radioTxPower`	Desired radio output power, in dBm.
`nodeType`	Type of device.
`requireConnectivity`	If 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

`parameters`	Some parameters may be supplied by the caller.
`options`	A 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
`channelMask`	A 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

address IP address, 16 bytes

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

Parameters

address IP address, 16 bytes

void emberSetCommProxyAppAddressHandler ( const uint8_t * address )

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

address IP address, 16 bytes

void emberSetNetworkKeysHandler	(	uint32_t	`sequence,`
		const uint8_t *	`masterKey,`
		uint32_t	`sequence2,`
		const uint8_t *	`masterKey2`
	)

Parameters

`sequence`	sequence number
`masterKey`	master key, 16 bytes
`sequence2`	second sequence number
`masterKey2NotUsed`	second key, 16 bytes

void emberSetParentPriority ( int8_t parentPriority )

Parameters

parentPriority Parent 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

address parent IP address, 16 bytes

A callback to tell the host to start security commissioning.

Parameters

address parent IP address, 16 bytes

Forming and Joining Thread Stack API Reference

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation

Forming and Joining
Thread Stack API Reference