gcoap Status

gcoap is a native implementation of CoAP for RIOT. It uses nanocoap for base functionality.

gcoap runs in its own thread. Client messages are processed asynchronously: a response is received via a callback from the gcoap thread. The gcoap thread also acts as a CoAP server that executes callbacks for application defined resources.

Feature Status

Feature	Description
Confirmable message type	Supports piggybacked ACKs; see #7192 for details and roadmap
Observe extension	Implemented server for non-confirmable message type; see #7548 for confirmable message type
Block extension	Complete, from nanocoap Packet API

Learning More

See the online API documentation for gcoap itself, as well as generic CoAP definitions. Also see a feature comparison with nanocoap.

Examples

App	Description
examples/gcoap	Generic command line message client, also server
examples/cord_epsim	Resource directory endpoint client
examples/cord_ep	Full resource directory endpoint client
applications: coap-chat	Command line chat demo
kb2ma: data collection	Uses Observe extension to push data read via SAUL API to a server

Open PRs

Feature	Description
Add DTLS support #12104	Waiting for dependent PRs
Context parameter for request #9857	In process

See all open 'gcoap' PRs and Issues. See all CoAP-tagged PRs and Issues.

Roadmap

Almost finished with #9309 for combined gcoap and nanocoap roadmap for options handling. As of 11/2019, only need to deprecate gcoap_finish().

With #9156, gcoap uses the same mechanism as nanocoap for options. This change opens the gate for the changes below.

• Move the implementation of gcoap_add_qstring() to a new function coap_add_qstring() in nanocoap. Also update coap_get_uri_query() to use NANOCOAP_QS_MAX for maximum length of a query string read from a message.
• #9000 increased gcoap stack size. A significant source of the problem was the size of the coap_pkt_t struct for gcoap, and #9156 reduces that struct size. Create a PR to reset stack size.

Below are other features we have in mind.

• #12838 deprecates gcoap_finish() Update the cord_epsim module to use coap_opt_finish() instead.
• Presently, a client rejects a response from a multicast request because the response origin address does not match the request destination address. #9857 provides the data for a client to handle this situation.
• #9310 added behavior to the client to not wait for a response to a non-confirmable request when the user does not specify a response handler. Continue this work with client and server support for RFC 7967, which specifies a No-Response option to ask the server not to send a response to certain requests.
• Add OSCORE support. #11761 provides an outline for this plan. We continued discussion at the 9/2019 RIOT summit.
• Update sock_udp_recv API to return -EINTR when the caller interrupts waiting in blocking mode. Presently the gnrc implementation returns -EINVAL (-22) in this case. This use is a hack because it extends the existing, intended meaning of -EINVAL. The interrupt causes a message to display in gcoap when debug output is enabled, which is confusing because it looks like a real error.
• Update documentation for GCOAP_PDU_BUF_SIZE. This size also is used to read an incoming message. If the message is too big for the buffer, gcoap silently drops it. You can see this in debug mode with "udp recv failure: -105" (ENOBUFS). When does it make sense to return a 4.13 Request Entity Too Large?
• Add a typedef for coap_block_t from the coap_block1_t struct. The original name was used because we first implemented block1 (request-based) blockwise transfer.
• #11093 adds definitions for the new methods FETCH, PATCH, and iPATCH. Add full support for them.
• Run and report on the ETSI CoAP Plugtest tests. These reports are described in @cabo's td-coap4 repository. He also provides a test client and server at coap.me. Thanks, Carsten!

Milestones

Release	Description
2019.10	Use complete nanocoap blockwise implementation (#10732)
2019.01	Use the new struct-based nanocoap options API (#9156). See API Options for details.
2018.01	Request retries for piggybacked ACK response (#7337)
2017.07	Server side of the Observe protocol (#6469)
2017.01	Reimplement networking code to use sock rather than GNRC (#6117)
2016.10	GNRC-based gcoap (#5598)