|
| 1 | +# dtls-ota |
| 2 | +Over-the-air firmware upgrade example for Nordic nRF52, using DTLSv1.2/UDP/IPv6/6LoWPAN over BLE. |
| 3 | + |
| 4 | +This project is meant to demonstrate a firmware upgrade mechanism based on [wolfBoot secure bootloader](https://github.com/wolfssl/wolfBoot), powered by wolfSSL. |
| 5 | + |
| 6 | +The bootloader expect the application to transfer the new firmware through a secure channel, store it in a partition on the flash memory and trigger an upgrade on the next reboot. |
| 7 | + |
| 8 | +The application in this example uses DTLSv1.2 over Bluetooth Low-Energy (BLE) to request a new firmware image from a remote server. Once the transfer is complete, the target is rebooted into |
| 9 | +the bootloader, which validates the new image and copies it to the active boot partition. |
| 10 | + |
| 11 | + |
| 12 | +## Components |
| 13 | + - Bootloader: [wolfBoot](https://github.com/wolfssl/wolfBoot) by wolfSSL |
| 14 | + - OS: [contiki](http://contiki-os.org/) |
| 15 | + - TLS: [wolfSSL](https://www.wolfssl.com) providing DTLS v1.2 support with ECC-based cipher |
| 16 | + - UDP/IPv6 stack: uIP |
| 17 | + - Application: Custom firmware upgrade contiki application with DTLS Client and wolfBoot integration |
| 18 | + |
| 19 | +## Preparing the initial firmware |
| 20 | + |
| 21 | +The flash memory on the nRF52 is divided as follows: |
| 22 | + |
| 23 | +``` |
| 24 | + - 0x000000 - 0x01efff : Reserved for Nordic SoftDevice binary |
| 25 | + - 0x01f000 - 0x02efff : Bootloader partition for wolfBoot |
| 26 | + - 0x02f000 - 0x056fff : Active (boot) partition |
| 27 | + - 0x057000 - 0x057fff : Unused |
| 28 | + - 0x058000 - 0x07ffff : Upgrade partition |
| 29 | +``` |
| 30 | + |
| 31 | +Running `make` assembles the following images: |
| 32 | + - pre-built SoftDevice binary (downloaded from developer.nordicsemi.com) |
| 33 | + - wolfBoot compiled to run at address 0x01f000 and linked with the nrf52 HAL |
| 34 | + - Contiki-OS with automatic start-up of the firmware upgrade process, in a signed image that can be verified by wolfBoot during start-up |
| 35 | + |
| 36 | +If it is the first time that `make` is executed, it will also: |
| 37 | + - Generate a new Ed25519 keypair, used to sign and verify the firmware images |
| 38 | + - Download a copy of Nordic SoftDevice binary from developer.nordicsemi.com |
| 39 | + |
| 40 | +Running `make flash` will upload the three components into the respective partitions onto the target. |
| 41 | + |
| 42 | +More information about wolfBoot upgrade mechanism can be found in the [wolfBoot](https://github.com/wolfSSL/wolfBoot) repository. |
| 43 | + |
| 44 | +## Firmware upgrade |
| 45 | + |
| 46 | +The directory [ota-server](ota-server) contains a small exaple DTLS v1.2 server that can be used to transfer a (signed) image to any client requesting a firmware upgrade. |
| 47 | +To compile ota-server for the host system, simply run `make` within the directory. |
| 48 | + |
| 49 | +In order to establish a layer-2 link with the target, the host must configure a 6loWPAN device on top of the system BLE support. |
| 50 | + |
| 51 | +Before starting, a file mac.txt must be created inside the ota-server directory, containing the physical address of the BLE interface on the target. |
| 52 | + |
| 53 | +To discover the address of the target, use `hcitool lescan` from the host. Among the discovered host, look for the target fingerprints: |
| 54 | +``` |
| 55 | +00:22:99:CC:EE:88 Contiki nRF52dk |
| 56 | +``` |
| 57 | + |
| 58 | +And create the file `mac.txt` accordingly: |
| 59 | +``` |
| 60 | +00:22:99:CC:EE:88 |
| 61 | +``` |
| 62 | + |
| 63 | +The script `start.sh` contains all the instruction needed to create the connection and start the ota-server, listening on port 11111 for incoming DTLS sessions. It will also assign a site-local fixed IPv6 address that the DTLS client on the target uses to contact ota-server. |
| 64 | + |
| 65 | +After the DTLS handshake, the server transmits the size of the firmware, and then the flash area content in chunks of 512B each. |
| 66 | + |
| 67 | +When the transfer is complete, a flag is activated at the end of the flash area to notify wolfBoot of a pending upgrade. |
| 68 | + |
| 69 | +After reboot, wolfBoot will copy the image from the secondary partition to the primary partition, to allow the new firmware to run, but only if the new firmware can be authenticated using the public Ed25519 key stored in the bootloader image. In all other cases, the upgrade is canceled and the old firmware can be started again. |
| 70 | + |
| 71 | +## Successful upgrade: serial output from target |
| 72 | + |
| 73 | +Below, an extract of the messages printed on the serial console of the target during and after the upgrade procedure: |
| 74 | + |
| 75 | +``` |
| 76 | +OTA BLE Firmware upgrade, powered by Contiki + WolfSSL. |
| 77 | +This firmware build: 1540927787 |
| 78 | +Client IPv6 address: |
| 79 | + fd00::xx:yy:zz |
| 80 | + fe80::xx:yy:zz |
| 81 | +wolfSSL: Setting peer address and port |
| 82 | +connecting to server... |
| 83 | +
|
| 84 | +Timeout! |
| 85 | +Retrying... |
| 86 | +Connected to OTA server. |
| 87 | +Firmware size: 127236 |
| 88 | +Erase complete. Start flashing |
| 89 | +RECV: 512/127236 |
| 90 | +RECV: 1024/127236 |
| 91 | +RECV: 1536/127236 |
| 92 | +RECV: 2048/127236 |
| 93 | +``` |
| 94 | +(cut prints of each datagram received) |
| 95 | +``` |
| 96 | +RECV: 126464/127236 |
| 97 | +RECV: 126976/127236 |
| 98 | +RECV: 127236/127236 |
| 99 | +Closing connection. |
| 100 | +Transfer complete. Triggering wolfBoot upgrade. |
| 101 | +Rebooting... |
| 102 | +OTA BLE Firmware upgrade, powered by Contiki + WolfSSL. |
| 103 | +This firmware build: 1540927848 |
| 104 | +``` |
| 105 | + |
| 106 | +In case of success, the build number can be used to verify that the system has actually been upgraded by comparing the build numbers before the transfer and after the reboot. |
| 107 | + |
| 108 | + |
| 109 | +## Copyright notice |
| 110 | +ota-server example is Copyright (c) 2018 wolfSSL Inc., and distributed under the term of GNU GPL2. |
| 111 | + |
| 112 | +dtls-ota embedded application and the ota-server example are Copyright (c) 2018 wolfSSL Inc., and distributed under the term of GNU GPL2, with a specific linking exception allowing to link against Nordic SoftDevice binary blob. |
| 113 | + |
| 114 | +wolfBoot, wolfSSL (formerly known as CyaSSL) and wolfCrypt are Copyright (c) 2006-2018 wolfSSL Inc., and licensed for use under GPLv2. |
| 115 | + |
| 116 | +Contiki OS and uIP are licensed under the terms of the 3-clause BSD license. |
| 117 | + |
| 118 | +wolfBoot, wolfSSL (formerly known as CyaSSL) and wolfCrypt are Copyright (c) 2006-2018 wolfSSL Inc., and licensed for use under GPLv2. |
| 119 | + |
| 120 | +See the documentation within each component subdirectory for more information about using and distributing this software. |
| 121 | + |
0 commit comments