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
Accept NULL path for gcoap_req_init() #10501	Waiting for review

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.
• 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().
• Add memory tuning section to module documentation. gcoap includes a number of compile-time macros that affect memory use. See #10566 for the list of macros.
• #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.

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)