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	Not implemented, but should be able to reuse/build-on nanocoap implementation

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/rdcli_simple	Resource directory client
examples/rdcli	Full resource directory 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
Context parameter for request #9857	In process
Document user configurable macros #10676, #10677. See #10566 for the list of macros.	In process
See all open 'gcoap' PRs and Issues. See all CoAP-tagged PRs and Issues.

Roadmap

See #9309 for combined gcoap and nanocoap roadmap for options handling. As of 11/2018, much of this work has been completed.

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.
• Update the gcoap module documentation to describe how to use options for more flexibility.
• Confirm gcoap supports use of the Block1 and Block2 options.
• #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.

• 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.
• coap_put_block1_ok() does not include a Block1 option in the final response (more = 0). Sec. 3.2 examples of RFC 7959 show that the final response must include this option. Fix coap_put_block1_ok().
• #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. Message posted late 2018 on IETF CORE mailing list suggests we may be able to adapt an existing implementation soon.
• Add DTLS support. See branch and discussion in #9450.
• 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?

Milestones

Release	Description
pending	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)