Border Routing Manager#

This module includes definitions related to Border Routing Manager.

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.

Modules#

otBorderRoutingPrefixTableIterator

otBorderRoutingRouterEntry

otBorderRoutingPrefixTableEntry

otPdProcessedRaInfo

Enumerations#

enum
OT_BORDER_ROUTING_STATE_UNINITIALIZED
OT_BORDER_ROUTING_STATE_DISABLED
OT_BORDER_ROUTING_STATE_STOPPED
OT_BORDER_ROUTING_STATE_RUNNING
}

Represents the state of Border Routing Manager.

enum
OT_BORDER_ROUTING_DHCP6_PD_STATE_DISABLED
OT_BORDER_ROUTING_DHCP6_PD_STATE_STOPPED
OT_BORDER_ROUTING_DHCP6_PD_STATE_RUNNING
}

This enumeration represents the state of DHCPv6 Prefix Delegation State.

Typedefs#

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

Represents a discovered router on the infrastructure link.

Represents an entry from the discovered prefix table.

typedef struct otPdProcessedRaInfo

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

typedef void(*
otBorderRoutingRequestDhcp6PdCallback)(otBorderRoutingDhcp6PdState aState, void *aContext)

When the state of a DHCPv6 Prefix Delegation (PD) on the Thread interface changes, this callback notifies processes in the OS of this changed state.

Functions#

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

Initializes the Border Routing Manager on given infrastructure interface.

otBorderRoutingSetEnabled(otInstance *aInstance, bool aEnabled)

Enables or disables the Border Routing Manager.

otBorderRoutingGetState(otInstance *aInstance)

Gets the current state of Border Routing Manager.

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

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.

void

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

otBorderRoutingSetExtraRouterAdvertOptions(otInstance *aInstance, const uint8_t *aOptions, uint16_t aLength)

Sets additional options to append at the end of emitted Router Advertisement (RA) messages.

otBorderRoutingGetRoutePreference(otInstance *aInstance)

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

void
otBorderRoutingSetRoutePreference(otInstance *aInstance, otRoutePreference aPreference)

Explicitly sets the preference of published routes in Network Data.

void

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

otBorderRoutingGetOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix)

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

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.

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

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

otBorderRoutingGetOnLinkPrefix(otInstance *aInstance, otIp6Prefix *aPrefix)

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

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.

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

Gets the currently favored NAT64 prefix.

void
otBorderRoutingPrefixTableInitIterator(otInstance *aInstance, otBorderRoutingPrefixTableIterator *aIterator)

Initializes an otBorderRoutingPrefixTableIterator.

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.

void
otBorderRoutingDhcp6PdSetEnabled(otInstance *aInstance, bool aEnabled)

Enables / Disables DHCPv6 Prefix Delegation.

otBorderRoutingDhcp6PdGetState(otInstance *aInstance)

Gets the current state of DHCPv6 Prefix Delegation.

void
otBorderRoutingDhcp6PdSetRequestCallback(otInstance *aInstance, otBorderRoutingRequestDhcp6PdCallback aCallback, void *aContext)

Sets the callback whenever the DHCPv6 PD state changes on the Thread interface.

Enumeration Documentation#

otBorderRoutingState#

otBorderRoutingState

Represents the state of Border Routing Manager.

Enumerator
OT_BORDER_ROUTING_STATE_UNINITIALIZED

Routing Manager is uninitialized.

OT_BORDER_ROUTING_STATE_DISABLED

Routing Manager is initialized but disabled.

OT_BORDER_ROUTING_STATE_STOPPED

Routing Manager in initialized and enabled but currently stopped.

OT_BORDER_ROUTING_STATE_RUNNING

Routing Manager is initialized, enabled, and running.


Definition at line 136 of file include/openthread/border_routing.h

otBorderRoutingDhcp6PdState#

otBorderRoutingDhcp6PdState

This enumeration represents the state of DHCPv6 Prefix Delegation State.

Enumerator
OT_BORDER_ROUTING_DHCP6_PD_STATE_DISABLED

DHCPv6 PD is disabled on the border router.

OT_BORDER_ROUTING_DHCP6_PD_STATE_STOPPED

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

OT_BORDER_ROUTING_DHCP6_PD_STATE_RUNNING

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


Definition at line 148 of file include/openthread/border_routing.h

Typedef Documentation#

otBorderRoutingPrefixTableIterator#

typedef 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().


