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)
 Enables the Thread Joiner role.
 
void otJoinerStop (otInstance *aInstance)
 Disables the Thread Joiner role.
 
otJoinerState otJoinerGetState (otInstance *aInstance)
 Gets the Joiner State.
 
const otExtAddressotJoinerGetId (otInstance *aInstance)
 Gets the Joiner ID.
 
otError otJoinerSetDiscerner (otInstance *aInstance, otJoinerDiscerner *aDiscerner)
 Sets the Joiner Discerner.
 
const otJoinerDiscernerotJoinerGetDiscerner (otInstance *aInstance)
 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)

Gets the Joiner Discerner.

For more information, refer to otJoinerSetDiscerner.

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)

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 the commissioning process.

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

◆ otJoinerGetState()

otJoinerState otJoinerGetState ( otInstance aInstance)

Gets 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 
)

Sets the Joiner Discerner.

The Joiner Discerner is used to calculate the Joiner ID during the Thread Commissioning process. For more information, refer to otJoinerGetId.

Note
The Joiner Discerner takes the place of the Joiner EUI-64 during the joiner session of Thread Commissioning.
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 
)

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)

Disables the Thread Joiner role.

Parameters
[in]aInstanceA pointer to an OpenThread instance.