Loading...
Searching...
No Matches
nanoCoAP Sock

Synchronous sock based messaging with nanocoap. More...

Detailed Description

Synchronous sock based messaging with nanocoap.

nanocoap sock uses the nanocoap CoAP library to provide a synchronous interface to RIOT's sock networking API to read and write CoAP messages. For a server, nanocoap sock accepts a list of resource paths with callbacks for writing the response. For a client, nanocoap sock provides a function to send a request and waits for the server response. nanocoap sock uses nanocoap's Buffer API to write message options.

Server Operation

See the nanocoap_server example, which is built on the nanocoap_server() function. A server must define CoAP resources for which it responds.

Each coap_resource_t is added to the XFA with NANOCOAP_RESOURCE(name) followed by the declaration of the CoAP resource, e.g.:

.path = "/board", .methods = COAP_GET, .handler = _board_handler,
};
#define NANOCOAP_RESOURCE(name)
CoAP XFA resource entry.
Definition nanocoap.h:417

nanocoap itself provides the COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER entry for /.well-known/core.

To use the CoAP resource XFA, enable the nanocoap_resources module.

Handler functions

For each resource, you must implement a coap_handler_t handler function. nanocoap provides functions to help implement the handler. If the handler is called via nanocoap_server(), the response buffer provided to the handler reuses the buffer for the request. So, your handler must read the request thoroughly before writing the response.

To read the request, use the functions in the Header and Options Read sections of the nanocoap documentation. If the pkt payload_len attribute is a positive value, start to read it at the payload pointer attribute.

If a response does not require specific CoAP options, use coap_reply_simple(). If there is a payload, it writes a Content-Format option with the provided value.

For a response with additional CoAP options, start by calling coap_build_reply(). Then use the Buffer API to write the rest of the response. See the instructions in the section Write Options and Payload below.

Client Operation

Follow the instructions in the section Write Options and Payload below.

To send the message and await the response, see nanocoap_sock_request() as well as nanocoap_sock_get(), which additionally copies the response payload to a user supplied buffer. Finally, read the response as described above in the server Handler functions section for reading a request.

Write Options and Payload

For both server responses and client requests, CoAP uses an Option mechanism to encode message metadata that is not required for each message. For example, the resource URI path is required only for a request, and is encoded as the Uri-Path option.

nanocoap sock uses the nanocoap Buffer API for options. The caller must provide the last option number written as well as the buffer position. The caller is primarily responsible for tracking and managing the space remaining in the buffer.

Before starting, ensure the CoAP header has been initialized with coap_build_hdr(). For a response, coap_build_reply() includes a call to coap_build_hdr(). Use the returned length to track the next position in the buffer to write and remaining length.

Next, use the functions in the Options Write Buffer API section of nanocoap to write each option. These functions require the position in the buffer to start writing, and return the number of bytes written. Options must be written in order by option number (see "CoAP option numbers" in CoAP defines).

Note
You must ensure the buffer has enough space remaining to write each option. The API does not verify the safety of writing an option.

If there is a payload, append a payload marker (0xFF). Then write the payload to within the maximum length remaining in the buffer.

Create a Block-wise Response (Block2)

Block-wise is a CoAP extension (RFC 7959) to divide a large payload across multiple physical packets. This section describes how to write a block-wise payload for a response, and is known as Block2. (Block1 is for a block-wise payload in a request.) See _riot_board_handler() in the nanocoap_server example for an example handler implementation.

Start with coap_block2_init() to read the client request and initialize a coap_slicer_t struct with the size and location for this slice of the overall payload. Then write the block2 option in the response with coap_opt_put_block2(). The option includes an indicator ("more") that a slice completes the overall payload transfer. You may not know the value for more at this point, but you must initialize the space in the packet for the option before writing the payload. The option is rewritten later.

Next, use the coap_blockwise_put_xxx() functions to write the payload content. These functions use the coap_block_slicer_t to enable or disable actually writing the content, depending on the current position within the overall payload transfer.

Finally, use the convenience function coap_block2_build_reply(), which finalizes the packet and calls coap_block2_finish() internally to update the block2 option.

Files

 
file  nanocoap_sock.h
 nanocoap high-level API
 
file  nanocoap_vfs.h
 VFS NanoCoAP helper functions.
 

