# Channel Manager

# Channel Manager

This module includes functions for Channel Manager.

## Summary

The functions in this module are available when Channel Manager features `OPENTHREAD_CONFIG_CHANNEL_MANAGER_ENABLE` or `OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE && OPENTHREAD_CONFIG_CHANNEL_MANAGER_CSL_CHANNEL_SELECT_ENABLE` are enabled. Channel Manager behavior depends on the device role. It manages the network-wide PAN channel on a Full Thread Device in rx-on-when-idle mode, or with `OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE && OPENTHREAD_CONFIG_CHANNEL_MANAGER_CSL_CHANNEL_SELECT_ENABLE` set, selects CSL channel in synchronized rx-off-when-idle mode. On a Minimal Thread Device `OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE && OPENTHREAD_CONFIG_CHANNEL_MANAGER_CSL_CHANNEL_SELECT_ENABLE` selects the CSL channel.

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga91cb300117a7d65504198f65194bc55a(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether the auto-channel-selection functionality for a network channel is enabled or not. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga52fb8db29cd2137cdb94819fedcd1f59(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint32_t` Gets the period interval (in seconds) used by auto-channel-selection functionality. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga9823040038d43f120f4da64581b43b45(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether the auto-csl-channel-selection functionality is enabled or not. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1gadd67c49ecd50833671220a39b711f446(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint16_t` Gets the CCA failure rate threshold. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga245c48a91b6d9e183fa5e42ccfdf2b0a(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint16_t` Gets the delay (in seconds) used by Channel Manager for a network channel change. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga29f0c64145c323893687ba9a6add6c33(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint32_t` Gets the favored channel mask. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1gad9e3ee77176366732333ccd0654bc52b(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint8_t` Gets the channel from the last successful call to `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga795e257c961a1933adb0b1cda52af64f` |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga018bb21e32868ec85108b53ebe9f7c3d(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint32_t` Gets the supported channel mask. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga795e257c961a1933adb0b1cda52af64f(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint8_t aChannel)` | `void` Requests a Thread network channel change. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1gabcc418c7fc63d10fa885d5937e52fcaf(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aSkipQualityCheck)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Requests that `ChannelManager` checks and selects a new channel and starts a channel change. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1gaf0d0717d59331914bda40065ba4d5086(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aSkipQualityCheck)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Requests that `ChannelManager` checks and selects a new CSL channel and starts a CSL channel change. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga99fd4da6016407af18f84e45cbd5daa2(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aEnabled)` | `void` Enables or disables the auto-channel-selection functionality for network channel. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga3d540882eb8135dd8a7e47cdaede80e8(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint32_t aInterval)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sets the period interval (in seconds) used by auto-channel-selection functionality. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga1dd58bc59333b4a8f301e976fd03cf64(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aEnabled)` | `void` Enables or disables the auto-channel-selection functionality for a CSL channel. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga9556434f82e377a4263113eb285050c6(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aThreshold)` | `void` Sets the CCA failure rate threshold. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1gabecf850105d3adbf5b7fc8edf783de7d(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aDelay)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sets the delay (in seconds) used for a network channel change. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga5552292ac8730b47743c7e2e56387bfb(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint32_t aChannelMask)` | `void` Sets the favored channel mask. |
| `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1gafed3b8616573e36ec18c9c4811ddeb9a(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint32_t aChannelMask)` | `void` Sets the supported channel mask. |

## Functions

### otChannelManagerGetAutoChannelSelectionEnabled

```
bool otChannelManagerGetAutoChannelSelectionEnabled(
  otInstance *aInstance
)
```
Indicates whether the auto-channel-selection functionality for a network channel is enabled or not.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | TRUE if enabled, FALSE if disabled. |

### otChannelManagerGetAutoChannelSelectionInterval

```
uint32_t otChannelManagerGetAutoChannelSelectionInterval(
  otInstance *aInstance
)
```
Gets the period interval (in seconds) used by auto-channel-selection functionality.

<br />

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

### otChannelManagerGetAutoCslChannelSelectionEnabled

```
bool otChannelManagerGetAutoCslChannelSelectionEnabled(
  otInstance *aInstance
)
```
Indicates whether the auto-csl-channel-selection functionality is enabled or not.

Only available with `OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE && OPENTHREAD_CONFIG_CHANNEL_MANAGER_CSL_CHANNEL_SELECT_ENABLE`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | TRUE if enabled, FALSE if disabled. |

### otChannelManagerGetCcaFailureRateThreshold

```
uint16_t otChannelManagerGetCcaFailureRateThreshold(
  otInstance *aInstance
)
```
Gets the CCA failure rate threshold.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | The CCA failure rate threshold. Value 0 maps to 0% and 0xffff maps to 100%. |

### otChannelManagerGetDelay

```
uint16_t otChannelManagerGetDelay(
  otInstance *aInstance
)
```
Gets the delay (in seconds) used by Channel Manager for a network channel change.

Only available on FTDs.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | The delay (in seconds) for channel change. |

### otChannelManagerGetFavoredChannels

```
uint32_t otChannelManagerGetFavoredChannels(
  otInstance *aInstance
)
```
Gets the favored channel mask.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | The favored channels as a bit-mask. |

### otChannelManagerGetRequestedChannel

```
uint8_t otChannelManagerGetRequestedChannel(
  otInstance *aInstance
)
```
Gets the channel from the last successful call to `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga795e257c961a1933adb0b1cda52af64f`

<br />

| Details ||
|---|---|
| **Returns** | The last requested channel or zero if there has been no channel change request yet. |

### otChannelManagerGetSupportedChannels

```
uint32_t otChannelManagerGetSupportedChannels(
  otInstance *aInstance
)
```
Gets the supported channel mask.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | The supported channels as a bit-mask. |

### otChannelManagerRequestChannelChange

```
void otChannelManagerRequestChannelChange(
  otInstance *aInstance,
  uint8_t aChannel
)
```
Requests a Thread network channel change.

The network switches to the given channel after a specified delay (see [otChannelManagerSetDelay()](https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1gabecf850105d3adbf5b7fc8edf783de7d)). The channel change is performed by updating the Pending Operational Dataset.

A subsequent call will cancel an ongoing previously requested channel change.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aChannel` | The new channel for the Thread network. | |

### otChannelManagerRequestChannelSelect

```
otError otChannelManagerRequestChannelSelect(
  otInstance *aInstance,
  bool aSkipQualityCheck
)
```
Requests that `ChannelManager` checks and selects a new channel and starts a channel change.

Unlike the `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga795e257c961a1933adb0b1cda52af64f` where the channel must be given as a parameter, this function asks the `ChannelManager` to select a channel by itself (based on collected channel quality info).

Once called, the Channel Manager will perform the following 3 steps:

1) `ChannelManager` decides if the channel change would be helpful. This check can be skipped if `aSkipQualityCheck` is set to true (forcing a channel selection to happen and skipping the quality check). This step uses the collected link quality metrics on the device (such as CCA failure rate, frame and message error rates per neighbor, etc.) to determine if the current channel quality is at the level that justifies a channel change.

2) If the first step passes, then `ChannelManager` selects a potentially better channel. It uses the collected channel quality data by `ChannelMonitor` module. The supported and favored channels are used at this step. (see `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1gafed3b8616573e36ec18c9c4811ddeb9a` and `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga5552292ac8730b47743c7e2e56387bfb`).

3) If the newly selected channel is different from the current channel, `ChannelManager` requests/starts the channel change process (internally invoking a `RequestChannelChange()`).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aSkipQualityCheck` | Indicates whether the quality check (step 1) should be skipped. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Channel selection finished successfully. | | `OT_ERROR_NOT_FOUND` | Supported channel mask is empty, therefore could not select a channel. | |

### otChannelManagerRequestCslChannelSelect

```
otError otChannelManagerRequestCslChannelSelect(
  otInstance *aInstance,
  bool aSkipQualityCheck
)
```
Requests that `ChannelManager` checks and selects a new CSL channel and starts a CSL channel change.

Only available with `OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE && OPENTHREAD_CONFIG_CHANNEL_MANAGER_CSL_CHANNEL_SELECT_ENABLE`. This function asks the `ChannelManager` to select a channel by itself (based on collected channel quality info).

Once called, the Channel Manager will perform the following 3 steps:

1) `ChannelManager` decides if the CSL channel change would be helpful. This check can be skipped if `aSkipQualityCheck` is set to true (forcing a CSL channel selection to happen and skipping the quality check). This step uses the collected link quality metrics on the device (such as CCA failure rate, frame and message error rates per neighbor, etc.) to determine if the current channel quality is at the level that justifies a CSL channel change.

2) If the first step passes, then `ChannelManager` selects a potentially better CSL channel. It uses the collected channel quality data by `ChannelMonitor` module. The supported and favored channels are used at this step. (see `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1gafed3b8616573e36ec18c9c4811ddeb9a` and `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga5552292ac8730b47743c7e2e56387bfb`).

3) If the newly selected CSL channel is different from the current CSL channel, `ChannelManager` starts the CSL channel change process.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aSkipQualityCheck` | Indicates whether the quality check (step 1) should be skipped. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Channel selection finished successfully. | | `OT_ERROR_NOT_FOUND` | Supported channel mask is empty, therefore could not select a channel. | |

### otChannelManagerSetAutoChannelSelectionEnabled

```
void otChannelManagerSetAutoChannelSelectionEnabled(
  otInstance *aInstance,
  bool aEnabled
)
```
Enables or disables the auto-channel-selection functionality for network channel.

When enabled, `ChannelManager` will periodically invoke a `RequestChannelSelect(false)`. The period interval can be set by `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga3d540882eb8135dd8a7e47cdaede80e8`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aEnabled` | Indicates whether to enable or disable this functionality. | |

### otChannelManagerSetAutoChannelSelectionInterval

```
otError otChannelManagerSetAutoChannelSelectionInterval(
  otInstance *aInstance,
  uint32_t aInterval
)
```
Sets the period interval (in seconds) used by auto-channel-selection functionality.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aInterval` | The interval in seconds. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The interval was set successfully. | | `OT_ERROR_INVALID_ARGS` | The `aInterval` is not valid (zero). | |

### otChannelManagerSetAutoCslChannelSelectionEnabled

```
void otChannelManagerSetAutoCslChannelSelectionEnabled(
  otInstance *aInstance,
  bool aEnabled
)
```
Enables or disables the auto-channel-selection functionality for a CSL channel.

Only available with `OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE && OPENTHREAD_CONFIG_CHANNEL_MANAGER_CSL_CHANNEL_SELECT_ENABLE`. When enabled, `ChannelManager` will periodically invoke a `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1gaf0d0717d59331914bda40065ba4d5086`. The period interval can be set by `https://openthread.io/reference/group/api-channel-manager#group__api-channel-manager_1ga3d540882eb8135dd8a7e47cdaede80e8`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aEnabled` | Indicates whether to enable or disable this functionality. | |

### otChannelManagerSetCcaFailureRateThreshold

```
void otChannelManagerSetCcaFailureRateThreshold(
  otInstance *aInstance,
  uint16_t aThreshold
)
```
Sets the CCA failure rate threshold.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aThreshold` | A CCA failure rate threshold. Value 0 maps to 0% and 0xffff maps to 100%. | |

### otChannelManagerSetDelay

```
otError otChannelManagerSetDelay(
  otInstance *aInstance,
  uint16_t aDelay
)
```
Sets the delay (in seconds) used for a network channel change.

Only available on FTDs. The delay should preferably be longer than the maximum data poll interval used by all Sleepy End Devices within the Thread network.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aDelay` | Delay in seconds. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Delay was updated successfully. | | `OT_ERROR_INVALID_ARGS` | The given delay `aDelay` is too short. | |

### otChannelManagerSetFavoredChannels

```
void otChannelManagerSetFavoredChannels(
  otInstance *aInstance,
  uint32_t aChannelMask
)
```
Sets the favored channel mask.

<br />

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

### otChannelManagerSetSupportedChannels

```
void otChannelManagerSetSupportedChannels(
  otInstance *aInstance,
  uint32_t aChannelMask
)
```
Sets the supported channel mask.

<br />

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

## 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).