Commissioner

This module includes functions for the Thread Commissioner role.

Summary

Enumerations
otCommissionerJoinerEvent	enum This enumeration defines a Joiner Event on the Commissioner.
otCommissionerState{   OT_COMMISSIONER_STATE_DISABLED = 0,   OT_COMMISSIONER_STATE_PETITION = 1,   OT_COMMISSIONER_STATE_ACTIVE = 2 }	enum This enumeration defines the Commissioner State.
otJoinerInfoType{   OT_JOINER_INFO_TYPE_ANY = 0,   OT_JOINER_INFO_TYPE_EUI64 = 1,   OT_JOINER_INFO_TYPE_DISCERNER = 2 }	enum This enumeration defines a Joiner Info Type.

Typedefs
otCommissionerEnergyReportCallback)(uint32_t aChannelMask, const uint8_t *aEnergyList, uint8_t aEnergyListLength, void *aContext)	typedef void(* This function pointer is called when the Commissioner receives an Energy Report.
otCommissionerJoinerCallback)(otCommissionerJoinerEvent aEvent, const otJoinerInfo *aJoinerInfo, const otExtAddress *aJoinerId, void *aContext)	typedef void(* This function pointer is called whenever the joiner state changes.
otCommissionerJoinerEvent	typedef enum otCommissionerJoinerEvent This enumeration defines a Joiner Event on the Commissioner.
otCommissionerPanIdConflictCallback)(uint16_t aPanId, uint32_t aChannelMask, void *aContext)	typedef void(* This function pointer is called when the Commissioner receives a PAN ID Conflict message.
otCommissionerState	typedef enum otCommissionerState This enumeration defines the Commissioner State.
otCommissionerStateCallback)(otCommissionerState aState, void *aContext)	typedef void(* This function pointer is called whenever the commissioner state changes.
otCommissioningDataset	typedef struct otCommissioningDataset This structure represents a Commissioning Dataset.
otJoinerInfo	typedef struct otJoinerInfo This structure represents a Joiner Info.
otJoinerInfoType	typedef enum otJoinerInfoType This enumeration defines a Joiner Info Type.
otJoinerPskd	typedef struct otJoinerPskd This structure represents a Joiner PSKd.
otSteeringData	typedef struct otSteeringData This structure represents the steering data.

Functions
otCommissionerAddJoiner(otInstance *aInstance, const otExtAddress *aEui64, const char *aPskd, uint32_t aTimeout)	otError This function adds a Joiner entry.
otCommissionerAddJoinerWithDiscerner(otInstance *aInstance, const otJoinerDiscerner *aDiscerner, const char *aPskd, uint32_t aTimeout)	otError This function adds a Joiner entry with a given Joiner Discerner value.
otCommissionerAnnounceBegin(otInstance *aInstance, uint32_t aChannelMask, uint8_t aCount, uint16_t aPeriod, const otIp6Address *aAddress)	otError This function sends an Announce Begin message.
otCommissionerEnergyScan(otInstance *aInstance, uint32_t aChannelMask, uint8_t aCount, uint16_t aPeriod, uint16_t aScanDuration, const otIp6Address *aAddress, otCommissionerEnergyReportCallback aCallback, void *aContext)	otError This function sends an Energy Scan Query message.
otCommissionerGetId(otInstance *aInstance)	const char * This function returns the Commissioner Id.
otCommissionerGetNextJoinerInfo(otInstance *aInstance, uint16_t *aIterator, otJoinerInfo *aJoiner)	otError This method get joiner info at aIterator position.
otCommissionerGetProvisioningUrl(otInstance *aInstance)	const char * This function gets the Provisioning URL.
otCommissionerGetSessionId(otInstance *aInstance)	uint16_t This function returns the Commissioner Session ID.
otCommissionerGetState(otInstance *aInstance)	otCommissionerState This function returns the Commissioner State.
otCommissionerPanIdQuery(otInstance *aInstance, uint16_t aPanId, uint32_t aChannelMask, const otIp6Address *aAddress, otCommissionerPanIdConflictCallback aCallback, void *aContext)	otError This function sends a PAN ID Query message.
otCommissionerRemoveJoiner(otInstance *aInstance, const otExtAddress *aEui64)	otError This function removes a Joiner entry.
otCommissionerRemoveJoinerWithDiscerner(otInstance *aInstance, const otJoinerDiscerner *aDiscerner)	otError This function removes a Joiner entry.
otCommissionerSendMgmtGet(otInstance *aInstance, const uint8_t *aTlvs, uint8_t aLength)	otError This function sends MGMT_COMMISSIONER_GET.
otCommissionerSendMgmtSet(otInstance *aInstance, const otCommissioningDataset *aDataset, const uint8_t *aTlvs, uint8_t aLength)	otError This function sends MGMT_COMMISSIONER_SET.
otCommissionerSetId(otInstance *aInstance, const char *aId)	otError This function sets the Commissioner Id.
otCommissionerSetProvisioningUrl(otInstance *aInstance, const char *aProvisioningUrl)	otError This function sets the Provisioning URL.
otCommissionerStart(otInstance *aInstance, otCommissionerStateCallback aStateCallback, otCommissionerJoinerCallback aJoinerCallback, void *aCallbackContext)	otError This function enables the Thread Commissioner role.
otCommissionerStop(otInstance *aInstance)	otError This function disables the Thread Commissioner role.

Macros
OT_COMMISSIONING_PASSPHRASE_MAX_SIZE 255	Maximum size of the Commissioning Passphrase.
OT_COMMISSIONING_PASSPHRASE_MIN_SIZE 6	Minimum size of the Commissioning Passphrase.
OT_JOINER_MAX_PSKD_LENGTH 32	Maximum string length of a Joiner PSKd (does not include null char).
OT_PROVISIONING_URL_MAX_SIZE 64	Max size (number of chars) in Provisioning URL string (excludes null char).
OT_STEERING_DATA_MAX_LENGTH 16	Max steering data length (bytes)

Structs
otCommissioningDataset	This structure represents a Commissioning Dataset.
otJoinerInfo	This structure represents a Joiner Info.
otJoinerPskd	This structure represents a Joiner PSKd.
otSteeringData	This structure represents the steering data.

Enumerations

otCommissionerJoinerEvent

 otCommissionerJoinerEvent

This enumeration defines a Joiner Event on the Commissioner.

otCommissionerState

 otCommissionerState

This enumeration defines the Commissioner State.

Properties
OT_COMMISSIONER_STATE_ACTIVE	Commissioner role is active.
OT_COMMISSIONER_STATE_DISABLED	Commissioner role is disabled.
OT_COMMISSIONER_STATE_PETITION	Currently petitioning to become a Commissioner.

otJoinerInfoType

 otJoinerInfoType

This enumeration defines a Joiner Info Type.

Properties
OT_JOINER_INFO_TYPE_ANY	Accept any Joiner (no EUI64 or Discerner is specified).
OT_JOINER_INFO_TYPE_DISCERNER	Joiner Discerner is specified (mSharedId.mDiscerner in otJoinerInfo).
OT_JOINER_INFO_TYPE_EUI64	Joiner EUI-64 is specified (mSharedId.mEui64 in otJoinerInfo).

Typedefs

otCommissionerEnergyReportCallback

void(* otCommissionerEnergyReportCallback)(uint32_t aChannelMask, const uint8_t *aEnergyList, uint8_t aEnergyListLength, void *aContext)

This function pointer is called when the Commissioner receives an Energy Report.

Details
Parameters	[in] aChannelMask The channel mask value. [in] aEnergyList A pointer to the energy measurement list. [in] aEnergyListLength Number of entries in aEnergyListLength. [in] aContext A pointer to application-specific context.

otCommissionerJoinerCallback

void(* otCommissionerJoinerCallback)(otCommissionerJoinerEvent aEvent, const otJoinerInfo *aJoinerInfo, const otExtAddress *aJoinerId, void *aContext)

This function pointer is called whenever the joiner state changes.

Details
Parameters	[in] aEvent The joiner event type. [in] aJoinerInfo A pointer to the Joiner Info. [in] aJoinerId A pointer to the Joiner ID (if not known, it will be NULL). [in] aContext A pointer to application-specific context.

otCommissionerJoinerEvent

enum otCommissionerJoinerEvent otCommissionerJoinerEvent

This enumeration defines a Joiner Event on the Commissioner.

otCommissionerPanIdConflictCallback

void(* otCommissionerPanIdConflictCallback)(uint16_t aPanId, uint32_t aChannelMask, void *aContext)

This function pointer is called when the Commissioner receives a PAN ID Conflict message.

Details
Parameters	[in] aPanId The PAN ID value. [in] aChannelMask The channel mask value. [in] aContext A pointer to application-specific context.

otCommissionerState

enum otCommissionerState otCommissionerState

This enumeration defines the Commissioner State.

otCommissionerStateCallback

void(* otCommissionerStateCallback)(otCommissionerState aState, void *aContext)

This function pointer is called whenever the commissioner state changes.

Details
Parameters	[in] aState The Commissioner state. [in] aContext A pointer to application-specific context.

otCommissioningDataset

struct otCommissioningDataset otCommissioningDataset

This structure represents a Commissioning Dataset.

otJoinerInfo

struct otJoinerInfo otJoinerInfo

This structure represents a Joiner Info.

otJoinerInfoType

enum otJoinerInfoType otJoinerInfoType

This enumeration defines a Joiner Info Type.

otJoinerPskd

struct otJoinerPskd otJoinerPskd

This structure represents a Joiner PSKd.

otSteeringData

struct otSteeringData otSteeringData

This structure represents the steering data.

Functions

otCommissionerAddJoiner

otError otCommissionerAddJoiner(
  otInstance *aInstance,
  const otExtAddress *aEui64,
  const char *aPskd,
  uint32_t aTimeout
)

This function adds a Joiner entry.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart().

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aEui64 A pointer to the Joiner's IEEE EUI-64 or NULL for any Joiner. [in] aPskd A pointer to the PSKd. [in] aTimeout A time after which a Joiner is automatically removed, in seconds.
Return Values	OT_ERROR_NONE Successfully added the Joiner. OT_ERROR_NO_BUFS No buffers available to add the Joiner. OT_ERROR_INVALID_ARGS aEui64 or aPskd is invalid. OT_ERROR_INVALID_STATE The commissioner is not active.

otCommissionerAddJoinerWithDiscerner

otError otCommissionerAddJoinerWithDiscerner(
  otInstance *aInstance,
  const otJoinerDiscerner *aDiscerner,
  const char *aPskd,
  uint32_t aTimeout
)

This function adds a Joiner entry with a given Joiner Discerner value.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart().

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDiscerner A pointer to the Joiner Discerner. [in] aPskd A pointer to the PSKd. [in] aTimeout A time after which a Joiner is automatically removed, in seconds.
Return Values	OT_ERROR_NONE Successfully added the Joiner. OT_ERROR_NO_BUFS No buffers available to add the Joiner. OT_ERROR_INVALID_ARGS aDiscerner or aPskd is invalid. OT_ERROR_INVALID_STATE The commissioner is not active.

otCommissionerAnnounceBegin

otError otCommissionerAnnounceBegin(
  otInstance *aInstance,
  uint32_t aChannelMask,
  uint8_t aCount,
  uint16_t aPeriod,
  const otIp6Address *aAddress
)

This function sends an Announce Begin message.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart().

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aChannelMask The channel mask value. [in] aCount The number of Announcement messages per channel. [in] aPeriod The time between two successive MLE Announce transmissions (in milliseconds). [in] aAddress A pointer to the IPv6 destination.
Return Values	OT_ERROR_NONE Successfully enqueued the Announce Begin message. OT_ERROR_NO_BUFS Insufficient buffers to generate an Announce Begin message. OT_ERROR_INVALID_STATE The commissioner is not active.

otCommissionerEnergyScan

otError otCommissionerEnergyScan(
  otInstance *aInstance,
  uint32_t aChannelMask,
  uint8_t aCount,
  uint16_t aPeriod,
  uint16_t aScanDuration,
  const otIp6Address *aAddress,
  otCommissionerEnergyReportCallback aCallback,
  void *aContext
)

This function sends an Energy Scan Query message.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart().

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aChannelMask The channel mask value. [in] aCount The number of energy measurements per channel. [in] aPeriod The time between energy measurements (milliseconds). [in] aScanDuration The scan duration for each energy measurement (milliseconds). [in] aAddress A pointer to the IPv6 destination. [in] aCallback A pointer to a function called on receiving an Energy Report message. [in] aContext A pointer to application-specific context.
Return Values	OT_ERROR_NONE Successfully enqueued the Energy Scan Query message. OT_ERROR_NO_BUFS Insufficient buffers to generate an Energy Scan Query message. OT_ERROR_INVALID_STATE The commissioner is not active.

otCommissionerGetId

const char * otCommissionerGetId(
  otInstance *aInstance
)

This function returns the Commissioner Id.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The Commissioner Id.

otCommissionerGetNextJoinerInfo

otError otCommissionerGetNextJoinerInfo(
  otInstance *aInstance,
  uint16_t *aIterator,
  otJoinerInfo *aJoiner
)

This method get joiner info at aIterator position.

Details
Parameters	[in] aInstance A pointer to instance. [in,out] aIterator A pointer to the Joiner Info iterator context. [out] aJoiner A reference to Joiner info.
Return Values	OT_ERROR_NONE Successfully get the Joiner info. OT_ERROR_NOT_FOUND Not found next Joiner.

otCommissionerGetProvisioningUrl

const char * otCommissionerGetProvisioningUrl(
  otInstance *aInstance
)

This function gets the Provisioning URL.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	A pointer to the URL string.

otCommissionerGetSessionId

uint16_t otCommissionerGetSessionId(
  otInstance *aInstance
)

This function returns the Commissioner Session ID.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The current commissioner session id.

otCommissionerGetState

otCommissionerState otCommissionerGetState(
  otInstance *aInstance
)

This function returns the Commissioner State.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Return Values	OT_COMMISSIONER_STATE_DISABLED Commissioner disabled. OT_COMMISSIONER_STATE_PETITION Becoming the commissioner. OT_COMMISSIONER_STATE_ACTIVE Commissioner enabled.

otCommissionerPanIdQuery

otError otCommissionerPanIdQuery(
  otInstance *aInstance,
  uint16_t aPanId,
  uint32_t aChannelMask,
  const otIp6Address *aAddress,
  otCommissionerPanIdConflictCallback aCallback,
  void *aContext
)

This function sends a PAN ID Query message.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart().

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aPanId The PAN ID to query. [in] aChannelMask The channel mask value. [in] aAddress A pointer to the IPv6 destination. [in] aCallback A pointer to a function called on receiving a PAN ID Conflict message. [in] aContext A pointer to application-specific context.
Return Values	OT_ERROR_NONE Successfully enqueued the PAN ID Query message. OT_ERROR_NO_BUFS Insufficient buffers to generate a PAN ID Query message. OT_ERROR_INVALID_STATE The commissioner is not active.

otCommissionerRemoveJoiner

otError otCommissionerRemoveJoiner(
  otInstance *aInstance,
  const otExtAddress *aEui64
)

This function removes a Joiner entry.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart().

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aEui64 A pointer to the Joiner's IEEE EUI-64 or NULL for any Joiner.
Return Values	OT_ERROR_NONE Successfully removed the Joiner. OT_ERROR_NOT_FOUND The Joiner specified by aEui64 was not found. OT_ERROR_INVALID_ARGS aEui64 is invalid. OT_ERROR_INVALID_STATE The commissioner is not active.

otCommissionerRemoveJoinerWithDiscerner

otError otCommissionerRemoveJoinerWithDiscerner(
  otInstance *aInstance,
  const otJoinerDiscerner *aDiscerner
)

This function removes a Joiner entry.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart().

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDiscerner A pointer to the Joiner Discerner.
Return Values	OT_ERROR_NONE Successfully removed the Joiner. OT_ERROR_NOT_FOUND The Joiner specified by aEui64 was not found. OT_ERROR_INVALID_ARGS aDiscerner is invalid. OT_ERROR_INVALID_STATE The commissioner is not active.

otCommissionerSendMgmtGet

otError otCommissionerSendMgmtGet(
  otInstance *aInstance,
  const uint8_t *aTlvs,
  uint8_t aLength
)

This function sends MGMT_COMMISSIONER_GET.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aTlvs A pointer to TLVs. [in] aLength The length of TLVs.
Return Values	OT_ERROR_NONE Successfully send the meshcop dataset command. OT_ERROR_NO_BUFS Insufficient buffer space to send. OT_ERROR_INVALID_STATE The commissioner is not active.

otCommissionerSendMgmtSet

otError otCommissionerSendMgmtSet(
  otInstance *aInstance,
  const otCommissioningDataset *aDataset,
  const uint8_t *aTlvs,
  uint8_t aLength
)

This function sends MGMT_COMMISSIONER_SET.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDataset A pointer to commissioning dataset. [in] aTlvs A pointer to TLVs. [in] aLength The length of TLVs.
Return Values	OT_ERROR_NONE Successfully send the meshcop dataset command. OT_ERROR_NO_BUFS Insufficient buffer space to send. OT_ERROR_INVALID_STATE The commissioner is not active.

otCommissionerSetId

otError otCommissionerSetId(
  otInstance *aInstance,
  const char *aId
)

This function sets the Commissioner Id.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aId A pointer to a string character array. Must be null terminated.
Return Values	OT_ERROR_NONE Successfully set the Commissioner Id. OT_ERROR_INVALID_ARGS Given name is too long. OT_ERROR_INVALID_STATE The commissioner is active and id cannot be changed.

otCommissionerSetProvisioningUrl

otError otCommissionerSetProvisioningUrl(
  otInstance *aInstance,
  const char *aProvisioningUrl
)

This function sets the Provisioning URL.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aProvisioningUrl A pointer to the Provisioning URL (may be NULL to set as empty string).
Return Values	OT_ERROR_NONE Successfully set the Provisioning URL. OT_ERROR_INVALID_ARGS aProvisioningUrl is invalid (too long).

otCommissionerStart

otError otCommissionerStart(
  otInstance *aInstance,
  otCommissionerStateCallback aStateCallback,
  otCommissionerJoinerCallback aJoinerCallback,
  void *aCallbackContext
)

This function enables the Thread Commissioner role.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aStateCallback A pointer to a function that is called when the commissioner state changes. [in] aJoinerCallback A pointer to a function that is called with a joiner event occurs. [in] aCallbackContext A pointer to application-specific context.
Return Values	OT_ERROR_NONE Successfully started the Commissioner service. OT_ERROR_ALREADY Commissioner is already started. OT_ERROR_INVALID_STATE Device is not currently attached to a network.

otCommissionerStop

otError otCommissionerStop(
  otInstance *aInstance
)

This function disables the Thread Commissioner role.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Return Values	OT_ERROR_NONE Successfully stopped the Commissioner service. OT_ERROR_ALREADY Commissioner is already stopped.

Macros

OT_COMMISSIONING_PASSPHRASE_MAX_SIZE

 OT_COMMISSIONING_PASSPHRASE_MAX_SIZE 255

Maximum size of the Commissioning Passphrase.

OT_COMMISSIONING_PASSPHRASE_MIN_SIZE

 OT_COMMISSIONING_PASSPHRASE_MIN_SIZE 6

Minimum size of the Commissioning Passphrase.

OT_JOINER_MAX_PSKD_LENGTH

 OT_JOINER_MAX_PSKD_LENGTH 32

Maximum string length of a Joiner PSKd (does not include null char).

OT_PROVISIONING_URL_MAX_SIZE

 OT_PROVISIONING_URL_MAX_SIZE 64

Max size (number of chars) in Provisioning URL string (excludes null char).

OT_STEERING_DATA_MAX_LENGTH

 OT_STEERING_DATA_MAX_LENGTH 16

Max steering data length (bytes)

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.