This module includes functions for the Thread Commissioner role.

Classes
struct	otSteeringData
	This structure represents the steering data.

struct	otCommissioningDataset
	This structure represents a Commissioning Dataset.

struct	otJoinerPskd
	This structure represents a Joiner PSKd.

struct	otJoinerInfo
	This structure represents a Joiner Info.

Macros
#define	OT_COMMISSIONING_PASSPHRASE_MIN_SIZE 6
	Minimum size of the Commissioning Passphrase.

#define	OT_COMMISSIONING_PASSPHRASE_MAX_SIZE 255
	Maximum size of the Commissioning Passphrase.

#define	OT_PROVISIONING_URL_MAX_SIZE 64
	Max size (number of chars) in Provisioning URL string (excludes null char).

#define	OT_STEERING_DATA_MAX_LENGTH 16
	Max steering data length (bytes)

#define	OT_JOINER_MAX_PSKD_LENGTH 32
	Maximum string length of a Joiner PSKd (does not include null char).

Typedefs
typedef enum otCommissionerState	otCommissionerState
	This enumeration defines the Commissioner State.

typedef enum otCommissionerJoinerEvent	otCommissionerJoinerEvent
	This enumeration defines a Joiner Event on the Commissioner.

typedef struct otSteeringData	otSteeringData
	This structure represents the steering data.

typedef struct otCommissioningDataset	otCommissioningDataset
	This structure represents a Commissioning Dataset.

typedef struct otJoinerPskd	otJoinerPskd
	This structure represents a Joiner PSKd.

typedef enum otJoinerInfoType	otJoinerInfoType
	This enumeration defines a Joiner Info Type.

typedef struct otJoinerInfo	otJoinerInfo
	This structure represents a Joiner Info.

typedef void(*	otCommissionerStateCallback ) ( otCommissionerState aState, void *aContext)
	This function pointer is called whenever the commissioner state changes.

typedef void(*	otCommissionerJoinerCallback ) ( otCommissionerJoinerEvent aEvent, const otJoinerInfo aJoinerInfo, const otExtAddress aJoinerId, void *aContext)
	This function pointer is called whenever the joiner state changes.

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

typedef void(*	otCommissionerPanIdConflictCallback ) (uint16_t aPanId, uint32_t aChannelMask, void *aContext)
	This function pointer is called when the Commissioner receives a PAN ID Conflict message.

Enumerations
enum	otCommissionerState { OT_COMMISSIONER_STATE_DISABLED = 0, OT_COMMISSIONER_STATE_PETITION = 1, OT_COMMISSIONER_STATE_ACTIVE = 2 }
	This enumeration defines the Commissioner State.

enum	otCommissionerJoinerEvent { OT_COMMISSIONER_JOINER_START = 0, OT_COMMISSIONER_JOINER_CONNECTED = 1, OT_COMMISSIONER_JOINER_FINALIZE = 2, OT_COMMISSIONER_JOINER_END = 3, OT_COMMISSIONER_JOINER_REMOVED = 4 }
	This enumeration defines a Joiner Event on the Commissioner.

enum	otJoinerInfoType { OT_JOINER_INFO_TYPE_ANY = 0, OT_JOINER_INFO_TYPE_EUI64 = 1, OT_JOINER_INFO_TYPE_DISCERNER = 2 }
	This enumeration defines a Joiner Info Type.

Functions
otError	otCommissionerStart ( otInstance aInstance, otCommissionerStateCallback aStateCallback, otCommissionerJoinerCallback aJoinerCallback, void aCallbackContext)
	This function enables the Thread Commissioner role.

otError	otCommissionerStop ( otInstance *aInstance)
	This function disables the Thread Commissioner role.

const char *	otCommissionerGetId ( otInstance *aInstance)
	This function returns the Commissioner Id.

otError	otCommissionerSetId ( otInstance aInstance, const char aId)
	This function sets the Commissioner Id.

otError	otCommissionerAddJoiner ( otInstance aInstance, const otExtAddress aEui64, const char *aPskd, uint32_t aTimeout)
	This function adds a Joiner entry.

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.

otError	otCommissionerGetNextJoinerInfo ( otInstance aInstance, uint16_t aIterator, otJoinerInfo *aJoiner)
	This method get joiner info at aIterator position.

otError	otCommissionerRemoveJoiner ( otInstance aInstance, const otExtAddress aEui64)
	This function removes a Joiner entry.

otError	otCommissionerRemoveJoinerWithDiscerner ( otInstance aInstance, const otJoinerDiscerner aDiscerner)
	This function removes a Joiner entry.

const char *	otCommissionerGetProvisioningUrl ( otInstance *aInstance)
	This function gets the Provisioning URL.

otError	otCommissionerSetProvisioningUrl ( otInstance aInstance, const char aProvisioningUrl)
	This function sets the Provisioning URL.

otError	otCommissionerAnnounceBegin ( otInstance aInstance, uint32_t aChannelMask, uint8_t aCount, uint16_t aPeriod, const otIp6Address aAddress)
	This function sends an Announce Begin message.

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.

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.

otError	otCommissionerSendMgmtGet ( otInstance aInstance, const uint8_t aTlvs, uint8_t aLength)
	This function sends MGMT_COMMISSIONER_GET.

otError	otCommissionerSendMgmtSet ( otInstance aInstance, const otCommissioningDataset aDataset, const uint8_t *aTlvs, uint8_t aLength)
	This function sends MGMT_COMMISSIONER_SET.

