Zephyr - Coaps Demo Client with Eclipse/TinyDtls

Reliable - Efficient - Encrypted

Version 0.9.0 - January 2024

This zephyr client demonstrates to use coaps (CoAP over DTLS 1.2) with the Eclipse/TinyDtls Library. In combination with Eclipse/Californium as Cloud-Server, it enables a device to use DTLS 1.2 Connection ID, which obsolete the commonly used frequently DTLS handshakes and eliminates that expensive overhead. Reducing the messages exchange mostly down to two ip-messages (one request, one response), it enables your device for

• reliable,
• efficient, and
• end-to-end encrypted

communication for messages up to a few hundred bytes. In combination with LTE-M/NB-IoT, CoAP / DTLS 1.2 CID enables to build mobile applications with

• zero-install and
• high cost-efficiency.

The demo client itself is in development stage. In "good and normal weather", the Thingy:91 flies from battery for 7 months. In "storm" it may require to be switched off and on again in very rare exceptions.

The demo client is intended as groundwork for your own ideas. "Out-of-the-box" this application is useful to easily check, if mobile IoT works at the locations and environment you want to use it. The demo reports also some details about the mobile networks functions. To build products and applications on this protocol stack requires to implement a production client and to adapt the coap-server for your function. The demo targets therefore people, which are already common with zephyr, or, even better, common with the development for the Thingy:91 itself. Without that knowledge it will be time consuming to make benefit out of this demo.

Note: The demo client is considered to use CoAP/DTLS 1.2 CID. Without server-side support for DTLS 1.2 CID, it will not work proper. Please ensure, that your server supports that.

Supported Devices

For now, only nRF9160 based devices are supported.

Device
Nordic Semiconductor, Thingy:91 Works "out-of-the-box" in the "wild". Not easy to extend with custom sensors.
Circuit Dojo, nRF9160 feather v5 Requires additional batteries, antennas, and closures to work in the "wild". The design of the feather allows to easily add custom sensors.
Nordic Semiconductor, nRF9160 DK Works "out-of-the-box" on the desk. The design allows to easily add custom sensors.

The demo works with ncs-2.6.0.

To benefit from the newer modem features, please consider to use the modem firmware 1.3.6. See "Getting started with Thingy:91" below how to apply it.

In the meantime it also supports the nRF9161-DK and the mfw 2.0.0 for that.

Maybe other modems and devices gets supported over the time as well. For some of the nRF9160 based devices porting should not be too hard.

nRF9160 based candidates
Sparkfun Thing Plus nRF9160 Qwiic and 2x5 plug for JTAG.
Icarus IoT Board v2 Includes a eSIM.
Conexio Stratus Built-in energy harvesting capability for autonomous operation. Includes a SIM card with 500MB in 10 years.
Fanstel LN60E Reduced to the minimum. Unfortunately the current version uses a LDO with 50µA quiescent current.
MIKROE LTE IoT 4 Click Even less, but with power LED. If you want to use it, remove the LED or cut the connects to the ground-plane next the LED.

Required HW-Tools for Thingy:91

In order to use this demo with a Thingy:91, you need:

• a Thingy:91 (maybe better two ;-)).
• the Thingy:91 is usually shipped with a SIM card. Check, if that covers your area/country. If not, you need a SIM card for your area/country. (Sometimes the Thingy:91 is shipped with an expired SIM card. Then you will need also an other one.)
• a debug probe to flash the device.
  • either a nRF9160-DK and a 10-wire-ribbon connector, 2x5, 0.050".
  • or a Segger j-Link and a cortex-M adapter.

Note: the Thingy:91 uses 1.8V VDD and requires the Jlink to support 1.8V as well. Not all Jlinks supporting that, ensure you get a right one! If the nRF9160-DK is used, ensure you select 1.8V for VDD-IO (SW9 on the DK).

Required HW-Tools for nRF9160 feather v5

In order to use this demo with a nRF9160 feather v5, you need:

