net/unicoap: Unified and Modular CoAP stack: Messaging and Minimal Server (pt 2) #21582

carl-tud · 2025-07-07T17:36:55Z

This PR is the second 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?

RFC 7252 messaging implementation
Implementation of the CoAP over UDP and CoAP over DTLS drivers, plus an additional zero-copy optimization for UDP
Basic server functionality, including XFA resource definitions and helpful debug logs
A sample server application
Structured documentation, including a tutorial from the first line of code to running the example and testing it using the included client script
Support for running unicoap on a thread of your choice, e.g., the main thread.

The new API is more flexible. CoAP endpoints are abstracted into a unicoap_endpoint_t structure and transport-specific settings are controlled by flags. For example, this is a simple resource that responds with "Hello, World!".

// Define request handler for /hello
static int handle_hello_request(unicoap_message_t* message, 
    const unicoap_aux_t* aux, unicoap_request_context_t* ctx, void* arg) {
    // The aux parameter provides access to auxiliary information, such as local and remote endpoints,
    // transport-specific data and internal properties such as the message token.

    // Retrieve remote (client) endpoint and log string description of protocol number.
    printf("/hello/world resource invoked over %s\n", unicoap_string_from_proto(aux->remote->proto));

    // Craft response using convenience initializer. Vectored payloads are supported, too.
    unicoap_response_init_string(message, UNICOAP_STATUS_CONTENT, "Hello, World!");

    // Send response.
    return unicoap_send_response(message, ctx);
}

// Statically define resource, but dynamic registrations are also possible.
UNICOAP_RESOURCE(helloworld) {
    // When you specify a path, you now need to specify each component separately.
    .path = UNICOAP_PATH("hello", "world"), // /hello/world,
    
    // Instruct unicoap to send confirmable messages when communicating over UDP or DTLS.
    // This flag abstracts the transport-specific message type.
    .flags = UNICOAP_RESOURCE_FLAG_RELIABLE,
    
    // Specify what methods to allow. In unicoap, there are no duplicate defines for method flags.
    .methods = UNICOAP_METHODS(UNICOAP_METHOD_GET, UNICOAP_METHOD_PUT),
    
    // Optionally, you can also restrict the resource to a set of transports.
    .protocols = UNICOAP_PROTOCOLS(UNICOAP_PROTO_DTLS, UNICOAP_PROTO_UDP),
    
    .handler = handle_hello_request,
    .handler_arg = NULL
};

More in the documentation (CI build sometimes not available, e.g., due to failing tests).

riot-ci · 2025-07-07T18:42:37Z

Murdock results

✔️ PASSED

c307339 fixup: forgot to check in util_macros.h

Success	Failures	Total	Runtime
10533	0	10534	12m:14s

Artifacts

Documentation preview

carl-tud · 2025-12-20T16:14:39Z

Note that this change drastically lowers the complexity of our path matching functions (UNICOAP_PATH to /a/string/path and UNCOAP_PATH to Uri-Path options)

carl-tud · 2025-12-20T16:18:32Z

Also, note that this change can potentially decrease ROM size given an application that defines a lot of deeply nested paths. Each path component is stored as a separate string, hence multiple paths sharing a bunch of components do not necessarily replicate the same information in memory (either through compiler optimisation or thru manually reusing the same string).

carl-tud · 2025-12-20T16:49:27Z

@mguetschow Do you want to have a look before I rebase this onto the current master to fix DTLS (and thereby rewrite history (at least this PR's...))

Co-authored-by: Mikolai Gütschow <[email protected]>

carl-tud · 2025-12-20T17:18:14Z

@carl-tud i need to fix this: unicoap holds stale dTLS session until they are explicitly closed by the peer

LasseRosenow · 2025-12-20T20:45:42Z

I changed the way paths are defined in unicoap applications to something more semantically unique instead of parsing compile-time slash-separated path strings. Why parse paths at runtime when we can force developers to give us a parsed representation directly?

This is the way! Really nice change!

… path obj

carl-tud · 2025-12-21T14:36:28Z

#21582 (comment)

@carl-tud i need to fix this: unicoap holds stale dTLS session until they are explicitly closed by the peer

@mguetschow Is there really a bug to fix here? Just tried examples/networking/coap/unicoap_server rebased on top of master's d51045bd9d..2bd24b6522 commits. Just works and the DTLS sessions is deconstructed once the server has sent its reponse.

Doesn't waiting for the client to close the session make sense given that the client may want to further observe the resource or continue to send requests to that particular host?

carl-tud · 2025-12-23T09:27:59Z

@carl-tud can you work around resources and handle all requests in one function? I.e., does a listener’s matcher need to return a resource? Figure out if that can be NULL.

mguetschow

I've just gone through your pre-Christmas changes (Github UI shows me 22 commits).

Mostly nits as usual, some static tests failing - and a 👍 for the path spec!

mguetschow · 2026-01-05T16:29:50Z

examples/networking/coap/unicoap_server/app.config

+
+# This is the full version of debug logging, including trace logs. When this is enabled,
+# the previously mentioned API misuse, missing modules, and fix-its will also be diagnosed.
+# So when you enable debug logging, you do not need to set CONFIG_UNICOAP_ASSIST.


should be @ref CONFIG_UNICOAP_ASSIST, I guess

mguetschow · 2026-01-05T16:30:26Z

examples/networking/coap/unicoap_server/client.py

 import aiocoap.resource as resource
 from aiocoap.transports.tinydtls import DTLSClientConnection

 logging.basicConfig(level=logging.DEBUG)


You probably want to move these down to fix static tests.

mguetschow · 2026-01-05T16:31:23Z

sys/net/application_layer/unicoap/server.c

+error:
+    SERVER_DEBUG("failed to send response, trying to send 5.05 unreliably\n");
+
+    /* try to send 5.05,  */
+    unicoap_response_init_empty(packet->message, UNICOAP_STATUS_INTERNAL_SERVER_ERROR);
+    unicoap_messaging_send(packet, _messaging_flags_resource(resource->flags) &
+                                         ~UNICOAP_MESSAGING_FLAG_RELIABLE);


should i not send a 500 instead (thereby leaving the option to send a 500 to the app)?

Were both supposed to be 500? If so, I don't understand your proposal.

mguetschow · 2026-01-05T16:33:00Z

examples/networking/coap/unicoap_server/client.py

+LOG_PREFIX = Path(__file__).name
+
+tell = lambda message: print(f"{LOG_PREFIX}: {message}")
+complain = lambda message: print(f"{LOG_PREFIX}: error: {message}", file=sys.stderr)


E731 (static tests) complain about your lambda :P

mguetschow · 2026-01-05T16:35:34Z

sys/include/net/unicoap/application.h

+ */
+typedef struct {
+    /**
+     * @brief Pointer to contiguously stored character pointers to null-terminated strings


..., terminated by NULL.

mguetschow · 2026-01-05T17:14:26Z