Border Routing Manager

This module includes definitions related to Border Routing Manager.

Summary

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

Border Routing Manager handles bi-directional routing between Thread network and adjacent infrastructure link (AIL).

It emits ICMRv6 ND Router Advertisement (RA) messages on AIL to advertise on-link and route prefixes. It also processes received RA messages from infrastructure and mirrors the discovered prefixes on the Thread Network Data to ensure devices on Thread mesh can reach AIL through the Border Router.

Routing Manager manages the Off-Mesh Routable (OMR) prefix on the Thread Network data which configures Thread devices with a suitable Off-Mesh Routable IPv6 address. It announces the reachability of this prefix on AIL by including it in the emitted RA messages as an IPv6 Route Information Option (RIO).

Routing Manager also monitors and adds on-link prefix on the infrastructure network. If a router on AIL is already providing RA messages containing an IPv6 Prefix Information Option (PIO) that enables IPv6 devices on the link to self-configure their own routable unicast IPv6 address, this address can be used by Thread devices to reach AIL. If Border Router finds no such RA message on AIL, it generates a ULA on-link prefix which it then advertises on AIL in the emitted RA messages.

Enumerations

otBorderRoutingDhcp6PdState{
  OT_BORDER_ROUTING_DHCP6_PD_STATE_DISABLED,
  OT_BORDER_ROUTING_DHCP6_PD_STATE_STOPPED,
  OT_BORDER_ROUTING_DHCP6_PD_STATE_RUNNING
}
enum
This enumeration represents the state of DHCPv6 Prefix Delegation State.
otBorderRoutingState{
  OT_BORDER_ROUTING_STATE_UNINITIALIZED,
  OT_BORDER_ROUTING_STATE_DISABLED,
  OT_BORDER_ROUTING_STATE_STOPPED,
  OT_BORDER_ROUTING_STATE_RUNNING
}
enum
Represents the state of Border Routing Manager.

Typedefs

otBorderRoutingPrefixTableEntry typedef
Represents an entry from the discovered prefix table.
otBorderRoutingPrefixTableIterator typedef
Represents an iterator to iterate through the Border Router's discovered prefix table.
otBorderRoutingRouterEntry typedef
Represents a discovered router on the infrastructure link.
otPdProcessedRaInfo typedef
Represents a group of data of platform-generated RA messages processed.

Functions