uint16_t	otCommissionerGetSessionId ( otInstance *aInstance)
	This function returns the Commissioner Session ID.

otCommissionerState	otCommissionerGetState ( otInstance *aInstance)
	This function returns the Commissioner State.

Detailed Description

This module includes functions for the Thread Commissioner role.

Typedef Documentation

◆ otCommissionerEnergyReportCallback

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

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

typedef void(* otCommissionerJoinerCallback) ( otCommissionerJoinerEvent aEvent, const otJoinerInfo *aJoinerInfo, const otExtAddress *aJoinerId, void *aContext)

This function pointer is called whenever the joiner state changes.

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.

◆ otCommissionerPanIdConflictCallback

typedef void(* otCommissionerPanIdConflictCallback) (uint16_t aPanId, uint32_t aChannelMask, void *aContext)

This function pointer is called when the Commissioner receives a PAN ID Conflict message.

Parameters

[in]	`aPanId`	The PAN ID value.
[in]	`aChannelMask`	The channel mask value.
[in]	`aContext`	A pointer to application-specific context.

◆ otCommissionerStateCallback

typedef void(* otCommissionerStateCallback) ( otCommissionerState aState, void *aContext)

This function pointer is called whenever the commissioner state changes.

Parameters

[in]	`aState`	The Commissioner state.
[in]	`aContext`	A pointer to application-specific context.

Enumeration Type Documentation

◆ otCommissionerState

enum otCommissionerState

This enumeration defines the Commissioner State.

Enumerator
OT_COMMISSIONER_STATE_DISABLED	Commissioner role is disabled.
OT_COMMISSIONER_STATE_PETITION	Currently petitioning to become a Commissioner.
OT_COMMISSIONER_STATE_ACTIVE	Commissioner role is active.

◆ otJoinerInfoType

enum otJoinerInfoType

This enumeration defines a Joiner Info Type.

Enumerator
OT_JOINER_INFO_TYPE_ANY	Accept any Joiner (no EUI64 or Discerner is specified).
OT_JOINER_INFO_TYPE_EUI64	Joiner EUI-64 is specified ( `mSharedId.mEui64` in `otJoinerInfo` ).
OT_JOINER_INFO_TYPE_DISCERNER	Joiner Discerner is specified ( `mSharedId.mDiscerner` in `otJoinerInfo` ).

Function Documentation

◆ otCommissionerAddJoiner()

otError otCommissionerAddJoiner	(	otInstance *	`aInstance,`
		const otExtAddress *	`aEui64,`
		const char *	`aPskd,`
		uint32_t	`aTimeout`
	)

This function adds a Joiner entry.

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.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart() .

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

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.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart() .

◆ otCommissionerAnnounceBegin()

otError otCommissionerAnnounceBegin	(	otInstance *	`aInstance,`
		uint32_t	`aChannelMask,`
		uint8_t	`aCount,`
		uint16_t	`aPeriod,`
		const otIp6Address *	`aAddress`
	)

This function sends an Announce Begin message.

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.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart() .

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

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.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart() .

◆ otCommissionerGetId()

const char* otCommissionerGetId ( otInstance * aInstance )

This function returns the Commissioner Id.

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.

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.

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.

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.

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.

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.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart() .

◆ otCommissionerRemoveJoiner()

otError otCommissionerRemoveJoiner	(	otInstance *	`aInstance,`
		const otExtAddress *	`aEui64`
	)

This function removes a Joiner entry.

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.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart() .

◆ otCommissionerRemoveJoinerWithDiscerner()

otError otCommissionerRemoveJoinerWithDiscerner	(	otInstance *	`aInstance,`
		const otJoinerDiscerner *	`aDiscerner`
	)

This function removes a Joiner entry.

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.

Note: Only use this after successfully starting the Commissioner role with otCommissionerStart() .

◆ otCommissionerSendMgmtGet()

otError otCommissionerSendMgmtGet	(	otInstance *	`aInstance,`
		const uint8_t *	`aTlvs,`
		uint8_t	`aLength`
	)

This function sends MGMT_COMMISSIONER_GET.

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.

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.

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.

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.

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.

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.

Commissioner API > Thread

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ otCommissionerEnergyReportCallback

◆ otCommissionerJoinerCallback

◆ otCommissionerPanIdConflictCallback

◆ otCommissionerStateCallback

Enumeration Type Documentation

◆ otCommissionerState

◆ otJoinerInfoType

Function Documentation

◆ otCommissionerAddJoiner()

◆ otCommissionerAddJoinerWithDiscerner()

◆ otCommissionerAnnounceBegin()

◆ otCommissionerEnergyScan()

◆ otCommissionerGetId()

◆ otCommissionerGetNextJoinerInfo()

◆ otCommissionerGetProvisioningUrl()

◆ otCommissionerGetSessionId()

◆ otCommissionerGetState()

◆ otCommissionerPanIdQuery()

◆ otCommissionerRemoveJoiner()

◆ otCommissionerRemoveJoinerWithDiscerner()

◆ otCommissionerSendMgmtGet()

◆ otCommissionerSendMgmtSet()

◆ otCommissionerSetId()

◆ otCommissionerSetProvisioningUrl()

◆ otCommissionerStart()

◆ otCommissionerStop()

Commissioner
API > Thread