• a nRF9160 feather v5 (maybe better two ;-)).
• the nRF9160 feather v5 is shipped with a SIM card. Check, if that covers your area/country. If not, you need a SIM card for your area/country.
• a debug probe to flash the device.
  • either a nRF9160-DK
  • or a nRF5340-DK (doesn't work for the Thingy:91!)
  • or a Segger j-Link
  • and a TC2030-CTX-NL 6-Pin “No Legs” cable with 10-pin micro-connector for Cortex processors for any of the above debug probes.

Note: the nRF9160 feather v5 uses 3.3V VDD and requires the Jlink to support 3.3V as well. Therefore a nRF5340-DK can be used. If the nRF9160-DK is used, ensure you select 3.0V for VDD-IO (SW9 on the DK).

Required HW-Tools for nRF9160-DK

In order to use this demo with a nRF9160-DK, you need:

• a nRF9160-DK (maybe better two ;-)).
• the nRF9160-DK is usually shipped with a SIM card. Check, if that covers your area/country. If not, you need a SIM card for your area/country. (Sometimes the nRF9160-DK is shipped with an expired SIM card. Then you will need also an other one.)
• the nRF9160-DK comes with a internal debug probe to flash the device. No additional equipment is required.

Note: the nRF9160-DK is a great tool to develop apps for the nRF9160 on your desk. For the "wild", a Thingy:91 or nRF9160 feather v5 does a better job.

Run It - Fast Track

It's not recommended, but you may start with using a pre-build firmware binary. Usually that will take about 1h to send a first message with your Thingy:91.

Fast Track

Build

In order to be able to build the demo-client, you need to install the development environment. That will take up to an afternoon to send your a message with your Thingy:91.

Install Tools and Tool-Chains

Basically, this requires to follow Developing with Zephyr. Though for now only the Nordic Semiconductor Thingy:91 is supported, it may be easier to go through Getting started with Thingy:91. This is also required, if you want to update your modem firmware.

Please check the proper installation of your tools building some of the provided samples there (e.g. zephyr/samples/basic/blinky or/and nrf/samples/nrf9160/udp).

Note: both, the zephyr's "developing" and Nordic Semiconductor's "getting started" has changed and may change over time and so it's hard to give good advice. Currently I have good experience with Nordic Semiconductor - Installing manually and Ubuntu 20.04. Installing nRF Connect for Desktop and apply the "Toolchain Manager" app works as well on Ubuntu 20.04 (support for 18.04 has been removed for the nRF Connect for Desktop). To use this toolchain-manager-installation after installing, start a terminal from that app to get a command console with an setup environment.

The toolchain-manager-installation also requires a slightly modified sources download, see "Download the Sources into an available zephyr workspace"

Download the Sources

This demo comes with a west.yml description. Download the demo:

west init --mr main -m https://github.com/boaks/zephyr-coaps-client.git zephyr-coaps-client

Note: Please obey the --mr main. Otherwise it will fail fetching the non existing "master" branch!

That creates a zephyr-coaps-client folder and you need to populate it further:

cd zephyr-coaps-client
west update 

That takes a while (couple of minutes). It downloads zephyr, the Nordic Semiconductor SDK and the tinydlts zephyr module.

Currently the demo uses the feature/connection_id branch of tinydtls. When that feature branch gets merged into main, this demo will be switched to that.

Download the Sources into an available zephyr workspace

Using

west init --mr main -m https://github.com/boaks/zephyr-coaps-client.git zephyr-coaps-client

from a toolchain-manager-installation, fails with an error message, that a workspace already exists. In order to add just this coaps-demo-app and the tinydtls module library to a workspace, open the workspace (for ncs the "ncs" installation folder and change to "v2.5.1" folder there). Here you find a ".west" folder, that contains the west-configuration for the workspace. Rename that ".west" folder into ".west.org" in order to replace that west-configuration by the one from this example. Now execute

west init --mr main -m https://github.com/boaks/zephyr-coaps-client.git

That creates a new west-configuration. You need to populate it further:

west update 

That takes a couple of seconds, though zephyr and nrf is already downloaded.

Build & Flash

After west completes the update, build the firmware: Change the current directory to "zephyr-coaps-client/coaps-client" (or "/coaps-client").

cd coaps-client
west build -b thingy91_nrf9160_ns

(For the nRF9160-DK use west build -b nrf9160dk_nrf9160_ns, and for the nRF9160 feather v5 use west build -b circuitdojo_feather_nrf9160_ns.)

and then flash that resulting firmware to your device

west flash

See also Updating Firmware Through External Debug Probe.

In some case, e.g. a firmware update with an notebook in the wild, it may be easier to use

nrfjprog --program build/zephyr/merged.hex --chiperase --verify -r

without west.

Run It

After flashing, the Thingy:91 starts to blink slow (purple) and after attaching to the mobile-network it switches to green. If the LED is switched off, the device is also connected with the plugtest-server of the Eclipse/Californium Sandbox.

Note: If the Thingy:91 starts for the first time in a new area, it may take longer (2-3 minutes) to connect to a mobile network. The Thingy:91 saves then the configuration and the next time, the startup is much faster, if the Thingy:91 is not relocated too far.

