Stay organized with collections Save and categorize content based on your preferences.

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
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
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
This structure represents a Commissioning Dataset.
otJoinerInfo typedef
struct otJoinerInfo
This structure represents a Joiner Info.
otJoinerInfoType typedef
This enumeration defines a Joiner Info Type.
otJoinerPskd typedef
struct otJoinerPskd
This structure represents a Joiner PSKd.
otSteeringData typedef
This structure represents the steering data.

Functions

otCommissionerAddJoiner(otInstance *aInstance, const otExtAddress *aEui64, const char *aPskd, uint32_t aTimeout)
This function adds a Joiner entry.
otCommissionerAddJoinerWithDiscerner(otInstance *aInstance, const otJoinerDiscerner *aDiscerner, const char *aPskd, uint32_t aTimeout)
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)
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)
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)
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)
This function returns the Commissioner State.
otCommissionerPanIdQuery(otInstance *aInstance, uint16_t aPanId, uint32_t aChannelMask, const otIp6Address *aAddress, otCommissionerPanIdConflictCallback aCallback, void *aContext)
This function sends a PAN ID Query message.
otCommissionerRemoveJoiner(otInstance *aInstance, const otExtAddress *aEui64)
This function removes a Joiner entry.
otCommissionerRemoveJoinerWithDiscerner(otInstance *aInstance, const otJoinerDiscerner *aDiscerner)
This function removes a Joiner entry.
otCommissionerSendMgmtGet(otInstance *aInstance, const uint8_t *aTlvs, uint8_t aLength)
This function sends MGMT_COMMISSIONER_GET.
otCommissionerSendMgmtSet(otInstance *aInstance, const otCommissioningDataset *aDataset, const uint8_t *aTlvs, uint8_t aLength)
This function sends MGMT_COMMISSIONER_SET.
otCommissionerSetId(otInstance *aInstance, const char *aId)
This function sets the Commissioner Id.
otCommissionerSetProvisioningUrl(otInstance *aInstance, const char *aProvisioningUrl)
This function sets the Provisioning URL.
otCommissionerStart(otInstance *aInstance, otCommissionerStateCallback aStateCallback, otCommissionerJoinerCallback aJoinerCallback, void *aCallbackContext)
This function enables the Thread Commissioner role.
otCommissionerStop(otInstance *aInstance)
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] 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.

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.

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.

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.

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.

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.

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.

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.