Data Structures

struct  nanocoap_sock_t
 NanoCoAP socket struct. More...
 
struct  coap_block_request_t
 Blockwise request helper struct. More...
 

Macros

#define CONFIG_NANOCOAP_SOCK_DTLS_TAG   (0xc0ab)
 Credman tag used for NanoCoAP Tag together with the credential type (PSK) needs to be unique.
 
#define CONFIG_NANOCOAP_SERVER_BUF_SIZE
 CoAP server work buf size Used both for RX and TX, needs to hold payload block + header.
 
#define CONFIG_NANOCOAP_SERVER_STACK_SIZE   THREAD_STACKSIZE_DEFAULT
 CoAP server thread stack size.
 

Enumerations

enum  nanocoap_socket_type_t { COAP_SOCKET_TYPE_UDP , COAP_SOCKET_TYPE_DTLS }
 NanoCoAP socket types. More...
 

Functions

static uint16_t nanocoap_sock_next_msg_id (nanocoap_sock_t *sock)
 Get next consecutive message ID for use when building a new CoAP request.
 
int nanocoap_server (sock_udp_ep_t *local, uint8_t *buf, size_t bufsize)
 Start a nanocoap server instance.
 
kernel_pid_t nanocoap_server_start (const sock_udp_ep_t *local)
 Create and start the nanoCoAP server thread.
 
static int nanocoap_sock_connect (nanocoap_sock_t *sock, const sock_udp_ep_t *local, const sock_udp_ep_t *remote)
 Create a CoAP client socket.
 
int nanocoap_sock_dtls_connect (nanocoap_sock_t *sock, sock_udp_ep_t *local, const sock_udp_ep_t *remote, credman_tag_t tag)
 Create a DTLS secured CoAP client socket.
 
int nanocoap_sock_url_connect (const char *url, nanocoap_sock_t *sock)
 Create a CoAP client socket by URL.
 
static void nanocoap_sock_close (nanocoap_sock_t *sock)
 Close a CoAP client socket.
 
ssize_t nanocoap_sock_get (nanocoap_sock_t *sock, const char *path, void *buf, size_t len)
 Simple synchronous CoAP (confirmable) GET.
 
ssize_t nanocoap_sock_put (nanocoap_sock_t *sock, const char *path, const void *request, size_t len, void *response, size_t len_max)
 Simple synchronous CoAP (confirmable) PUT.
 
ssize_t nanocoap_sock_put_non (nanocoap_sock_t *sock, const char *path, const void *request, size_t len, void *response, size_t len_max)
 Simple non-confirmable PUT.
 
ssize_t nanocoap_sock_put_url (const char *url, const void *request, size_t len, void *response, size_t len_max)
 Simple synchronous CoAP (confirmable) PUT to URL.
 
ssize_t nanocoap_sock_post (nanocoap_sock_t *sock, const char *path, const void *request, size_t len, void *response, size_t len_max)
 Simple synchronous CoAP (confirmable) POST.
 
ssize_t nanocoap_sock_post_non (nanocoap_sock_t *sock, const char *path, const void *request, size_t len, void *response, size_t len_max)
 Simple non-confirmable POST.
 
ssize_t nanocoap_sock_post_url (const char *url, const void *request, size_t len, void *response, size_t len_max)
 Simple synchronous CoAP (confirmable) POST to URL.
 
ssize_t nanocoap_sock_fetch (nanocoap_sock_t *sock, const char *path, const void *request, size_t len, void *response, size_t len_max)
 Simple synchronous CoAP (confirmable) FETCH (RFC 8132)
 
ssize_t nanocoap_sock_fetch_non (nanocoap_sock_t *sock, const char *path, const void *request, size_t len, void *response, size_t len_max)
 Simple non-confirmable FETCH (RFC 8132)
 
ssize_t nanocoap_sock_fetch_url (const char *url, const void *request, size_t len, void *response, size_t len_max)
 Simple synchronous CoAP (confirmable) FETCH to URL (RFC 8132)
 
ssize_t nanocoap_sock_delete (nanocoap_sock_t *sock, const char *path)
 Simple synchronous CoAP (confirmable) DELETE.
 
ssize_t nanocoap_sock_delete_url (const char *url)
 Simple synchronous CoAP (confirmable) DELETE for URL.
 
