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
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
Defines the Commissioner State.
otCommissionerStateCallback)(otCommissionerState aState, void *aContext) typedef
void(*
Pointer is called whenever the commissioner state changes.
otCommissioningDataset typedef
Represents a Commissioning Dataset.
otJoinerInfo typedef
struct otJoinerInfo
Represents a Joiner Info.
otJoinerInfoType typedef
Defines a Joiner Info Type.
otJoinerPskd typedef
struct otJoinerPskd
Represents a Joiner PSKd.
otSteeringData typedef
Represents the steering data.

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

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.

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.

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.

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.

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.

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.

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.