otBorderRoutingClearRouteInfoOptionPreference(otInstance *aInstance)
void
Clears a previously set preference value for advertised Route Info Options.
otBorderRoutingClearRoutePreference(otInstance *aInstance)
void
Clears a previously set preference value for published routes in Network Data.
otBorderRoutingDhcp6PdGetState(otInstance *aInstance)
Gets the current state of DHCPv6 Prefix Delegation.
otBorderRoutingDhcp6PdSetEnabled(otInstance *aInstance, bool aEnabled)
void
Enables / Disables DHCPv6 Prefix Delegation.
otBorderRoutingGetFavoredNat64Prefix(otInstance *aInstance, otIp6Prefix *aPrefix, otRoutePreference *aPreference)
Gets the currently favored NAT64 prefix.
otBorderRoutingGetFavoredOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix, otRoutePreference *aPreference)
Gets the currently favored Off-Mesh-Routable (OMR) Prefix.
otBorderRoutingGetFavoredOnLinkPrefix(otInstance *aInstance, otIp6Prefix *aPrefix)
Gets the currently favored On-Link Prefix.
otBorderRoutingGetNat64Prefix(otInstance *aInstance, otIp6Prefix *aPrefix)
Gets the local NAT64 Prefix of the Border Router.
otBorderRoutingGetNextPrefixTableEntry(otInstance *aInstance, otBorderRoutingPrefixTableIterator *aIterator, otBorderRoutingPrefixTableEntry *aEntry)
Iterates over the entries in the Border Router's discovered prefix table.
otBorderRoutingGetNextRouterEntry(otInstance *aInstance, otBorderRoutingPrefixTableIterator *aIterator, otBorderRoutingRouterEntry *aEntry)
Iterates over the discovered router entries on the infrastructure link.
otBorderRoutingGetOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix)
Gets the local Off-Mesh-Routable (OMR) Prefix, for example fdfc:1ff5:1512:5622::/64.
otBorderRoutingGetOnLinkPrefix(otInstance *aInstance, otIp6Prefix *aPrefix)
Gets the local On-Link Prefix for the adjacent infrastructure link.
otBorderRoutingGetPdOmrPrefix(otInstance *aInstance, otBorderRoutingPrefixTableEntry *aPrefixInfo)
Gets the DHCPv6 Prefix Delegation (PD) provided off-mesh-routable (OMR) prefix.
otBorderRoutingGetPdProcessedRaInfo(otInstance *aInstance, otPdProcessedRaInfo *aPdProcessedRaInfo)
Gets the data of platform generated RA message processed.
otBorderRoutingGetRouteInfoOptionPreference(otInstance *aInstance)
Gets the current preference used when advertising Route Info Options (RIO) in Router Advertisement messages sent over the infrastructure link.
otBorderRoutingGetRoutePreference(otInstance *aInstance)
Gets the current preference used for published routes in Network Data.
otBorderRoutingGetState(otInstance *aInstance)
Gets the current state of Border Routing Manager.
otBorderRoutingInit(otInstance *aInstance, uint32_t aInfraIfIndex, bool aInfraIfIsRunning)
Initializes the Border Routing Manager on given infrastructure interface.
otBorderRoutingPrefixTableInitIterator(otInstance *aInstance, otBorderRoutingPrefixTableIterator *aIterator)
void
otBorderRoutingSetEnabled(otInstance *aInstance, bool aEnabled)
Enables or disables the Border Routing Manager.
otBorderRoutingSetRouteInfoOptionPreference(otInstance *aInstance, otRoutePreference aPreference)
void
Explicitly sets the preference to use when advertising Route Info Options (RIO) in Router Advertisement messages sent over the infrastructure link.
otBorderRoutingSetRoutePreference(otInstance *aInstance, otRoutePreference aPreference)
void
Explicitly sets the preference of published routes in Network Data.

Structs

otBorderRoutingPrefixTableEntry

Represents an entry from the discovered prefix table.

otBorderRoutingPrefixTableIterator

Represents an iterator to iterate through the Border Router's discovered prefix table.

otBorderRoutingRouterEntry

Represents a discovered router on the infrastructure link.

otPdProcessedRaInfo

Represents a group of data of platform-generated RA messages processed.

Enumerations

otBorderRoutingDhcp6PdState

 otBorderRoutingDhcp6PdState

This enumeration represents the state of DHCPv6 Prefix Delegation State.

Properties
OT_BORDER_ROUTING_DHCP6_PD_STATE_DISABLED

DHCPv6 PD is disabled on the border router.

OT_BORDER_ROUTING_DHCP6_PD_STATE_RUNNING

DHCPv6 PD is enabled and will try to request and publish a prefix.

OT_BORDER_ROUTING_DHCP6_PD_STATE_STOPPED

DHCPv6 PD in enabled but won't try to request and publish a prefix.

otBorderRoutingState

 otBorderRoutingState

Represents the state of Border Routing Manager.

Properties
OT_BORDER_ROUTING_STATE_DISABLED

Routing Manager is initialized but disabled.

OT_BORDER_ROUTING_STATE_RUNNING

Routing Manager is initialized, enabled, and running.

OT_BORDER_ROUTING_STATE_STOPPED

Routing Manager in initialized and enabled but currently stopped.

OT_BORDER_ROUTING_STATE_UNINITIALIZED

Routing Manager is uninitialized.

Typedefs

otBorderRoutingPrefixTableEntry

struct otBorderRoutingPrefixTableEntry otBorderRoutingPrefixTableEntry

Represents an entry from the discovered prefix table.

The entries in the discovered table track the Prefix/Route Info Options in the received Router Advertisement messages from other routers on the infrastructure link.

otBorderRoutingPrefixTableIterator

struct otBorderRoutingPrefixTableIterator otBorderRoutingPrefixTableIterator

Represents an iterator to iterate through the Border Router's discovered prefix table.

The fields in this type are opaque (intended for use by OpenThread core only) and therefore should not be accessed or used by caller.

Before using an iterator, it MUST be initialized using otBorderRoutingPrefixTableInitIterator().

otBorderRoutingRouterEntry

struct otBorderRoutingRouterEntry otBorderRoutingRouterEntry

Represents a discovered router on the infrastructure link.

otPdProcessedRaInfo

struct otPdProcessedRaInfo otPdProcessedRaInfo

Represents a group of data of platform-generated RA messages processed.

Functions

otBorderRoutingClearRouteInfoOptionPreference

void otBorderRoutingClearRouteInfoOptionPreference(
  otInstance *aInstance
)

Clears a previously set preference value for advertised Route Info Options.

After a call to this function, BR will use device's role to determine the RIO preference: Medium preference when in router/leader role and low preference when in child role.

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

otBorderRoutingClearRoutePreference

void otBorderRoutingClearRoutePreference(
  otInstance *aInstance
)

Clears a previously set preference value for published routes in Network Data.

After a call to this function, BR will determine the preference automatically based on the device's role and link quality (to the parent when acting as end-device).

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

otBorderRoutingDhcp6PdGetState

otBorderRoutingDhcp6PdState otBorderRoutingDhcp6PdGetState(
  otInstance *aInstance
)

Gets the current state of DHCPv6 Prefix Delegation.

Requires OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE to be enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The current state of DHCPv6 Prefix Delegation.

otBorderRoutingDhcp6PdSetEnabled

void otBorderRoutingDhcp6PdSetEnabled(
  otInstance *aInstance,
  bool aEnabled
)

Enables / Disables DHCPv6 Prefix Delegation.

OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE must be enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aEnabled
Whether to accept platform generated RA messages.

otBorderRoutingGetFavoredNat64Prefix

otError otBorderRoutingGetFavoredNat64Prefix(
  otInstance *aInstance,
  otIp6Prefix *aPrefix,
  otRoutePreference *aPreference
)

Gets the currently favored NAT64 prefix.

The favored NAT64 prefix can be discovered from infrastructure link or can be this device's local NAT64 prefix.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aPrefix
A pointer to output the favored NAT64 prefix.
[out] aPreference
A pointer to output the preference associated the favored prefix.
Return Values
OT_ERROR_INVALID_STATE
The Border Routing Manager is not initialized yet.
OT_ERROR_NONE
Successfully retrieved the favored NAT64 prefix.

otBorderRoutingGetFavoredOmrPrefix

otError otBorderRoutingGetFavoredOmrPrefix(
  otInstance *aInstance,
  otIp6Prefix *aPrefix,
  otRoutePreference *aPreference
)

Gets the currently favored Off-Mesh-Routable (OMR) Prefix.

The favored OMR prefix can be discovered from Network Data or can be this device's local OMR prefix.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aPrefix
A pointer to output the favored OMR prefix.
[out] aPreference
A pointer to output the preference associated the favored prefix.
Return Values
OT_ERROR_INVALID_STATE
The Border Routing Manager is not running yet.
OT_ERROR_NONE
Successfully retrieved the favored OMR prefix.

otBorderRoutingGetFavoredOnLinkPrefix

otError otBorderRoutingGetFavoredOnLinkPrefix(
  otInstance *aInstance,
  otIp6Prefix *aPrefix
)

Gets the currently favored On-Link Prefix.

The favored prefix is either a discovered on-link prefix on the infrastructure link or the local on-link prefix.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aPrefix
A pointer to where the prefix will be output to.
Return Values
OT_ERROR_INVALID_STATE
The Border Routing Manager is not initialized yet.
OT_ERROR_NONE
Successfully retrieved the favored on-link prefix.

otBorderRoutingGetNat64Prefix

otError otBorderRoutingGetNat64Prefix(
  otInstance *aInstance,
  otIp6Prefix *aPrefix
)

Gets the local NAT64 Prefix of the Border Router.

NAT64 Prefix might not be advertised in the Thread network.

OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE must be enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aPrefix
A pointer to where the prefix will be output to.
Return Values
OT_ERROR_INVALID_STATE
The Border Routing Manager is not initialized yet.
OT_ERROR_NONE
Successfully retrieved the NAT64 prefix.

otBorderRoutingGetNextPrefixTableEntry

