Border Agent

This module includes functions for the Thread Border Agent role.

Summary

Enumerations
otBorderAgentState{
  OT_BORDER_AGENT_STATE_STOPPED = 0,
  OT_BORDER_AGENT_STATE_STARTED = 1,
  OT_BORDER_AGENT_STATE_ACTIVE = 2
} 		enum
Defines the Border Agent state.

Typedefs
otBorderAgentCounters typedef
otBorderAgentEphemeralKeyCallback)(void *aContext) typedef
void(*
Callback function pointer to signal changes related to the Border Agent's ephemeral key.
otBorderAgentId typedef
Represents a Border Agent Identifier.
otBorderAgentState typedef
Defines the Border Agent state.

Functions
otBorderAgentClearEphemeralKey(otInstance *aInstance)
void
Cancels the ephemeral key that is in use.
otBorderAgentDisconnect(otInstance *aInstance)
void
Disconnects the Border Agent from any active secure sessions.
otBorderAgentGetCounters(otInstance *aInstance)
Gets the counters of the Thread Border Agent.
otBorderAgentGetId(otInstance *aInstance, otBorderAgentId *aId)
Gets the randomly generated Border Agent ID.
otBorderAgentGetState(otInstance *aInstance)
Gets the otBorderAgentState of the Thread Border Agent role.
otBorderAgentGetUdpPort(otInstance *aInstance)
uint16_t
Gets the UDP port of the Thread Border Agent service.
otBorderAgentIsEphemeralKeyActive(otInstance *aInstance)
bool
Indicates whether or not an ephemeral key is currently active.
otBorderAgentSetEphemeralKey(otInstance *aInstance, const char *aKeyString, uint32_t aTimeout, uint16_t aUdpPort)
Sets the ephemeral key for a given timeout duration.
otBorderAgentSetEphemeralKeyCallback(otInstance *aInstance, otBorderAgentEphemeralKeyCallback aCallback, void *aContext)
void
Sets the callback function used by the Border Agent to notify any changes related to use of ephemeral key.
otBorderAgentSetId(otInstance *aInstance, const otBorderAgentId *aId)
Sets the Border Agent ID.

Macros
OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT (2 * 60 * 1000u)
Default ephemeral key timeout interval in milliseconds.
OT_BORDER_AGENT_ID_LENGTH (16)
The length of Border Agent/Router ID in bytes.
OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH (32)
Maximum length of the ephemeral key string.
OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT (10 * 60 * 1000u)
Maximum ephemeral key timeout interval in milliseconds.
OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH (6)
Minimum length of the ephemeral key string.

Structs
otBorderAgentCounters
otBorderAgentId

Represents a Border Agent Identifier.

Enumerations

otBorderAgentState

 otBorderAgentState

Defines the Border Agent state.

Properties
OT_BORDER_AGENT_STATE_ACTIVE

Border agent is connected with external commissioner.

OT_BORDER_AGENT_STATE_STARTED

Border agent is started.

OT_BORDER_AGENT_STATE_STOPPED

Border agent role is disabled.

Typedefs

otBorderAgentCounters

struct otBorderAgentCounters otBorderAgentCounters

otBorderAgentEphemeralKeyCallback

void(* otBorderAgentEphemeralKeyCallback)(void *aContext)

Callback function pointer to signal changes related to the Border Agent's ephemeral key.

This callback is invoked whenever:

  • The Border Agent starts using an ephemeral key.
  • Any parameter related to the ephemeral key, such as the port number, changes.
  • A commissioner candidate successfully establishes a secure session with the Border Agent using the ephemeral key. This situation can be identified by otBorderAgentGetState() being OT_BORDER_AGENT_STATE_ACTIVE (this event can be used to stop advertising the mDNS service "_meshcop-e._udp").
  • The Border Agent stops using the ephemeral key due to:
    • A direct call to otBorderAgentClearEphemeralKey().
    • The ephemeral key timing out.
    • An external commissioner successfully using the key to connect and then disconnecting.
    • Reaching the maximum number of allowed failed connection attempts.

Any OpenThread API, including otBorderAgent APIs, can be safely called from this callback.

Details
Parameters
[in] aContext
A pointer to an arbitrary context (provided when callback is set).

otBorderAgentId

struct otBorderAgentId otBorderAgentId

Represents a Border Agent Identifier.

otBorderAgentState

enum otBorderAgentState otBorderAgentState

Defines the Border Agent state.

Functions

otBorderAgentClearEphemeralKey

void otBorderAgentClearEphemeralKey(
  otInstance *aInstance
)

Cancels the ephemeral key that is in use.

Requires OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE.

Can be used to cancel a previously set ephemeral key before it times out. If the Border Agent is not running or there is no ephemeral key in use, calling this function has no effect.

If a commissioner is connected using the ephemeral key and is currently active, calling this function does not change its state. In this case the otBorderAgentIsEphemeralKeyActive() will continue to return TRUE until the commissioner disconnects, or the ephemeral key timeout expires. To terminate active commissioner sessions, use the otBorderAgentDisconnect() API.

Details
Parameters
[in] aInstance
The OpenThread instance.

otBorderAgentDisconnect

void otBorderAgentDisconnect(
  otInstance *aInstance
)

Disconnects the Border Agent from any active secure sessions.

If Border Agent is connected to a commissioner candidate with ephemeral key, calling this API will cause the ephemeral key to be cleared after the session is disconnected.

The Border Agent state may not change immediately upon calling this method. The state will be updated when the connection update is notified with a delay.

Details
Parameters
[in] aInstance
The OpenThread instance.

otBorderAgentGetCounters

const otBorderAgentCounters * otBorderAgentGetCounters(
  otInstance *aInstance
)

Gets the counters of the Thread Border Agent.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
A pointer to the Border Agent counters.

otBorderAgentGetId

otError otBorderAgentGetId(
  otInstance *aInstance,
  otBorderAgentId *aId
)

Gets the randomly generated Border Agent ID.

Requires OPENTHREAD_CONFIG_BORDER_AGENT_ID_ENABLE.

The ID is saved in persistent storage and survives reboots. The typical use case of the ID is to be published in the MeshCoP mDNS service as the id TXT value for the client to identify this Border Router/Agent device.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aId
A pointer to buffer to receive the ID.
Return Values
OT_ERROR_NONE
If successfully retrieved the Border Agent ID.
...
If failed to retrieve the Border Agent ID.
See also:
otBorderAgentSetId

otBorderAgentGetState

otBorderAgentState otBorderAgentGetState(
  otInstance *aInstance
)

Gets the otBorderAgentState of the Thread Border Agent role.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The current otBorderAgentState of the Border Agent.

otBorderAgentGetUdpPort

uint16_t otBorderAgentGetUdpPort(
  otInstance *aInstance
)

Gets the UDP port of the Thread Border Agent service.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
UDP port of the Border Agent.

otBorderAgentIsEphemeralKeyActive

bool otBorderAgentIsEphemeralKeyActive(
  otInstance *aInstance
)

Indicates whether or not an ephemeral key is currently active.

Requires OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE.

Details
Parameters
[in] aInstance
The OpenThread instance.
Return Values
TRUE
An ephemeral key is active.
FALSE
No ephemeral key is active.

otBorderAgentSetEphemeralKey

otError otBorderAgentSetEphemeralKey(
  otInstance *aInstance,
  const char *aKeyString,
  uint32_t aTimeout,
  uint16_t aUdpPort
)

Sets the ephemeral key for a given timeout duration.

Requires OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE.

The ephemeral key can be set when the Border Agent is already running and is not currently connected to any external commissioner (i.e., it is in OT_BORDER_AGENT_STATE_STARTED state). Otherwise OT_ERROR_INVALID_STATE is returned. To terminate active commissioner sessions, use the otBorderAgentDisconnect() API.

The given aKeyString is directly used as the ephemeral PSK (excluding the trailing null \0 character ). The aKeyString length must be between OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH and OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH, inclusive.

Setting the ephemeral key again before a previously set key has timed out will replace the previously set key and reset the timeout.

During the timeout interval, the ephemeral key can be used only once by an external commissioner to establish a connection. After the commissioner disconnects, the ephemeral key is cleared, and the Border Agent reverts to using PSKc. If the timeout expires while a commissioner is still connected, the session will be terminated, and the Border Agent will cease using the ephemeral key and revert to PSKc.

Details
Parameters
[in] aInstance
The OpenThread instance.
[in] aKeyString
The ephemeral key string (used as PSK excluding the trailing null \0 character).
[in] aTimeout
The timeout duration in milliseconds to use the ephemeral key. If zero, the default OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT value will be used. If the given timeout value is larger than OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT, the max value OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT will be used instead.
[in] aUdpPort
The UDP port to use with ephemeral key. If zero, an ephemeral port will be used. otBorderAgentGetUdpPort() will return the current UDP port being used.
Return Values
OT_ERROR_NONE
Successfully set the ephemeral key.
OT_ERROR_INVALID_STATE
Border Agent is not running or it is connected to an external commissioner.
OT_ERROR_INVALID_ARGS
The given aKeyString is not valid (too short or too long).
OT_ERROR_FAILED
Failed to set the key (e.g., could not bind to UDP port).

otBorderAgentSetEphemeralKeyCallback

void otBorderAgentSetEphemeralKeyCallback(
  otInstance *aInstance,
  otBorderAgentEphemeralKeyCallback aCallback,
  void *aContext
)

Sets the callback function used by the Border Agent to notify any changes related to use of ephemeral key.

Requires OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE.

A subsequent call to this function will replace any previously set callback.

Details
Parameters
[in] aInstance
The OpenThread instance.
[in] aCallback
The callback function pointer.
[in] aContext
The arbitrary context to use with callback.

otBorderAgentSetId

otError otBorderAgentSetId(
  otInstance *aInstance,
  const otBorderAgentId *aId
)

Sets the Border Agent ID.

Requires OPENTHREAD_CONFIG_BORDER_AGENT_ID_ENABLE.

The Border Agent ID will be saved in persistent storage and survive reboots. It's required to set the ID only once after factory reset. If the ID has never been set by calling this function, a random ID will be generated and returned when otBorderAgentGetId is called.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aId
A pointer to the Border Agent ID.
Return Values
OT_ERROR_NONE
If successfully set the Border Agent ID.
...
If failed to set the Border Agent ID.
See also:
otBorderAgentGetId

Macros

OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT

 OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT (2 * 60 * 1000u)

Default ephemeral key timeout interval in milliseconds.

OT_BORDER_AGENT_ID_LENGTH

 OT_BORDER_AGENT_ID_LENGTH (16)

The length of Border Agent/Router ID in bytes.

OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH

 OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH (32)

Maximum length of the ephemeral key string.

OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT

 OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT (10 * 60 * 1000u)

Maximum ephemeral key timeout interval in milliseconds.

OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH

 OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH (6)

Minimum length of the ephemeral key string.

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.