CoAP Server

The CoAP Server sample demonstrates how to register CoAP resources and respond to CoAP requests from a client, using Zephyr’s CoAP server subsystem. It runs on an nRF71 Series or nRF70 Series device connected over Wi-Fi®.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Board target

nRF7120 DK

nrf7120dk

nrf7120dk/nrf7120/cpuapp

nRF7002 DK

PCA10143

nrf7002dk

nrf7002dk/nrf5340/cpuapp

Overview

This is Zephyr’s CoAP service sample, built to run on the development kits listed on the Requirements section. The sample registers CoAP resources to a main CoAP service and responds to client requests for them over UDP. All services and resources must be available at compile time, as they are placed into dedicated linker sections.

The sample listens for requests on the default CoAP UDP port (5683, or 5684 for secure CoAP), over either IPv4 or IPv6 depending on the Wi-Fi snippet used to build it (see Wi-Fi). Over IPv6, the sample joins the site-local CoAP all-nodes multicast address. The server replies from the same local address a request arrived on, so a client sees a matching reply even when the device has more than one active address.

The sample serves plain CoAP by default. Building with the overlay-dtls.conf extra configuration file (see Configuration files) switches it to secure CoAP (CoAPS) over DTLS, using the PSK identity and key defined in the src/dummy_psk.h header file.

The DTLS service can also authenticate itself with a server certificate and private key (see src/certificate.h) instead of PSK, using a certificate-based cipher suite. By default, this is a self-signed demo certificate. Enabling the CONFIG_NET_SAMPLE_CERTS_WITH_SC Kconfig option switches the sample to a CA-signed certificate and its CA certificate instead, for testing proper certificate chain validation. It only builds in when an RSA or ECDSA ECDHE cipher suite is enabled, which the overlay-dtls.conf file does not select by default. To use it, add an extra configuration file on top of the overlay-dtls.conf file that selects a matching cipher suite, such as CONFIG_MBEDTLS_CIPHERSUITE_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 for the sample’s RSA demo certificate.

The sample exports the following resources:

/test
/seg1/seg2/seg3
/query
/separate
/large
/location-query
/large-update

These resources allow a good part of the ETSI test cases to be run against the sample.

The block-wise /large* endpoints track each client’s transfer separately, from a small fixed-size pool (see Configuration options). A new client is rejected with 5.03 Service Unavailable if the pool is full and every slot is still active.

The sample itself has no output on success beyond the logging described in Sample output. Verify its functionality using an external CoAP client, or a tool such as tcpdump or Wireshark to inspect the traffic.

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 zephyr/samples/net/sockets/coap_server/Kconfig):

  • CONFIG_NET_SAMPLE_COAPS_SERVICE - Enables the CoAP secure service (CoAPS) over DTLS.

  • CONFIG_NET_SAMPLE_COAP_SERVER_SERVICE_PORT - Port number for the CoAP service. Defaults to 5684 if the secure service is enabled, or 5683 otherwise.

  • CONFIG_NET_SAMPLE_COAP_MAX_LARGE_TRANSFERS - Maximum number of clients that can have a block-wise transfer in progress on the same /large* endpoint at once.

  • CONFIG_NET_SAMPLE_COAP_LARGE_TRANSFER_TIMEOUT_SEC - Idle time before a stalled client’s slot on a /large* endpoint can be reused by another client.

  • CONFIG_NET_SAMPLE_PSK_HEADER_FILE - Header file containing the pre-shared key used by the secure service.

  • CONFIG_NET_SAMPLE_CERTS_WITH_SC - Runs the secure service with signed certificates instead of a pre-shared 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 (not supported on Nordic Semiconductor Wi-Fi devices)

  • 7: EAP-TLS

  • 8: WEP

  • 9: WPA-PSK

  • 10: WPA-Auto-Personal

  • 11: DPP (not supported on Nordic Semiconductor Wi-Fi devices)

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:

Configuration files

The sample provides predefined configuration files, located in zephyr/samples/net/sockets/coap_server:

  • prj.conf - Default configuration file, used for plain (non-secure) CoAP.

  • overlay-dtls.conf - Additional configuration for secure CoAP (CoAPS) over DTLS.

To add a specific extra configuration file to the build, add the -DEXTRA_CONF_FILE=<extra_conf_file> flag to your west build command.

