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 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]aChannelMaskThe channel mask value.
[in]aEnergyListA pointer to the energy measurement list.
[in]aEnergyListLengthNumber of entries in aEnergyListLength.
[in]aContextA 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]aEventThe joiner event type.
[in]aJoinerInfoA pointer to the Joiner Info.
[in]aJoinerIdA pointer to the Joiner ID (if not known, it will be NULL).
[in]aContextA 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]aPanIdThe PAN ID value.
[in]aChannelMaskThe channel mask value.
[in]aContextA 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]aStateThe Commissioner state.
[in]aContextA 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 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]aInstanceA pointer to an OpenThread instance.
[in]aEui64A pointer to the Joiner's IEEE EUI-64 or NULL for any Joiner.
[in]aPskdA pointer to the PSKd.
[in]aTimeoutA time after which a Joiner is automatically removed, in seconds.
Return values
OT_ERROR_NONESuccessfully added the Joiner.
OT_ERROR_NO_BUFSNo buffers available to add the Joiner.
OT_ERROR_INVALID_ARGSaEui64 or aPskd is invalid.
OT_ERROR_INVALID_STATEThe 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]aInstanceA pointer to an OpenThread instance.
[in]aDiscernerA pointer to the Joiner Discerner.
[in]aPskdA pointer to the PSKd.
[in]aTimeoutA time after which a Joiner is automatically removed, in seconds.
Return values
OT_ERROR_NONESuccessfully added the Joiner.
OT_ERROR_NO_BUFSNo buffers available to add the Joiner.
OT_ERROR_INVALID_ARGSaDiscerner or aPskd is invalid.
OT_ERROR_INVALID_STATEThe 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]aInstanceA pointer to an OpenThread instance.
[in]aChannelMaskThe channel mask value.
[in]aCountThe number of Announcement messages per channel.
[in]aPeriodThe time between two successive MLE Announce transmissions (in milliseconds).
[in]aAddressA pointer to the IPv6 destination.
Return values
OT_ERROR_NONESuccessfully enqueued the Announce Begin message.
OT_ERROR_NO_BUFSInsufficient buffers to generate an Announce Begin message.
OT_ERROR_INVALID_STATEThe 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]aInstanceA pointer to an OpenThread instance.
[in]aChannelMaskThe channel mask value.
[in]aCountThe number of energy measurements per channel.
[in]aPeriodThe time between energy measurements (milliseconds).
[in]aScanDurationThe scan duration for each energy measurement (milliseconds).
[in]aAddressA pointer to the IPv6 destination.
[in]aCallbackA pointer to a function called on receiving an Energy Report message.
[in]aContextA pointer to application-specific context.
Return values
OT_ERROR_NONESuccessfully enqueued the Energy Scan Query message.
OT_ERROR_NO_BUFSInsufficient buffers to generate an Energy Scan Query message.
OT_ERROR_INVALID_STATEThe 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]aInstanceA 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]aInstanceA pointer to instance.
[in,out]aIteratorA pointer to the Joiner Info iterator context.
[out]aJoinerA reference to Joiner info.
Return values
OT_ERROR_NONESuccessfully get the Joiner info.
OT_ERROR_NOT_FOUNDNot found next Joiner.

◆ otCommissionerGetProvisioningUrl()

const char* otCommissionerGetProvisioningUrl ( otInstance aInstance)

This function gets the Provisioning URL.

Parameters
[in]aInstanceA 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]aInstanceA pointer to an OpenThread instance.
Returns
The current commissioner session id.

◆ otCommissionerGetState()

otCommissionerState otCommissionerGetState ( otInstance aInstance)

This function returns the Commissioner State.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Return values
OT_COMMISSIONER_STATE_DISABLEDCommissioner disabled.
OT_COMMISSIONER_STATE_PETITIONBecoming the commissioner.
OT_COMMISSIONER_STATE_ACTIVECommissioner 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]aInstanceA pointer to an OpenThread instance.
[in]aPanIdThe PAN ID to query.
[in]aChannelMaskThe channel mask value.
[in]aAddressA pointer to the IPv6 destination.
[in]aCallbackA pointer to a function called on receiving a PAN ID Conflict message.
[in]aContextA pointer to application-specific context.
Return values
OT_ERROR_NONESuccessfully enqueued the PAN ID Query message.
OT_ERROR_NO_BUFSInsufficient buffers to generate a PAN ID Query message.
OT_ERROR_INVALID_STATEThe 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]aInstanceA pointer to an OpenThread instance.
[in]aEui64A pointer to the Joiner's IEEE EUI-64 or NULL for any Joiner.
Return values
OT_ERROR_NONESuccessfully removed the Joiner.
OT_ERROR_NOT_FOUNDThe Joiner specified by aEui64 was not found.
OT_ERROR_INVALID_ARGSaEui64 is invalid.
OT_ERROR_INVALID_STATEThe 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]aInstanceA pointer to an OpenThread instance.
[in]aDiscernerA pointer to the Joiner Discerner.
Return values
OT_ERROR_NONESuccessfully removed the Joiner.
OT_ERROR_NOT_FOUNDThe Joiner specified by aEui64 was not found.
OT_ERROR_INVALID_ARGSaDiscerner is invalid.
OT_ERROR_INVALID_STATEThe 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]aInstanceA pointer to an OpenThread instance.
[in]aTlvsA pointer to TLVs.
[in]aLengthThe length of TLVs.
Return values
OT_ERROR_NONESuccessfully send the meshcop dataset command.
OT_ERROR_NO_BUFSInsufficient buffer space to send.
OT_ERROR_INVALID_STATEThe 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]aInstanceA pointer to an OpenThread instance.
[in]aDatasetA pointer to commissioning dataset.
[in]aTlvsA pointer to TLVs.
[in]aLengthThe length of TLVs.
Return values
OT_ERROR_NONESuccessfully send the meshcop dataset command.
OT_ERROR_NO_BUFSInsufficient buffer space to send.
OT_ERROR_INVALID_STATEThe commissioner is not active.

◆ otCommissionerSetId()

otError otCommissionerSetId ( otInstance aInstance,
const char *  aId 
)

This function sets the Commissioner Id.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aIdA pointer to a string character array. Must be null terminated.
Return values
OT_ERROR_NONESuccessfully set the Commissioner Id.
OT_ERROR_INVALID_ARGSGiven name is too long.
OT_ERROR_INVALID_STATEThe commissioner is active and id cannot be changed.

◆ otCommissionerSetProvisioningUrl()

otError otCommissionerSetProvisioningUrl ( otInstance aInstance,
const char *  aProvisioningUrl 
)

This function sets the Provisioning URL.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aProvisioningUrlA pointer to the Provisioning URL (may be NULL to set as empty string).
Return values
OT_ERROR_NONESuccessfully set the Provisioning URL.
OT_ERROR_INVALID_ARGSaProvisioningUrl is invalid (too long).

◆ otCommissionerStart()

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

This function enables the Thread Commissioner role.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aStateCallbackA pointer to a function that is called when the commissioner state changes.
[in]aJoinerCallbackA pointer to a function that is called with a joiner event occurs.
[in]aCallbackContextA pointer to application-specific context.
Return values
OT_ERROR_NONESuccessfully started the Commissioner service.
OT_ERROR_ALREADYCommissioner is already started.
OT_ERROR_INVALID_STATEDevice is not currently attached to a network.

◆ otCommissionerStop()

otError otCommissionerStop ( otInstance aInstance)

This function disables the Thread Commissioner role.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Return values
OT_ERROR_NONESuccessfully stopped the Commissioner service.
OT_ERROR_ALREADYCommissioner is already stopped.