Channel Manager#
This module includes functions for Channel Manager.
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#
Requests a Thread network channel change.
Gets the channel from the last successful call to otChannelManagerRequestChannelChange()
Gets the delay (in seconds) used by Channel Manager for a network channel change.
Sets the delay (in seconds) used for a network channel change.
Requests that ChannelManager
checks and selects a new channel and starts a channel change.
Requests that ChannelManager
checks and selects a new CSL channel and starts a CSL channel change.
Enables or disables the auto-channel-selection functionality for network channel.
Indicates whether the auto-channel-selection functionality for a network channel is enabled or not.
Enables or disables the auto-channel-selection functionality for a CSL channel.
Indicates whether the auto-csl-channel-selection functionality is enabled or not.
Sets the period interval (in seconds) used by auto-channel-selection functionality.
Gets the period interval (in seconds) used by auto-channel-selection functionality.
Gets the supported channel mask.
Sets the supported channel mask.
Gets the favored channel mask.
Sets the favored channel mask.
Gets the CCA failure rate threshold.
Sets the CCA failure rate threshold.
Function Documentation#
otChannelManagerRequestChannelChange#
void otChannelManagerRequestChannelChange (otInstance * aInstance, uint8_t aChannel)
Requests a Thread network channel change.
[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.
75
of file include/openthread/channel_manager.h
otChannelManagerGetRequestedChannel#
uint8_t otChannelManagerGetRequestedChannel (otInstance * aInstance)
Gets the channel from the last successful call to otChannelManagerRequestChannelChange()
N/A | aInstance |
Returns
The last requested channel or zero if there has been no channel change request yet.
83
of file include/openthread/channel_manager.h
otChannelManagerGetDelay#
uint16_t otChannelManagerGetDelay (otInstance * aInstance)
Gets the delay (in seconds) used by Channel Manager for a network channel change.
[in] | aInstance | A pointer to an OpenThread instance. |
Only available on FTDs.
Returns
The delay (in seconds) for channel change.
95
of file include/openthread/channel_manager.h
otChannelManagerSetDelay#
otError otChannelManagerSetDelay (otInstance * aInstance, uint16_t aDelay)
Sets the delay (in seconds) used for a network channel change.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aDelay | Delay in seconds. |
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.
110
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.
[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()
).
140
of file include/openthread/channel_manager.h
otChannelManagerRequestCslChannelSelect#
otError otChannelManagerRequestCslChannelSelect (otInstance * aInstance, bool aSkipQualityCheck)
Requests that ChannelManager
checks and selects a new CSL channel and starts a CSL channel change.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aSkipQualityCheck | Indicates whether the quality check (step 1) should be skipped. |
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.
171
of file include/openthread/channel_manager.h
otChannelManagerSetAutoChannelSelectionEnabled#
void otChannelManagerSetAutoChannelSelectionEnabled (otInstance * aInstance, bool aEnabled)
Enables or disables the auto-channel-selection functionality for network channel.
[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 otChannelManagerSetAutoChannelSelectionInterval()
.
183
of file include/openthread/channel_manager.h
otChannelManagerGetAutoChannelSelectionEnabled#
bool otChannelManagerGetAutoChannelSelectionEnabled (otInstance * aInstance)
Indicates whether the auto-channel-selection functionality for a network channel is enabled or not.
[in] | aInstance | A pointer to an OpenThread instance. |
Returns
TRUE if enabled, FALSE if disabled.
193
of file include/openthread/channel_manager.h
otChannelManagerSetAutoCslChannelSelectionEnabled#
void otChannelManagerSetAutoCslChannelSelectionEnabled (otInstance * aInstance, bool aEnabled)
Enables or disables the auto-channel-selection functionality for a CSL channel.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aEnabled | Indicates whether to enable or disable this functionality. |
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()
.
207
of file include/openthread/channel_manager.h
otChannelManagerGetAutoCslChannelSelectionEnabled#
bool otChannelManagerGetAutoCslChannelSelectionEnabled (otInstance * aInstance)
Indicates whether the auto-csl-channel-selection functionality is enabled or not.
[in] | aInstance | A pointer to an OpenThread instance. |
Only available with OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE && OPENTHREAD_CONFIG_CHANNEL_MANAGER_CSL_CHANNEL_SELECT_ENABLE
.
Returns
TRUE if enabled, FALSE if disabled.
220
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.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aInterval | The interval in seconds. |
232
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.
[in] | aInstance | A pointer to an OpenThread instance. |
Returns
The interval in seconds.
242
of file include/openthread/channel_manager.h
otChannelManagerGetSupportedChannels#
uint32_t otChannelManagerGetSupportedChannels (otInstance * aInstance)
Gets the supported channel mask.
[in] | aInstance | A pointer to an OpenThread instance. |
Returns
The supported channels as a bit-mask.
252
of file include/openthread/channel_manager.h
otChannelManagerSetSupportedChannels#
void otChannelManagerSetSupportedChannels (otInstance * aInstance, uint32_t aChannelMask)
Sets the supported channel mask.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aChannelMask | A channel mask. |
261
of file include/openthread/channel_manager.h
otChannelManagerGetFavoredChannels#
uint32_t otChannelManagerGetFavoredChannels (otInstance * aInstance)
Gets the favored channel mask.
[in] | aInstance | A pointer to an OpenThread instance. |
Returns
The favored channels as a bit-mask.
271
of file include/openthread/channel_manager.h
otChannelManagerSetFavoredChannels#
void otChannelManagerSetFavoredChannels (otInstance * aInstance, uint32_t aChannelMask)
Sets the favored channel mask.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aChannelMask | A channel mask. |
280
of file include/openthread/channel_manager.h
otChannelManagerGetCcaFailureRateThreshold#
uint16_t otChannelManagerGetCcaFailureRateThreshold (otInstance * aInstance)
Gets the CCA failure rate threshold.
[in] | aInstance | A pointer to an OpenThread instance. |
Returns
The CCA failure rate threshold. Value 0 maps to 0% and 0xffff maps to 100%.
290
of file include/openthread/channel_manager.h
otChannelManagerSetCcaFailureRateThreshold#
void otChannelManagerSetCcaFailureRateThreshold (otInstance * aInstance, uint16_t aThreshold)
Sets the CCA failure rate threshold.
[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%. |
299
of file include/openthread/channel_manager.h