Wi-Fi

Use the wifi-ipv4 snippet to build and run the sample over IPv4, or the wifi-ipv6 snippet to run it over IPv6 instead, on the development kits that the sample supports.

Building and running

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

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.

Use the nrf7002dk/nrf5340/cpuapp or nrf7120dk/nrf7120/cpuapp board target together with the wifi-ipv4 or wifi-ipv6 snippet. For example:

# nRF7002 DK, IPv4
west build -b nrf7002dk/nrf5340/cpuapp -S wifi-ipv4

# nRF7120 DK, IPv4
west build -b nrf7120dk/nrf7120/cpuapp -S wifi-ipv4

# nRF7002 DK, IPv6
west build -b nrf7002dk/nrf5340/cpuapp -S wifi-ipv6

Alternatively, build against the predefined test case in the sample.yaml file:

west build -b nrf7120dk/nrf7120/cpuapp -T nrf.extended.sample.net.sockets.coap_server.wifi-ipv4

To build the sample with secure CoAP resources instead, add the overlay-dtls.conf extra configuration file on top of the base configuration.

Testing

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

  1. 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.

  2. Connect to the kit with a terminal emulator (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.

  3. Wait for the sample to connect to the configured Wi-Fi network, and note the IP address logged on the terminal.

  4. From a host on the same network, install libcoap (for example, sudo apt install libcoap3-bin on Ubuntu) and send a CoAP request to one of the resources listed in Overview:

    coap-client-notls -m get coap://<dut_ip_address>/test

    Replace <dut_ip_address> with the IP address of the development kit. Use -m put, -m post, or -m delete together with -e <data> to exercise the other CoAP methods, for example:

    coap-client-notls -m put -e "test data" coap://<dut_ip_address>/large-update

    For an IPv6 build, wrap the address in brackets instead: coap://[<dut_ipv6_address>]/test.

  5. Observe the response printed by coap-client, and the matching request logged by the sample on the terminal.

  6. Optionally, inspect the exchanged traffic with a tool such as Wireshark, or see the Wi-Fi: Monitor sample documentation to capture Wi-Fi traffic directly from the development kit.

To test the secure CoAP (CoAPS) variant, build with the overlay-dtls.conf extra configuration file (see Configuration files), then connect with a DTLS-PSK capable build of the client, such as coap-client-gnutls or coap-client-openssl, using the identity and key from the src/dummy_psk.h header file:

coap-client-gnutls -m get -u PSK_identity -k $'\x01\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f' coaps://<dut_ip_address>/test

The $'...' quoting passes the key’s raw bytes through the shell. Check coap-client --help if your build expects the key encoded differently.

Sample output

This is a typical log output of the sample:

[00:00:26.518,841] <inf> net_samples_common: Network connectivity established and IP address assigned
[00:00:27.568,380] <inf> net_coap_service_sample: *******
[00:00:27.568,391] <inf> net_coap_service_sample: type: 0 code 1 id 44042
[00:00:27.568,393] <inf> net_coap_service_sample: *******
[...]
[00:00:50.363,259] <inf> net_coap_service_sample: *******
[00:00:50.363,266] <inf> net_coap_service_sample: type: 0 code 1 id 29028
[00:00:50.363,273] <inf> net_coap_service_sample: num queries: 2
[00:00:50.363,285] <inf> net_coap_service_sample: query[1]: first=1
[00:00:50.363,298] <inf> net_coap_service_sample: query[2]: second=2
[00:00:50.363,303] <inf> net_coap_service_sample: *******
[...]
[00:00:50.411,302] <inf> net_coap_service_sample: CoAP observer added
[...]
[00:01:12.429,818] <inf> net_coap_service_sample: CoAP observer removed

The ******* lines bracket each request’s type, code, and ID. Some resources, such as /query, log extra detail in between.

Troubleshooting

If you have issues with connectivity on nRF71 Series or nRF70 Series devices, see the Wi-Fi: Monitor sample documentation to learn how to capture and analyze Wi-Fi traffic in order to debug connectivity issues. Also, verify that the Wi-Fi credentials configured for your device match your access point, as described in the Configuration options section on this page.

References

Dependencies

This sample uses the following Zephyr libraries: