openthread: add libraries based on commit 57ef721

Update OpenThread libraries with newest commit Signed-off-by: Nordic Builder <pylon@nordicsemi.no>
nrfconnect · Oct 24, 2023 · 78cc07e · 78cc07e
1 parent 363f1bb
commit 78cc07e
Show file tree

Hide file tree

Showing 98 changed files with 3,246 additions and 1,383 deletions.
diff --git a/openthread/include/openthread-system.h b/openthread/include/openthread-system.h
@@ -42,7 +42,7 @@ extern "C" {
 #endif
 
 /**
- * This function performs all platform-specific initialization of OpenThread's drivers.
+ * Performs all platform-specific initialization of OpenThread's drivers.
  *
  * @note This function is not called by the OpenThread library. Instead, the system/RTOS should call this function
  *       when initialization of OpenThread's drivers is most appropriate.
@@ -54,7 +54,7 @@ extern "C" {
 void otSysInit(int argc, char *argv[]);
 
 /**
- * This function performs all platform-specific deinitialization for OpenThread's drivers.
+ * Performs all platform-specific deinitialization for OpenThread's drivers.
  *
  * @note This function is not called by the OpenThread library. Instead, the system/RTOS should call this function
  *       when deinitialization of OpenThread's drivers is most appropriate.
@@ -63,7 +63,7 @@ void otSysInit(int argc, char *argv[]);
 void otSysDeinit(void);
 
 /**
- * This function returns true if a pseudo-reset was requested.
+ * Returns true if a pseudo-reset was requested.
  *
  * In such a case, the main loop should shut down and re-initialize the OpenThread instance.
  *
@@ -74,7 +74,7 @@ void otSysDeinit(void);
 bool otSysPseudoResetWasRequested(void);
 
 /**
- * This function performs all platform-specific processing for OpenThread's example applications.
+ * Performs all platform-specific processing for OpenThread's example applications.
  *
  * @note This function is not called by the OpenThread library. Instead, the system/RTOS should call this function
  *       in the main loop when processing OpenThread's drivers is most appropriate.
@@ -85,7 +85,7 @@ bool otSysPseudoResetWasRequested(void);
 void otSysProcessDrivers(otInstance *aInstance);
 
 /**
- * This function is called whenever platform drivers needs processing.
+ * Is called whenever platform drivers needs processing.
  *
  * @note This function is not handled by the OpenThread library. Instead, the system/RTOS should handle this function
  *       and schedule a call to `otSysProcessDrivers()`.

diff --git a/openthread/include/openthread/backbone_router.h b/openthread/include/openthread/backbone_router.h
@@ -52,7 +52,7 @@ extern "C" {
  */
 
 /**
- * This structure represents Backbone Router configuration.
+ * Represents Backbone Router configuration.
  *
  */
 typedef struct otBackboneRouterConfig
@@ -64,7 +64,7 @@ typedef struct otBackboneRouterConfig
 } otBackboneRouterConfig;
 
 /**
- * This function gets the Primary Backbone Router information in the Thread Network.
+ * Gets the Primary Backbone Router information in the Thread Network.
  *
  * @param[in]   aInstance            A pointer to an OpenThread instance.
  * @param[out]  aConfig              A pointer to where to put Primary Backbone Router information.

diff --git a/openthread/include/openthread/backbone_router_ftd.h b/openthread/include/openthread/backbone_router_ftd.h
@@ -161,7 +161,7 @@ otError otBackboneRouterSetConfig(otInstance *aInstance, const otBackboneRouterC
 otError otBackboneRouterRegister(otInstance *aInstance);
 
 /**
- * This method returns the Backbone Router registration jitter value.
+ * Returns the Backbone Router registration jitter value.
  *
  * @returns The Backbone Router registration jitter value.
  *
@@ -171,7 +171,7 @@ otError otBackboneRouterRegister(otInstance *aInstance);
 uint8_t otBackboneRouterGetRegistrationJitter(otInstance *aInstance);
 
 /**
- * This method sets the Backbone Router registration jitter value.
+ * Sets the Backbone Router registration jitter value.
  *
  * @param[in]  aJitter the Backbone Router registration jitter value to set.
  *
@@ -181,7 +181,7 @@ uint8_t otBackboneRouterGetRegistrationJitter(otInstance *aInstance);
 void otBackboneRouterSetRegistrationJitter(otInstance *aInstance, uint8_t aJitter);
 
 /**
- * This method gets the local Domain Prefix configuration.
+ * Gets the local Domain Prefix configuration.
  *
  * @param[in]  aInstance A pointer to an OpenThread instance.
  * @param[out] aConfig   A pointer to the Domain Prefix configuration.
@@ -193,7 +193,7 @@ void otBackboneRouterSetRegistrationJitter(otInstance *aInstance, uint8_t aJitte
 otError otBackboneRouterGetDomainPrefix(otInstance *aInstance, otBorderRouterConfig *aConfig);
 
 /**
- * This method configures response status for next DUA registration.
+ * Configures response status for next DUA registration.
  *
  * Note: available only when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled.
  *       Only used for test and certification.
@@ -235,7 +235,7 @@ typedef enum
 } otBackboneRouterMulticastListenerEvent;
 
 /**
- * This function pointer is called whenever the Multicast Listeners change.
+ * Pointer is called whenever the Multicast Listeners change.
  *
  * @param[in] aContext  The user context pointer.
  * @param[in] aEvent    The Multicast Listener event.
@@ -247,7 +247,7 @@ typedef void (*otBackboneRouterMulticastListenerCallback)(void
                                                           const otIp6Address                    *aAddress);
 
 /**
- * This method sets the Backbone Router Multicast Listener callback.
+ * Sets the Backbone Router Multicast Listener callback.
  *
  * @param[in] aInstance  A pointer to an OpenThread instance.
  * @param[in] aCallback  A pointer to the Multicast Listener callback.
@@ -302,7 +302,7 @@ otError otBackboneRouterMulticastListenerAdd(otInstance *aInstance, const otIp6A
 typedef uint16_t otBackboneRouterMulticastListenerIterator; ///< Used to iterate through Multicast Listeners.
 
 /**
- * This structure represents a Backbone Router Multicast Listener info.
+ * Represents a Backbone Router Multicast Listener info.
  *
  */
 typedef struct otBackboneRouterMulticastListenerInfo
