Border Agent#

otBorderAgentState#

otBorderAgentState

Defines the Border Agent state.

otBorderAgentId#

typedef struct otBorderAgentId otBorderAgentId

Represents a Border Agent Identifier.

otBorderAgentState#

typedef enum otBorderAgentState otBorderAgentState

Defines the Border Agent state.

otBorderAgentCounters#

typedef struct otBorderAgentCounters otBorderAgentCounters

otBorderAgentEphemeralKeyCallback#

typedef void(* otBorderAgentEphemeralKeyCallback) (void *aContext) )(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.

otBorderAgentGetCounters#

const otBorderAgentCounters * otBorderAgentGetCounters (otInstance * aInstance)

Gets the counters of the Thread Border Agent.

Returns

• A pointer to the Border Agent counters.

otBorderAgentGetState#

otBorderAgentState otBorderAgentGetState (otInstance * aInstance)

Gets the otBorderAgentState of the Thread Border Agent role.

Returns

• The current otBorderAgentState of the Border Agent.

otBorderAgentGetUdpPort#

uint16_t otBorderAgentGetUdpPort (otInstance * aInstance)

Gets the UDP port of the Thread Border Agent service.

Returns

• UDP port of the Border Agent.

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.

See Also

• otBorderAgentSetId

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.

See Also

• otBorderAgentGetId

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.

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.

otBorderAgentIsEphemeralKeyActive#

bool otBorderAgentIsEphemeralKeyActive (otInstance * aInstance)

Indicates whether or not an ephemeral key is currently active.

Requires OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE.

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.

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.

OT_BORDER_AGENT_ID_LENGTH#

#define OT_BORDER_AGENT_ID_LENGTH

(16)

The length of Border Agent/Router ID in bytes.

OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH#

#define OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH

(6)

Minimum length of the ephemeral key string.

OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH#

#define OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH

(32)

Maximum length of the ephemeral key string.

OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT#

#define OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT

(2 * 60 * 1000u)

Default ephemeral key timeout interval in milliseconds.

OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT#

#define OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT

(10 * 60 * 1000u)

Maximum ephemeral key timeout interval in milliseconds.