openthread: rpc: support otMessageRegisterTxCallback

Implement serialization of otMessageRegisterTxCallback() API
that allows to register a callback invoked when a message
has been transmitted successfully or it has been dropped.

Add ot_rpc_callback module to avoid passing the raw function
pointer and context to the peer device.

Implement "ot udp txcallback enable|disable" shell command
to enable testing this feature with "ot udp send" command.

Signed-off-by: Damian Krolik <[email protected]>

Author: Damian-Nordic

doc/nrf/libraries/networking/ot_rpc.rst

@@ -140,6 +140,7 @@ OpenThread RPC currently supports the serialization of the following OpenThread
 * :c:func:`otMessageGetOffset`
 * :c:func:`otMessageGetThreadLinkInfo`
 * :c:func:`otMessageRead`
+* :c:func:`otMessageRegisterTxCallback`
 * :c:func:`otNetDataGet`
 * :c:func:`otNetDataGetNextOnMeshPrefix`
 * :c:func:`otNetDataGetNextService`

samples/nrf_rpc/protocols_serialization/client/src/ot_shell.c

@@ -53,6 +53,7 @@ struct srp_service {
 static bool ot_cli_is_initialized;
 static otUdpSocket udp_socket;
 static const char udp_payload[] = "Hello OpenThread World!";
+static bool udp_tx_callback_enabled;
 static char srp_client_host_name[OT_DNS_MAX_NAME_SIZE];
 static struct srp_service services[SERVICE_NUM];
 
@@ -2021,6 +2022,13 @@ static int cmd_udp_connect(const struct shell *sh, size_t argc, char *argv[])
 	return ot_cli_command_exec(cmd_udp_connect_impl, sh, argc, argv);
 }
 
+static void udp_tx_callback(const otMessage *msg, otError error, void *ctx)
+{
+	struct shell *sh = ctx;
+
+	shell_print(sh, "UDP tx result: %d", error);
+}
+
 static otError cmd_udp_send_impl(const struct shell *sh, size_t argc, char *argv[])
 {
 	otError error;
@@ -2060,6 +2068,10 @@ static otError cmd_udp_send_impl(const struct shell *sh, size_t argc, char *argv
 		return error;
 	}
 
+	if (udp_tx_callback_enabled) {
+		otMessageRegisterTxCallback(msg, udp_tx_callback, (void *)sh);
+	}
+
 	error = otUdpSend(NULL, &udp_socket, msg, &msg_info);
 	if (error != OT_ERROR_NONE) {
 		otMessageFree(msg);
@@ -2083,12 +2095,34 @@ static int cmd_udp_close(const struct shell *sh, size_t argc, char *argv[])
 	return ot_cli_command_exec(cmd_udp_close_impl, sh, argc, argv);
 }
 
+static otError cmd_udp_txcallback_impl(const struct shell *sh, size_t argc, char *argv[])
+{
+	if (argc == 1) {
+		shell_print(sh, "%s", udp_tx_callback_enabled ? "enabled" : "disabled");
+	} else if (strcmp(argv[1], "enable") == 0) {
+		udp_tx_callback_enabled = true;
+	} else if (strcmp(argv[1], "disable") == 0) {
+		udp_tx_callback_enabled = false;
+	} else {
+		return OT_ERROR_INVALID_ARGS;
+	}
+
+	return OT_ERROR_NONE;
+}
+
+static int cmd_udp_txcallback(const struct shell *sh, size_t argc, char *argv[])
+{
+	return ot_cli_command_exec(cmd_udp_txcallback_impl, sh, argc, argv);
+}
+
 SHELL_STATIC_SUBCMD_SET_CREATE(
 	udp_cmds, SHELL_CMD_ARG(open, NULL, "Open socket", cmd_udp_open, 1, 0),
 	SHELL_CMD_ARG(bind, NULL, "Bind socket [-u|-b] <addr> <port>", cmd_udp_bind, 3, 1),
 	SHELL_CMD_ARG(connect, NULL, "Connect socket <addr> <port>", cmd_udp_connect, 3, 0),
 	SHELL_CMD_ARG(send, NULL, "Send message [addr port] <message>", cmd_udp_send, 2, 2),
-	SHELL_CMD_ARG(close, NULL, "Close socket", cmd_udp_close, 1, 0), SHELL_SUBCMD_SET_END);
+	SHELL_CMD_ARG(close, NULL, "Close socket", cmd_udp_close, 1, 0),
+	SHELL_CMD_ARG(txcallback, NULL, "Enable/disable tx callback", cmd_udp_txcallback, 1, 1),
+	SHELL_SUBCMD_SET_END);
 
 static otError cmd_channel_impl(const struct shell *sh, size_t argc, char *argv[])
 {

subsys/net/openthread/rpc/Kconfig

@@ -65,6 +65,10 @@ config OPENTHREAD_RPC_CLIENT_NUM_SENT_COAP_REQUESTS
 	  Defines the number of slots for storing a callback along with its context
 	  for ongoing CoAP requests awaiting a response.
 
+config OPENTHREAD_RPC_CLIENT_NUM_TX_CALLBACKS
+	int "Maximum number of registered message TX callbacks"
+	default 8
+
 config OPENTHREAD_RPC_CLIENT_RADIO_TIME_REFRESH_PERIOD
 	int "Radio time sync period [s]"
 	default 30

subsys/net/openthread/rpc/client/ot_rpc_message.c

@@ -5,9 +5,11 @@
  */
 
 #include <nrf_rpc/nrf_rpc_serialize.h>
+#include <ot_rpc_callback.h>
+#include <ot_rpc_common.h>
 #include <ot_rpc_ids.h>
+#include <ot_rpc_lock.h>
 #include <ot_rpc_types.h>
-#include <ot_rpc_common.h>
 
 #include <nrf_rpc_cbor.h>
 
@@ -16,6 +18,9 @@
 
 #include <string.h>
 
+OT_RPC_CALLBACK_TABLE_DEFINE(tx_cb, otMessageTxCallback,
+			     CONFIG_OPENTHREAD_RPC_CLIENT_NUM_TX_CALLBACKS);
+
 otError otMessageAppend(otMessage *aMessage, const void *aBuf, uint16_t aLength)
 {
 	struct nrf_rpc_cbor_ctx ctx;
@@ -177,3 +182,59 @@ otError otMessageGetThreadLinkInfo(const otMessage *aMessage, otThreadLinkInfo *
 
 	return error;
 }
+
+void otMessageRegisterTxCallback(otMessage *aMessage, otMessageTxCallback aCallback, void *aContext)
+{
+	ot_rpc_res_tab_key key = (ot_rpc_res_tab_key)aMessage;
+	ot_rpc_callback_id cb_id;
+	struct nrf_rpc_cbor_ctx ctx;
+
+	cb_id = ot_rpc_tx_cb_alloc(aCallback, aContext);
+
+	if (aCallback != NULL && cb_id == OT_RPC_CALLBACK_ID_NULL) {
+		/* Failed to allocate a callback entry. */
+		nrf_rpc_err(-ENOMEM, NRF_RPC_ERR_SRC_SEND, &ot_group,
+			    OT_RPC_CMD_MESSAGE_REGISTER_TX_CALLBACK, NRF_RPC_PACKET_TYPE_CMD);
+		return;
+	}
+
+	NRF_RPC_CBOR_ALLOC(&ot_group, ctx, 2 + sizeof(key) + sizeof(cb_id));
+	nrf_rpc_encode_uint(&ctx, key);
+	nrf_rpc_encode_uint(&ctx, cb_id);
+	nrf_rpc_cbor_cmd_no_err(&ot_group, OT_RPC_CMD_MESSAGE_REGISTER_TX_CALLBACK, &ctx,
+				nrf_rpc_rsp_decode_void, NULL);
+}
+
+static void ot_rpc_cmd_message_tx_cb(const struct nrf_rpc_group *group,
+				     struct nrf_rpc_cbor_ctx *ctx, void *handler_data)
+{
+	ot_rpc_callback_id cb_id;
+	ot_rpc_res_tab_key msg_key;
+	otError error;
+	otMessageTxCallback cb;
+	void *context;
+
+	cb_id = nrf_rpc_decode_uint(ctx);
+	msg_key = nrf_rpc_decode_uint(ctx);
+	error = nrf_rpc_decode_uint(ctx);
+
+	if (!nrf_rpc_decoding_done_and_check(group, ctx)) {
+		ot_rpc_report_cmd_decoding_error(OT_RPC_CMD_MESSAGE_TX_CB);
+		return;
+	}
+
+	ot_rpc_mutex_lock();
+
+	cb = ot_rpc_tx_cb_get(cb_id, &context);
+
+	if (cb != NULL) {
+		ot_rpc_tx_cb_free(cb_id);
+		cb((const otMessage *)msg_key, error, context);
+	}
+
+	ot_rpc_mutex_unlock();
+	nrf_rpc_rsp_send_void(group);
+}
+
+NRF_RPC_CBOR_CMD_DECODER(ot_group, ot_rpc_cmd_message_tx_cb, OT_RPC_CMD_MESSAGE_TX_CB,
+			 ot_rpc_cmd_message_tx_cb, NULL);

subsys/net/openthread/rpc/common/CMakeLists.txt

@@ -7,6 +7,7 @@
 zephyr_library()
 
 zephyr_library_sources(
+  ot_rpc_callback.c
   ot_rpc_common.c
   ot_rpc_group.c
 )

subsys/net/openthread/rpc/common/ot_rpc_callback.c

@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+#include "ot_rpc_callback.h"
+
+ot_rpc_callback_id ot_rpc_callback_alloc(struct ot_rpc_callback *table, size_t table_size,
+					 ot_rpc_callback_func func, void *context)
+{
+	struct ot_rpc_callback *cb;
+	ot_rpc_callback_id free_id = OT_RPC_CALLBACK_ID_NULL;
+
+	if (func == NULL) {
+		return OT_RPC_CALLBACK_ID_NULL;
+	}
+
+	for (ot_rpc_callback_id id = 1; id <= table_size; id++) {
+		cb = &table[id - 1];
+
+		/* Avoid adding the same function and context twice - reuse the previous entry. */
+		if (cb->func == func && cb->context == context) {
+			return id;
+		}
+
+		if (free_id == OT_RPC_CALLBACK_ID_NULL && cb->func == NULL) {
+			free_id = id;
+		}
+	}
+
+	if (free_id != OT_RPC_CALLBACK_ID_NULL) {
+		cb = &table[free_id - 1];
+		cb->func = func;
+		cb->context = context;
+	}
+
+	return free_id;
+}
+
+ot_rpc_callback_func ot_rpc_callback_get(struct ot_rpc_callback *table, size_t table_size,
+					 ot_rpc_callback_id id, void **context_out)
+{
+	struct ot_rpc_callback *cb;
+
+	if (id == OT_RPC_CALLBACK_ID_NULL || id > table_size) {
+		return NULL;
+	}
+
+	cb = &table[id - 1];
+	*context_out = cb->context;
+
+	return cb->func;
+}
+
+void ot_rpc_callback_free(struct ot_rpc_callback *table, size_t table_size, ot_rpc_callback_id id)
+{
+	struct ot_rpc_callback *cb;
+
+	if (id == OT_RPC_CALLBACK_ID_NULL || id > table_size) {
+		return;
+	}
+
+	cb = &table[id - 1];
+	cb->func = NULL;
+	cb->context = NULL;
+}

subsys/net/openthread/rpc/common/ot_rpc_callback.h

@@ -0,0 +1,85 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+#ifndef OT_RPC_CALLBACK_H
+#define OT_RPC_CALLBACK_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+#ifndef ARRAY_SIZE
+#define ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0]))
+#endif
+
+/**
+ * @brief Generic function pointer type.
+ *
+ * A function pointer type that is guaranteed to store a pointer to function of any type.
+ */
+typedef void (*ot_rpc_callback_func)(void);
+
+/**
+ * @brief Structure to hold a function pointer of any type and its related context.
+ */
+struct ot_rpc_callback {
+	ot_rpc_callback_func func;
+	void *context;
+};
+
+/**
+ * @brief OpenThread RPC callback ID.
+ *
+ * A portable representation of a callback and its related context that can be passed to a remote
+ * device during remote procedure calls.
+ */
+typedef uint32_t ot_rpc_callback_id;
+
+enum {
+	OT_RPC_CALLBACK_ID_NULL = 0,
+};
+
+ot_rpc_callback_id ot_rpc_callback_alloc(struct ot_rpc_callback *table, size_t table_size,
+					 ot_rpc_callback_func func, void *context);
+ot_rpc_callback_func ot_rpc_callback_get(struct ot_rpc_callback *table, size_t table_size,
+					 ot_rpc_callback_id id, void **context_out);
+void ot_rpc_callback_free(struct ot_rpc_callback *table, size_t table_size, ot_rpc_callback_id id);
+
+/**
+ * @brief Defines a named callback table with the specified function pointer type and size.
+ *
+ * This creates an array of callback entries and provides type-safe functions for managing and
+ * accessing the callback table:
+ *
+ * @code
+ * ot_rpc_callback_id ot_rpc_NAME_alloc(TYPE func, void *context);
+ * TYPE ot_rpc_NAME_get(ot_rpc_callback_id id, void **context_out);
+ * void ot_rpc_NAME_free(ot_rpc_callback_id id);
+ * @endcode
+ *
+ * The callback table enables the local device to register a callback on the peer device without
+ * sending the actual raw function pointer and context. Instead, the sender stores the raw function
+ * pointer and context in a local callback table and sends only the identifier of the allocated
+ * entry.
+ * This approach enhances portability and reduces the risk of errors in callback handling.
+ */
+#define OT_RPC_CALLBACK_TABLE_DEFINE(name, type, size)                                             \
+	static struct ot_rpc_callback name[size];                                                  \
+                                                                                                   \
+	static inline ot_rpc_callback_id ot_rpc_##name##_alloc(type func, void *context)           \
+	{                                                                                          \
+		return ot_rpc_callback_alloc(name, ARRAY_SIZE(name), (ot_rpc_callback_func)func,   \
+					     context);                                             \
+	}                                                                                          \
+	static inline type ot_rpc_##name##_get(ot_rpc_callback_id id, void **context_out)          \
+	{                                                                                          \
+		return (type)ot_rpc_callback_get(name, ARRAY_SIZE(name), id, context_out);         \
+	}                                                                                          \
+	static inline void ot_rpc_##name##_free(ot_rpc_callback_id id)                             \
+	{                                                                                          \
+		ot_rpc_callback_free(name, ARRAY_SIZE(name), id);                                  \
+	}
+
+#endif /* OT_RPC_CALLBACK_H */

subsys/net/openthread/rpc/common/ot_rpc_ids.h

@@ -25,6 +25,7 @@ enum ot_rpc_cmd_client {
 	OT_RPC_CMD_DNS_ADDRESS_RESPONSE_CB,
 	OT_RPC_CMD_DNS_BROWSE_RESPONSE_CB,
 	OT_RPC_CMD_DNS_SERVICE_RESPONSE_CB,
+	OT_RPC_CMD_MESSAGE_TX_CB,
 };
 
 /** @brief Command IDs accepted by the OpenThread over RPC server.
@@ -106,6 +107,7 @@ enum ot_rpc_cmd_server {
 	OT_RPC_CMD_MESSAGE_GET_OFFSET,
 	OT_RPC_CMD_MESSAGE_READ,
 	OT_RPC_CMD_MESSAGE_GET_THREAD_LINK_INFO,
+	OT_RPC_CMD_MESSAGE_REGISTER_TX_CALLBACK,
 	OT_RPC_CMD_UDP_OPEN,
 	OT_RPC_CMD_UDP_IS_OPEN,
 	OT_RPC_CMD_UDP_SEND,

subsys/net/openthread/rpc/server/ot_rpc_dataset.c

@@ -5,7 +5,6 @@
  */
 
 #include <nrf_rpc/nrf_rpc_serialize.h>
-#include <nrf_rpc/nrf_rpc_cbkproxy.h>
 #include <ot_rpc_ids.h>
 #include <ot_rpc_types.h>
 #include <ot_rpc_common.h>