Press the Thingy:91's call-button (the symbolic "N" in the center of the orange cover). The LED should start with blue and changes very fast to lightblue. If it is re-attached at the mobile-network, it switches to green. And if the response from the server is received, the LED switches off again. On error, the LED is switched to red. Usually it takes all together 1 second (LTE-M/CAT-M1) and only 2 ip-messages are exchanged.

(If you use the nRF9160-DK, then press "Button 1".)

Done.

The demo client exchanges encrypted messages with the coap-server. These messages are only for demonstration, the data is considered to be replaced by your own ideas.

Demo message:

1-01:52:49 [d-hh:mm:ss], Thingy:91 v0.9.101+4, 0*25, 1*1, 2*0, 3*0, failures 0
NCS: 2.5.1, HW: B0A, MFW: 1.3.6, IMEI: 352656100985434
!4154 mV 96% (168 days left) battery
Restart: Reboot
ICCID: 8935711001078444905F, eDRX cycle: off, HPPLMN interval: 10 [h]
IMSI: 278773000008810
Network: CAT-M1,roaming,Band 20,PLMN 26202,TAC 47490,Cell 52470017,EARFCN 6300
PDN: flolive.net,100.64.153.239,rate-limit 256,86400 s
PSM: TAU 90000 [s], Act 0 [s], AS-RAI, Released: 2021 ms
!CE: down: 1, up: 1, RSRP: -108 dBm, CINR: 0 dB, SNR: 1 dB
Stat: tx 21 kB, rx 2 kB, max 872 B, avg 401 B
Cell updates 17, Network searchs 3 (326 s), PSM delays 0 (0 s)
Modem Restarts 0, Sockets 3, DTLS handshakes 1
Wakeups 25, 93 s, connected 150 s, asleep 0 s
!22.81 C
!46.36 %H
!1002 hPa

It starts with the up-time in the first line, followed by the label "Thingy:91" and the client's and NCS version. The sent statistic. "0*25" := 25 exchanges without retransmission, "1*1" := 1 exchange with 1 retransmission finishs that first line. The current exchange is not included in this statistic. The second line contains the harware version of the nRF9160 chip, the modem firmware version, and the IMEI. Followed by the line withs the battery status and the lines with information from the SIM-card. In some cases the network details are of interest and the next lines contains that. The last lines of technical informations before the sensor values contains several statistics, e.g. the amount of transfered data and modem restarts.

The demo uses the "echo" resource of the plugtest-server, therefore the response contains just the same message.

If you want to see, what your Thingy:91 has sent to the server, see cf-browser.

Configuration

The application comes with a KConfig to configure some functions. Use

west build -b thingy91_nrf9160_ns -t menuconfig

for the console variant, and

west build -b thingy91_nrf9160_ns -t guiconfig

for the GUI variant.

For details please read the provided help for this settings and the Configuration page.

Next Steps

As mentioned at the introduction, the demo is intended as groundwork for your own ideas.

Next Steps

See also Roadmap for the plan of the next months.

If you want to consider the power consumption in your idea, please see Power Consumption and if you want to make own measurements may be helpful.

Sometimes it is interesting, which mobile networks are available at some locations. Thingy:91 - Cellular Explorer helps here. It comes also with support for a firmware update using XMODEM and some additional function in order to test the features of the mobile network.

A more elaborated example see mobile-beehive-scale.

Updating to a Newer Versions

First update the project itself using

cd coaps-client
git pull

then update the other modules using

cd ..
west update

In many cases, the next build requires to use

cd coaps-client
west build -b thingy91_nrf9160_ns --pristine

The --pristine resets the current configuration. You may need to configure it again. In some rare cases it may be even required to remove the "build" folder before.

If west build ... --pristine keeps failing, the west update may require to update also some "west requirements". Therefore execute

pip3 install --user -r zephyr/scripts/requirements.txt
pip3 install --user -r nrf/scripts/requirements.txt
pip3 install --user -r bootloader/mcuboot/scripts/requirements.txt

and retry west build ... --pristine again.

Manually Update the Zephyr SDK

In some case it may be required to also update the Zephyr SDK. Follow the instructions there and test, if that fixes your issues when updating the NCS version.

Licenses

This demo itself is licensed under EPL-2.0.

Some files are used especially for the Thingy:91 and are licensed under Nordic-5. This files are only licensed to be used with Nordic Semiconductor devices. See boards and child_image.

The demo uses several third-party content, please refer to NOTICE for details.