Definition at line 89 of file include/openthread/border_routing.h

otBorderRoutingRouterEntry#

typedef struct otBorderRoutingRouterEntry otBorderRoutingRouterEntry

Represents a discovered router on the infrastructure link.


Definition at line 101 of file include/openthread/border_routing.h

otBorderRoutingPrefixTableEntry#

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


Definition at line 119 of file include/openthread/border_routing.h

otPdProcessedRaInfo#

typedef struct otPdProcessedRaInfo otPdProcessedRaInfo

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


Definition at line 130 of file include/openthread/border_routing.h

otBorderRoutingRequestDhcp6PdCallback#

typedef void(* otBorderRoutingRequestDhcp6PdCallback) (otBorderRoutingDhcp6PdState aState, void *aContext) )(otBorderRoutingDhcp6PdState aState, void *aContext)

When the state of a DHCPv6 Prefix Delegation (PD) on the Thread interface changes, this callback notifies processes in the OS of this changed state.

Parameters
[in]aState

The state of DHCPv6 Prefix Delegation State.

[in]aContext

A pointer to arbitrary context information.


Definition at line 509 of file include/openthread/border_routing.h

Function Documentation#

otBorderRoutingInit#

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

Initializes the Border Routing Manager on given infrastructure interface.

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.

Note

  • This method MUST be called before any other otBorderRouting* APIs.

  • This method can be re-called to change the infrastructure interface, but the Border Routing Manager should be disabled first, and re-enabled after.

See Also


Definition at line 176 of file include/openthread/border_routing.h

otBorderRoutingSetEnabled#

otError otBorderRoutingSetEnabled (otInstance * aInstance, bool aEnabled)

Enables or disables the Border Routing Manager.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aEnabled

A boolean to enable/disable the routing manager.

Note

  • The Border Routing Manager is disabled by default.


Definition at line 190 of file include/openthread/border_routing.h

otBorderRoutingGetState#

otBorderRoutingState otBorderRoutingGetState (otInstance * aInstance)

Gets the current state of Border Routing Manager.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • The current state of Border Routing Manager.


Definition at line 200 of file include/openthread/border_routing.h

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.

Parameters
N/AaInstance

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.

Returns

  • The current Route Info Option preference.


Definition at line 216 of file include/openthread/border_routing.h

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.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aPreference

The route preference to use.

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


Definition at line 229 of file include/openthread/border_routing.h

otBorderRoutingClearRouteInfoOptionPreference#

void otBorderRoutingClearRouteInfoOptionPreference (otInstance * aInstance)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

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.


Definition at line 240 of file include/openthread/border_routing.h

otBorderRoutingSetExtraRouterAdvertOptions#

otError otBorderRoutingSetExtraRouterAdvertOptions (otInstance * aInstance, const uint8_t * aOptions, uint16_t aLength)

Sets additional options to append at the end of emitted Router Advertisement (RA) messages.

Parameters
[in]aInstance

A pointer to the encoded options. Can be NULL to clear.

[in]aOptions

Number of bytes in aOptions.

N/AaLength

The content of aOptions is copied internally, so it can be a temporary buffer (e.g., a stack allocated array).

Subsequent calls to this function overwrite the previously set value.


Definition at line 256 of file include/openthread/border_routing.h

otBorderRoutingGetRoutePreference#

otRoutePreference otBorderRoutingGetRoutePreference (otInstance * aInstance)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

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.

Returns

  • The current published route preference.


Definition at line 271 of file include/openthread/border_routing.h

otBorderRoutingSetRoutePreference#

void otBorderRoutingSetRoutePreference (otInstance * aInstance, otRoutePreference aPreference)

Explicitly sets the preference of published routes in Network Data.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aPreference

The route preference to use.

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


Definition at line 283 of file include/openthread/border_routing.h

otBorderRoutingClearRoutePreference#

void otBorderRoutingClearRoutePreference (otInstance * aInstance)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

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


Definition at line 294 of file include/openthread/border_routing.h

otBorderRoutingGetOmrPrefix#

otError otBorderRoutingGetOmrPrefix (otInstance * aInstance, otIp6Prefix * aPrefix)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[out]aPrefix

A pointer to where the prefix will be output to.

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.

See Also


Definition at line 315 of file include/openthread/border_routing.h

otBorderRoutingGetPdOmrPrefix#

otError otBorderRoutingGetPdOmrPrefix (otInstance * aInstance, otBorderRoutingPrefixTableEntry * aPrefixInfo)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[out]aPrefixInfo

