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 
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
onEnable / 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
deviceNameA 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.
deviceNameLengthThe length of the name.
void emberBecomeCommissionerReturn ( EmberStatus  status)
void emberCommissionerStatusHandler ( uint16_t  flags,
const uint8_t *  commissionerName,
uint8_t  commissionerNameLength 
)
Parameters
flagsA 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)
commissionerNameThe name of the active commissioner, or NULL if there is none or the name is not known.
commissionerNameLengthThe length of commissonerName.

This function reports on the current commissioner state.

Parameters
flagsA 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)
commissionerNameThe name of the active commissioner, or NULL if there is none or the name is not known.
commissionerNameLengthThe 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
statusWhether 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
statusWhether 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
enableIf 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
commissionerKeythe key
commissionerKeyLengthkey 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
modeThe joining mode
lengthThe 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
eui64The EUI64 of the next node expected to join. NULL may be used if the EUI64 is not known.
keyThe joining key that the device will be using.
keyLengthThe 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
pskcPSKc: 16 bytes in length
void emberStopCommissioning ( void  )

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