This information applies to the following SoftDevices: S132, S140
The CoAP over DTLS Client example demonstrates how DTLS can be integrated to Nordic's CoAP implementation for the client role.
The supplied CoAP client example has the same behavior as the CoAP client examples in terms of access of resources on the server. However, to enable secure communication perform security setup to the remote server using the coap_security_setup API.
This example application, although referred to as CoAP client, is technically an example of concurrent CoAP Client and Server implementation. And it is possible to setup DTLS sessions for both server and client roles simultaneously. Maximum concurrent DTLS sessions in the example are limited to 2. The example tear down security setup with a peer when the bluetooth link is disconnected. Refer coap_security_destroy for on tearing down a DTLS session.
As a CoAP Client, this application sends LED state control requests to the Light Server Example application, as demonstrated in Figure 1. For the first message initiated by this client example, DTLS handshake is initiated and the message is buffered until handshake is complete.
- Warning
- TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 cipher is not supported in the current DTLS configuration.
Figure 1: Setup of the CoAP client with Light server application
Additionally, as a CoAP Server, temperature is exposed as a resource that can be GET and PUT from the CoAP client on the PC and shown in Figure 2.
Figure 2: Setup of the CoAP client application
These examples are designed to complement the CoAP server example applications. The server is identified by its IPv6 address, which needs to be configured in main.c
.
The client examples also implement an endpoint that hosts the following resources:
host
|-- .well-known
| `-- core
`-- sensors
`-- thermometer
The thermometer resource simply stores an integer value in the range of -100 to +100, to demonstrate that the device can be set up to work as a CoAP client and server concurrently.
Configuration parameters for all used modules are defined and described in the sdk_config.h file. This file is located in the config subfolder of the main application folder.
- Warning
- As already mentioned, the DTLS state can be maintained only for one role at any given point and accessing both roles simultaneously may result in undesired, unexpected behavior.
- Note
- This application is not power optimized!
-
This application will start advertising again after disconnection.
Common module dependency and usage
This section summarizes the usage of nRF5x resources and common modules in the examples apart from the IoT 6lowpan and IPv6 stack library.
Module | Inclusion/Usage | Description |
Timer | 2 | Two timers are used one for IoT timer and the other for the button module. |
Buttons | 2 | Buttons are used for initiating CoAP requests. See Button assignments. |
LEDs | 4 | LEDs are used to indicate the application states. See LED assignments. |
Adv Data Encoder | Yes | The device name used is 'DTLS-COAPClient', IPSP Service UUID is included in the UUID list. |
RNG Driver | Yes | Random number generator is used for security procedures in mbed TLS library. |
Scheduler | Yes | Scheduler is used for processing stack events. |
Setup
The example uses Nordic's IPv6 stack to set up the CoAP server with DTLS is implemented using the mbedTLS library. You can find the source code and the project file of the example in the following folder: <InstallFolder>\examples\iot\dtls\coap_client
LED assignments
- After sending a CoAP request by pressing either Button 1 or Button 2, LED 3 blinks once if the received response code is "2.04 - Changed", as expected. LED 4 blinks once if any other response code is received. Both are turned on in case of an assertion failure in the application.
- LED 1 and LED 2 display the state of the application, as described in the table below.
LED 1 | LED 2 | |
Blinking | Off | Device advertising as BLE peripheral. |
On | Blinking | BLE link established, IPv6 interface down. |
Off | On | BLE link established, IPv6 interface up. |
On | On | Assertion failure in the application. |
Button assignments
- Button 1: send a CoAP request to the peer running the CoAP server example to toggle LED 3.
- Button 2: send a CoAP request to the peer running the CoAP server example to toggle LED 4.
- Note
- If commissioning is enabled, additional LED and Button assignments are made.
Testing
This example is designed to work with the CoAP over DTLS Server example. However, if only one nRF5x DK is available, the Californium CoAP Framework can be used as a secure CoAP Server on a PC.
See Connecting devices to the router for a list of relevant Linux commands.
- Edit
main.c
to set the correct IPv6 server address.
- Compile and program the application. Observe that the device is advertising.
- Prepare the Linux router device by initializing the 6LoWPAN module.
- Discover the advertising device by using the hcitool lescan command.
- Connect to the discovered device from the Linux console by using the Bluetooth 6LoWPAN connect command.
- Check if the connected state is reflected by the LEDs.
- Run the Wireshark or tshark program to monitor the btX interface.
- An ICMPv6 ping can be used on the link-local and on the global IPv6 address assigned to the device to check if the device is reachable.
- Note
- To find the global address, use the prefix assigned to the interface in Router Advertisement.
- As a CoAP client, this application can be used to toggle LED 3 and LED 4 on a peer.
- Note
- On the first request, a DTLS handshake is requested and application must retry the request once the handshake is complete. The handshake takes a few seconds to complete.
- Disconnect from the device using the Bluetooth 6LoWPAN disconnect command.
- Observe that the device is advertising.
Known Issues
Below is a summary of known issues with the example.
- The first CoAP request that triggers the DTLS handshake message is not transmitted and the application must retry once the handshake is complete. The handshake takes a few seconds to complete.
- If the DTLS handshake fails, no indication is provided to the application of the same. And there is no way to recover from this situation apart from disconnecting the BLE link and trying it again.
- There is no indication on the LEDs, when the handshake is successfully complete. The only way to conclusively establish this is using wireshark or tshark.
Troubleshooting Guide
- It is possible that the global address is not immediately available on the connection as the Neighbor Discovery, Router Advertisement, and Duplicate Address Detection procedures take a few seconds to complete.
- If you observe that the CoAP server responses are received at the btX interface but the CoAP client device never receives them, it is possible that the forwarding between networks is not enabled. This can be done on Linux using the command
sysctl -w net.ipv6.conf.all.forwarding=1
.
- In case the CoAP client device is reachable, but the requests from the CoAP client device do not make it to the server, it is possible that the application is not configured with the correct remote server address. Verify that the address SERVER_IPV6_ADDRESS in the client application matches the server address.