Commissioner

This module includes functions for the Thread Commissioner role.

Summary

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

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

Functions
otCommissionerAddJoiner(otInstance *aInstance, const otExtAddress *aEui64, const char *aPskd, uint32_t aTimeout)	otError Adds a Joiner entry.
otCommissionerAddJoinerWithDiscerner(otInstance *aInstance, const otJoinerDiscerner *aDiscerner, const char *aPskd, uint32_t aTimeout)	otError 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 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 Sends an Energy Scan Query message.
otCommissionerGetId(otInstance *aInstance)	const char * Returns the Commissioner Id.
otCommissionerGetNextJoinerInfo(otInstance *aInstance, uint16_t *aIterator, otJoinerInfo *aJoiner)	otError Get joiner info at aIterator position.
otCommissionerGetProvisioningUrl(otInstance *aInstance)	const char * Gets the Provisioning URL.
otCommissionerGetSessionId(otInstance *aInstance)	uint16_t Returns the Commissioner Session ID.
otCommissionerGetState(otInstance *aInstance)	otCommissionerState Returns the Commissioner State.
otCommissionerPanIdQuery(otInstance *aInstance, uint16_t aPanId, uint32_t aChannelMask, const otIp6Address *aAddress, otCommissionerPanIdConflictCallback aCallback, void *aContext)	otError Sends a PAN ID Query message.
otCommissionerRemoveJoiner(otInstance *aInstance, const otExtAddress *aEui64)	otError Removes a Joiner entry.
otCommissionerRemoveJoinerWithDiscerner(otInstance *aInstance, const otJoinerDiscerner *aDiscerner)	otError Removes a Joiner entry.
otCommissionerSendMgmtGet(otInstance *aInstance, const uint8_t *aTlvs, uint8_t aLength)	otError Sends MGMT_COMMISSIONER_GET.
otCommissionerSendMgmtSet(otInstance *aInstance, const otCommissioningDataset *aDataset, const uint8_t *aTlvs, uint8_t aLength)	otError Sends MGMT_COMMISSIONER_SET.
otCommissionerSetId(otInstance *aInstance, const char *aId)	otError Sets the Commissioner Id.
otCommissionerSetProvisioningUrl(otInstance *aInstance, const char *aProvisioningUrl)	otError Sets the Provisioning URL.
otCommissionerStart(otInstance *aInstance, otCommissionerStateCallback aStateCallback, otCommissionerJoinerCallback aJoinerCallback, void *aCallbackContext)	otError Enables the Thread Commissioner role.
otCommissionerStop(otInstance *aInstance)	otError 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	Represents a Commissioning Dataset.
otJoinerInfo	Represents a Joiner Info.
otJoinerPskd	Represents a Joiner PSKd.
otSteeringData	Represents the steering data.

Enumerations

otCommissionerJoinerEvent

 otCommissionerJoinerEvent

Defines a Joiner Event on the Commissioner.

otCommissionerState

 otCommissionerState

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

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)

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)

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

Defines a Joiner Event on the Commissioner.

otCommissionerPanIdConflictCallback

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

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

Defines the Commissioner State.

otCommissionerStateCallback

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

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

Represents a Commissioning Dataset.

otJoinerInfo

struct otJoinerInfo otJoinerInfo

Represents a Joiner Info.

otJoinerInfoType

enum otJoinerInfoType otJoinerInfoType

Defines a Joiner Info Type.

otJoinerPskd

struct otJoinerPskd otJoinerPskd

Represents a Joiner PSKd.

otSteeringData

struct otSteeringData otSteeringData

Represents the steering data.

Functions

otCommissionerAddJoiner

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

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
)

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
)

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
)

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
)

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
)

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
)

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
)

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
)

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
)

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
)

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
)

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
)

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
)

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
)

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
)

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
)

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
)

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.