Channel Manager

This module includes functions for Channel Manager.

Functions

void otChannelManagerRequestChannelChange (otInstance *aInstance, uint8_t aChannel)
 Requests a Thread network channel change.
 
uint8_t otChannelManagerGetRequestedChannel (otInstance *aInstance)
 This function gets the channel from the last successful call to otChannelManagerRequestChannelChange()
 
uint16_t otChannelManagerGetDelay (otInstance *aInstance)
 This function gets the delay (in seconds) used by Channel Manager for a channel change.
 
otError otChannelManagerSetDelay (otInstance *aInstance, uint16_t aDelay)
 Sets the delay (in seconds) used for a channel change.
 
otError otChannelManagerRequestChannelSelect (otInstance *aInstance, bool aSkipQualityCheck)
 This function 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 otChannelManagerGetAutoChannelSelectionEnabled (otInstance *aInstance)
 This function indicates whether the auto-channel-selection functionality is enabled or not.
 
otError otChannelManagerSetAutoChannelSelectionInterval (otInstance *aInstance, uint32_t aInterval)
 Sets the period interval (in seconds) used by auto-channel-selection functionality.
 
uint32_t otChannelManagerGetAutoChannelSelectionInterval (otInstance *aInstance)
 This function gets the period interval (in seconds) used by auto-channel-selection functionality.
 
uint32_t otChannelManagerGetSupportedChannels (otInstance *aInstance)
 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 otChannelManagerGetCcaFailureRateThreshold (otInstance *aInstance)
 Gets the CCA failure rate threshold.
 
void otChannelManagerSetCcaFailureRateThreshold (otInstance *aInstance, uint16_t aThreshold)
 Sets the CCA failure rate threshold.

Detailed Description

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.

Function Documentation

◆ otChannelManagerGetAutoChannelSelectionEnabled()

bool otChannelManagerGetAutoChannelSelectionEnabled ( otInstance aInstance)

This function indicates whether the auto-channel-selection functionality is enabled or not.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Returns
TRUE if enabled, FALSE if disabled.

◆ otChannelManagerGetAutoChannelSelectionInterval()

uint32_t otChannelManagerGetAutoChannelSelectionInterval ( otInstance aInstance)

This function gets the period interval (in seconds) used by auto-channel-selection functionality.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Returns
The interval in seconds.

◆ otChannelManagerGetCcaFailureRateThreshold()

uint16_t otChannelManagerGetCcaFailureRateThreshold ( otInstance aInstance)

Gets the CCA failure rate threshold.

Parameters
[in]aInstanceA 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)

This function gets the delay (in seconds) used by Channel Manager for a channel change.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Returns
The delay (in seconds) for channel change.

◆ otChannelManagerGetFavoredChannels()

uint32_t otChannelManagerGetFavoredChannels ( otInstance aInstance)

Gets the favored channel mask.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Returns
The favored channels as a bit-mask.

◆ otChannelManagerGetRequestedChannel()

uint8_t otChannelManagerGetRequestedChannel ( otInstance aInstance)

This function gets the channel from the last successful call to otChannelManagerRequestChannelChange()

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.

Parameters
[in]aInstanceA 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.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aChannelThe new channel for the Thread network.

◆ otChannelManagerRequestChannelSelect()

otError otChannelManagerRequestChannelSelect ( otInstance aInstance,
bool  aSkipQualityCheck 
)

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

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aSkipQualityCheckIndicates whether the quality check (step 1) should be skipped.
Return values
OT_ERROR_NONEChannel selection finished successfully.
OT_ERROR_NOT_FOUNDSupported 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.

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

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aEnabledIndicates 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.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aIntervalThe interval in seconds.
Return values
OT_ERROR_NONEThe interval was set successfully.
OT_ERROR_INVALID_ARGSThe aInterval is not valid (zero).

◆ otChannelManagerSetCcaFailureRateThreshold()

void otChannelManagerSetCcaFailureRateThreshold ( otInstance aInstance,
uint16_t  aThreshold 
)

Sets the CCA failure rate threshold.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aThresholdA 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 channel change.

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

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aDelayDelay in seconds.
Return values
OT_ERROR_NONEDelay was updated successfully.
OT_ERROR_INVALID_ARGSThe given delay aDelay is too short.

◆ otChannelManagerSetFavoredChannels()

void otChannelManagerSetFavoredChannels ( otInstance aInstance,
uint32_t  aChannelMask 
)

Sets the favored channel mask.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aChannelMaskA channel mask.

◆ otChannelManagerSetSupportedChannels()

void otChannelManagerSetSupportedChannels ( otInstance aInstance,
uint32_t  aChannelMask 
)

Sets the supported channel mask.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aChannelMaskA channel mask.