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

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

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.

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] aEui64 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.

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)