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

otChannelManagerGetAutoChannelSelectionEnabled(otInstance *aInstance)
bool
Indicates whether the auto-channel-selection functionality for a network channel is enabled or not.
otChannelManagerGetAutoChannelSelectionInterval(otInstance *aInstance)
uint32_t
Gets the period interval (in seconds) used by auto-channel-selection functionality.
otChannelManagerGetAutoCslChannelSelectionEnabled(otInstance *aInstance)
bool
Indicates whether the auto-csl-channel-selection functionality is enabled or not.
otChannelManagerGetCcaFailureRateThreshold(otInstance *aInstance)
uint16_t
Gets the CCA failure rate threshold.
otChannelManagerGetDelay(otInstance *aInstance)
uint16_t
Gets the delay (in seconds) used by Channel Manager for a network channel change.
otChannelManagerGetFavoredChannels(otInstance *aInstance)
uint32_t
Gets the favored channel mask.
otChannelManagerGetRequestedChannel(otInstance *aInstance)
uint8_t
Gets the channel from the last successful call to otChannelManagerRequestChannelChange()
otChannelManagerGetSupportedChannels(otInstance *aInstance)
uint32_t
Gets the supported channel mask.
otChannelManagerRequestChannelChange(otInstance *aInstance, uint8_t aChannel)
void
Requests a Thread network channel change.
otChannelManagerRequestChannelSelect(otInstance *aInstance, bool aSkipQualityCheck)
Requests that ChannelManager checks and selects a new channel and starts a channel change.
otChannelManagerRequestCslChannelSelect(otInstance *aInstance, bool aSkipQualityCheck)
Requests that ChannelManager checks and selects a new CSL channel and starts a CSL channel change.
otChannelManagerSetAutoChannelSelectionEnabled(otInstance *aInstance, bool aEnabled)
void
Enables or disables the auto-channel-selection functionality for network channel.
otChannelManagerSetAutoChannelSelectionInterval(otInstance *aInstance, uint32_t aInterval)
Sets the period interval (in seconds) used by auto-channel-selection functionality.
otChannelManagerSetAutoCslChannelSelectionEnabled(otInstance *aInstance, bool aEnabled)
void
Enables or disables the auto-channel-selection functionality for a CSL channel.
otChannelManagerSetCcaFailureRateThreshold(otInstance *aInstance, uint16_t aThreshold)
void
Sets the CCA failure rate threshold.
otChannelManagerSetDelay(otInstance *aInstance, uint16_t aDelay)
Sets the delay (in seconds) used for a network channel change.
otChannelManagerSetFavoredChannels(otInstance *aInstance, uint32_t aChannelMask)
void
Sets the favored channel mask.
otChannelManagerSetSupportedChannels(otInstance *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.

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.

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.

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.

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.

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.

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 otChannelManagerRequestChannelChange()

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.

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()). The channel change is performed by updating the Pending Operational Dataset.

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

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 otChannelManagerRequestChannelChange() 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 otChannelManagerSetSupportedChannels() and otChannelManagerSetFavoredChannels()).

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

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 otChannelManagerSetSupportedChannels() and otChannelManagerSetFavoredChannels()).

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

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 otChannelManagerSetAutoChannelSelectionInterval().

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.

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 otChannelManagerRequestCslChannelSelect(). The period interval can be set by otChannelManagerSetAutoChannelSelectionInterval().

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.

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.

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.

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.

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. For more information, or to contribute to our documentation, refer to Resources.