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

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

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

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.

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

Commissioner

Summary

Enumerations

Typedefs

Functions

Structs

Enumerations

otCommissionerJoinerEvent

otCommissionerState

otJoinerInfoType

Typedefs

otCommissionerEnergyReportCallback

otCommissionerJoinerCallback

otCommissionerJoinerEvent

otCommissionerPanIdConflictCallback

otCommissionerState

otCommissionerStateCallback

otCommissioningDataset

otJoinerInfo

otJoinerInfoType

otJoinerPskd

otSteeringData

Functions

otCommissionerAddJoiner

otCommissionerAddJoinerWithDiscerner

otCommissionerAnnounceBegin

otCommissionerEnergyScan

otCommissionerGetNextJoinerInfo

otCommissionerGetProvisioningUrl

otCommissionerGetSessionId

otCommissionerGetState

otCommissionerPanIdQuery

otCommissionerRemoveJoiner

otCommissionerRemoveJoinerWithDiscerner

otCommissionerSendMgmtGet

otCommissionerSendMgmtSet

otCommissionerSetProvisioningUrl

otCommissionerStart

otCommissionerStop

Macros

OT_COMMISSIONING_PASSPHRASE_MAX_SIZE

OT_COMMISSIONING_PASSPHRASE_MIN_SIZE

OT_JOINER_MAX_PSKD_LENGTH

OT_PROVISIONING_URL_MAX_SIZE

OT_STEERING_DATA_MAX_LENGTH