net/unicoap: Unified and Modular CoAP Stack: Minimal Client (pt 3) by carl-tud · Pull Request #22266 · RIOT-OS/RIOT

carl-tud · 2026-05-09T23:31:27Z

This PR is the third in a series to introduce unicoap, a unified and modular CoAP implementation for RIOT. An overview of all PRs related to unicoap is presented in #21389, including reasons why unicoap is needed and a performance analysis.

What does this PR include?

Basic client functionality, including URI support
A sample client shell application
Structured documentation, including a tutorial from the first line of code to running the example and testing it using the included server script

The new API is more flexible. CoAP resource addresses are abstracted into a unicoap_destination_t structure and transport-specific settings are controlled by flags. For example, this is how you can send a request to a

// Define asynchronous response handler (blocking version is also available)
static int handle_response(
  const unicoap_message_t* response, const unicoap_aux_t* aux,
  int error, void* arg
) {
  if (error) {
    // handle error
  }
  printf("status=%s (%zu bytes)\n", unicoap_label_from_status(response->status, response->payload_size);
  return 0;
}

int main(void) {
  // Allocate request message
  unicoap_message_t request;
  // Init as request. Multiple initialisers exist. This one accepts a null-terminated C (UTF-8) string.
  unicoap_request_init_string(&request, UNICOAP_METHOD_PUT, "nack? quack? quack-ack, nack!");
  
  // Next, set the destination. Full URIs are supported (including address literals and zones). 
  // You can also pass a `sock_tl_ep` if you like using `unicoap_destination_endpoint`.  This API leaves 
  // room for SVCB (Service Binding) records in the DNS.
  unicoap_destination_t destination = 
    unicoap_destination_uri("coap://example.org:10815/hello?name=duck&hungry=1");
  
  // Finally, send. The RELIABLE flag instruct unicoap to send confirmable messages when 
  // communicating over UDP or DTLS, abstracting transport-specific message formats.
  int res = unicoap_send_request_async(&request, &destination, 
                   handle_response, UNICOAP_CLIENT_FLAG_RELIABLE, NULL);
  // handle errors
  return 0.
}

I'll organise the monolithic commit into multiple structured commits once this has passed review, and rebase this PR onto #21582 once merged.

LasseRosenow · 2026-05-11T11:35:38Z

Can you make this a guide? (https://github.com/RIOT-OS/RIOT/tree/master/doc/guides/c_tutorials)

mguetschow

Have just started looking at the provided example :)

mguetschow · 2026-05-11T16:02:33Z

@@ -0,0 +1,75 @@
+# Default Makefile, for simple unicoap server sample application


Suggested change

# Default Makefile, for simple unicoap server sample application

# Default Makefile, for simple unicoap client sample application

mguetschow · 2026-05-11T16:04:20Z

@@ -0,0 +1,30 @@
+# Sample Client Application With `unicoap`
+
+This a sample application demonstrating how you send CoAP requests using `unicoap`,


Suggested change

This a sample application demonstrating how you send CoAP requests using `unicoap`,

This is a sample application demonstrating how you send CoAP requests using `unicoap`,

mguetschow · 2026-05-11T16:06:08Z

+python3 server.py"
+```
+
+to send a CoAP request through the tap interface to the CoAP server.


Suggested change

to send a CoAP request through the tap interface to the CoAP server.

Now, you can send CoAP requests from RIOT through the tap interface to the CoAP server.

Maybe you also want to briefly mention which endpoints the server supports?

mguetschow · 2026-05-11T16:06:36Z

+BOARD=native make flash term
+```
+This will compile and run the application.
+The application will print a network-layer address.


Suggested change

The application will print a network-layer address.

Not really relevant on the client side I'd say?

mguetschow · 2026-05-11T16:14:29Z

+#if IS_USED(MODULE_UNICOAP_DRIVER_DTLS)
+# include "net/sock/dtls/creds.h"
+# include "net/credman.h"
+# include "net/dsm.h"
+# include "unicoap_example_dtls.h"
+
+/* Example credential tag for credman. Tag together with the credential type needs to be unique. */
+# define EXAMPLE_DTLS_CREDENTIAL_TAG 42 /* This should answer your question. */
+
+static const uint8_t psk_id_0[] = PSK_DEFAULT_IDENTITY;
+static const uint8_t psk_key_0[] = PSK_DEFAULT_KEY;
+static const credman_credential_t credential = {
+    .type = CREDMAN_TYPE_PSK,
+    .tag = EXAMPLE_DTLS_CREDENTIAL_TAG,
+    .params = {
+        .psk = {
+            .key = { .s = psk_key_0, .len = sizeof(psk_key_0) - 1, },
+            .id = { .s = psk_id_0, .len = sizeof(psk_id_0) - 1, },
+        }
+    },
+};
+#endif /* IS_USED(MODULE_UNICOAP_DRIVER_DTLS) */


Why commenting this out? Doesn't it work yet?

Perhaps looking at C code for hours has damaged my neuronal capacity, but I don't see anything commented out?

mguetschow · 2026-05-11T16:27:41Z

+
+#define MAIN_QUEUE_SIZE (4)
+static msg_t _main_msg_queue[MAIN_QUEUE_SIZE];
+
+static const shell_command_t commands[] = {
+    { "coap", "unicoap client", _cli },
+    { NULL, NULL, NULL }
+};
+


Suggested change

#define MAIN_QUEUE_SIZE (4)

static msg_t _main_msg_queue[MAIN_QUEUE_SIZE];

static const shell_command_t commands[] = {

{ "coap", "unicoap client", _cli },

{ NULL, NULL, NULL }

};

SHELL_COMMAND(coap, "unicoap client", _cli)

Pretty sure you don't actually need the msg queue. You can start the shell below with NULL instead of commands.

mguetschow

First round of review, mostly typos and nitpicks. I couldn't find the promised client tutorial and the example might benefit from further comments as you did for the server example.

Otherwise: Great work, as always!

mguetschow · 2026-05-13T09:43:24Z

+/**
+ * @brief Flags for enabling advanced features in client exchanges
+ *
+ * Pass these flags to one the `unicoap_send_request` functions to modify transmission,


Suggested change

* Pass these flags to one the `unicoap_send_request` functions to modify transmission,

* Pass these flags to one of the `unicoap_send_request` functions to modify transmission,

mguetschow · 2026-05-13T09:43:43Z

+     * @brief Sets the type of the message to confirmable (`CON`),
+     * if the endpoint is an UDP or DTLS endpoint.
+     *
+     * This flag is ignored with reliable transports.. For unreliable transports, a message


Suggested change

* This flag is ignored with reliable transports.. For unreliable transports, a message

* This flag is ignored with reliable transports. For unreliable transports, a message

mguetschow · 2026-05-13T09:44:05Z

+     * This flag is ignored with reliable transports.. For unreliable transports, a message
+     * sent with this flag will require an acknowledgement to be sent from the CoAP
+     * peer.
+     *


What is the default here? Disabled I'd guess?

mguetschow · 2026-05-13T09:44:27Z

+ * @name Private request API
+ */
+/**
+ * @brief Sends off client message and creates a state object for pending request


Suggested change

* @brief Sends off client message and creates a state object for pending request

* @brief Sends off client message and creates a state object for the pending request

mguetschow · 2026-05-13T09:44:46Z

+ * @param callback Callback -- either response or block callback, see @ref unicoap_callback_t
+ * @param callback_arg Opaque argument passed to callback
+ * @param flags Client flags
+ * @param profile Profile, e.g., OSCORE profile


Suggested change

* @param profile Profile, e.g., OSCORE profile

doesn't exist (yet?)

mguetschow · 2026-05-13T13:00:36Z

+    /** @brief Callback function registered by the client API */
+    unicoap_callback_t callback;
+
+    /** @brief Argument to passed to @p callback */


Suggested change

/** @brief Argument to passed to @p callback */

/** @brief Argument to be passed to @p callback */

mguetschow · 2026-05-13T13:02:31Z

+                                                  const uint8_t* token, size_t token_length);
+
+
+unicoap_client_memo_t* unicoap_client_memo_find_refno(int refno);


doc missing, also below

mguetschow · 2026-05-13T13:07:44Z

+    /* First bit is sign bit, then 3 bits for min index and then 12 bits of randomness.
+     * For 16 or fewer memos, we thus don't have to search at all. */
+    size_t index_min = (refno & 0x7000) >> 12;
+    uint16_t reference_id = refno & 0xfff;


can we have (file-local) defines for these magic numbers?

mguetschow · 2026-05-13T13:09:37Z

+    assert(refno > 0);
+#if IS_ACTIVE(CONFIG_UNICOAP_CLIENT_CANCELLABLE)
+    /* First bit is sign bit, then 3 bits for min index and then 12 bits of randomness.
+     * For 16 or fewer memos, we thus don't have to search at all. */


Why don't we just use the array index as refno?

mguetschow · 2026-05-13T13:11:07Z

+        _STATE_DEBUG("[NOTIF] use of released state obj\n");
+        return;
+    }
+    assert(memo->endpoint.proto != UNICOAP_PROTO_UNSPECIFIED);


This is kind of trivial now that we returned in the opposite case.

carl-tud added 2 commits May 8, 2026 15:57

net/unicoap/udp: add UDP transport driver

3d57f45

net/unicoap/dtls: add DTLS transport driver

4afa652

carl-tud mentioned this pull request May 9, 2026

