1
2# CoAP client example
3
4(See the README.md file in the upper level 'examples' directory for more information about examples.)
5This CoAP client example is very simplified adaptation of one of the
6[libcoap](https://github.com/obgm/libcoap) examples.
7
8CoAP client example will connect your ESP32 device to a CoAP server, send off a GET request and
9fetch the response data from CoAP server.  The client can be extended to PUT / POST / DELETE requests,
10as well as supporting the Observer extensions [RFC7641](https://tools.ietf.org/html/rfc7641).
11
12If the URI is prefixed with coaps:// instead of coap://, then the CoAP client will attempt to use
13the DTLS protocol using the defined Pre-Shared Keys(PSK) or Public Key Infrastructure (PKI) which the
14CoAP server needs to know about.
15
16If the URI is prefixed with coap+tcp://, then the CoAP will try to use TCP for the communication.
17
18NOTE: coaps+tcp:// is not currently supported, even though both libcoap and MbedTLS support it.
19
20The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with
21constrained nodes and constrained networks in the Internet of Things.
22The protocol is designed for machine-to-machine (M2M) applications such as smart energy and
23building automation.
24
25Please refer to [RFC7252](https://www.rfc-editor.org/rfc/pdfrfc/rfc7252.txt.pdf) for more details.
26
27## How to use example
28
29### Configure the project
30
31```
32idf.py menuconfig
33```
34
35Example Connection Configuration  --->
36 * Set WiFi SSID under Example Configuration
37 * Set WiFi Password under Example Configuration
38Example CoAP Client Configuration  --->
39 * Set CoAP Target Uri
40 * If PSK, Set CoAP Preshared Key to use in connection to the server
41 * If PSK, Set CoAP PSK Client identity (username)
42Component config  --->
43  CoAP Configuration  --->
44    * Set encryption method definition, PSK (default) or PKI
45    * Enable CoAP debugging if required
46  High resolution timer (esp_timer)  --->
47    * Hardware timer to use for esp_timer - change if required (FRC2 for QEMU)
48
49### Build and Flash
50
51Build the project and flash it to the board, then run monitor tool to view serial output:
52
53```
54idf.py build
55idf.py -p PORT flash monitor
56```
57
58(To exit the serial monitor, type ``Ctrl-]``.)
59
60See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
61
62## Example Output
63Prerequisite: we startup a CoAP server on coap server example,
64or use the default of coap://californium.eclipseprojects.io.
65
66and you could receive data from CoAP server if succeed,
67such as the following log:
68
69```
70...
71I (332) wifi: mode : sta (30:ae:a4:04:1b:7c)
72I (1672) wifi: n:11 0, o:1 0, ap:255 255, sta:11 0, prof:1
73I (1672) wifi: state: init -> auth (b0)
74I (1682) wifi: state: auth -> assoc (0)
75I (1692) wifi: state: assoc -> run (10)
76I (1692) wifi: connected with huawei_cw, channel 11
77I (1692) wifi: pm start, type: 1
78
79I (2582) event: sta ip: 192.168.3.89, mask: 255.255.255.0, gw: 192.168.3.1
80I (2582) CoAP_client: Connected to AP
81I (2582) CoAP_client: DNS lookup succeeded. IP=35.185.40.182
82Received:
83****************************************************************
84CoAP RFC 7252                                  Cf 3.0.0-SNAPSHOT
85****************************************************************
86This server is using the Eclipse Californium (Cf) CoAP framework
87published under EPL+EDL: http://www.eclipse.org/californium/
88
89(c) 2014-2020 Institute for Pervasive Computing, ETH Zurich and others
90****************************************************************
91...
92```
93
94## libcoap Documentation
95This can be found at [libcoap Documentation](https://libcoap.net/documentation.html).
96The current API is 4.3.0.
97
98## libcoap Specific Issues
99These can be raised at [libcoap Issues](https://github.com/obgm/libcoap/issues).
100
101## Troubleshooting
102* Please make sure Target Url includes valid `host`, optional `port`,
103optional `path`, and begins with `coap://`, `coaps://` or `coap+tcp://`
104for a coap server that supports TCP
105(not all do including coap+tcp://californium.eclipseprojects.io).
106
107* CoAP logging can be enabled by running 'idf.py menuconfig -> Component config -> CoAP Configuration' and setting appropriate log level
108