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] 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] aState
The Commissioner state. [in] aContext
A pointer to application-specific context.
Enumeration Type Documentation
◆ otCommissionerState
enum otCommissionerState |
◆ otJoinerInfoType
enum 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 ( |
OT_JOINER_INFO_TYPE_DISCERNER | Joiner Discerner is specified ( |
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
oraPskd
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
oraPskd
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().
◆ otCommissionerGetId()
const char* otCommissionerGetId | ( | otInstance * | aInstance | ) |
This function returns the Commissioner Id.
- Parameters
-
[in] aInstance
A 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] 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] aDiscerner
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.
◆ otCommissionerSetId()
otError otCommissionerSetId | ( | otInstance * | aInstance, |
const char * | aId |
||
) |
This function sets the Commissioner Id.
- Parameters
-
[in] aInstance
A pointer to an OpenThread instance. [in] aId
A pointer to a string character array. Must be null terminated.
- Return values
-
OT_ERROR_NONE
Successfully set the Commissioner Id. OT_ERROR_INVALID_ARGS
Given name is too long. OT_ERROR_INVALID_STATE
The commissioner is active and id cannot be changed.
◆ 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.