The friendly Operating System for the Internet of Things

High-level interface to CoAP messaging. More...

Detailed Description

gcoap provides a high-level interface for writing CoAP messages via RIOT's sock networking API. gcoap internalizes network event processing so an application only needs to focus on request/response handling. For a server, gcoap accepts a list of resource paths with callbacks for writing the response. For a client, gcoap provides a function to send a request, with a callback for reading the server response. Generation of the request or response requires from one to three well-defined steps, depending on inclusion of a payload.

gcoap allocates a RIOT message processing thread, so a single instance can serve multiple applications. This approach also means gcoap uses a single UDP port, which supports RFC 6282 compression. Internally, gcoap depends on the nanocoap package for base level structs and functionality.

Server Operation

gcoap listens for requests on GCOAP_PORT, 5683 by default. You can redefine this by uncommenting the appropriate lines in gcoap's make file.

gcoap allows an application to specify a collection of request resource paths it wants to be notified about. Create an array of resources, coap_resource_t structs. Use gcoap_register_listener() at application startup to pass in these resources, wrapped in a gcoap_listener_t.

gcoap itself defines a resource for /.well-known/core discovery, which lists all of the registered paths.

Creating a response

An application resource includes a callback function, a coap_handler_t. After reading the request, the callback must use one or two functions provided by gcoap to format the response, as described below. The callback must read the request thoroughly before calling the functions, because the response buffer likely reuses the request buffer. See examples/gcoap/gcoap_cli.c for a simple example of a callback.

Here is the expected sequence for a callback function:

Read request completely and parse request payload, if any. Use the coap_pkt_t payload and payload_len attributes.

If there is a payload, follow the three steps below.

  1. Call gcoap_resp_init() to initialize the response.
  2. Write the request payload, starting at the updated payload pointer in the coap_pkt_t. If some error occurs, return a negative errno code from the handler, and gcoap will send a server error (5.00).
  3. Call gcoap_finish() to complete the PDU after writing the payload, and return the result. gcoap will send the message.

If no payload, call only gcoap_response() to write the full response. Alternatively, you still can use gcoap_resp_init() and gcoap_finish(), as described above. In fact, the gcoap_response() function is inline, and uses those two functions.

Client Operation

Client operation includes two phases: creating and sending a request, and handling the response aynchronously in a client supplied callback. See examples/gcoap/gcoap_cli.c for a simple example of sending a request and reading the response.

Creating a request

Here is the expected sequence for preparing and sending a request:

Allocate a buffer and a coap_pkt_t for the request.

If there is a payload, follow the three steps below.

  1. Call gcoap_req_init() to initialize the request.
  2. Write the request payload, starting at the updated payload pointer in the coap_pkt_t.
  3. Call gcoap_finish(), which updates the packet for the payload.

If no payload, call only gcoap_request() to write the full request. Alternatively, you still can use gcoap_req_init() and gcoap_finish(), as described above. The gcoap_request() function is inline, and uses those two functions.

Finally, call gcoap_req_send2() for the destination endpoint, as well as a callback function for the host's response.

Handling the response

When gcoap receives the response to a request, it executes the callback from the request. gcoap also executes the callback when a response is not received within GCOAP_RESPONSE_TIMEOUT.

Here is the expected sequence for handling a response in the callback.

  1. Test for a server response or timeout in the req_state callback parameter. See the GCOAP_MEMO... constants.
  2. Test the response with coap_get_code_class() and coap_get_code_detail().
  3. Test the response payload with the coap_pkt_t payload_len and content_type attributes.
  4. Read the payload, if any.

Implementation Notes

Building a packet

The sequence and functions described above to build a request or response is designed to provide a relatively simple API for the user.

The structure of a CoAP PDU requires that options are placed between the header and the payload. So, gcoap provides space in the buffer for them in the request/response ...init() function, and then writes them during gcoap_finish(). We trade some inefficiency/work in the buffer for simplicity in the API.

Waiting for a response

We take advantage of RIOT's asynchronous messaging by using an xtimer to wait for a response, so the gcoap thread does not block while waiting. The user is notified via the same callback, whether the message is received or the wait times out. We track the response with an entry in the _coap_state.open_reqs array.

Files

file  gcoap.h
 gcoap definition
 

Data Structures

