Commissioner

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

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

Enumeration Type Documentation

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

This enumeration defines a Joiner Info Typer.

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

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

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.