int nanocoap_sock_get_blockwise (nanocoap_sock_t *sock, const char *path, coap_blksize_t blksize, coap_blockwise_cb_t callback, void *arg)
 Performs a blockwise coap get request on a socket.
 
int nanocoap_get_blockwise_url (const char *url, coap_blksize_t blksize, coap_blockwise_cb_t callback, void *arg)
 Performs a blockwise coap get request to the specified url.
 
ssize_t nanocoap_get_blockwise_url_to_buf (const char *url, coap_blksize_t blksize, void *buf, size_t len)
 Performs a blockwise coap get request to the specified url, store the response in a buffer.
 
ssize_t nanocoap_sock_request (nanocoap_sock_t *sock, coap_pkt_t *pkt, size_t len)
 Simple synchronous CoAP request.
 
ssize_t nanocoap_sock_request_cb (nanocoap_sock_t *sock, coap_pkt_t *pkt, coap_request_cb_t cb, void *arg)
 Simple synchronous CoAP request with callback.
 
ssize_t nanocoap_request (coap_pkt_t *pkt, const sock_udp_ep_t *local, const sock_udp_ep_t *remote, size_t len)
 Simple synchronous CoAP request.
 
static int nanocoap_block_request_connect_url (coap_block_request_t *ctx, nanocoap_sock_t *sock, const char *url, coap_method_t method, coap_blksize_t blksize)
 Initialize block request context by URL and connect a socket.
 
int nanocoap_sock_block_request (coap_block_request_t *ctx, const void *data, size_t len, bool more, coap_request_cb_t cb, void *arg)
 Do a block-wise request, send a single block.
 

Macro Definition Documentation

◆ CONFIG_NANOCOAP_SERVER_BUF_SIZE

#define CONFIG_NANOCOAP_SERVER_BUF_SIZE
Value:
#define CONFIG_NANOCOAP_BLOCKSIZE_DEFAULT
CoAP block-wise-transfer size that should be used by default.
Definition nanocoap.h:168
#define CONFIG_NANOCOAP_URI_MAX
Maximum length of a resource path string read from or written to a message.
Definition nanocoap.h:154

CoAP server work buf size Used both for RX and TX, needs to hold payload block + header.

Definition at line 167 of file nanocoap_sock.h.

◆ CONFIG_NANOCOAP_SERVER_STACK_SIZE

#define CONFIG_NANOCOAP_SERVER_STACK_SIZE   THREAD_STACKSIZE_DEFAULT

CoAP server thread stack size.

Definition at line 175 of file nanocoap_sock.h.

◆ CONFIG_NANOCOAP_SOCK_DTLS_TAG

#define CONFIG_NANOCOAP_SOCK_DTLS_TAG   (0xc0ab)

Credman tag used for NanoCoAP Tag together with the credential type (PSK) needs to be unique.

Definition at line 159 of file nanocoap_sock.h.

Enumeration Type Documentation

◆ nanocoap_socket_type_t

NanoCoAP socket types.

Enumerator
COAP_SOCKET_TYPE_UDP 

transport is plain UDP

COAP_SOCKET_TYPE_DTLS 

transport is DTLS

Definition at line 181 of file nanocoap_sock.h.

Function Documentation

◆ nanocoap_block_request_connect_url()

static int nanocoap_block_request_connect_url ( coap_block_request_t ctx,
nanocoap_sock_t sock,
const char *  url,
coap_method_t  method,
coap_blksize_t  blksize 
)
inlinestatic

Initialize block request context by URL and connect a socket.

Parameters
[out]ctxThe block request context to initialize
[out]sockSocket to initialize and use for the request
[in]urlThe request URL
[in]methodRequest method (COAP_METHOD_{GET|PUT|POST|FETCH})
[in]blksizeRequest blocksize exponent
Return values
0Success
<0Error (see nanocoap_sock_url_connect for details)

Definition at line 635 of file nanocoap_sock.h.

◆ nanocoap_get_blockwise_url()

int nanocoap_get_blockwise_url ( const char *  url,
coap_blksize_t  blksize,
coap_blockwise_cb_t  callback,
void *  arg 
)

Performs a blockwise coap get request to the specified url.

