# Joiner

# Joiner

This module includes functions for the Thread Joiner role.

## Summary


> [!NOTE]
> **Note:** The functions in this module require `OPENTHREAD_CONFIG_JOINER_ENABLE=1`.

<br />

| ### Enumerations ||
|---|---|
| `https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga842970ea6edb21955fdabfa66749965f` | enumDefines the Joiner State. |

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga0580f475d59515225c40f63239cfbd8a)(otError aError, void *aContext)` | typedef `void(*` Pointer is called to notify the completion of a join operation. |
| `https://openthread.io/reference/group/api-joiner#group__api-joiner_1gac06baf2155b925db341c4a28c8eff60e` | typedef `struct https://openthread.io/reference/struct/ot-joiner-discerner` Represents a Joiner Discerner. |
| `https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga55b7084c06d8eb08562d3267c0dab83a` | typedef `enum https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga842970ea6edb21955fdabfa66749965f` Defines the Joiner State. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-joiner#group__api-joiner_1gadc775c31ae61dbb33f8fa0fc68db0925(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `const https://openthread.io/reference/struct/ot-joiner-discerner *` Gets the Joiner Discerner. |
| `https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga29942ce6c3a2de02d64821cb86f717d9(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `const https://openthread.io/reference/struct/ot-ext-address *` Gets the Joiner ID. |
| `https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga07f9fc20f65ea45aeb0c41e2bfff7da5(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga842970ea6edb21955fdabfa66749965f` Gets the Joiner State. |
| `https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga91b50aed158aee79ca0101ea0034278e(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-joiner-discerner *aDiscerner)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sets the Joiner Discerner. |
| `https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga788df6d2d36014dd9c8175449244e0e5(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const char *aPskd, const char *aProvisioningUrl, const char *aVendorName, const char *aVendorModel, const char *aVendorSwVersion, const char *aVendorData, https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga0580f475d59515225c40f63239cfbd8a aCallback, void *aContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Enables the Thread Joiner role. |
| `https://openthread.io/reference/group/api-joiner#group__api-joiner_1gabae2f3cdcb27299bf370cac9e3e280d0(https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga842970ea6edb21955fdabfa66749965f aState)` | `const char *` Converts a given joiner state enumeration value to a human-readable string. |
| `https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga97cda4f2ba3f8f923ad095a440a44c5c(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `void` Disables the Thread Joiner role. |

| ### Macros ||
|---|---|
| `https://openthread.io/reference/group/api-joiner#group__api-joiner_1gad388d4a2bab50212f628742ec927d354 64` | Maximum length of a Joiner Discerner in bits. |

| ### Structs ||
|---|---|
| [otJoinerDiscerner](https://openthread.io/reference/struct/ot-joiner-discerner) | Represents a Joiner Discerner. |

## Enumerations

### otJoinerState

```
 otJoinerState
```
Defines the Joiner State.

## Typedefs

### otJoinerCallback

```
void(* otJoinerCallback)(otError aError, void *aContext)
```
Pointer is called to notify the completion of a join operation.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aError` | OT_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] aContext` | A pointer to application-specific context. | |

### otJoinerDiscerner

```
struct otJoinerDiscerner otJoinerDiscerner
```
Represents a Joiner Discerner.

### otJoinerState

```
enum otJoinerState otJoinerState
```
Defines the Joiner State.

## Functions

### otJoinerGetDiscerner

```
const otJoinerDiscerner * otJoinerGetDiscerner(
  otInstance *aInstance
)
```
Gets the Joiner Discerner.

For more information, refer to [otJoinerSetDiscerner](https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga91b50aed158aee79ca0101ea0034278e).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A 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.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to the OpenThread instance. | |
| **Returns** | A pointer to the Joiner ID. |

### otJoinerGetState

```
otJoinerState otJoinerGetState(
  otInstance *aInstance
)
```
Gets the Joiner State.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | The joiner state. |

### 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](https://openthread.io/reference/group/api-joiner#group__api-joiner_1ga29942ce6c3a2de02d64821cb86f717d9).

> [!NOTE]
> **Note:** The Joiner Discerner takes the place of the Joiner EUI-64 during the joiner session of Thread Commissioning.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to the OpenThread instance. | | `[in] aDiscerner` | A pointer to a Joiner Discerner. If NULL clears any previously set discerner. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The Joiner Discerner updated successfully. | | `OT_ERROR_INVALID_ARGS` | `aDiscerner` is not valid (specified length is not within valid range). | | `OT_ERROR_INVALID_STATE` | There 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.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aPskd` | A pointer to the PSKd. | | `[in] aProvisioningUrl` | A pointer to the Provisioning URL (may be NULL). | | `[in] aVendorName` | A pointer to the Vendor Name (may be NULL). | | `[in] aVendorModel` | A pointer to the Vendor Model (may be NULL). | | `[in] aVendorSwVersion` | A pointer to the Vendor SW Version (may be NULL). | | `[in] aVendorData` | A pointer to the Vendor Data (may be NULL). | | `[in] aCallback` | A pointer to a function that is called when the join operation completes. | | `[in] aContext` | A pointer to application-specific context. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully started the Joiner role. | | `OT_ERROR_BUSY` | The previous attempt is still on-going. | | `OT_ERROR_INVALID_ARGS` | `aPskd` or `aProvisioningUrl` is invalid. | | `OT_ERROR_INVALID_STATE` | The IPv6 stack is not enabled or Thread stack is fully enabled. | |

### otJoinerStateToString

```
const char * otJoinerStateToString(
  otJoinerState aState
)
```
Converts a given joiner state enumeration value to a human-readable string.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aState` | The joiner state. | |
| **Returns** | A human-readable string representation of `aState`. |

### otJoinerStop

```
void otJoinerStop(
  otInstance *aInstance
)
```
Disables the Thread Joiner role.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |

## Macros

### OT_JOINER_MAX_DISCERNER_LENGTH

```
 OT_JOINER_MAX_DISCERNER_LENGTH 64
```
Maximum length of a Joiner Discerner in bits.

## Resources

OpenThread API Reference topics originate from the source code, available
on [GitHub](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).