unicoap: Unified CoAP Suite

Send requests and create server resources using the Constrained Application Protocol across different transports. More...

Detailed Description

Send requests and create server resources using the Constrained Application Protocol across different transports.

Module. Specify USEMODULE += unicoap in your application's Makefile.

Warning

unicoap is work in progress. Not all functionality is implemented in RIOT yet, however the documentation already exists. Do not expect everything to work yet.

unicoap is RIOT's unified and modular framework for communication via the Constrained Application Protocol. unicoap supports different transports and several CoAP features, enabled by a layered and modular design. Support for each CoAP transport, such as UDP, is available through drivers.

unicoap aims to eventually replace GCoAP, nanoCoAP small CoAP library, and nanoCoAP Sock, in favor of a more beginner-friendly and easily extensible design.

CoAP

The Constrained Application Protocol (CoAP) is a lightweight alternative to HTTP. HTTP as a general-purpose application protocol carries a significant overhead and is thus problematic for IoT networks with limited bandwidth and nodes with little memory. CoAP covers a range of features needed in the IoT, such as resource discovery, message fragmentation, and end-to-end message protection.

Quick start

In your application Makefile, add

USEMODULE += unicoap
USEMODULE += unicoap_driver_udp

unicoap enables support for CoAP over various transport protocols. Currently, unicoap supports a CoAP over UDP Driver and CoAP over DTLS Driver. You must specify at least one driver to use networking functionality. If you just want to use message APIs, you can use the framing implementation of each driver, such as the RFC 7252 Framing submodule for the RFC 7252 PDU format. unicoap implements both a client and a server. To create a CoAP server, visit Writing a Server Application.

To configure unicoap, go to the unicoap Compile-Time Configuration. For extending unicoap, refer to Behind The Scenes of unicoap.

Topics
	Behind The Scenes of unicoap
	CoAP Server
	Register CoAP resources and handle requests asynchronously.
	Drivers
	Collection of transport drivers.
	Message APIs
	Create and serialize CoAP messages.
	Transport Protocol Abstractions
	CoAP endpoint, resource identifiers, and schemes.
	unicoap Compile-Time Configuration
	Customize limits and capabilities of unicoap.

Files
file	unicoap.h
	Main header for unicoap
file	util_macros.h
	Utility macros for unicoap

Data Structures
struct	unicoap_job_t
	A job that can be enqueued and executed by the unicoap message processing loop. More...

Managing the unicoap instance
kernel_pid_t	unicoap_init (void)
	Initializes the unicoap stack.
int	unicoap_deinit (void)
	Tears down the unicoap stack, closing the background thread.
static void	unicoap_loop_run (void)
	Runs unicoap processing loop.
int	unicoap_loop_enqueue (unicoap_job_t *job)
	Schedules event to be run in the internal processing loop at the next possible instance.
#define	UNICOAP_JOB(func)
	Initializes a unicoap_job_t.

Macro Definition Documentation

UNICOAP_JOB

#define UNICOAP_JOB

(

func

)

Value:

    { \
    .super = { \
        .handler = _UNICOAP_TRY_TYPECHECK_JOB_FUNC(func) \
    } \
}

Initializes a unicoap_job_t.

Parameters

func	A function that must be of type void (unicoap_job_t* job).

Returns

Designated initializer for unicoap_job_t

Definition at line 93 of file unicoap.h.

Function Documentation

unicoap_deinit()

int unicoap_deinit

(

void

)

Tears down the unicoap stack, closing the background thread.

Provided CONFIG_UNICOAP_CREATE_THREAD is enabled, this function will also zombify the thread created on initialization.

Returns

Zero on success, -1 otherwise

unicoap_init()

kernel_pid_t unicoap_init

(

void

)

Initializes the unicoap stack.

If you disable the auto_init_unicoap you will need to call this function manually. Otherwise, and provided auto_init is used, unicoap will be initialized automatically.

Returns

unicoap thread PID

unicoap_loop_enqueue()

int unicoap_loop_enqueue

(

unicoap_job_t *

job

)

Schedules event to be run in the internal processing loop at the next possible instance.

Parameters

[in,out]

job

Job to run on unicoap message processing loop

Returns

Negative error number in case of failure or zero on success.

This function facilitates running client requests when CONFIG_UNICOAP_CREATE_THREAD is disabled.

Remarks

You can start enqueuing jobs even before the unicoap processing loop has been started. The jobs will become eligible for execution once the loop starts running, which usually is when the unicoap thread has been created. If CONFIG_UNICOAP_CREATE_THREAD is disabled, this will be after you have called unicoap_loop_run, which blocks.

static unicoap_job_t sample = UNICOAP_JOB(my_handler);

unicoap_loop_run()

static void unicoap_loop_run ( void )

inlinestatic

Runs unicoap processing loop.

This function never returns, unless explicitly instructed using unicoap_deinit.

Warning

You must not call this function when CONFIG_UNICOAP_CREATE_THREAD is enabled. If CONFIG_UNICOAP_CREATE_THREAD is enabled, this function is not defined.

Never returns (because event_queue_t does not allow that...)

Definition at line 72 of file unicoap.h.