Commissioning Utilities.

Enumerations
enum	{ EMBER_NO_COMMISSIONER = 0, EMBER_HAVE_COMMISSIONER = BIT(0), EMBER_AM_COMMISSIONER = BIT(1), EMBER_JOINING_ENABLED = BIT(2), EMBER_JOINING_WITH_EUI_STEERING = BIT(3) }
	Flag values for emberCommissionerStatusHandler() .

enum	EmberJoiningMode { EMBER_NO_JOINING , EMBER_JOINING_ALLOW_ALL_STEERING , EMBER_JOINING_ALLOW_EUI_STEERING , EMBER_JOINING_ALLOW_SMALL_EUI_STEERING }
	Joining modes, passed to emberSetJoiningMode() on the commissioner. No change takes place until emberSendSteeringData() is called. If steering is used, the EUI-64s of the joining devices should be passed to emberAddSteeringEui64() before calling emberSendSteeringData() .

Functions
void	emberBecomeCommissioner (const uint8_t *deviceName, uint8_t deviceNameLength)
	This function petitions to make this device the commissioner for the network. This will succeed if there is no active commissioner and fail if there is one.

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	emberStopCommissioning (void)
	This function causes this device to cease being the active commissioner. This call always succeeds and has no return.

void	emberGetCommissioner (void)
	This function causes the stack to call emberCommissionerStatusHandler() to report the current commissioner status. This always succeeds and has no return.

void	emberAllowNativeCommissioner (bool on)
	This function causes the stack to allow a connection to a native commissioner.

void	emberAllowNativeCommissionerReturn ( EmberStatus status)
	This function provides the result of a call to emberAllowNativeCommissioner() : either EMBER_SUCCESS or EMBER_INVALID_CALL.

void	emberSetCommissionerKey (const uint8_t *commissionerKey, uint8_t commissionerKeyLength)
	This function sets the key that a native commissioner must use to establish a connection to a Thread router. The commissionerKey argument is known as the "commissioning credential" in the Thread spec and must be between 6 and 255 bytes in length. Internally, it is hashed to derive the 16-byte Pre-Shared Key for the commissioner, known as the PSKc.

void	emberSetCommissionerKeyReturn ( EmberStatus status)
	This function 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	emberCommissionerStatusHandler (uint16_t flags, const uint8_t *commissionerName, uint8_t commissionerNameLength)
	This function reports on the current commissioner state.

void	emberSetJoiningMode ( EmberJoiningMode mode, uint8_t length)
	This function sets the joining mode, clearing the steering data if steering is to be used.

void	emberAddSteeringEui64 (const EmberEui64 *eui64)
	This function adds the given EUI64 to the steering data if this device is the active commissioner; has no effect otherwise.

void	emberSendSteeringData (void)
	This function sends the current steering data to the network, enabling joining in the process.

void	emberSendSteeringDataReturn ( EmberStatus status)
	This function provides the result of a call to emberSendSteeringData() .

void	emberSetJoinKey (const EmberEui64 eui64, const uint8_t key, uint8_t keyLength)
	This function supplies the commissioner with the key a joining node will be using.

void	emberSetJoinKeyReturn ( EmberStatus status)
	This function provides the result of a call to emberSetJoinKey() .

void	emberEnableHostDtlsClient (bool enable)
	This function allows DTLS implementations on the host.

void	emberCommissionNetwork (uint8_t preferredChannel, uint32_t fallbackChannelMask, const uint8_t networkId, uint8_t networkIdLength, uint16_t panId, const uint8_t ulaPrefix, const uint8_t extendedPanId, const EmberKeyData key, uint32_t keySequence)
	This function commissions the network.

void	emberCommissionNetworkReturn ( EmberStatus status)
	This function provides the result of a call to emberCommissionNetwork.

Detailed Description

See network-management.h for source code.

Enumeration Type Documentation

anonymous enum

Enumerator
EMBER_NO_COMMISSIONER
EMBER_HAVE_COMMISSIONER
EMBER_AM_COMMISSIONER
EMBER_JOINING_ENABLED
EMBER_JOINING_WITH_EUI_STEERING

enum EmberJoiningMode

Enumerator
EMBER_NO_JOINING	Disable joining.
EMBER_JOINING_ALLOW_ALL_STEERING	Allow joining, with no steering information.
EMBER_JOINING_ALLOW_EUI_STEERING	Allow joining, clearing steering data.
EMBER_JOINING_ALLOW_SMALL_EUI_STEERING	Allow joining, clearing steering data. Only the low three bytes of EUI-64s will be used for steering. Note: This option is deprecated in Thread 1.1.

Function Documentation

void emberAddSteeringEui64 ( const EmberEui64 * eui64 )

The steering data is a Bloom filter for the EUI64s of the devices that are expected to join the network. Each added EUI64 is passed to a hash function to choose a set of bits in the filter, and those bits are set. Each potential joiner can then hash their own EUI64 and check if the resulting bits are set in the advertised filter. If so, the device is (probably) expected to join; if not, it definitely is not expected to join.

void emberAllowNativeCommissioner ( bool on )

