This module includes functions for the Thread Commissioner role. More...

Data Structures
struct	otSteeringData

struct	otCommissioningDataset

struct	otJoinerInfo

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_PSKD_MAX_SIZE 32
	Size of a Joiner PSKd (bytes)

Typedefs
typedef enum otCommissionerState	otCommissionerState

typedef enum otCommissionerJoinerEvent	otCommissionerJoinerEvent

typedef struct otSteeringData	otSteeringData

typedef struct otCommissioningDataset	otCommissioningDataset

typedef struct otJoinerInfo	otJoinerInfo

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

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

typedef void(*	otCommissionerEnergyReportCallback )(uint32_t aChannelMask, const uint8_t aEnergyList, uint8_t aEnergyListLength, void aContext)

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

Enumerations
enum	otCommissionerState { OT_COMMISSIONER_STATE_DISABLED = 0, OT_COMMISSIONER_STATE_PETITION = 1, OT_COMMISSIONER_STATE_ACTIVE = 2 }

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 }

Functions
otError	otCommissionerStart (otInstance aInstance, otCommissionerStateCallback aStateCallback, otCommissionerJoinerCallback aJoinerCallback, void aCallbackContext)

otError	otCommissionerStop (otInstance *aInstance)

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

otError	otCommissionerGetNextJoinerInfo (otInstance aInstance, uint16_t aIterator, otJoinerInfo *aJoiner)

otError	otCommissionerRemoveJoiner (otInstance aInstance, const otExtAddress aEui64)

const char *	otCommissionerGetProvisioningUrl (otInstance *aInstance)

otError	otCommissionerSetProvisioningUrl (otInstance aInstance, const char aProvisioningUrl)

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

otError	otCommissionerEnergyScan (otInstance aInstance, uint32_t aChannelMask, uint8_t aCount, uint16_t aPeriod, uint16_t aScanDuration, const otIp6Address aAddress, otCommissionerEnergyReportCallback aCallback, void *aContext)

otError	otCommissionerPanIdQuery (otInstance aInstance, uint16_t aPanId, uint32_t aChannelMask, const otIp6Address aAddress, otCommissionerPanIdConflictCallback aCallback, void *aContext)

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

otError	otCommissionerSendMgmtSet (otInstance aInstance, const otCommissioningDataset aDataset, const uint8_t *aTlvs, uint8_t aLength)

uint16_t	otCommissionerGetSessionId (otInstance *aInstance)

otCommissionerState	otCommissionerGetState (otInstance *aInstance)

otError	otCommissionerGeneratePskc (const char aPassPhrase, const char aNetworkName, const otExtendedPanId aExtPanId, otPskc aPskc)

Detailed Description

This module includes functions for the Thread Commissioner role.

Typedef Documentation

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.

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

This function pointer is called whenever the joiner state changes.

Parameters

[in]	aEvent	The joiner event type.
[in]	aJoinerId	A pointer to the Joiner ID.
[in]	aContext	A pointer to application-specific context.

typedef enum otCommissionerJoinerEvent otCommissionerJoinerEvent

This enumeration defines a Joiner Event on the Commissioner.

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.

typedef enum otCommissionerState otCommissionerState

This enumeration defines the Commissioner State.

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

This function pointer is called whenever the commissioner state changes.

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.

typedef struct otCommissioningDataset otCommissioningDataset

This structure represents a Commissioning Dataset.

typedef struct otJoinerInfo otJoinerInfo

This structure represents a Joiner Info.

typedef struct otSteeringData otSteeringData

This structure represents the steering data.

Enumeration Type Documentation

enum otCommissionerJoinerEvent

This enumeration defines a Joiner Event on the Commissioner.

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.

Function Documentation

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().

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().

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().

otError otCommissionerGeneratePskc	(	const char *	aPassPhrase,
		const char *	aNetworkName,
		const otExtendedPanId *	aExtPanId,
		otPskc *	aPskc
	)

This helper function generates PSKc from a given pass-phrase, network name, and extended PAN Id.

PSKc is used to establish the Commissioner Session.

Parameters

[in]	aPassPhrase	The commissioning pass-phrase.
[in]	aNetworkName	The network name for PSKc computation.
[in]	aExtPanId	The extended PAN ID for PSKc computation.
[out]	aPskc	A pointer to variable to output the generated PSKc.

Return values

OT_ERROR_NONE	Successfully generate PSKc.
OT_ERROR_INVALID_ARGS	If any of the input arguments is invalid.

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.

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.

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.

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.

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().

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().

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.

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.

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

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

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

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation