net/unicoap: Unified and Modular CoAP Stack: Minimal Client (pt 3)

[carl-tud]

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.

Declaration of AI-Tools / LLMs usage:

AI-Tools / LLMs that were used are:

nada, niente

[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!

[github-actions]

Hey @carl-tud, thank you for your contribution to RIOT!

Please note that we require for all PRs to RIOT a declaration of AI-Tools / LLMs usage. It appears as if this section is missing in your PR. Please copy and fill in the section from .github/PULL_REQUEST_TEMPLATE.md.

Thank you!

[mguetschow]

you could mark this as being feature-gated behind the CONFIG_CANCELLABLE flag

[mguetschow]

IPv7

[riot-ci]

Murdock results

❌ FAILED

61de3ef fixup: make blocking client func fail on unicoap thread

Artifacts

[mguetschow]

There is also MUTEX_INIT_LOCKED that you could use directly in the initializer