# Channel Monitoring

# Channel Monitoring

This module includes functions for channel monitoring feature.

## Summary

The functions in this module are available when channel monitor feature (`OPENTHREAD_CONFIG_CHANNEL_MONITOR_ENABLE`) is enabled.

Channel monitoring will periodically monitor all channels to help determine the cleaner channels (channels with less interference).

When channel monitoring is active, a zero-duration Energy Scan is performed, collecting a single RSSI sample on every channel per sample interval. The RSSI samples are compared with a pre-specified RSSI threshold. As an indicator of channel quality, the channel monitoring module maintains and provides the average rate/percentage of RSSI samples that are above the threshold within (approximately) a specified sample window (referred to as channel occupancy).

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-channel-monitor#group__api-channel-monitor_1gaf2540643ecbbad45860a5b2b7a75ea74(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint8_t aChannel)` | `uint16_t` Gets the current channel occupancy for a given channel. |
| `https://openthread.io/reference/group/api-channel-monitor#group__api-channel-monitor_1ga1583309cc08b1d64ca2a5b9d07dc41ad(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `int8_t` Get channel monitoring RSSI threshold in dBm. |
| `https://openthread.io/reference/group/api-channel-monitor#group__api-channel-monitor_1ga5f72370bd216c385440355113ef9fc45(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint32_t` Get channel monitoring total number of RSSI samples (per channel). |
| `https://openthread.io/reference/group/api-channel-monitor#group__api-channel-monitor_1ga9077ec1ec0e1e38257db097443dd31d6(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint32_t` Get channel monitoring sample interval in milliseconds. |
| `https://openthread.io/reference/group/api-channel-monitor#group__api-channel-monitor_1gad353165d869ec7d451fdae28ef7caaf9(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint32_t` Get channel monitoring averaging sample window length (number of samples). |
| `https://openthread.io/reference/group/api-channel-monitor#group__api-channel-monitor_1ga3742f76aee1f9a47efc58c4c92b6bdb8(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether the Channel Monitoring operation is enabled and running. |
| `https://openthread.io/reference/group/api-channel-monitor#group__api-channel-monitor_1gad15af69b1c22e84ad9fbf1fbde931924(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aEnabled)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Enables or disables the Channel Monitoring operation. |

## Functions

### otChannelMonitorGetChannelOccupancy

```
uint16_t otChannelMonitorGetChannelOccupancy(
  otInstance *aInstance,
  uint8_t aChannel
)
```
Gets the current channel occupancy for a given channel.

The channel occupancy value represents the average rate/percentage of RSSI samples that were above RSSI threshold ("bad" RSSI samples).

For the first "sample window" samples, the average is maintained as the actual percentage (i.e., ratio of number of "bad" samples by total number of samples). After "window" samples, the averager uses an exponentially weighted moving average. Practically, this means the average is representative of up to `3 * window` last samples with highest weight given to the latest `kSampleWindow` samples.

Max value of `0xffff` indicates all RSSI samples were above RSSI threshold (i.e. 100% of samples were "bad").

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aChannel` | The channel for which to get the link occupancy. | |
| **Returns** | The current channel occupancy for the given channel. |

### otChannelMonitorGetRssiThreshold

```
int8_t otChannelMonitorGetRssiThreshold(
  otInstance *aInstance
)
```
Get channel monitoring RSSI threshold in dBm.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | The RSSI threshold in dBm. |

### otChannelMonitorGetSampleCount

```
uint32_t otChannelMonitorGetSampleCount(
  otInstance *aInstance
)
```
Get channel monitoring total number of RSSI samples (per channel).

The count indicates total number samples per channel by channel monitoring module since its start (since Thread network interface was enabled).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | Total number of RSSI samples (per channel) taken so far. |

### otChannelMonitorGetSampleInterval

```
uint32_t otChannelMonitorGetSampleInterval(
  otInstance *aInstance
)
```
Get channel monitoring sample interval in milliseconds.

<br />

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

### otChannelMonitorGetSampleWindow

```
uint32_t otChannelMonitorGetSampleWindow(
  otInstance *aInstance
)
```
Get channel monitoring averaging sample window length (number of samples).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | The averaging sample window. |

### otChannelMonitorIsEnabled

```
bool otChannelMonitorIsEnabled(
  otInstance *aInstance
)
```
Indicates whether the Channel Monitoring operation is enabled and running.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | TRUE if the Channel Monitoring operation is enabled, FALSE otherwise. |

### otChannelMonitorSetEnabled

```
otError otChannelMonitorSetEnabled(
  otInstance *aInstance,
  bool aEnabled
)
```
Enables or disables the Channel Monitoring operation.

Once operation starts, any previously collected data is cleared. However, after operation is disabled, the previous collected data is still valid and can be read.


> [!NOTE]
> **Note:** OpenThread core internally enables or disables the Channel Monitoring operation when the IPv6 interface is brought up or down, for example in a call to `https://openthread.io/reference/group/api-ip6#group__api-ip6_1ga5c01df2121fb605fad92bb153302e6e2`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aEnabled` | TRUE to enable/start Channel Monitoring operation, FALSE to disable/stop it. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Channel Monitoring state changed successfully | | `OT_ERROR_ALREADY` | Channel Monitoring is already in the same state. | |

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