Note: This call must be made on the leader before forming a network.

Parameters

`on`	Enable / disable connections to native commissioners

void emberAllowNativeCommissionerReturn ( EmberStatus status )

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

void emberBecomeCommissioner	(	const uint8_t *	`deviceName,`
		uint8_t	`deviceNameLength`
	)

Parameters

`deviceName`	A name for this device as a human-readable string. If this device becomes the commissioner this name is sent to any other would-be commissioners so that the user can identify the current commissioner.
`deviceNameLength`	The length of the name.

void emberBecomeCommissionerReturn ( EmberStatus status )

void emberCommissionerStatusHandler	(	uint16_t	`flags,`
		const uint8_t *	`commissionerName,`
		uint8_t	`commissionerNameLength`
	)

Parameters

`flags`	A 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)
`commissionerName`	The name of the active commissioner, or NULL if there is none or the name is not known.
`commissionerNameLength`	The length of commissonerName.

This function reports on the current commissioner state.

Parameters

`flags`	A 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)
`commissionerName`	The name of the active commissioner, or NULL if there is none or the name is not known.
`commissionerNameLength`	The length of commissonerName.

void emberCommissionNetwork	(	uint8_t	`preferredChannel,`
		uint32_t	`fallbackChannelMask,`
		const uint8_t *	`networkId,`
		uint8_t	`networkIdLength,`
		uint16_t	`panId,`
		const uint8_t *	`ulaPrefix,`
		const uint8_t *	`extendedPanId,`
		const EmberKeyData *	`key,`
		uint32_t	`keySequence`
	)

This call must be made prior to calling emberJoinCommissioned() . It will not be successful if the node is already on a network.

All options except panId are REQUIRED. If a REQUIRED option is not provided, the callback emberJoinNetworkReturn will be sent to the app with an EMBER_BAD_ARGUMENT status.

Notes: If preferredChannel is 0, EMBER_ALL_802_15_4_CHANNELS_MASK is used instead of fallbackChannelMask. If preferredChannel is valid, it will automatically be added to the fallbackChannelMask.

Parameters

`preferredChannel`	[the preferred channel]
`fallbackChannelMask`	[the fallback channel mask]
`networkId`	[the network ID]
`networkIdLength`	[the string length of networkId]
`panId`	[the short pan ID]
`ulaPrefix`	[the 8-byte ULA prefix]
`extendedPanId`	[the 8-byte extended pan ID]
`key`	[the master key]
`keySequence`	[starting key sequence, default: 0]

void emberCommissionNetworkReturn ( EmberStatus status )

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

status Whether the call to emberCommissionNetwork was successful

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

status Whether the call to emberCommissionNetwork was successful

void emberEnableHostDtlsClient ( bool enable )

This call is made in order to force the host to interface with an external commissioner if available, or use DTLS capabilities on the host (if they exist) for Thread joining or other security handshakes.

This is enabled by default for the Thread Border Router implementation. However, if the device (Border Router or otherwise) wants to use existing DTLS capabilities on the NCP stack, such as for joining, this should be toggled to false.

Parameters

enable If true, this call allows the host to perform DTLS.

void emberGetCommissioner ( void )

void emberSendSteeringData ( void )

void emberSendSteeringDataReturn ( EmberStatus status )

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

void emberSetCommissionerKey	(	const uint8_t *	`commissionerKey,`
		uint8_t	`commissionerKeyLength`
	)

Note: This call must be made on the leader before forming a network, or on an on-mesh commissioner that wants to set the PSKc in the active dataset.

Parameters

`commissionerKey`	the key
`commissionerKeyLength`	key length

void emberSetCommissionerKeyReturn ( EmberStatus status )

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

void emberSetJoiningMode	(	EmberJoiningMode	`mode,`
		uint8_t	`length`
	)

No change takes place until emberSendSteeringData() is called. If steering is used, the EUI-64s of the joining devices should be passed to emberAddSteeringEui64() before calling emberSendSteeringData() .

Parameters

`mode`	The joining mode
`length`	The length in bytes of the Bloom filter to be included in the Steering Data TLV. This field is only applicable when mode is set to EMBER_JOINING_ALLOW_EUI_STEERING. Refer to the Thread specification for details on the Bloom filter and the probability of collisions given the number of bits in the Bloom filter and the number of identifiers included.

void emberSetJoinKey	(	const EmberEui64 *	`eui64,`
		const uint8_t *	`key,`
		uint8_t	`keyLength`
	)

Parameters

`eui64`	The EUI64 of the next node expected to join. NULL may be used if the EUI64 is not known.
`key`	The joining key that the device will be using.
`keyLength`	The length of the joining key.

void emberSetJoinKeyReturn ( EmberStatus status )

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

void emberSetPskcHandler ( const uint8_t * pskc )

Parameters

pskc PSKc: 16 bytes in length

void emberStopCommissioning ( void )

When this call is made, emberCommissionerStatusHandler will not return the EMBER_AM_COMMISSIONER flag anymore.

Commissioning Thread Stack API Reference

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation

Commissioning
Thread Stack API Reference