CoAP Client

This sample demonstrates the communication between a public CoAP server and a CoAP client application that is running on a Nordic Semiconductor SoC that enables IP networking through cellular or Wi-Fi® connectivity.

Cellular connectivity is supported on the nRF91 Series SiPs, while Wi-Fi connectivity is supported on the nRF53 or nRF54 Series SoCs hosting the nRF70 Series Wi-Fi companion ICs.

The sample uses the connection manager that provides a common connectivity API for LTE and Wi-Fi stacks.

Requirements 

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target	Shields
Thingy:91	PCA20035	thingy91	`thingy91/nrf9160/ns`
nRF9161 DK	PCA10153	nrf9161dk	`nrf9161dk/nrf9161/ns`
nRF9160 DK	PCA10090	nrf9160dk	`nrf9160dk/nrf9160/ns`
nRF9151 DK	PCA10171	nrf9151dk	`nrf9151dk/nrf9151/ns`
nRF7120 DK		nrf7120dk	`nrf7120dk/nrf7120/cpuapp/ns`
nRF7002 DK	PCA10143	nrf7002dk	`nrf7002dk/nrf5340/cpuapp/ns`
nRF54LM20 DK	PCA10184	nrf54lm20dk	`nrf54lm20dk/nrf54lm20b/cpuapp` `nrf54lm20dk/nrf54lm20a/cpuapp`	`"nrf7002eb2"`
nRF54H20 DK	PCA10175	nrf54h20dk	`nrf54h20dk/nrf54h20/cpuapp`	`"nrf7002eb_interposer_p1;nrf7002eb"`
Native Simulator		native_sim	`native_sim`

The sample also requires a public CoAP server IP address or URL available on the Internet.

For more security, it is recommended to use the */ns variant of the board target. When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

Overview 

The CoAP Client sample performs the following actions:

Connect to the configured public CoAP test server.
Send a periodic GET request for a test resource that is available on the server.
Display the received data about the resource on a terminal emulator.