net/unicoap: tracking: Unified and Modular CoAP Stack #21389

Open

5 tasks

LasseRosenow reviewed May 11, 2026

View reviewed changes

carl-tud added 18 commits May 11, 2026 16:05

net/unicoap/rfc7252: add RFC7252 messaging driver

a279302

net/unicoap: add transport interface

58662ea

net/unicoap/server: add simple CoAP server

0ad963e

net/unicoap: add state management and private API

125112e

net/unicoap: add public lifecycle and config API

a24784e

net/unicoap: prefixed logging in options.c

1db939c

net/unicoap: docs and gardening in message headers

51f6842

auto_init: unicoap auto-init

a95c30e

net/unicoap: add docs for server module

2f0be42

tests/unittests: test unicoap server APIs

07dead9

examples/networking/coap/unicoap_server: add unicoap server example

c40dc02

(temporary) unicoap client impl + example

640e78d

fix CON response ACK (new state notif sys)

181218b

client DNS logging

bc42004

allow optional cancellation of pending requests

0104be0

fix changed messaging API in server

66866bf

fix changed messaging API in server, vol 2

9571833

keep client functions out of server

185b973

carl-tud force-pushed the unicoap-03-client-minimal branch from 4d1d4f2 to 185b973 Compare May 11, 2026 15:07

mguetschow reviewed May 11, 2026

View reviewed changes

carl-tud mentioned this pull request May 11, 2026

net/unicoap: Unified and Modular CoAP Stack: Resource Observation (pt 4) #22277

Draft

carl-tud changed the title ~~net/unicoap: Unified and Modular CoAP stack: Minimal client (pt 3)~~ net/unicoap: Unified and Modular CoAP Stack: Minimal Client (pt 3) May 11, 2026

mguetschow reviewed May 13, 2026

View reviewed changes

		@@ -0,0 +1,75 @@
		# Default Makefile, for simple unicoap server sample application

	# Default Makefile, for simple unicoap server sample application
	# Default Makefile, for simple unicoap client sample application

		@@ -0,0 +1,30 @@
		# Sample Client Application With `unicoap`

		This a sample application demonstrating how you send CoAP requests using `unicoap`,

	This a sample application demonstrating how you send CoAP requests using `unicoap`,
	This is a sample application demonstrating how you send CoAP requests using `unicoap`,

	to send a CoAP request through the tap interface to the CoAP server.
	Now, you can send CoAP requests from RIOT through the tap interface to the CoAP server.

	* Pass these flags to one the `unicoap_send_request` functions to modify transmission,
	* Pass these flags to one of the `unicoap_send_request` functions to modify transmission,

	* This flag is ignored with reliable transports.. For unreliable transports, a message
	* This flag is ignored with reliable transports. For unreliable transports, a message

	* @brief Sends off client message and creates a state object for pending request
	* @brief Sends off client message and creates a state object for the pending request

	/** @brief Argument to passed to @p callback */
	/** @brief Argument to be passed to @p callback */

		const uint8_t* token, size_t token_length);


		unicoap_client_memo_t* unicoap_client_memo_find_refno(int refno);

Conversation

carl-tud commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR include?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mguetschow left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mguetschow left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

carl-tud commented May 9, 2026 •

edited

Loading