This function will fetch the content of the specified resource path via block-wise-transfer. A coap_blockwise_cb_t will be called on each received block.

Parameters
[in]urlAbsolute URL pointer to source path (i.e. not containing a fragment identifier)
[in]blksizesender suggested SZX for the COAP block request
[in]callbackcallback to be executed on each received block
[in]argoptional function arguments
Returns
-EINVAL if an invalid url is provided
-1 if failed to fetch the url content
0 on success

◆ nanocoap_get_blockwise_url_to_buf()

ssize_t nanocoap_get_blockwise_url_to_buf ( const char *  url,
coap_blksize_t  blksize,
void *  buf,
size_t  len 
)

Performs a blockwise coap get request to the specified url, store the response in a buffer.

This function will fetch the content of the specified resource path via block-wise-transfer. The blocks will be re-assembled into buf

Parameters
[in]urlAbsolute URL pointer to source path (i.e. not containing a fragment identifier)
[in]blksizesender suggested SZX for the COAP block request
[in]bufTarget buffer
[in]lenTarget buffer length
Returns
<0 on error
-EINVAL if an invalid url is provided
-ENOBUFS if the provided buffer was too small
size of the response payload on success

◆ nanocoap_request()

ssize_t nanocoap_request ( coap_pkt_t pkt,
const sock_udp_ep_t local,
const sock_udp_ep_t remote,
size_t  len 
)

Simple synchronous CoAP request.

Parameters
[in,out]pktPacket struct containing the request. Is reused for the response
[in]localLocal UDP endpoint, may be NULL
[in]remoteremote UDP endpoint
[in]lenTotal length of the buffer associated with the request
Returns
length of response on success
<0 on error

◆ nanocoap_server()

int nanocoap_server ( sock_udp_ep_t local,
uint8_t *  buf,
size_t  bufsize 
)

Start a nanocoap server instance.

This function only returns if there's an error binding to local, or if receiving of UDP packets fails.

Parameters
[in]locallocal UDP endpoint to bind to
[in]bufinput buffer to use
[in]bufsizesize of buf
Returns
-1 on error

◆ nanocoap_server_start()

kernel_pid_t nanocoap_server_start ( const sock_udp_ep_t local)

Create and start the nanoCoAP server thread.

To automatically start the nanoCoAP server on startup, select the nanocoap_server_auto_init module.

Parameters
[in]localUDP endpoint to bind to
Returns
pid of the server thread

◆ nanocoap_sock_block_request()

int nanocoap_sock_block_request ( coap_block_request_t ctx,
const void *  data,
size_t  len,
bool  more,
coap_request_cb_t  cb,
void *  arg 
)

Do a block-wise request, send a single block.

     This method is expected to be called in a loop until all
     payload blocks have been transferred.
Precondition
ctx was initialized with nanocoap_block_request_connect_url or manually.
Parameters
[in]ctxblockwise request context
[in]datapayload to send
[in]lenpayload length
[in]moremore blocks after this one (will be set automatically if len > block size)
[in]cbcallback for response
[in]argcallback context
Returns
Number of payload bytes written on success Negative error on failure

◆ nanocoap_sock_close()

static void nanocoap_sock_close ( nanocoap_sock_t sock)
inlinestatic

Close a CoAP client socket.

Parameters
[in]sockCoAP UDP socket

Definition at line 306 of file nanocoap_sock.h.

◆ nanocoap_sock_connect()

static int nanocoap_sock_connect ( nanocoap_sock_t sock,
const sock_udp_ep_t local,
const sock_udp_ep_t remote 
)
inlinestatic

Create a CoAP client socket.

Parameters
[out]sockCoAP UDP socket
[in]localLocal UDP endpoint, may be NULL
[in]remoteremote UDP endpoint
Returns
0 on success
<0 on error

Definition at line 261 of file nanocoap_sock.h.

◆ nanocoap_sock_delete()

ssize_t nanocoap_sock_delete ( nanocoap_sock_t sock,
const char *  path 
)

Simple synchronous CoAP (confirmable) DELETE.

Parameters
[in]socksocket to use for the request
[in]pathremote path (with query) to delete
Returns
0 on success
<0 on error

◆ nanocoap_sock_delete_url()

ssize_t nanocoap_sock_delete_url ( const char *  url)

