Border Router Multi AIL Detection

This module includes functions for the OpenThread Multi-AIL Detection feature.

Summary

All the functions in this module require both the OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE and OPENTHREAD_CONFIG_BORDER_ROUTING_MULTI_AIL_DETECTION_ENABLE to be enabled.

Typedefs
`otBorderRoutingMultiAilCallback)(bool aDetected, void *aContext)`	typedef `void(*` A callback function pointer called when the multi-AIL detection state changes.

Functions
`otBorderRoutingIsMultiAilDetected(otInstance *aInstance)`	`bool` Gets the current detected state regarding multiple Adjacent Infrastructure Links (AILs).
`otBorderRoutingIsMultiAilDetectionEnabled(otInstance *aInstance)`	`bool` Checks if the Multi-AIL Detector is enabled.
`otBorderRoutingIsMultiAilDetectionRunning(otInstance *aInstance)`	`bool` Checks if the Multi-AIL Detector is running.
`otBorderRoutingSetMultiAilCallback(otInstance aInstance, otBorderRoutingMultiAilCallback aCallback, void aContext)`	`void` Sets a callback function to be notified of changes in the multi-AIL detection state.
`otBorderRoutingSetMultiAilDetectionEnabled(otInstance *aInstance, bool aEnable)`	`void` Enables or disables the Multi-AIL Detector.

Typedefs

otBorderRoutingMultiAilCallback

void(* otBorderRoutingMultiAilCallback)(bool aDetected, void *aContext)

A callback function pointer called when the multi-AIL detection state changes.

This callback function is invoked by the OpenThread stack whenever the detector determines a change in whether Border Routers on the Thread mesh might be connected to different Adjacent Infrastructure Links (AILs).

See otBorderRoutingIsMultiAilDetected() for more details.

Details

Parameters

`[in] aDetected`	`TRUE` if multiple AILs are now detected, `FALSE` otherwise.
`[in] aContext`	A pointer to arbitrary context information provided when the callback was registered using `otBorderRoutingSetMultiAilCallback()`.

Functions

otBorderRoutingIsMultiAilDetected

bool otBorderRoutingIsMultiAilDetected(
  otInstance *aInstance
)

Gets the current detected state regarding multiple Adjacent Infrastructure Links (AILs).

It returns whether the detector currently believes that Border Routers (BRs) on the Thread mesh may be connected to different AILs.

The detection mechanism operates as follows: The detector monitors the number of peer BRs listed in the Thread Network Data (see otBorderRoutingCountPeerBrs()) and compares this count with the number of peer BRs discovered by processing received Router Advertisement (RA) messages on its connected AIL. If the count derived from Network Data consistently exceeds the count derived from RAs for a detection duration of 10 minutes, it concludes that BRs are likely connected to different AILs. To clear state a shorter window of 1 minute is used.

The detection window of 10 minutes helps to avoid false positives due to transient changes. The detector uses 200 seconds for reachability checks of peer BRs (sending Neighbor Solicitation). Stale Network Data entries are also expected to age out within a few minutes. So a 10-minute detection time accommodates both cases.

While generally effective, this detection mechanism may get less reliable in scenarios with a large number of BRs, particularly exceeding ten. This is related to the "Network Data Publisher" mechanism, where BRs might refrain from publishing their external route information in the Network Data to conserve its limited size, potentially skewing the Network Data BR count.

Details

Parameters

[in] aInstance

A pointer to the OpenThread instance.

Return Values

`TRUE`	Has detected that BRs are likely connected to multiple AILs.
`FALSE`	Has not detected (or no longer detects) that BRs are connected to multiple AILs.

otBorderRoutingIsMultiAilDetectionEnabled

bool otBorderRoutingIsMultiAilDetectionEnabled(
  otInstance *aInstance
)

Checks if the Multi-AIL Detector is enabled.

Details

Parameters

[in] aInstance

A pointer to the OpenThread instance.

Return Values

`TRUE`	If the detector is enabled.
`FALSE`	If the detector is disabled.

otBorderRoutingIsMultiAilDetectionRunning

bool otBorderRoutingIsMultiAilDetectionRunning(
  otInstance *aInstance
)

Checks if the Multi-AIL Detector is running.

The detector runs when it is enabled and the infrastructure interface is also active.

Details

Parameters

[in] aInstance

A pointer to the OpenThread instance.

Return Values

`TRUE`	If the detector is running.
`FALSE`	If the detector is not running.

otBorderRoutingSetMultiAilCallback

void otBorderRoutingSetMultiAilCallback(
  otInstance *aInstance,
  otBorderRoutingMultiAilCallback aCallback,
  void *aContext
)

Sets a callback function to be notified of changes in the multi-AIL detection state.

Subsequent calls to this function will overwrite the previous callback setting. Using NULL for aCallback will disable the callback.

Details

Parameters

`[in] aInstance`	A pointer to the OpenThread instance.
`[in] aCallback`	A pointer to the function (`otBorderRoutingMultiAilCallback`) to be called upon state changes, or `NULL` to unregister a previously set callback.
`[in] aContext`	A pointer to application-specific context that will be passed back in the `aCallback` function. This can be `NULL` if no context is needed.

otBorderRoutingSetMultiAilDetectionEnabled

void otBorderRoutingSetMultiAilDetectionEnabled(
  otInstance *aInstance,
  bool aEnable
)

Enables or disables the Multi-AIL Detector.

If OPENTHREAD_CONFIG_BORDER_ROUTING_MULTI_AIL_DETECTION_AUTO_ENABLE_MODE is enabled, the detector is enabled by default and starts running when the infra-if network is initialized and becomes active (running).

Details

Parameters

`[in] aInstance`	A pointer to the OpenThread instance.
`[in] aEnable`	TRUE to enable the detector, FALSE to disable.

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.