Border Agent
This module includes functions for the Thread Border Agent role.
Summary
Enumerations |
|
---|---|
otBorderAgentState{
|
enum Defines the Border Agent state. |
Typedefs |
|
---|---|
otBorderAgentCounters
|
typedefstruct otBorderAgentCounters
|
otBorderAgentEphemeralKeyCallback)(void *aContext)
|
typedefvoid(*
Callback function pointer to signal changes related to the Border Agent's ephemeral key. |
otBorderAgentId
|
typedefstruct otBorderAgentId
Represents a Border Agent Identifier. |
otBorderAgentState
|
typedefenum otBorderAgentState
Defines the Border Agent state. |
Functions |
|
---|---|
otBorderAgentClearEphemeralKey(otInstance *aInstance)
|
void
Cancels the ephemeral key that is in use.
|
otBorderAgentGetCounters(otInstance *aInstance)
|
const otBorderAgentCounters *
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
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.
- 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.
- A direct call to
Any OpenThread API, including otBorderAgent
APIs, can be safely called from this callback.
Details | |||
---|---|---|---|
Parameters |
|
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.
Details | |||
---|---|---|---|
Parameters |
|
otBorderAgentGetCounters
const otBorderAgentCounters * otBorderAgentGetCounters( otInstance *aInstance )
Gets the counters of the Thread Border Agent.
Details | |||
---|---|---|---|
Parameters |
|
||
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 |
|
||||
Return Values |
|
otBorderAgentSetId
otBorderAgentGetState
otBorderAgentState otBorderAgentGetState( otInstance *aInstance )
Gets the otBorderAgentState of the Thread Border Agent role.
Details | |||
---|---|---|---|
Parameters |
|
||
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 |
|
||
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 |
|
||||
Return Values |
|
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.
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 |
|
||||||||
Return Values |
|
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 |
|
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 |
|
||||
Return Values |
|
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.