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.

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 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.
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.
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.
otCommissionerGeneratePSKc(otInstance *aInstance, const char *aPassPhrase, const char *aNetworkName, const otExtendedPanId *aExtPanId, uint8_t *aPSKc)
This method generates PSKc.
otCommissionerGetNextJoinerInfo(otInstance *aInstance, uint16_t & aIterator, otJoinerInfo & aJoiner)
This method get joiner info at aIterator position.
otCommissionerGetProvisioningUrl(otInstance *aInstance, uint16_t *aLength)
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.
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.
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.

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.

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 otExtAddress *aJoinerId, void *aContext)

This function pointer is called whenever the joiner state changes.

Details
Parameters
[in] aEvent
The joiner event type.
[in] aJoinerId
A pointer to the Joiner ID.
[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.

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.

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.

otCommissionerGeneratePSKc

otError otCommissionerGeneratePSKc(
  otInstance *aInstance,
  const char *aPassPhrase,
  const char *aNetworkName,
  const otExtendedPanId *aExtPanId,
  uint8_t *aPSKc
)

This method generates PSKc.

PSKc is used to establish the Commissioner Session.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aPassPhrase
The commissioning passphrase.
[in] aNetworkName
The network name for PSKc computation.
[in] aExtPanId
The extended pan id for PSKc computation.
[out] aPSKc
A pointer to the generated PSKc.
Return Values
OT_ERROR_NONE
Successfully generate PSKc.
OT_ERROR_INVALID_ARGS
If any of the input arguments is invalid.

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 iterator to the index of the joiner.
[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,
  uint16_t *aLength
)

This function gets the Provisioning URL.

Note that the returned URL string buffer is not necessarily null-terminated.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aLength
A pointer to uint16_t to return the length (number of chars) in the URL string.

Details
Returns
A pointer to char buffer containing the URL string, or NULL if aLength is NULL.

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.

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).
Return Values
OT_ERROR_NONE
Successfully set the Provisioning URL.
OT_ERROR_INVALID_ARGS
aProvisioningUrl is invalid.

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

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 role.
OT_ERROR_INVALID_STATE
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_PSKD_MAX_SIZE

 OT_PSKD_MAX_SIZE 32

Size of a Joiner PSKd (bytes)

OT_STEERING_DATA_MAX_LENGTH

 OT_STEERING_DATA_MAX_LENGTH 16

Max steering data length (bytes)