The public CoAP server used in this sample is Californium CoAP server (coap://californium.eclipseprojects.io:5683). This server runs Eclipse Californium, which is an open source implementation of the CoAP protocol that is targeted at the development and testing of IoT applications.

This sample uses the resource obs (Californium observable resource) in the communication between the CoAP client and the public CoAP server. The communication follows the standard request/response pattern and is based on the change in the state of the value of the resource. The sample queries one resource at a time.

Selecting the server and resource 

The server and resource to query are configured with Kconfig options and default to the Californium test server:

CONFIG_COAP_SAMPLE_SERVER_HOSTNAME and CONFIG_COAP_SAMPLE_SERVER_PORT- The CoAP server to connect to.
CONFIG_COAP_SAMPLE_RESOURCE- The resource to query on that server.

Mutual DTLS (client certificate authentication)

The sample can optionally use DTLS to secure the CoAP communication (CoAPS), with client authentication (mutual TLS).

Note

This functionality is only supported on Wi-Fi boards and not on cellular boards.

Enable the CONFIG_COAP_SAMPLE_DTLS option to provision a CA certificate, a client certificate, and a client private key, and to connect over CoAPS using mutual X.509 authentication. Set CONFIG_COAP_SAMPLE_CA_CERT_FILE, CONFIG_COAP_SAMPLE_CLIENT_CERT_FILE, and CONFIG_COAP_SAMPLE_CLIENT_KEY_FILE to the CA certificate, client certificate, and client private key to provision, matching what the server you connect to expects.

The sample includes an example CA trust chain and client certificate and private key under cert/, for use against the Eclipse Californium CoAP interoperability server:

cert/cf-ca.pem — CA trust chain, used to validate the server certificate
cert/cf-client.pem — client certificate
cert/cf-client-key.pem — client private key (EC P-256)

The wifi-dtls.conf extra-conf file configures the sample with mutual X.509 authentication and the cipher suite needed for the Californium interop server.

Wi-Fi 

On Wi-Fi boards, use the wifi.conf extra-conf file, using the coap_client_EXTRA_CONF_FILE sysbuild variable. To perform mutual DTLS (CoAPS) with the Californium interoperability server (see Mutual DTLS (client certificate authentication)), add the wifi-dtls.conf extra-conf file on top of wifi.conf.

Configuration 

See Configuring and building for information about how to permanently or temporarily change the configuration.

Configuration options 

The following sample-specific Kconfig options are used in this sample (located in samples/net/coap_client/Kconfig):

CONFIG_COAP_SAMPLE_RESOURCE

(string) CoAP resource - defaults to Californium observable resource

CONFIG_COAP_SAMPLE_SERVER_HOSTNAME

(string) CoAP server hostname

CONFIG_COAP_SAMPLE_SERVER_PORT

(int) CoAP server port

CONFIG_COAP_SAMPLE_REQUEST_INTERVAL_SECONDS

(int) Request interval in seconds

CONFIG_COAP_SAMPLE_DTLS

(bool) Enable DTLS (CoAPS) with mutual X.509 authentication

Enable DTLS for CoAP (CoAPS) using mutual X.509 certificate authentication. When enabled, the default server port changes to 5684 and the socket is created with IPPROTO_DTLS_1_2.

CONFIG_COAP_SAMPLE_DTLS_SEC_TAG

(int) DTLS security tag

Security tag used to store the DTLS credentials.

CONFIG_COAP_SAMPLE_DTLS_HANDSHAKE_TIMEOUT_MAX_MS

(int) Maximum DTLS handshake retransmission timeout in milliseconds

Caps the DTLS handshake retransmission backoff, to avoid blocking for up to a minute.

CONFIG_COAP_SAMPLE_CA_CERT_FILE

(string) CA certificate file (PEM)

Path to the CA certificate used to verify the server. Relative to the sample root directory.

CONFIG_COAP_SAMPLE_CLIENT_CERT_FILE

(string) Client certificate file (PEM)

Path to the client certificate presented during mutual TLS.

CONFIG_COAP_SAMPLE_CLIENT_KEY_FILE

(string) Client private key file (PEM)

Path to the client private key.

Configuring Wi-Fi access point credentials 

This sample uses the Wi-Fi credentials library to manage Wi-Fi credentials. Before the sample can connect to a Wi-Fi network, you must configure at least one credential set.

Once you have flashed your device with this sample, connect to your device’s UART interface and add credentials using the following command:

wifi cred add -s NetworkSSID -k SecurityMode -p NetworkPassword

Where NetworkSSID is replaced with the SSID of the Wi-Fi access point you want your device to connect to, and NetworkPassword is its password. SecurityMode is replaced by the number as listed here:

0: None
1: WPA2-PSK
2: WPA2-PSK-256
3: SAE-HNP
4: SAE-H2E
5: SAE-AUTO
6: WAPI
7: EAP-TLS
8: WEP
9: WPA-PSK
10: WPA-Auto-Personal
11: DPP

If you are not sure which security mode to use, enable the CONFIG_NET_L2_WIFI_SHELL Kconfig option and use the wifi scan command to display a list of all accessible networks along with their corresponding security modes. Then either reboot the device or use the wifi cred auto_connect command to manually trigger a connection attempt.

From now on, these credentials will be automatically used when the configured network is reachable.

When building as firmware image for a non-secure board target, the Wi-Fi credentials backend will be set to PSA using TF-M.

See the Wi-Fi: Shell sample document for more details on the wifi cred command.

Wi-Fi static credential options

If you want to configure the credentials statically, set the CONFIG_WIFI_CREDENTIALS_STATIC Kconfig option to y.

Important

Do not use static credentials in production environments.

Other options for statically configuring your Wi-Fi credentials:

CONFIG_WIFI_CREDENTIALS_STATIC - This option enables static Wi-Fi configuration.
CONFIG_WIFI_CREDENTIALS_STATIC_SSID - Wi-Fi SSID.
CONFIG_WIFI_CREDENTIALS_STATIC_PASSWORD - Wi-Fi password.
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_OPEN - Wi-Fi network uses no password.
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_PSK - Wi-Fi network uses a password and PSK security (default).
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_PSK_SHA256 - Wi-Fi network uses a password and PSK-256 security.
CONFIG_WIFI_CREDENTIALS_STATIC_TYPE_SAE - Wi-Fi network uses a password and SAE security.

Sending traces over UART on an nRF91 Series DK 

To send modem traces over UART on an nRF91 Series DK, configuration must be added for the UART device in the devicetree and Kconfig. This is done by adding the modem trace UART snippet when building and programming.

Use the Cellular Monitor app for capturing and analyzing modem traces.

TF-M logging must use the same UART as the application. For more details, see shared TF-M logging.

Building and running 

This sample can be found under samples/net/coap_client in the nRF Connect SDK folder structure.

For more security, it is recommended to use the */ns variant of the board target (see the Requirements section above.) When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

Testing 

After programming the sample to your development kit, complete the following steps to test it:

Connect the kit to the computer using a USB cable. The kit is assigned a serial port. Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS. To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the nrfutil device list command. Alternatively, check your operating system’s device manager or its equivalent.
Connect to the kit with a terminal emulator (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.
Power on or reset the kit.
Observe that the following output is displayed in the terminal:
```
The CoAP client sample started
```
Observe that the discovered IP address of the public CoAP server is displayed on the terminal emulator.
Observe that your DK sends periodic CoAP GET requests to the configured server for a configured resource after it gets LTE connection.
Observe that the sample either displays the response data received from the server or indicates a timeout on the terminal. For more information on the response codes, see COAP response codes.

Sample output 

The sample displays the data in the following format:

CoAP GET request sent sent to californium.eclipseprojects.io, resource: obs
CoAP response: code: 0x45, payload: 15:29:45

Instead of displaying every single CoAP frame content, the sample displays only the essential data. For the above sample output, the information displayed on the terminal conveys the following:

code:0x45 - CoAP response code (2.05 - Content), which is constant across responses
payload: 15:39:40 - the actual message payload (current time in UTC format) from the resource that is queried in this sample

References 

RFC 7252 - The Constrained Application Protocol

Dependencies 

This sample uses the following Zephyr libraries: