Commissioner

This module includes functions for the Thread Commissioner role.

Summary

Enumerations

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(OTCALL *
This function pointer is called when the Commissioner receives an Energy Report.
otCommissionerPanIdConflictCallback)(uint16_t aPanId, uint32_t aChannelMask, void *aContext) typedef
void(OTCALL *
This function pointer is called when the Commissioner receives a PAN ID Conflict message.
otCommissionerState typedef
This enumeration defines the Commissioner State.
otCommissioningDataset typedef
This structure represents a Commissioning Dataset.
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.
otCommissionerGetProvisioningUrl(otInstance *aInstance, uint16_t *aLength)
const char *
This function gets the Provisioning URL.
otCommissionerGetSessionId(otInstance *aInstance)
OTAPI uint16_t OTCALL
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)
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.

otSteeringData

This structure represents the steering data.

Enumerations

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(OTCALL * 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.

otCommissionerPanIdConflictCallback

void(OTCALL * 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.

otCommissioningDataset

struct otCommissioningDataset otCommissioningDataset

This structure represents a Commissioning Dataset.

otSteeringData

struct otSteeringData otSteeringData

This structure represents the steering data.

Functions

otCommissionerAddJoiner

OTAPI otError OTCALL 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

OTAPI otError OTCALL 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

OTAPI otError OTCALL 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

OTAPI otError OTCALL 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.

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

OTAPI uint16_t OTCALL 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

OTAPI otCommissionerStateOTCALL 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

OTAPI otError OTCALL 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

OTAPI otError OTCALL 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

OTAPI otError OTCALL 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

OTAPI otError OTCALL 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

OTAPI otError OTCALL 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

OTAPI otError OTCALL otCommissionerStart(
  otInstance *aInstance
)

This function enables the Thread Commissioner role.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
OT_ERROR_NONE
Successfully started the Commissioner role.
OT_ERROR_INVALID_STATE
Commissioner is already started.

otCommissionerStop

OTAPI otError OTCALL 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_STEERING_DATA_MAX_LENGTH

 OT_STEERING_DATA_MAX_LENGTH 16

Max steering data length (bytes)