A pointer to where the prefix info will be output to.

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

OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE must be enabled.

See Also


Definition at line 335 of file include/openthread/border_routing.h

otBorderRoutingGetPdProcessedRaInfo#

otError otBorderRoutingGetPdProcessedRaInfo (otInstance * aInstance, otPdProcessedRaInfo * aPdProcessedRaInfo)

Gets the data of platform generated RA message processed.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[out]aPdProcessedRaInfo

A pointer to where the prefix info will be output to.

OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE must be enabled.


Definition at line 350 of file include/openthread/border_routing.h

otBorderRoutingGetFavoredOmrPrefix#

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

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

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.

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


Definition at line 365 of file include/openthread/border_routing.h

otBorderRoutingGetOnLinkPrefix#

otError otBorderRoutingGetOnLinkPrefix (otInstance * aInstance, otIp6Prefix * aPrefix)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[out]aPrefix

A pointer to where the prefix will be output to.

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.


Definition at line 380 of file include/openthread/border_routing.h

otBorderRoutingGetFavoredOnLinkPrefix#

otError otBorderRoutingGetFavoredOnLinkPrefix (otInstance * aInstance, otIp6Prefix * aPrefix)

Gets the currently favored On-Link Prefix.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[out]aPrefix

A pointer to where the prefix will be output to.

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


Definition at line 394 of file include/openthread/border_routing.h

otBorderRoutingGetNat64Prefix#

otError otBorderRoutingGetNat64Prefix (otInstance * aInstance, otIp6Prefix * aPrefix)

Gets the local NAT64 Prefix of the Border Router.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[out]aPrefix

A pointer to where the prefix will be output to.

NAT64 Prefix might not be advertised in the Thread network.

OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE must be enabled.


Definition at line 410 of file include/openthread/border_routing.h

otBorderRoutingGetFavoredNat64Prefix#

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

Gets the currently favored NAT64 prefix.

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.

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


Definition at line 425 of file include/openthread/border_routing.h

otBorderRoutingPrefixTableInitIterator#

void otBorderRoutingPrefixTableInitIterator (otInstance * aInstance, otBorderRoutingPrefixTableIterator * aIterator)

Initializes an otBorderRoutingPrefixTableIterator.

Parameters
[in]aInstance

The OpenThread instance.

[out]aIterator

A pointer to the iterator to initialize.

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.


Definition at line 443 of file include/openthread/border_routing.h

otBorderRoutingGetNextPrefixTableEntry#

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

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

Parameters
[in]aInstance

The OpenThread instance.

[inout]aIterator

A pointer to the iterator.

[out]aEntry

A pointer to the entry to populate.

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


Definition at line 459 of file include/openthread/border_routing.h

otBorderRoutingGetNextRouterEntry#

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

Iterates over the discovered router entries on the infrastructure link.

Parameters
[in]aInstance

The OpenThread instance.

[inout]aIterator

A pointer to the iterator.

[out]aEntry

A pointer to the entry to populate.


Definition at line 474 of file include/openthread/border_routing.h

otBorderRoutingDhcp6PdSetEnabled#

void otBorderRoutingDhcp6PdSetEnabled (otInstance * aInstance, bool aEnabled)

Enables / Disables DHCPv6 Prefix Delegation.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aEnabled

Whether to accept platform generated RA messages.

OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE must be enabled.


Definition at line 487 of file include/openthread/border_routing.h

otBorderRoutingDhcp6PdGetState#

otBorderRoutingDhcp6PdState otBorderRoutingDhcp6PdGetState (otInstance * aInstance)

Gets the current state of DHCPv6 Prefix Delegation.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Requires OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE to be enabled.

Returns

  • The current state of DHCPv6 Prefix Delegation.


Definition at line 499 of file include/openthread/border_routing.h

otBorderRoutingDhcp6PdSetRequestCallback#

void otBorderRoutingDhcp6PdSetRequestCallback (otInstance * aInstance, otBorderRoutingRequestDhcp6PdCallback aCallback, void * aContext)

Sets the callback whenever the DHCPv6 PD state changes on the Thread interface.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aCallback

A pointer to a function that is called whenever the DHCPv6 PD state changes.

[in]aContext

A pointer to arbitrary context information.

Subsequent calls to this function replace the previously set callback.


Definition at line 522 of file include/openthread/border_routing.h