Joiner

This module includes functions for the Thread Joiner role.

Classes

struct  otJoinerDiscerner
 This structure represents a Joiner Discerner.

Macros

#define OT_JOINER_MAX_DISCERNER_LENGTH   64
 Maximum length of a Joiner Discerner in bits.

Typedefs

typedef enum otJoinerState otJoinerState
 This enumeration defines the Joiner State.
 
typedef struct otJoinerDiscerner otJoinerDiscerner
 This structure represents a Joiner Discerner.
 
typedef void(* otJoinerCallback) (otError aError, void *aContext)
 This function pointer is called to notify the completion of a join operation.

Enumerations

enum  otJoinerState {
  OT_JOINER_STATE_IDLE = 0,
  OT_JOINER_STATE_DISCOVER = 1,
  OT_JOINER_STATE_CONNECT = 2,
  OT_JOINER_STATE_CONNECTED = 3,
  OT_JOINER_STATE_ENTRUST = 4,
  OT_JOINER_STATE_JOINED = 5
}
 This enumeration defines the Joiner State.

Functions

otError otJoinerStart (otInstance *aInstance, const char *aPskd, const char *aProvisioningUrl, const char *aVendorName, const char *aVendorModel, const char *aVendorSwVersion, const char *aVendorData, otJoinerCallback aCallback, void *aContext)
 This function enables the Thread Joiner role.
 
void otJoinerStop (otInstance *aInstance)
 This function disables the Thread Joiner role.
 
otJoinerState otJoinerGetState (otInstance *aInstance)
 This function returns the Joiner State.
 
const otExtAddressotJoinerGetId (otInstance *aInstance)
 This function gets the Joiner ID.
 
otError otJoinerSetDiscerner (otInstance *aInstance, otJoinerDiscerner *aDiscerner)
 This function sets the Joiner Discerner.
 
const otJoinerDiscernerotJoinerGetDiscerner (otInstance *aInstance)
 This function gets the Joiner Discerner.
 
const char * otJoinerStateToString (otJoinerState aState)
 This function converts a given joiner state enumeration value to a human-readable string.

Detailed Description

This module includes functions for the Thread Joiner role.

Note
The functions in this module require OPENTHREAD_CONFIG_JOINER_ENABLE=1.

Typedef Documentation

◆ otJoinerCallback

typedef void(* otJoinerCallback) (otError aError, void *aContext)

This function pointer is called to notify the completion of a join operation.

Parameters
[in]aErrorOT_ERROR_NONE if the join process succeeded. OT_ERROR_SECURITY if the join process failed due to security credentials. OT_ERROR_NOT_FOUND if no joinable network was discovered. OT_ERROR_RESPONSE_TIMEOUT if a response timed out.
[in]aContextA pointer to application-specific context.

Function Documentation

◆ otJoinerGetDiscerner()

const otJoinerDiscerner* otJoinerGetDiscerner ( otInstance aInstance)

This function gets the Joiner Discerner.

Parameters
[in]aInstanceA pointer to the OpenThread instance.
Returns
A pointer to Joiner Discerner or NULL if none is set.

◆ otJoinerGetId()

const otExtAddress* otJoinerGetId ( otInstance aInstance)

This function gets the Joiner ID.

If a Joiner Discerner is not set, Joiner ID is the first 64 bits of the result of computing SHA-256 over factory-assigned IEEE EUI-64. Otherwise the Joiner ID is calculated from the Joiner Discerner value.

The Joiner ID is also used as the device's IEEE 802.15.4 Extended Address during commissioning process.

Parameters
[in]aInstanceA pointer to the OpenThread instance.
Returns
A pointer to the Joiner ID.

◆ otJoinerGetState()

otJoinerState otJoinerGetState ( otInstance aInstance)

This function returns the Joiner State.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Return values
OT_JOINER_STATE_IDLE
OT_JOINER_STATE_DISCOVER
OT_JOINER_STATE_CONNECT
OT_JOINER_STATE_CONNECTED
OT_JOINER_STATE_ENTRUST
OT_JOINER_STATE_JOINED

◆ otJoinerSetDiscerner()

otError otJoinerSetDiscerner ( otInstance aInstance,
otJoinerDiscerner aDiscerner 
)

This function sets the Joiner Discerner.

The Joiner Discerner is used to calculate the Joiner ID used during commissioning/joining process.

By default (when a discerner is not provided or set to NULL), Joiner ID is derived as first 64 bits of the result of computing SHA-256 over factory-assigned IEEE EUI-64. Note that this is the main behavior expected by Thread specification.

Parameters
[in]aInstanceA pointer to the OpenThread instance.
[in]aDiscernerA pointer to a Joiner Discerner. If NULL clears any previously set discerner.
Return values
OT_ERROR_NONEThe Joiner Discerner updated successfully.
OT_ERROR_INVALID_ARGSaDiscerner is not valid (specified length is not within valid range).
OT_ERROR_INVALID_STATEThere is an ongoing Joining process so Joiner Discerner could not be changed.

◆ otJoinerStart()

otError otJoinerStart ( otInstance aInstance,
const char *  aPskd,
const char *  aProvisioningUrl,
const char *  aVendorName,
const char *  aVendorModel,
const char *  aVendorSwVersion,
const char *  aVendorData,
otJoinerCallback  aCallback,
void *  aContext 
)

This function enables the Thread Joiner role.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aPskdA pointer to the PSKd.
[in]aProvisioningUrlA pointer to the Provisioning URL (may be NULL).
[in]aVendorNameA pointer to the Vendor Name (may be NULL).
[in]aVendorModelA pointer to the Vendor Model (may be NULL).
[in]aVendorSwVersionA pointer to the Vendor SW Version (may be NULL).
[in]aVendorDataA pointer to the Vendor Data (may be NULL).
[in]aCallbackA pointer to a function that is called when the join operation completes.
[in]aContextA pointer to application-specific context.
Return values
OT_ERROR_NONESuccessfully started the Joiner role.
OT_ERROR_BUSYThe previous attempt is still on-going.
OT_ERROR_INVALID_ARGSaPskd or aProvisioningUrl is invalid.
OT_ERROR_INVALID_STATEThe IPv6 stack is not enabled or Thread stack is fully enabled.

◆ otJoinerStateToString()

const char* otJoinerStateToString ( otJoinerState  aState)

This function converts a given joiner state enumeration value to a human-readable string.

Parameters
[in]aStateThe joiner state.
Returns
A human-readable string representation of aState.

◆ otJoinerStop()

void otJoinerStop ( otInstance aInstance)

This function disables the Thread Joiner role.

Parameters
[in]aInstanceA pointer to an OpenThread instance.