otError otBorderRoutingGetNextPrefixTableEntry(
  otInstance *aInstance,
  otBorderRoutingPrefixTableIterator *aIterator,
  otBorderRoutingPrefixTableEntry *aEntry
)

Iterates over the entries in the Border Router's discovered prefix table.

Prefix entries associated with the same discovered router on an infrastructure link are guaranteed to be grouped together (retrieved back-to-back).

Details
Parameters
[in] aInstance
The OpenThread instance.
[in,out] aIterator
A pointer to the iterator.
[out] aEntry
A pointer to the entry to populate.
Return Values
OT_ERROR_NONE
Iterated to the next entry, aEntry and aIterator are updated.
OT_ERROR_NOT_FOUND
No more entries in the table.

otBorderRoutingGetNextRouterEntry

otError otBorderRoutingGetNextRouterEntry(
  otInstance *aInstance,
  otBorderRoutingPrefixTableIterator *aIterator,
  otBorderRoutingRouterEntry *aEntry
)

Iterates over the discovered router entries on the infrastructure link.

Details
Parameters
[in] aInstance
The OpenThread instance.
[in,out] aIterator
A pointer to the iterator.
[out] aEntry
A pointer to the entry to populate.
Return Values
OT_ERROR_NONE
Iterated to the next router, aEntry and aIterator are updated.
OT_ERROR_NOT_FOUND
No more router entries.

otBorderRoutingGetOmrPrefix

otError otBorderRoutingGetOmrPrefix(
  otInstance *aInstance,
  otIp6Prefix *aPrefix
)

Gets the local Off-Mesh-Routable (OMR) Prefix, for example fdfc:1ff5:1512:5622::/64.

An OMR Prefix is a randomly generated 64-bit prefix that's published in the Thread network if there isn't already an OMR prefix. This prefix can be reached from the local Wi-Fi or Ethernet network.

Note: When DHCPv6 PD is enabled, the border router may publish the prefix from DHCPv6 PD.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aPrefix
A pointer to where the prefix will be output to.
Return Values
OT_ERROR_INVALID_STATE
The Border Routing Manager is not initialized yet.
OT_ERROR_NONE
Successfully retrieved the OMR prefix.
See also:
otBorderRoutingGetPdOmrPrefix

otBorderRoutingGetOnLinkPrefix

otError otBorderRoutingGetOnLinkPrefix(
  otInstance *aInstance,
  otIp6Prefix *aPrefix
)

Gets the local On-Link Prefix for the adjacent infrastructure link.

The local On-Link Prefix is a 64-bit prefix that's advertised on the infrastructure link if there isn't already a usable on-link prefix being advertised on the link.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aPrefix
A pointer to where the prefix will be output to.
Return Values
OT_ERROR_INVALID_STATE
The Border Routing Manager is not initialized yet.
OT_ERROR_NONE
Successfully retrieved the local on-link prefix.

otBorderRoutingGetPdOmrPrefix

otError otBorderRoutingGetPdOmrPrefix(
  otInstance *aInstance,
  otBorderRoutingPrefixTableEntry *aPrefixInfo
)

Gets the DHCPv6 Prefix Delegation (PD) provided off-mesh-routable (OMR) prefix.

Only mPrefix, mValidLifetime and mPreferredLifetime fields are used in the returned prefix info.

OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE must be enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aPrefixInfo
A pointer to where the prefix info will be output to.
Return Values
OT_ERROR_NONE
Successfully retrieved the OMR prefix.
OT_ERROR_INVALID_STATE
The Border Routing Manager is not initialized yet.
OT_ERROR_NOT_FOUND
There are no valid PD prefix on this BR.
See also:
otBorderRoutingGetOmrPrefix
otPlatBorderRoutingProcessIcmp6Ra

otBorderRoutingGetPdProcessedRaInfo

otError otBorderRoutingGetPdProcessedRaInfo(
  otInstance *aInstance,
  otPdProcessedRaInfo *aPdProcessedRaInfo
)

Gets the data of platform generated RA message processed.

OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE must be enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aPrefixInfo
A pointer to where the prefix info will be output to.
Return Values
OT_ERROR_NONE
Successfully retrieved the Info.
OT_ERROR_INVALID_STATE
The Border Routing Manager is not initialized yet.
OT_ERROR_NOT_FOUND
There are no valid Info on this BR.

otBorderRoutingGetRouteInfoOptionPreference

otRoutePreference otBorderRoutingGetRouteInfoOptionPreference(
  otInstance *aInstance
)

Gets the current preference used when advertising Route Info Options (RIO) in Router Advertisement messages sent over the infrastructure link.

The RIO preference is determined as follows:

  • If explicitly set by user by calling otBorderRoutingSetRouteInfoOptionPreference(), the given preference is used.
  • Otherwise, it is determined based on device's current role: Medium preference when in router/leader role and low preference when in child role.

Details
Returns
The current Route Info Option preference.

otBorderRoutingGetRoutePreference

otRoutePreference otBorderRoutingGetRoutePreference(
  otInstance *aInstance
)

Gets the current preference used for published routes in Network Data.

The preference is determined as follows:

  • If explicitly set by user by calling otBorderRoutingSetRoutePreference(), the given preference is used.
  • Otherwise, it is determined automatically by RoutingManager based on the device's role and link quality.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The current published route preference.

otBorderRoutingGetState

otBorderRoutingState otBorderRoutingGetState(
  otInstance *aInstance
)

Gets the current state of Border Routing Manager.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The current state of Border Routing Manager.

otBorderRoutingInit

otError otBorderRoutingInit(
  otInstance *aInstance,
  uint32_t aInfraIfIndex,
  bool aInfraIfIsRunning
)

Initializes the Border Routing Manager on given infrastructure interface.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aInfraIfIndex
The infrastructure interface index.
[in] aInfraIfIsRunning
A boolean that indicates whether the infrastructure interface is running.
Return Values
OT_ERROR_NONE
Successfully started the Border Routing Manager on given infrastructure.
OT_ERROR_INVALID_STATE
The Border Routing Manager is in a state other than disabled or uninitialized.
OT_ERROR_INVALID_ARGS
The index of the infrastructure interface is not valid.
OT_ERROR_FAILED
Internal failure. Usually due to failure in generating random prefixes.
See also:
otPlatInfraIfStateChanged.
otBorderRoutingSetEnabled.

otBorderRoutingPrefixTableInitIterator

void otBorderRoutingPrefixTableInitIterator(
  otInstance *aInstance,
  otBorderRoutingPrefixTableIterator *aIterator
)

Initializes an otBorderRoutingPrefixTableIterator.

An iterator MUST be initialized before it is used.

An iterator can be initialized again to restart from the beginning of the table.

When iterating over entries in the table, to ensure the update times mMsecSinceLastUpdate of entries are consistent, they are given relative to the time the iterator was initialized.

Details
Parameters
[in] aInstance
The OpenThread instance.
[out] aIterator
A pointer to the iterator to initialize.

otBorderRoutingSetEnabled

otError otBorderRoutingSetEnabled(
  otInstance *aInstance,
  bool aEnabled
)

Enables or disables the Border Routing Manager.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aEnabled
A boolean to enable/disable the routing manager.
Return Values
OT_ERROR_INVALID_STATE
The Border Routing Manager is not initialized yet.
OT_ERROR_NONE
Successfully enabled/disabled the Border Routing Manager.

otBorderRoutingSetRouteInfoOptionPreference

void otBorderRoutingSetRouteInfoOptionPreference(
  otInstance *aInstance,
  otRoutePreference aPreference
)

Explicitly sets the preference to use when advertising Route Info Options (RIO) in Router Advertisement messages sent over the infrastructure link.

After a call to this function, BR will use the given preference for all its advertised RIOs. The preference can be cleared by calling otBorderRoutingClearRouteInfoOptionPreference().

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aPreference
The route preference to use.

otBorderRoutingSetRoutePreference

void otBorderRoutingSetRoutePreference(
  otInstance *aInstance,
  otRoutePreference aPreference
)

Explicitly sets the preference of published routes in Network Data.

After a call to this function, BR will use the given preference. The preference can be cleared by calling otBorderRoutingClearRoutePreference().

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aPreference
The route preference to use.

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.