nRF5 SDK for Thread and Zigbee v4.0.0
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Commissioner

This module includes functions for the Thread Commissioner role. More...

Data Structures

struct  otSteeringData
 
struct  otCommissioningDataset
 
struct  otJoinerInfo
 

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_PSKD_MAX_SIZE   32
 Size of a Joiner PSKd (bytes)
 

Typedefs

typedef enum otCommissionerState otCommissionerState
 
typedef enum
otCommissionerJoinerEvent 
otCommissionerJoinerEvent
 
typedef struct otSteeringData otSteeringData
 
typedef struct
otCommissioningDataset 
otCommissioningDataset
 
typedef struct otJoinerInfo otJoinerInfo
 
typedef void(* otCommissionerStateCallback )(otCommissionerState aState, void *aContext)
 
typedef void(* otCommissionerJoinerCallback )(otCommissionerJoinerEvent aEvent, const otExtAddress *aJoinerId, void *aContext)
 
typedef void(* otCommissionerEnergyReportCallback )(uint32_t aChannelMask, const uint8_t *aEnergyList, uint8_t aEnergyListLength, void *aContext)
 
typedef void(* otCommissionerPanIdConflictCallback )(uint16_t aPanId, uint32_t aChannelMask, void *aContext)
 

Enumerations

enum  otCommissionerState { OT_COMMISSIONER_STATE_DISABLED = 0, OT_COMMISSIONER_STATE_PETITION = 1, OT_COMMISSIONER_STATE_ACTIVE = 2 }
 
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
}
 

Functions

otError otCommissionerStart (otInstance *aInstance, otCommissionerStateCallback aStateCallback, otCommissionerJoinerCallback aJoinerCallback, void *aCallbackContext)
 
otError otCommissionerStop (otInstance *aInstance)
 
otError otCommissionerAddJoiner (otInstance *aInstance, const otExtAddress *aEui64, const char *aPskd, uint32_t aTimeout)
 
otError otCommissionerGetNextJoinerInfo (otInstance *aInstance, uint16_t *aIterator, otJoinerInfo *aJoiner)
 
otError otCommissionerRemoveJoiner (otInstance *aInstance, const otExtAddress *aEui64)
 
const char * otCommissionerGetProvisioningUrl (otInstance *aInstance)
 
otError otCommissionerSetProvisioningUrl (otInstance *aInstance, const char *aProvisioningUrl)
 
otError otCommissionerAnnounceBegin (otInstance *aInstance, uint32_t aChannelMask, uint8_t aCount, uint16_t aPeriod, const otIp6Address *aAddress)
 
otError otCommissionerEnergyScan (otInstance *aInstance, uint32_t aChannelMask, uint8_t aCount, uint16_t aPeriod, uint16_t aScanDuration, const otIp6Address *aAddress, otCommissionerEnergyReportCallback aCallback, void *aContext)
 
otError otCommissionerPanIdQuery (otInstance *aInstance, uint16_t aPanId, uint32_t aChannelMask, const otIp6Address *aAddress, otCommissionerPanIdConflictCallback aCallback, void *aContext)
 
otError otCommissionerSendMgmtGet (otInstance *aInstance, const uint8_t *aTlvs, uint8_t aLength)
 
otError otCommissionerSendMgmtSet (otInstance *aInstance, const otCommissioningDataset *aDataset, const uint8_t *aTlvs, uint8_t aLength)
 
uint16_t otCommissionerGetSessionId (otInstance *aInstance)
 
otCommissionerState otCommissionerGetState (otInstance *aInstance)
 
otError otCommissionerGeneratePskc (const char *aPassPhrase, const char *aNetworkName, const otExtendedPanId *aExtPanId, otPskc *aPskc)
 

Detailed Description

This module includes functions for the Thread Commissioner role.

Typedef Documentation

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.
typedef void(* otCommissionerJoinerCallback)(otCommissionerJoinerEvent aEvent, const otExtAddress *aJoinerId, void *aContext)

This function pointer is called whenever the joiner state changes.

Parameters
[in]aEventThe joiner event type.
[in]aJoinerIdA pointer to the Joiner ID.
[in]aContextA pointer to application-specific context.

This enumeration defines a Joiner Event on the Commissioner.

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.

This enumeration defines the Commissioner State.

typedef void(* otCommissionerStateCallback)(otCommissionerState aState, void *aContext)

This function pointer is called whenever the commissioner state changes.

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.

This structure represents a Commissioning Dataset.

typedef struct otJoinerInfo otJoinerInfo

This structure represents a Joiner Info.

This structure represents the steering data.

Enumeration Type Documentation

This enumeration defines a Joiner Event on the Commissioner.

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.

Function Documentation

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().
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().
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().
otError otCommissionerGeneratePskc ( const char *  aPassPhrase,
const char *  aNetworkName,
const otExtendedPanId aExtPanId,
otPskc aPskc 
)

This helper function generates PSKc from a given pass-phrase, network name, and extended PAN Id.

PSKc is used to establish the Commissioner Session.

Parameters
[in]aPassPhraseThe commissioning pass-phrase.
[in]aNetworkNameThe network name for PSKc computation.
[in]aExtPanIdThe extended PAN ID for PSKc computation.
[out]aPskcA pointer to variable to output the generated PSKc.
Return values
OT_ERROR_NONESuccessfully generate PSKc.
OT_ERROR_INVALID_ARGSIf any of the input arguments is invalid.
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.
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.
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.
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.
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().
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().
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.
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.
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).
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 role.
OT_ERROR_INVALID_STATECommissioner is already started.
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 role.
OT_ERROR_INVALID_STATECommissioner is already stopped.