openthread: Add header for OpenThread module

* Add header with public API of OpenThread module.
* Add module include directory to Zephyr include directories.
* Use new header in platform implementation.

Signed-off-by: Adrian Gielniewski <adrian.gielniewski@nordicsemi.no>

Author: adigie

modules/openthread/CMakeLists.txt

@@ -279,6 +279,7 @@ zephyr_library_sources(
   openthread.c
 )
 zephyr_library_sources_ifdef(CONFIG_OPENTHREAD_SHELL shell.c)
+zephyr_include_directories(include)
 
 add_subdirectory(platform)
 

modules/openthread/include/openthread.h

@@ -0,0 +1,163 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_MODULES_OPENTHREAD_OPENTHREAD_H_
+#define ZEPHYR_MODULES_OPENTHREAD_OPENTHREAD_H_
+
+#include <zephyr/kernel.h>
+
+#include <openthread/instance.h>
+#include <openthread/message.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief The common callback type for receiving IPv4 (translated by NAT64) and IPv6 datagrams.
+ *
+ * This callback is called when a datagram is received.
+ *
+ * @param message The message to receive.
+ * @param context The context to pass to the callback.
+ */
+typedef void (*openthread_receive_cb)(struct otMessage *message, void *context);
+
+/** OpenThread state change callback  */
+
+/**
+ * @brief OpenThread state change callback structure
+ *
+ * Used to register a callback in the callback list. As many
+ * callbacks as needed can be added as long as each of them
+ * are unique pointers of struct openthread_state_changed_callback.
+ *
+ * @note You may destroy the object only after it is unregistered from the callback list.
+ */
+struct openthread_state_changed_callback {
+	/**
+	 * @brief Callback for notifying configuration or state changes.
+	 *
+	 * @param otCallback OpenThread callback to register.
+	 * See https://openthread.io/reference/group/api-instance#otstatechangedcallback for
+	 * details.
+	 */
+	otStateChangedCallback otCallback;
+
+	/** User data if required */
+	void *user_data;
+
+	/**
+	 * Internally used field for list handling
+	 *  - user must not directly modify
+	 */
+	sys_snode_t node;
+};
+
+/**
+ * @brief Register callbacks that will be called when a certain configuration
+ * or state changes occur within OpenThread.
+ *
+ * @param cb Callback struct to register.
+ */
+int openthread_state_changed_callback_register(struct openthread_state_changed_callback *cb);
+
+/**
+ * @brief Unregister OpenThread configuration or state changed callbacks.
+ *
+ * @param cb Callback struct to unregister.
+ */
+int openthread_state_changed_callback_unregister(struct openthread_state_changed_callback *cb);
+
+/**
+ * @brief Get OpenThread thread identification.
+ */
+k_tid_t openthread_thread_id_get(void);
+
+/**
+ * @brief Get pointer to default OpenThread instance.
+ *
+ * @retval !NULL On success.
+ * @retval NULL  On failure.
+ */
+struct otInstance *openthread_get_default_instance(void);
+
+/**
+ * @brief Initialize the OpenThread module.
+ *
+ * This function:
+ * - Initializes the OpenThread module.
+ * - Creates an OpenThread single instance.
+ * - Starts the shell.
+ * - Enables the UART and NCP HDLC for coprocessor purposes.
+ * - Initializes the NAT64 translator.
+ * - Creates a work queue for the OpenThread module.
+ *
+ * @note This function is automatically called by Zephyr's networking layer.
+ * If you want to initialize the OpenThread independently, call this function
+ * in your application init code.
+ *
+ * @retval 0 On success.
+ * @retval -EIO On failure.
+ */
+int openthread_init(void);
+
+/**
+ * @brief Run the OpenThread network.
+ *
+ * @details Prepares the OpenThread network and enables it.
+ * Depends on active settings: it uses the stored network configuration,
+ * starts the joining procedure or uses the default network configuration.
+ * Additionally, when the device is MTD, it sets the SED mode to properly
+ * attach the network.
+ */
+int openthread_run(void);
+
+/**
+ * @brief Disable the OpenThread network.
+ */
+int openthread_stop(void);
+
+/**
+ * @brief Set the additional callback for receiving packets.
+ *
+ * @details This callback is called once a packet is received and can be
+ * used to inject packets into the Zephyr networking stack.
+ * Setting this callback is optional.
+ *
+ * @param cb Callback to set.
+ * @param context Context to pass to the callback.
+ */
+void openthread_set_receive_cb(openthread_receive_cb cb, void *context);
+
+/**
+ * @brief Lock internal mutex before accessing OpenThread API.
+ *
+ * @details OpenThread API is not thread-safe. Therefore, before accessing any
+ * API function, you need to lock the internal mutex, to prevent the
+ * OpenThread thread from pre-empting the API call.
+ */
+void openthread_mutex_lock(void);
+
+/**
+ * @brief Try to lock internal mutex before accessing OpenThread API.
+ *
+ * @details This function behaves like openthread_mutex_lock(), provided that
+ * the internal mutex is unlocked. Otherwise, it returns a negative value without
+ * waiting.
+ */
+int openthread_mutex_try_lock(void);
+
+/**
+ * @brief Unlock internal mutex after accessing OpenThread API.
+ */
+void openthread_mutex_unlock(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ZEPHYR_MODULES_OPENTHREAD_OPENTHREAD_H_ */

modules/openthread/openthread.c

@@ -17,10 +17,11 @@ LOG_MODULE_REGISTER(net_openthread_platform, CONFIG_OPENTHREAD_PLATFORM_LOG_LEVE
 #include <zephyr/init.h>
 #include <zephyr/version.h>
 #include <zephyr/sys/check.h>
-#include <zephyr/net/openthread.h>
 
 #include "platform/platform-zephyr.h"
 
+#include <openthread.h>
+
 #include <openthread/child_supervision.h>
 #include <openthread/cli.h>
 #include <openthread/ip6.h>

modules/openthread/platform/ble.c

@@ -19,8 +19,7 @@
 #include <zephyr/bluetooth/uuid.h>
 #include <zephyr/bluetooth/gatt.h>
 
-/* Zephyr OpenThread integration Library */
-#include <zephyr/net/openthread.h>
+#include <openthread.h>
 
 /* OpenThread BLE driver API */
 #include <openthread/error.h>
@@ -163,7 +162,7 @@ static void ot_plat_ble_thread(void *unused1, void *unused2, void *unused3)
 			ring_buf_get(&ot_plat_ble_ring_buf, ot_plat_ble_msg_buf, len);
 		}
 
-		openthread_api_mutex_lock(openthread_get_default_context());
+		openthread_mutex_lock();
 
 		if (len <= PLAT_BLE_MSG_DATA_MAX) {
 			/* The packet parameter in otPlatBleGattServerOnWriteRequest is not const.
@@ -178,7 +177,7 @@ static void ot_plat_ble_thread(void *unused1, void *unused2, void *unused3)
 		} else if (len == PLAT_BLE_MSG_DISCONNECT) {
 			otPlatBleGapOnDisconnected(ble_openthread_instance, 0);
 		}
-		openthread_api_mutex_unlock(openthread_get_default_context());
+		openthread_mutex_unlock();
 	}
 }
 

modules/openthread/shell.c

@@ -6,11 +6,12 @@
 
 #include <zephyr/kernel.h>
 #include <stdio.h>
-#include <zephyr/net/openthread.h>
 #include <zephyr/sys/printk.h>
 #include <zephyr/shell/shell.h>
 #include <zephyr/shell/shell_uart.h>
 
+#include <openthread.h>
+
 #include <openthread/cli.h>
 #include <openthread/instance.h>