Channel Manager#

This module includes functions for Channel Manager.

The functions in this module are available when Channel Manager feature (OPENTHREAD_CONFIG_CHANNEL_MANAGER_ENABLE) is enabled. Channel Manager is available only on an FTD build.

Functions#

void
otChannelManagerRequestChannelChange(otInstance *aInstance, uint8_t aChannel)

Requests a Thread network channel change.

uint8_t

Gets the channel from the last successful call to otChannelManagerRequestChannelChange()

uint16_t
otChannelManagerGetDelay(otInstance *aInstance)

Gets the delay (in seconds) used by Channel Manager for a channel change.

otChannelManagerSetDelay(otInstance *aInstance, uint16_t aDelay)

Sets the delay (in seconds) used for a channel change.

otChannelManagerRequestChannelSelect(otInstance *aInstance, bool aSkipQualityCheck)

Requests that ChannelManager checks and selects a new channel and starts a channel change.

void
otChannelManagerSetAutoChannelSelectionEnabled(otInstance *aInstance, bool aEnabled)

Enables or disables the auto-channel-selection functionality.

bool

Indicates whether the auto-channel-selection functionality is enabled or not.

otChannelManagerSetAutoChannelSelectionInterval(otInstance *aInstance, uint32_t aInterval)

Sets the period interval (in seconds) used by auto-channel-selection functionality.

uint32_t

Gets the period interval (in seconds) used by auto-channel-selection functionality.

uint32_t

Gets the supported channel mask.

void
otChannelManagerSetSupportedChannels(otInstance *aInstance, uint32_t aChannelMask)

Sets the supported channel mask.

uint32_t
otChannelManagerGetFavoredChannels(otInstance *aInstance)

Gets the favored channel mask.

void
otChannelManagerSetFavoredChannels(otInstance *aInstance, uint32_t aChannelMask)

Sets the favored channel mask.

uint16_t

Gets the CCA failure rate threshold.

void
otChannelManagerSetCcaFailureRateThreshold(otInstance *aInstance, uint16_t aThreshold)

Sets the CCA failure rate threshold.

Function Documentation#

otChannelManagerRequestChannelChange#

void otChannelManagerRequestChannelChange (otInstance * aInstance, uint8_t aChannel)

Requests a Thread network channel change.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aChannel

The new channel for the Thread network.

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.


Definition at line 69 of file include/openthread/channel_manager.h

otChannelManagerGetRequestedChannel#

uint8_t otChannelManagerGetRequestedChannel (otInstance * aInstance)

Gets the channel from the last successful call to otChannelManagerRequestChannelChange()

Parameters
N/AaInstance

Returns

  • The last requested channel or zero if there has been no channel change request yet.


Definition at line 77 of file include/openthread/channel_manager.h

otChannelManagerGetDelay#

uint16_t otChannelManagerGetDelay (otInstance * aInstance)

Gets the delay (in seconds) used by Channel Manager for a channel change.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The delay (in seconds) for channel change.


Definition at line 87 of file include/openthread/channel_manager.h

otChannelManagerSetDelay#

otError otChannelManagerSetDelay (otInstance * aInstance, uint16_t aDelay)

Sets the delay (in seconds) used for a channel change.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aDelay

Delay in seconds.

The delay should preferably be longer than the maximum data poll interval used by all sleepy-end-devices within the Thread network.


Definition at line 102 of file include/openthread/channel_manager.h

otChannelManagerRequestChannelSelect#

otError otChannelManagerRequestChannelSelect (otInstance * aInstance, bool aSkipQualityCheck)

Requests that ChannelManager checks and selects a new channel and starts a channel change.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aSkipQualityCheck

Indicates whether the quality check (step 1) should be skipped.

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


Definition at line 132 of file include/openthread/channel_manager.h

otChannelManagerSetAutoChannelSelectionEnabled#

void otChannelManagerSetAutoChannelSelectionEnabled (otInstance * aInstance, bool aEnabled)

Enables or disables the auto-channel-selection functionality.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aEnabled

Indicates whether to enable or disable this functionality.

When enabled, ChannelManager will periodically invoke a RequestChannelSelect(false). The period interval can be set by SetAutoChannelSelectionInterval().


Definition at line 144 of file include/openthread/channel_manager.h

otChannelManagerGetAutoChannelSelectionEnabled#

bool otChannelManagerGetAutoChannelSelectionEnabled (otInstance * aInstance)

Indicates whether the auto-channel-selection functionality is enabled or not.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • TRUE if enabled, FALSE if disabled.


Definition at line 154 of file include/openthread/channel_manager.h

otChannelManagerSetAutoChannelSelectionInterval#

otError otChannelManagerSetAutoChannelSelectionInterval (otInstance * aInstance, uint32_t aInterval)

Sets the period interval (in seconds) used by auto-channel-selection functionality.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aInterval

The interval in seconds.


Definition at line 166 of file include/openthread/channel_manager.h

otChannelManagerGetAutoChannelSelectionInterval#

uint32_t otChannelManagerGetAutoChannelSelectionInterval (otInstance * aInstance)

Gets the period interval (in seconds) used by auto-channel-selection functionality.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The interval in seconds.


Definition at line 176 of file include/openthread/channel_manager.h

otChannelManagerGetSupportedChannels#

uint32_t otChannelManagerGetSupportedChannels (otInstance * aInstance)

Gets the supported channel mask.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The supported channels as a bit-mask.


Definition at line 186 of file include/openthread/channel_manager.h

otChannelManagerSetSupportedChannels#

void otChannelManagerSetSupportedChannels (otInstance * aInstance, uint32_t aChannelMask)

Sets the supported channel mask.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aChannelMask

A channel mask.


Definition at line 195 of file include/openthread/channel_manager.h

otChannelManagerGetFavoredChannels#

uint32_t otChannelManagerGetFavoredChannels (otInstance * aInstance)

Gets the favored channel mask.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The favored channels as a bit-mask.


Definition at line 205 of file include/openthread/channel_manager.h

otChannelManagerSetFavoredChannels#

void otChannelManagerSetFavoredChannels (otInstance * aInstance, uint32_t aChannelMask)

Sets the favored channel mask.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aChannelMask

A channel mask.


Definition at line 214 of file include/openthread/channel_manager.h

otChannelManagerGetCcaFailureRateThreshold#

uint16_t otChannelManagerGetCcaFailureRateThreshold (otInstance * aInstance)

Gets the CCA failure rate threshold.

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%.


Definition at line 224 of file include/openthread/channel_manager.h

otChannelManagerSetCcaFailureRateThreshold#

void otChannelManagerSetCcaFailureRateThreshold (otInstance * aInstance, uint16_t aThreshold)

Sets the CCA failure rate threshold.

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%.


Definition at line 233 of file include/openthread/channel_manager.h