struct  gcoap_listener
 A modular collection of resources for a server. More...
 
struct  gcoap_request_memo_t
 Memo to handle a response for a request. More...
 
struct  gcoap_state_t
 Container for the state of gcoap itself. More...
 

Macros

#define GCOAP_MSG_QUEUE_SIZE   (4)
 Size for module message queue.
 
#define GCOAP_PORT   (5683)
 Server port; use RFC 7252 default if not defined.
 
#define GCOAP_PDU_BUF_SIZE   (128)
 Size of the buffer used to build a CoAP request or response. More...
 
#define GCOAP_REQ_OPTIONS_BUF   (8)
 Size of the buffer used to write options, other than Uri-Path, in a request. More...
 
#define GCOAP_RESP_OPTIONS_BUF   (8)
 Size of the buffer used to write options in a response. More...
 
#define GCOAP_REQ_WAITING_MAX   (2)
 Maximum number of requests awaiting a response.
 
#define GCOAP_TOKENLEN_MAX   (8)
 Maximum length in bytes for a token.
 
#define GCOAP_HEADER_MAXLEN   (sizeof(coap_hdr_t) + GCOAP_TOKENLEN_MAX)
 Maximum length in bytes for a header, including the token.
 
#define GCOAP_TOKENLEN   (2)
 Length in bytes for a token; use 2 if not defined.
 
#define GCOAP_PAYLOAD_MARKER   (0xFF)
 Marks the boundary between header and payload.
 
#define GCOAP_RECV_TIMEOUT   (1 * US_PER_SEC)
 Time in usec that the event loop waits for an incoming CoAP message.
 
#define GCOAP_NON_TIMEOUT   (5000000U)
 Default time to wait for a non-confirmable response, in usec. More...
 
#define GCOAP_MSG_TYPE_TIMEOUT   (0x1501)
 Identifies waiting timed out for a response to a sent message. More...
 
#define GCOAP_MSG_TYPE_INTR   (0x1502)
 Identifies a request to interrupt listening for an incoming message on a sock. More...
 

Typedefs

typedef struct gcoap_listener gcoap_listener_t
 A modular collection of resources for a server.
 
typedef void(* gcoap_resp_handler_t) (unsigned req_state, coap_pkt_t *pdu)
 Handler function for a server response, including the state for the originating request. More...
 

Functions

kernel_pid_t gcoap_init (void)
 Initializes the gcoap thread and device. More...
 
void gcoap_register_listener (gcoap_listener_t *listener)
 Starts listening for resource paths. More...
 
int gcoap_req_init (coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code, char *path)
 Initializes a CoAP request PDU on a buffer. More...
 
ssize_t gcoap_finish (coap_pkt_t *pdu, size_t payload_len, unsigned format)
 Finishes formatting a CoAP PDU after the payload has been written. More...
 
static ssize_t gcoap_request (coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code, char *path)
 Writes a complete CoAP request PDU when there is not a payload. More...
 
size_t gcoap_req_send2 (uint8_t *buf, size_t len, sock_udp_ep_t *remote, gcoap_resp_handler_t resp_handler)
 Sends a buffer containing a CoAP request to the provided endpoint. More...
 
size_t gcoap_req_send (uint8_t *buf, size_t len, ipv6_addr_t *addr, uint16_t port, gcoap_resp_handler_t resp_handler)
 Sends a buffer containing a CoAP request to the provided host/port. More...
 
int gcoap_resp_init (coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code)
 Initializes a CoAP response packet on a buffer. More...
 
static ssize_t gcoap_response (coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code)
 Writes a complete CoAP response PDU when there is no payload. More...
 
void gcoap_op_state (uint8_t *open_reqs)
 Provides important operational statistics. More...
 

States for the memo used to track waiting for a response

#define GCOAP_MEMO_UNUSED   (0)
 This memo is unused.
 
#define GCOAP_MEMO_WAIT   (1)
 Request sent; awaiting response.
 
#define GCOAP_MEMO_RESP   (2)
 Got response.
 
#define GCOAP_MEMO_TIMEOUT   (3)
 Timeout waiting for response.
 
#define GCOAP_MEMO_ERR   (4)
 Error processing response packet.
 

Macro Definition Documentation

#define GCOAP_MSG_TYPE_INTR   (0x1502)

Allows the event loop to process IPC messages.

