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.

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 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.
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.
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.
otCommissionerGeneratePSKc(otInstance *aInstance, const char *aPassPhrase, const char *aNetworkName, const otExtendedPanId *aExtPanId, uint8_t *aPSKc)	otError This method generates PSKc.
otCommissionerGetNextJoinerInfo(otInstance *aInstance, uint16_t & aIterator, otJoinerInfo & aJoiner)	otError This method get joiner info at aIterator position.
otCommissionerGetProvisioningUrl(otInstance *aInstance, uint16_t *aLength)	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.
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.
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.

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 otExtAddress *aJoinerId, void *aContext)

This function pointer is called whenever the joiner state changes.

Details
Parameters	[in] aEvent The joiner event type. [in] aJoinerId A pointer to the Joiner ID. [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.

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.

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.

otCommissionerGeneratePSKc

otError otCommissionerGeneratePSKc(
  otInstance *aInstance,
  const char *aPassPhrase,
  const char *aNetworkName,
  const otExtendedPanId *aExtPanId,
  uint8_t *aPSKc
)

This method generates PSKc.

PSKc is used to establish the Commissioner Session.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aPassPhrase The commissioning passphrase. [in] aNetworkName The network name for PSKc computation. [in] aExtPanId The extended pan id for PSKc computation. [out] aPSKc A pointer to the generated PSKc.
Return Values	OT_ERROR_NONE Successfully generate PSKc. OT_ERROR_INVALID_ARGS If any of the input arguments is invalid.

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 iterator to the index of the joiner. [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,
  uint16_t *aLength
)

This function gets the Provisioning URL.

Note that the returned URL string buffer is not necessarily null-terminated.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [out] aLength A pointer to uint16_t to return the length (number of chars) in the URL string.

Details
Returns	A pointer to char buffer containing the URL string, or NULL if aLength is NULL.

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.

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).
Return Values	OT_ERROR_NONE Successfully set the Provisioning URL. OT_ERROR_INVALID_ARGS aProvisioningUrl is invalid.

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 role. OT_ERROR_INVALID_STATE Commissioner is already started.

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 role. OT_ERROR_INVALID_STATE 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_PSKD_MAX_SIZE

 OT_PSKD_MAX_SIZE 32

Size of a Joiner PSKd (bytes)

OT_STEERING_DATA_MAX_LENGTH

 OT_STEERING_DATA_MAX_LENGTH 16

Max steering data length (bytes)