@@ -312,7 +312,7 @@ typedef struct otBackboneRouterMulticastListenerInfo
 } otBackboneRouterMulticastListenerInfo;
 
 /**
- * This function gets the next Multicast Listener info (using an iterator).
+ * Gets the next Multicast Listener info (using an iterator).
  *
  * @param[in]      aInstance      A pointer to an OpenThread instance.
  * @param[in,out]  aIterator      A pointer to the iterator. On success the iterator will be updated to point to next
@@ -346,7 +346,7 @@ typedef enum
 } otBackboneRouterNdProxyEvent;
 
 /**
- * This function pointer is called whenever the Nd Proxy changed.
+ * Pointer is called whenever the Nd Proxy changed.
  *
  * @param[in] aContext  The user context pointer.
  * @param[in] aEvent    The ND Proxy event.
@@ -359,7 +359,7 @@ typedef void (*otBackboneRouterNdProxyCallback)(void                        *aCo
                                                 const otIp6Address          *aDua);
 
 /**
- * This method sets the Backbone Router ND Proxy callback.
+ * Sets the Backbone Router ND Proxy callback.
  *
  * @param[in] aInstance  A pointer to an OpenThread instance.
  * @param[in] aCallback  A pointer to the ND Proxy callback.
@@ -382,7 +382,7 @@ typedef struct otBackboneRouterNdProxyInfo
 } otBackboneRouterNdProxyInfo;
 
 /**
- * This method gets the Backbone Router ND Proxy info.
+ * Gets the Backbone Router ND Proxy info.
  *
  * @param[in]   aInstance     A pointer to an OpenThread instance.
  * @param[in]   aDua          The Domain Unicast Address.
@@ -408,7 +408,7 @@ typedef enum
 } otBackboneRouterDomainPrefixEvent;
 
 /**
- * This function pointer is called whenever the Domain Prefix changed.
+ * Pointer is called whenever the Domain Prefix changed.
  *
  * @param[in] aContext       The user context pointer.
  * @param[in] aEvent         The Domain Prefix event.
@@ -419,7 +419,7 @@ typedef void (*otBackboneRouterDomainPrefixCallback)(void
                                                      otBackboneRouterDomainPrefixEvent aEvent,
                                                      const otIp6Prefix                *aDomainPrefix);
 /**
- * This method sets the Backbone Router Domain Prefix callback.
+ * Sets the Backbone Router Domain Prefix callback.
  *
  * @param[in] aInstance  A pointer to an OpenThread instance.
  * @param[in] aCallback  A pointer to the Domain Prefix callback.

diff --git a/openthread/include/openthread/border_agent.h b/openthread/include/openthread/border_agent.h
@@ -52,7 +52,31 @@ extern "C" {
  */
 
 /**
- * This enumeration defines the Border Agent state.
+ * The length of Border Agent/Router ID in bytes.
+ *
+ */
+#define OT_BORDER_AGENT_ID_LENGTH (16)
+
+/**
+ * @struct otBorderAgentId
+ *
+ * Represents a Border Agent ID.
+ *
+ */
+OT_TOOL_PACKED_BEGIN
+struct otBorderAgentId
+{
+    uint8_t mId[OT_BORDER_AGENT_ID_LENGTH];
+} OT_TOOL_PACKED_END;
+
+/**
+ * Represents a Border Agent ID.
+ *
+ */
+typedef struct otBorderAgentId otBorderAgentId;
+
+/**
+ * Defines the Border Agent state.
  *
  */
 typedef enum otBorderAgentState
@@ -82,6 +106,42 @@ otBorderAgentState otBorderAgentGetState(otInstance *aInstance);
  */
 uint16_t otBorderAgentGetUdpPort(otInstance *aInstance);
 
+/**
+ * Gets the randomly generated Border Agent ID.
+ *
+ * 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.
+ *
+ * @param[in]    aInstance  A pointer to an OpenThread instance.
+ * @param[out]   aId        A pointer to buffer to receive the ID.
+ *
+ * @retval OT_ERROR_NONE  If successfully retrieved the Border Agent ID.
+ * @retval ...            If failed to retrieve the Border Agent ID.
+ *
+ * @sa otBorderAgentSetId
+ *
+ */
+otError otBorderAgentGetId(otInstance *aInstance, otBorderAgentId *aId);
+
+/**
+ * Sets the Border Agent ID.
+ *
+ * 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.
+ *
+ * @param[in]    aInstance  A pointer to an OpenThread instance.
+ * @param[out]   aId        A pointer to the Border Agent ID.
+ *
+ * @retval OT_ERROR_NONE  If successfully set the Border Agent ID.
+ * @retval ...            If failed to set the Border Agent ID.
+ *
+ * @sa otBorderAgentGetId
+ *
+ */
+otError otBorderAgentSetId(otInstance *aInstance, const otBorderAgentId *aId);
+
 /**
  * @}
  *

diff --git a/openthread/include/openthread/border_router.h b/openthread/include/openthread/border_router.h
@@ -54,7 +54,7 @@ extern "C" {
  */
 
 /**
- * This method provides a full or stable copy of the local Thread Network Data.
+ * Provides a full or stable copy of the local Thread Network Data.
  *
  * @param[in]      aInstance    A pointer to an OpenThread instance.
  * @param[in]      aStable      TRUE when copying the stable version, FALSE when copying the full version.
@@ -94,7 +94,7 @@ otError otBorderRouterAddOnMeshPrefix(otInstance *aInstance, const otBorderRoute
 otError otBorderRouterRemoveOnMeshPrefix(otInstance *aInstance, const otIp6Prefix *aPrefix);
 
 /**
- * This function gets the next On Mesh Prefix in the local Network Data.
+ * Gets the next On Mesh Prefix in the local Network Data.
  *
  * @param[in]      aInstance  A pointer to an OpenThread instance.
  * @param[in,out]  aIterator  A pointer to the Network Data iterator context. To get the first on-mesh entry
@@ -139,7 +139,7 @@ otError otBorderRouterAddRoute(otInstance *aInstance, const otExternalRouteConfi
 otError otBorderRouterRemoveRoute(otInstance *aInstance, const otIp6Prefix *aPrefix);
 
 /**
- * This function gets the next external route in the local Network Data.
+ * Gets the next external route in the local Network Data.
  *
  * @param[in]      aInstance  A pointer to an OpenThread instance.
  * @param[in,out]  aIterator  A pointer to the Network Data iterator context. To get the first external route entry
@@ -168,6 +168,35 @@ otError otBorderRouterGetNextRoute(otInstance            *aInstance,
  */
 otError otBorderRouterRegister(otInstance *aInstance);
 
+/**
+ * Function pointer callback which is invoked when Network Data (local or leader) gets full.
+ *
+ * @param[in] aContext A pointer to arbitrary context information.
+ *
+ */
+typedef void (*otBorderRouterNetDataFullCallback)(void *aContext);
+
+/**
+ * Sets the callback to indicate when Network Data gets full.
+ *
+ * Requires `OPENTHREAD_CONFIG_BORDER_ROUTER_SIGNAL_NETWORK_DATA_FULL`.
+ *
+ * The callback is invoked whenever:
+ * - The device is acting as a leader and receives a Network Data registration from a Border Router (BR) that it cannot
+ *   add to Network Data (running out of space).
+ * - The device is acting as a BR and new entries cannot be added to its local Network Data.
+ * - The device is acting as a BR and tries to register its local Network Data entries with the leader, but determines
+ *    that its local entries will not fit.
+ *
+ * @param[in]  aInstance    A pointer to an OpenThread instance.
+ * @param[in]  aCallback    The callback.
+ * @param[in]  aContext     A pointer to arbitrary context information used with @p aCallback.
+ *
+ */
+void otBorderRouterSetNetDataFullCallback(otInstance                       *aInstance,
+                                          otBorderRouterNetDataFullCallback aCallback,
+                                          void                             *aContext);
+
 /**
  * @}
  *