Definition at line 226 of file gcoap.h.

#define GCOAP_MSG_TYPE_TIMEOUT   (0x1501)

Definition at line 218 of file gcoap.h.

#define GCOAP_NON_TIMEOUT   (5000000U)

Set to 0 to disable timeout.

Definition at line 215 of file gcoap.h.

#define GCOAP_PDU_BUF_SIZE   (128)

Definition at line 161 of file gcoap.h.

#define GCOAP_REQ_OPTIONS_BUF   (8)

Accommodates Content-Format.

Definition at line 169 of file gcoap.h.

#define GCOAP_RESP_OPTIONS_BUF   (8)

Accommodates Content-Format.

Definition at line 176 of file gcoap.h.

Typedef Documentation

typedef void(* gcoap_resp_handler_t) (unsigned req_state, coap_pkt_t *pdu)

If request timed out, the packet header is for the request.

Definition at line 244 of file gcoap.h.

Function Documentation

ssize_t gcoap_finish ( coap_pkt_t *  pdu,
size_t  payload_len,
unsigned  format 
)

Assumes the PDU has been initialized with gcoap_req_init() or gcoap_resp_init().

Parameters
[in]pduRequest metadata
[in]payload_lenLength of the payload, or 0 if none
[in]formatFormat code for the payload; use COAP_FORMAT_NONE if not specified
Returns
size of the PDU
< 0 on error
kernel_pid_t gcoap_init ( void  )

Must call once before first use.

Returns
PID of the gcoap thread on success.
-EEXIST, if thread already has been created.
-EINVAL, if the IP port already is in use.
void gcoap_op_state ( uint8_t *  open_reqs)

Useful for monitoring.

Parameters
[out]open_reqsCount of unanswered requests
void gcoap_register_listener ( gcoap_listener_t listener)
Parameters
listenerListener containing the resources.
int gcoap_req_init ( coap_pkt_t *  pdu,
uint8_t *  buf,
size_t  len,
unsigned  code,
char *  path 
)
Parameters
[in]pduRequest metadata
[in]bufBuffer containing the PDU
[in]lenLength of the buffer
[in]codeRequest code
[in]pathResource path
Returns
0 on success
< 0 on error
size_t gcoap_req_send ( uint8_t *  buf,
size_t  len,
ipv6_addr_t addr,
uint16_t  port,
gcoap_resp_handler_t  resp_handler 
)
Deprecated:
Please use gcoap_req_send2() instead
Parameters
[in]bufBuffer containing the PDU
[in]lenLength of the buffer
[in]addrDestination for the packet
[in]portPort at the destination
[in]resp_handlerCallback when response received
Returns
length of the packet
0 if cannot send
size_t gcoap_req_send2 ( uint8_t *  buf,
size_t  len,
sock_udp_ep_t remote,
gcoap_resp_handler_t  resp_handler 
)
Parameters
[in]bufBuffer containing the PDU
[in]lenLength of the buffer
[in]remoteDestination for the packet
[in]resp_handlerCallback when response received
Returns
length of the packet
0 if cannot send
static ssize_t gcoap_request ( coap_pkt_t *  pdu,
uint8_t *  buf,
size_t  len,
unsigned  code,
char *  path 
)
inlinestatic
Parameters
[in]pduRequest metadata
[in]bufBuffer containing the PDU
[in]lenLength of the buffer
[in]codeRequest code
[in]pathResource path
Returns
size of the PDU within the buffer
< 0 on error

Definition at line 331 of file gcoap.h.

int gcoap_resp_init ( coap_pkt_t *  pdu,
uint8_t *  buf,
size_t  len,
unsigned  code 
)

Initializes payload location within the buffer based on packet setup.

Parameters
[in]pduResponse metadata
[in]bufBuffer containing the PDU
[in]lenLength of the buffer
[in]codeResponse code
Returns
0 on success
< 0 on error
static ssize_t gcoap_response ( coap_pkt_t *  pdu,
uint8_t *  buf,
size_t  len,
unsigned  code 
)
inlinestatic
Parameters
[in]pduResponse metadata
[in]bufBuffer containing the PDU
[in]lenLength of the buffer
[in]codeResponse code
Returns
size of the PDU within the buffer
< 0 on error

Definition at line 397 of file gcoap.h.