Channel Manager

This module includes functions for Channel Manager.

Summary

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

Functions

otChannelManagerGetAutoChannelSelectionEnabled(otInstance *aInstance)
bool
This function indicates whether the auto-channel-selection functionality is enabled or not.
otChannelManagerGetAutoChannelSelectionInterval(otInstance *aInstance)
uint32_t
This function gets the period interval (in seconds) used by auto-channel-selection functionality.
otChannelManagerGetDelay(otInstance *aInstance)
uint16_t
This function gets the delay (in seconds) used by Channel Manager for a channel change.
otChannelManagerGetFavoredChannels(otInstance *aInstance)
uint32_t
This function gets the favored channel mask.
otChannelManagerGetRequestedChannel(otInstance *aInstance)
uint8_t
This function gets the channel from the last successful call to otChannelManagerRequestChannelChange()
otChannelManagerGetSupportedChannels(otInstance *aInstance)
uint32_t
This function gets the supported channel mask.
otChannelManagerRequestChannelChange(otInstance *aInstance, uint8_t aChannel)
void
This function requests a Thread network channel change.
otChannelManagerRequestChannelSelect(otInstance *aInstance, bool aSkipQualityCheck)
This function requests that ChannelManager checks and selects a new channel and starts a channel change.
otChannelManagerSetAutoChannelSelectionEnabled(otInstance *aInstance, bool aEnabled)
void
This function enables/disables the auto-channel-selection functionality.
otChannelManagerSetAutoChannelSelectionInterval(otInstance *aInstance, uint32_t aInterval)
This function sets the period interval (in seconds) used by auto-channel-selection functionality.
otChannelManagerSetDelay(otInstance *aInstance, uint16_t aDelay)
This function sets the delay (in seconds) used for a channel change.
otChannelManagerSetFavoredChannels(otInstance *aInstance, uint32_t aChannelMask)
void
This function sets the favored channel mask.
otChannelManagerSetSupportedChannels(otInstance *aInstance, uint32_t aChannelMask)
void
This function sets the supported channel mask.

Functions

otChannelManagerGetAutoChannelSelectionEnabled

bool otChannelManagerGetAutoChannelSelectionEnabled(
  otInstance *aInstance
)

This function indicates whether the auto-channel-selection functionality 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
)

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

otChannelManagerGetDelay

uint16_t otChannelManagerGetDelay(
  otInstance *aInstance
)

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

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

otChannelManagerGetFavoredChannels

uint32_t otChannelManagerGetFavoredChannels(
  otInstance *aInstance
)

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

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

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

This function requests a Thread network channel change.

See also:
otChannelManagerSetDelay). The channel change is performed by updating the Pending Operational Dataset.

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
)

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

See also:
otChannelManagerSetSupportedChannels,
otChannelManagerSetFavoredChannels).

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.
OT_ERROR_INVALID_STATE
Thread is not enabled or not enough data to select a new channel.
OT_ERROR_DISABLED_FEATURE
ChannelMonintor feature is disabled by build-time configuration options.

otChannelManagerSetAutoChannelSelectionEnabled

void otChannelManagerSetAutoChannelSelectionEnabled(
  otInstance *aInstance,
  bool aEnabled
)

This function enables/disables the auto-channel-selection functionality.

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

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
)

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

otChannelManagerSetDelay

otError otChannelManagerSetDelay(
  otInstance *aInstance,
  uint16_t aDelay
)

This function sets the delay (in seconds) used for a channel change.

The delay should preferably be longer than 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
)

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

This function sets the supported channel mask.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aChannelMask
A channel mask.