CoAP¶
High-level interface to CoAP messaging.
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.
gcoap also supports the Observe extension (RFC 7641) for a server. gcoap provides functions to generate and send an observe notification that are similar to the functions to send a client request.
Contents
- Server Operation
- Client Operation
- Observe Server Operation
- Implementation Notes
- Implementation Status
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) ordered by the resource path, specifically the ASCII encoding of the path characters (digit and capital precede lower case). Use gcoap.h::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.
- Call
gcoap.h::gcoap_resp_init()
to initialize the response. - Write the response 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).
- Call
gcoap.h::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.h::gcoap_response()
to write the full response. Alternatively, you still can use gcoap.h::gcoap_resp_init()
and gcoap.h::gcoap_finish()
, as described above. In fact, the gcoap.h::gcoap_response()
function is inline, and uses those two functions.
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.
- Call
gcoap.h::gcoap_resp_init()
to initialize the response. - Write the response 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).
- Call
gcoap.h::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.h::gcoap_response()
to write the full response. Alternatively, you still can use gcoap.h::gcoap_resp_init()
and gcoap.h::gcoap_finish()
, as described above. In fact, the gcoap.h::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 to prepare and send a request:
Allocate a buffer and a coap_pkt_t for the request.
If there is a payload, follow the steps below.
- Call
gcoap.h::gcoap_req_init()
to initialize the request.- Optionally, mark the request confirmable by calling
nanocoap.h::coap_hdr_set_type()
with COAP_TYPE_CON.
- Optionally, mark the request confirmable by calling
- Write the request payload, starting at the updated payload pointer in the coap_pkt_t.
- Call
gcoap.h::gcoap_finish()
, which updates the packet for the payload.
If no payload, call only gcoap.h::gcoap_request()
to write the full request. Alternatively, you still can use gcoap.h::gcoap_req_init()
and gcoap.h::gcoap_finish()
, as described above. The gcoap.h::gcoap_request()
function is inline, and uses those two functions.
Finally, call gcoap.h::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.
- Test for a server response or timeout in the req_state callback parameter. See the GCOAP_MEMO… constants.
- Test the response with
nanocoap.h::coap_get_code_class()
andnanocoap.h::coap_get_code_detail()
. - Test the response payload with the coap_pkt_t payload_len and content_type attributes.
- Read the payload, if any.
Creating a request¶
Here is the expected sequence to prepare and send a request:
Allocate a buffer and a coap_pkt_t for the request.
If there is a payload, follow the steps below.
- Call
gcoap.h::gcoap_req_init()
to initialize the request.- Optionally, mark the request confirmable by calling
nanocoap.h::coap_hdr_set_type()
with COAP_TYPE_CON.
- Optionally, mark the request confirmable by calling
- Write the request payload, starting at the updated payload pointer in the coap_pkt_t.
- Call
gcoap.h::gcoap_finish()
, which updates the packet for the payload.
If no payload, call only gcoap.h::gcoap_request()
to write the full request. Alternatively, you still can use gcoap.h::gcoap_req_init()
and gcoap.h::gcoap_finish()
, as described above. The gcoap.h::gcoap_request()
function is inline, and uses those two functions.
Finally, call gcoap.h::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.
- Test for a server response or timeout in the req_state callback parameter. See the GCOAP_MEMO… constants.
- Test the response with
nanocoap.h::coap_get_code_class()
andnanocoap.h::coap_get_code_detail()
. - Test the response payload with the coap_pkt_t payload_len and content_type attributes.
- Read the payload, if any.
Observe Server Operation¶
A CoAP client may register for Observe notifications for any resource that an application has registered with gcoap. An application does not need to take any action to support Observe client registration. However, gcoap limits registration for a given resource to a single observer.
An Observe notification is considered a response to the original client registration request. So, the Observe server only needs to create and send the notification no further communication or callbacks are required.
Creating a notification¶
Here is the expected sequence to prepare and send a notification:
Allocate a buffer and a coap_pkt_t for the notification, then follow the steps below.
- Call
gcoap.h::gcoap_obs_init()
to initialize the notification for a resource. Test the return value, which may indicate there is not an observer for the resource. If so, you are done. - Write the notification payload, starting at the updated payload pointer in the coap_pkt_t.
- Call
gcoap.h::gcoap_finish()
, which updates the packet for the payload.
Finally, call gcoap.h::gcoap_obs_send()
for the resource.
Other considerations¶
By default, the value for the Observe option in a notification is three bytes long. For resources that change slowly, this length can be reduced via GCOAP_OBS_VALUE_WIDTH.
A client always may re-register for a resource with the same token or with a new token to indicate continued interest in receiving notifications about it. Of course the client must not already be using any new token in the registration for a different resource. Successful registration always is indicated by the presence of the Observe option in the response.
To cancel registration, the server expects to receive a GET request with the Observe option value set to 1. The server does not support cancellation via a reset (RST) response to a non-confirmable notification.
Creating a notification¶
Here is the expected sequence to prepare and send a notification:
Allocate a buffer and a coap_pkt_t for the notification, then follow the steps below.
- Call
gcoap.h::gcoap_obs_init()
to initialize the notification for a resource. Test the return value, which may indicate there is not an observer for the resource. If so, you are done. - Write the notification payload, starting at the updated payload pointer in the coap_pkt_t.
- Call
gcoap.h::gcoap_finish()
, which updates the packet for the payload.
Finally, call gcoap.h::gcoap_obs_send()
for the resource.
Other considerations¶
By default, the value for the Observe option in a notification is three bytes long. For resources that change slowly, this length can be reduced via GCOAP_OBS_VALUE_WIDTH.
A client always may re-register for a resource with the same token or with a new token to indicate continued interest in receiving notifications about it. Of course the client must not already be using any new token in the registration for a different resource. Successful registration always is indicated by the presence of the Observe option in the response.
To cancel registration, the server expects to receive a GET request with the Observe option value set to 1. The server does not support cancellation via a reset (RST) response to a non-confirmable notification.
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.h::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.
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.h::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.
Implementation Status¶
gcoap includes server and client capability. Available features include:
- Message Type: Supports non-confirmable (NON) messaging. Additionally provides a callback on timeout. Provides piggybacked ACK response to a confirmable (CON) request.
- Observe extension: Provides server-side registration and notifications.
- Server and Client provide helper functions for writing the response/request. See the CoAP topic in the source documentation for details. See the gcoap example for sample implementations.
- Server allows an application to register a ‘listener’, which includes an array of endpoint paths and function callbacks used to write a response.
- Server listens on a port at startup; defaults to 5683.
- Client operates asynchronously; sends request and then handles response in a user provided callback.
- Client generates token; length defined at compile time.
- Options: Supports Content-Format for payload.
-
GCOAP_MEMO_UNUSED
¶ This memo is unused.
1
(0)
-
GCOAP_MEMO_WAIT
¶ Request sent; awaiting response.
1
(1)
-
GCOAP_MEMO_RESP
¶ Got response.
1
(2)
-
GCOAP_MEMO_TIMEOUT
¶ Timeout waiting for response.
1
(3)
-
GCOAP_MEMO_ERR
¶ Error processing response packet.
1
(4)
-
GCOAP_OBS_MEMO_UNUSED
¶ This memo is unused.
1
(0)
-
GCOAP_OBS_MEMO_IDLE
¶ Registration OK; no current activity.
1
(1)
-
GCOAP_OBS_MEMO_PENDING
¶ Resource changed; notification pending.
1
(2)
-
GCOAP_OBS_INIT_OK
¶ 1
(0)
-
GCOAP_OBS_INIT_ERR
¶ 1
(-1)
-
GCOAP_OBS_INIT_UNUSED
¶ 1
(-2)
-
struct gcoap_listener
gcoap_listener_t
¶ A modular collection of resources for a server.
-
void(*
gcoap_resp_handler_t
()¶ Handler function for a server response, including the state for the originating request.
If request timed out, the packet header is for the request.
-
kernel_types.h::kernel_pid_t
gcoap_init
(void)¶ Initializes the gcoap thread and device.
Must call once before first use.
Return values
- 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_register_listener
(gcoap.h::gcoap_listener_t
* listener)¶ Starts listening for resource paths.
Parameters
listener: Listener containing the resources.
-
int
gcoap_req_init
(coap_pkt_t * pdu, uint8_t * buf,msp430_types.h::size_t
len, unsigned code, const char * path)¶ Initializes a CoAP request PDU on a buffer.
Parameters
pdu: Request metadata buf: Buffer containing the PDU len: Length of the buffer code: Request code: GCOAP_[GET|POST|PUT|DELETE] path: Resource path, must start with ‘/’ Return values
- 0 on success
- < 0 on error
-
msp430_types.h::ssize_t
gcoap_finish
(coap_pkt_t * pdu,msp430_types.h::size_t
payload_len, unsigned format)¶ Finishes formatting a CoAP PDU after the payload has been written.
Assumes the PDU has been initialized with a gcoap_xxx_init() function, like
gcoap.h::gcoap_req_init()
.Parameters
pdu: Request metadata payload_len: Length of the payload, or 0 if none format: Format code for the payload; use COAP_FORMAT_NONE if not specified Return values
- size of the PDU
- < 0 on error
-
msp430_types.h::ssize_t
gcoap_request
(coap_pkt_t * pdu, uint8_t * buf,msp430_types.h::size_t
len, unsigned code, char * path)¶ Writes a complete CoAP request PDU when there is not a payload.
Parameters
pdu: Request metadata buf: Buffer containing the PDU len: Length of the buffer code: Request code: GCOAP_[GET|POST|PUT|DELETE] path: Resource path, must start with ‘/’ Return values
- size of the PDU within the buffer
- < 0 on error
-
msp430_types.h::size_t
gcoap_req_send2
(const uint8_t * buf,msp430_types.h::size_t
len, constsock/udp.h::sock_udp_ep_t
* remote,gcoap.h::gcoap_resp_handler_t
resp_handler)¶ Sends a buffer containing a CoAP request to the provided endpoint.
Parameters
buf: Buffer containing the PDU len: Length of the buffer remote: Destination for the packet resp_handler: Callback when response received, may be NULL Return values
- length of the packet
- 0 if cannot send
-
msp430_types.h::size_t
gcoap_req_send
(const uint8_t * buf,msp430_types.h::size_t
len, const ipv6_addr_t * addr, uint16_t port,gcoap.h::gcoap_resp_handler_t
resp_handler)¶ Sends a buffer containing a CoAP request to the provided host/port.
Please use
gcoap.h::gcoap_req_send2()
insteadParameters
buf: Buffer containing the PDU len: Length of the buffer addr: Destination for the packet port: Port at the destination resp_handler: Callback when response received, may be NULL Return values
- length of the packet
- 0 if cannot send
-
int
gcoap_resp_init
(coap_pkt_t * pdu, uint8_t * buf,msp430_types.h::size_t
len, unsigned code)¶ Initializes a CoAP response packet on a buffer.
Initializes payload location within the buffer based on packet setup.
Parameters
pdu: Response metadata buf: Buffer containing the PDU len: Length of the buffer code: Response code Return values
- 0 on success
- < 0 on error
-
msp430_types.h::ssize_t
gcoap_response
(coap_pkt_t * pdu, uint8_t * buf,msp430_types.h::size_t
len, unsigned code)¶ Writes a complete CoAP response PDU when there is no payload.
Parameters
pdu: Response metadata buf: Buffer containing the PDU len: Length of the buffer code: Response code Return values
- size of the PDU within the buffer
- < 0 on error
-
int
gcoap_obs_init
(coap_pkt_t * pdu, uint8_t * buf,msp430_types.h::size_t
len, const coap_resource_t * resource)¶ Initializes a CoAP Observe notification packet on a buffer, for the observer registered for a resource.
First verifies that an observer has been registered for the resource.
Parameters
pdu: Notification metadata buf: Buffer containing the PDU len: Length of the buffer resource: Resource for the notification Return values
- GCOAP_OBS_INIT_OK on success
- GCOAP_OBS_INIT_ERR on error
- GCOAP_OBS_INIT_UNUSED if no observer for resource
-
msp430_types.h::size_t
gcoap_obs_send
(const uint8_t * buf,msp430_types.h::size_t
len, const coap_resource_t * resource)¶ Sends a buffer containing a CoAP Observe notification to the observer registered for a resource.
Assumes a single observer for a resource.
Parameters
buf: Buffer containing the PDU len: Length of the buffer resource: Resource to send Return values
- length of the packet
- 0 if cannot send
-
uint8_t
gcoap_op_state
(void)¶ Provides important operational statistics.
Useful for monitoring.
Return values
- count of unanswered requests
-
int
gcoap_get_resource_list
(void * buf,msp430_types.h::size_t
maxlen, uint8_t cf)¶ Get the resource list, currently only
CoRE Link Format
(COAP_FORMAT_LINK) supported.If
buf
:= NULL, nothing will be written but the size of the resulting resource list is computed and returned.Parameters
buf: output buffer to write resource list into, my be NULL maxlen: length of buf
, ignored ifbuf
is NULLcf: content format to use for the resource list, currently only COAP_FORMAT_LINK supported add support for
JSON CoRE Link Format
add support for ‘CBOR CoRE Link Format`
Return values
- the number of bytes written to
buf
- -1 on error
- the number of bytes written to
-
int
gcoap_add_qstring
(coap_pkt_t * pdu, const char * key, const char * val)¶ Adds a single Uri-Query option to a CoAP request.
To add multiple Uri-Query options, simply call this function multiple times. The Uri-Query options will be added in the order those calls.
Parameters
pdu: The package that is being build key: Key to add to the query string val: Value to assign to key
(may be NULL)Return values
- overall length of new query string
- -1 on error
-
GCOAP_MSG_QUEUE_SIZE
¶ Size for module message queue.
1
(4)
-
GCOAP_PORT
¶ Server port; use RFC 7252 default if not defined.
1
(5683)
-
GCOAP_PDU_BUF_SIZE
¶ Size of the buffer used to build a CoAP request or response.
1
(128)
-
GCOAP_REQ_WAITING_MAX
¶ Maximum number of requests awaiting a response.
1
(2)
-
GCOAP_TOKENLEN_MAX
¶ Maximum length in bytes for a token.
1
(8)
-
GCOAP_HEADER_MAXLEN
¶ Maximum length in bytes for a header, including the token.
1
(sizeof(coap_hdr_t) + GCOAP_TOKENLEN_MAX)
-
GCOAP_TOKENLEN
¶ Length in bytes for a token; use 2 if not defined.
1
(2)
-
GCOAP_PAYLOAD_MARKER
¶ Marks the boundary between header and payload.
1
(0xFF)
-
GCOAP_SEND_LIMIT_NON
¶ Value for send_limit in request memo when non-confirmable type.
1
(-1)
-
GCOAP_RECV_TIMEOUT
¶ Time in usec that the event loop waits for an incoming CoAP message.
1
(1 * US_PER_SEC)
-
GCOAP_NON_TIMEOUT
¶ Default time to wait for a non-confirmable response [in usec].
1
(5000000U)
Set to 0 to disable timeout.
-
GCOAP_MSG_TYPE_TIMEOUT
¶ Identifies waiting timed out for a response to a sent message.
1
(0x1501)
-
GCOAP_MSG_TYPE_INTR
¶ Identifies a request to interrupt listening for an incoming message on a sock.
1
(0x1502)
Allows the event loop to process IPC messages.
-
GCOAP_OBS_CLIENTS_MAX
¶ Maximum number of Observe clients; use 2 if not defined.
1
(2)
-
GCOAP_OBS_REGISTRATIONS_MAX
¶ Maximum number of registrations for Observable resources; use 2 if not defined.
1
(2)
-
GCOAP_OBS_VALUE_WIDTH
¶ Width in bytes of the Observe option value for a notification.
1
(3)
This width is used to determine the length of the ‘tick’ used to measure the time between observable changes to a resource. A tick is expressed internally as GCOAP_OBS_TICK_EXPONENT, which is the base-2 log value of the tick length in microseconds.
The canonical setting for the value width is 3 (exponent 5), which results in a tick length of 32 usec, per sec. 3.4, 4.4 of the RFC. Width 2 (exponent 16) results in a tick length of ~65 msec, and width 1 (exponent 24) results in a tick length of ~17 sec.
The tick length must be short enough so that the Observe value strictly increases for each new notification. The purpose of the value is to allow a client to detect message reordering within the network latency period (128 sec). For resources that change only slowly, the reduced message length is useful when packet size is limited.
-
GCOAP_OBS_TICK_EXPONENT
¶ See GCOAP_OBS_VALUE_WIDTH.
1
(5)
-
GCOAP_STACK_SIZE
¶ Stack size for module thread.
1 2
(THREAD_STACKSIZE_DEFAULT + DEBUG_EXTRA_STACKSIZE \ + sizeof(coap_pkt_t))
-
GCOAP_RESEND_BUFS_MAX
¶ Count of PDU buffers available for resending confirmable messages.
1
(1)
-
struct
gcoap_listener
¶ A modular collection of resources for a server.
-
const coap_resource_t *
resources
¶ First element in the array of resources; must order alphabetically.
-
msp430_types.h::size_t
resources_len
¶ Length of array.
-
struct gcoap_listener *
next
¶ Next listener in list.
-
const coap_resource_t *
-
struct
gcoap_resend_t
¶ Extends request memo for resending a confirmable request.
-
uint8_t *
pdu_buf
¶ Buffer containing the PDU.
-
msp430_types.h::size_t
pdu_len
¶ Length of pdu_buf.
-
uint8_t *
-
struct
gcoap_request_memo_t
¶ Memo to handle a response for a request.
-
unsigned
state
¶ State of this memo, a GCOAP_MEMO…
-
int
send_limit
¶ Remaining resends, 0 if none; GCOAP_SEND_LIMIT_NON if non-confirmable.
-
uint8_t
hdr_buf
()¶ Copy of PDU header, if no resends.
-
gcoap_resend_t
data
¶ Endpoint and PDU buffer, for resend.
-
union gcoap_request_memo_t::@187
msg
¶ Request message data; if confirmable, supports resending message.
-
sock/udp.h::sock_udp_ep_t
remote_ep
¶ Remote endpoint.
-
gcoap.h::gcoap_resp_handler_t
resp_handler
¶ Callback for the response.
-
xtimer.h::xtimer_t
response_timer
¶ Limits wait for response.
-
unsigned
-
struct
gcoap_observe_memo_t
¶ Memo for Observe registration and notifications.
-
sock/udp.h::sock_udp_ep_t
*observer
¶ Client endpoint; unused if null.
-
const coap_resource_t *
resource
¶ Entity being observed.
-
uint8_t
token
()¶ Client token for notifications.
-
unsigned
token_len
¶ Actual length of token attribute.
-