Simple synchronous CoAP (confirmable) DELETE for URL.

Parameters
[in]urlURL of the resource that should be deleted
Returns
0 on success
<0 on error

◆ nanocoap_sock_dtls_connect()

int nanocoap_sock_dtls_connect ( nanocoap_sock_t sock,
sock_udp_ep_t local,
const sock_udp_ep_t remote,
credman_tag_t  tag 
)

Create a DTLS secured CoAP client socket.

Parameters
[out]sockCoAP UDP socket
[in]localLocal UDP endpoint, may be NULL
[in]remoteremote UDP endpoint
[in]tagTag of the PSK credential to use Has to be added with credman_add
Returns
0 on success
<0 on error

◆ nanocoap_sock_fetch()

ssize_t nanocoap_sock_fetch ( nanocoap_sock_t sock,
const char *  path,
const void *  request,
size_t  len,
void *  response,
size_t  len_max 
)

Simple synchronous CoAP (confirmable) FETCH (RFC 8132)

Parameters
[in]socksocket to use for the request
[in]pathremote path and query
[in]requestbuffer containing the payload
[in]lenlength of the payload to send
[out]responsebuffer for the response, may be NULL
[in]len_maxlength of response
Returns
length of response payload on success
<0 on error

◆ nanocoap_sock_fetch_non()

ssize_t nanocoap_sock_fetch_non ( nanocoap_sock_t sock,
const char *  path,
const void *  request,
size_t  len,
void *  response,
size_t  len_max 
)

Simple non-confirmable FETCH (RFC 8132)

Parameters
[in]socksocket to use for the request
[in]pathremote path and query
[in]requestbuffer containing the payload
[in]lenlength of the payload to send
[out]responsebuffer for the response, may be NULL
[in]len_maxlength of response
Returns
length of response payload on success
0 if the request was sent and no response buffer was provided, independently of success (because no response is requested in that case)
<0 on error

◆ nanocoap_sock_fetch_url()

ssize_t nanocoap_sock_fetch_url ( const char *  url,
const void *  request,
size_t  len,
void *  response,
size_t  len_max 
)

Simple synchronous CoAP (confirmable) FETCH to URL (RFC 8132)

Parameters
[in]urlAbsolute URL pointer to source path
[in]requestbuffer containing the payload
[in]lenlength of the payload to send
[out]responsebuffer for the response, may be NULL
[in]len_maxlength of response
Returns
length of response payload on success
<0 on error

◆ nanocoap_sock_get()

ssize_t nanocoap_sock_get ( nanocoap_sock_t sock,
const char *  path,
void *  buf,
size_t  len 
)

Simple synchronous CoAP (confirmable) GET.

Parameters
[in]socksocket to use for the request
[in]pathremote path and query
[out]bufbuffer to write response to
[in]lenlength of buffer
Returns
length of response payload on success
<0 on error

◆ nanocoap_sock_get_blockwise()

int nanocoap_sock_get_blockwise ( nanocoap_sock_t sock,
const char *  path,
coap_blksize_t  blksize,
coap_blockwise_cb_t  callback,
void *  arg 
)

Performs a blockwise coap get request on a socket.

This function will fetch the content of the specified resource path via block-wise-transfer. A coap_blockwise_cb_t will be called on each received block.

Parameters
[in]socksocket to use for the request
[in]pathpointer to source path
[in]blksizesender suggested SZX for the COAP block request
[in]callbackcallback to be executed on each received block
[in]argoptional function arguments
Returns
-1 if failed to fetch the url content
0 on success

◆ nanocoap_sock_next_msg_id()

static uint16_t nanocoap_sock_next_msg_id ( nanocoap_sock_t sock)
inlinestatic

Get next consecutive message ID for use when building a new CoAP request.

Parameters
[in]sockCoAP socket on which the ID is used
Returns
A new message ID that can be used for a request or response.

Definition at line 220 of file nanocoap_sock.h.

◆ nanocoap_sock_post()

ssize_t nanocoap_sock_post ( nanocoap_sock_t sock,
const char *  path,
const void *  request,
size_t  len,
void *  response,
size_t  len_max 
)

Simple synchronous CoAP (confirmable) POST.

Parameters
[in]socksocket to use for the request
[in]pathremote path and query
[in]requestbuffer containing the payload
[in]lenlength of the payload to send
[out]responsebuffer for the response, may be NULL
[in]len_maxlength of response
Returns
length of response payload on success
<0 on error

◆ nanocoap_sock_post_non()

ssize_t nanocoap_sock_post_non ( nanocoap_sock_t sock,
const char *  path,
const void *  request,
size_t  len,
void *  response,
size_t  len_max 
)

Simple non-confirmable POST.

Parameters
[in]socksocket to use for the request
[in]pathremote path and query
[in]requestbuffer containing the payload
[in]lenlength of the payload to send
[out]responsebuffer for the response, may be NULL
[in]len_maxlength of response
Returns
length of response payload on success
0 if the request was sent and no response buffer was provided, independently of success (because no response is requested in that case)
<0 on error

◆ nanocoap_sock_post_url()

ssize_t nanocoap_sock_post_url ( const char *  url,
const void *  request,
size_t  len,
void *  response,
size_t  len_max 
)

Simple synchronous CoAP (confirmable) POST to URL.

Parameters
[in]urlAbsolute URL pointer to source path
[in]requestbuffer containing the payload
[in]lenlength of the payload to send
[out]responsebuffer for the response, may be NULL
[in]len_maxlength of response
Returns
length of response payload on success
<0 on error

◆ nanocoap_sock_put()

ssize_t nanocoap_sock_put ( nanocoap_sock_t sock,
const char *  path,
const void *  request,
size_t  len,
void *  response,
size_t  len_max 
)

Simple synchronous CoAP (confirmable) PUT.

Parameters
[in]socksocket to use for the request
[in]pathremote path and query
[in]requestbuffer containing the payload
[in]lenlength of the payload to send
[out]responsebuffer for the response, may be NULL
[in]len_maxlength of response
Returns
length of response payload on success
<0 on error

◆ nanocoap_sock_put_non()

ssize_t nanocoap_sock_put_non ( nanocoap_sock_t sock,
const char *  path,
const void *  request,
size_t  len,
void *  response,
size_t  len_max 
)

Simple non-confirmable PUT.

Parameters
[in]socksocket to use for the request
[in]pathremote path and query
[in]requestbuffer containing the payload
[in]lenlength of the payload to send
[out]responsebuffer for the response, may be NULL
[in]len_maxlength of response
Returns
length of response payload on success
0 if the request was sent and no response buffer was provided, independently of success (because no response is requested in that case)
<0 on error

◆ nanocoap_sock_put_url()

ssize_t nanocoap_sock_put_url ( const char *  url,
const void *  request,
size_t  len,
void *  response,
size_t  len_max 
)

Simple synchronous CoAP (confirmable) PUT to URL.

Parameters
[in]urlAbsolute URL pointer to source path
[in]requestbuffer containing the payload
[in]lenlength of the payload to send
[out]responsebuffer for the response, may be NULL
[in]len_maxlength of response
Returns
length of response payload on success
<0 on error

◆ nanocoap_sock_request()

ssize_t nanocoap_sock_request ( nanocoap_sock_t sock,
coap_pkt_t pkt,
size_t  len 
)

Simple synchronous CoAP request.

Parameters
[in]socksocket to use for the request
[in,out]pktPacket struct containing the request. Is reused for the response
[in]lenTotal length of the buffer associated with the request
Returns
length of response on success
<0 on error

◆ nanocoap_sock_request_cb()

ssize_t nanocoap_sock_request_cb ( nanocoap_sock_t sock,
coap_pkt_t pkt,
coap_request_cb_t  cb,
void *  arg 
)

Simple synchronous CoAP request with callback.

     The response will be handled by a callback, which avoids copying the
     response packet out of the network stack internal buffer.
Parameters
[in]socksocket to use for the request
[in,out]pktPacket struct containing the request. Is reused for the response
[in]cbCallback executed for response packet
[in]argOptional callback argumnent
Returns
length of response on success
<0 on error

◆ nanocoap_sock_url_connect()

int nanocoap_sock_url_connect ( const char *  url,
nanocoap_sock_t sock 
)

Create a CoAP client socket by URL.

Parameters
[in]urlURL with server information to connect to
[out]sockCoAP UDP socket
Returns
0 on success
<0 on error