From c2b6a8de3e15fa66d48a373b3504fcebf12d905b Mon Sep 17 00:00:00 2001 From: Riku Isokoski Date: Sun, 21 Aug 2022 14:50:09 +0300 Subject: Fix markdown format with autoformatter (#1284) --- bootloader/README.md | 51 ++++++++++++++++++++----------------- bootloader/ota-dfu-python/README.md | 47 +++++++++++++++++----------------- 2 files changed, 51 insertions(+), 47 deletions(-) (limited to 'bootloader') diff --git a/bootloader/README.md b/bootloader/README.md index 2cb6b8bf..51ddfa6b 100644 --- a/bootloader/README.md +++ b/bootloader/README.md @@ -1,4 +1,5 @@ # About this bootloader + The [bootloader](https://github.com/lupyuen/pinetime-rust-mynewt/tree/master/libs/pinetime_boot/src) is mostly developed by [Lup Yuen](https://github.com/lupyuen). It is based on [MCUBoot](https://www.mcuboot.com) and [Mynewt](https://mynewt.apache.org/). The goal of this project is to provide a common bootloader for multiple (all?) Pinetime projects. It allows to upgrade the current bootloader and even replace the current application by another one that supports the same bootloader. @@ -12,6 +13,7 @@ When it is run, this bootloader looks in the SPI flash memory if a new firmware As this bootloader does not provide any OTA capability, it is not able to actually download a new version of the application. Providing OTA functionality is thus the responsibility of the application firmware. # About MCUBoot + MCUBoot is run at boot time. In normal operation, it just jumps to the reset handler of the application firmware to run it. Once the application firmware is running, MCUBoot does not run at all. ![MCUBoot boot sequence diagram](../doc/bootloader/boot.png "MCUBoot boot sequence diagram") @@ -19,8 +21,9 @@ MCUBoot is run at boot time. In normal operation, it just jumps to the reset han But MCUBoot does much more than that : it can upgrade the firmware that is currently running by a new one, and it is also able to revert to the previous version of the firmware in case the new one does not run properly. To do this, it uses 2 memory 'slots' : - - **The primary slot** : it contains the current firmware, the one that will be executed by MCUBoot - - **The secondary slot** : it is used to store the upgraded version of the firmware, when available. + +- **The primary slot** : it contains the current firmware, the one that will be executed by MCUBoot +- **The secondary slot** : it is used to store the upgraded version of the firmware, when available. At boot time, MCUBoot detects that a new version of the firmware is available in the secondary slot and swaps them : the current version of the firmware is copied from the primary to the secondary slot and vice-versa. @@ -35,6 +38,7 @@ The next time MCUBoot will be run (after a MCU reset), MCUBoot will check if the Note than MCUBoot **does not** provide any means to download and store the new version of the firmware into the secondary slot. This must be implemented by the application firmware. # Degraded cases + This chapter describes degraded cases that are handled by our bootloader and those that are not supported. Case | Current bootloader | Solution @@ -50,72 +54,73 @@ New firmware does not run properly but sets the valid bit and refreshes the watc # Using the bootloader ## Bootloader graphic + The bootloader loads a graphic (Pinetime logo) from the SPI Flash memory. If this graphic is not loaded in the memory, the LCD will display garbage (the content of the SPI flash memory). The SPI Flash memory is not accessible via the SWD debugger. Use the firmware 'pinetime-graphics' to load the graphic into memory. All you have to do is build it and program it at address 0x00 : - - Build: -``` -$ make pinetime-graphics +- Build: + +```sh +make pinetime-graphics ``` - - Program (using OpenOCD for example) : +- Program (using OpenOCD for example) : + ``` program pinetime-graphics.bin 0 ``` - - Let it run for ~10s (it does nothing for 5 seconds, then write the logo into the SPI memory, then (slowly) displays it on the LCD). +- Let it run for ~10s (it does nothing for 5 seconds, then write the logo into the SPI memory, then (slowly) displays it on the LCD). ## Bootloader binary + The binary comes from https://github.com/lupyuen/pinetime-rust-mynewt/releases/tag/v5.0.4 It must be flash at address **0x00** in the internal flash memory. Using OpenOCD: -` -program bootloader-5.0.4.bin 0 -` +`program bootloader-5.0.4.bin 0` ## Application firmware image + Build the binary compatible with the booloader: -` -make pinetime-mcuboot-app -` +`make pinetime-mcuboot-app` The binary is located in */src/pinetime-mcuboot-app.bin*. It must me converted into a MCUBoot image using *imgtool.py* from [MCUBoot](https://github.com/mcu-tools/mcuboot/tree/master/scripts). Simply checkout the project and run the script /scripts/imgtool.py with the following command line: -` -imgtool.py create --align 4 --version 1.0.0 --header-size 32 --slot-size 475136 --pad-header /src/pinetime-mcuboot-app.bin image.bin -` +```sh +imgtool.py create --align 4 --version 1.0.0 --header-size 32 --slot-size 475136 --pad-header /src/pinetime-mcuboot-app.bin image.bin +``` The image must be then flashed at address **0x8000** in the internal flash memory. Using OpenOCD: -` -program image.bin 0x8000 -` +`program image.bin 0x8000` ## OTA and DFU + Pack the image into a .zip file for the NRF DFU protocol: -` +```sh adafruit-nrfutil dfu genpkg --dev-type 0x0052 --application image.bin dfu.zip -` +``` Use NRFConnect or dfu.py (in /bootloader/ota-dfu-python) to upload the zip file to the device: -` +```sh sudo dfu.py -z /home/jf/nrf52/bootloader/dfu.zip -a --legacy -` +``` **Note** : dfu.py is a slightly modified version of [this repo](https://github.com/daniel-thompson/ota-dfu-python). ### Firmware validation + Once the OTA is done, InfiniTime will reset the watch to apply the update. When the watch reboots, the new firmware is running. One last step is needed to finalize the upgrade : the new firmware must be manually validated. If the watch resets while the image is not validated, the bootloader will automatically revert to the previous version of the firmware. diff --git a/bootloader/ota-dfu-python/README.md b/bootloader/ota-dfu-python/README.md index 3397db4d..c38e597a 100644 --- a/bootloader/ota-dfu-python/README.md +++ b/bootloader/ota-dfu-python/README.md @@ -1,13 +1,13 @@ # Python nRF5 OTA DFU Controller So... this is my fork of dingara's fork of astronomer80's fork of -foldedtoad's Python OTA DFU utility. +foldedtoad's Python OTA DFU utility. -My own contribution is little more than a brute force conversion to -python3. It is sparsely tested so there are likely to be a few +My own contribution is little more than a brute force conversion to +python3. It is sparsely tested so there are likely to be a few remaining bytes versus string bugs remaining in the places I didn't test . I used it primarily as part of -[wasp-os](https://github.com/daniel-thompson/wasp-os) as a way to +[wasp-os](https://github.com/daniel-thompson/wasp-os) as a way to deliver OTA updates to nRF52-based smart watches, especially the [Pine64 PineTime](https://www.pine64.org/pinetime/). @@ -17,24 +17,24 @@ This is a Python program that uses `gatttool` (provided with the Linux BlueZ dri ### Main features: -* Perform OTA DFU to an nRF5 peripheral without an external USB BLE dongle. -* Ability to detect if the peripheral is running in application mode or bootloader, and automatically switch if needed (buttonless). -* Support for both Legacy (SDK <= 11) and Secure (SDK >= 12) bootloader. +- Perform OTA DFU to an nRF5 peripheral without an external USB BLE dongle. +- Ability to detect if the peripheral is running in application mode or bootloader, and automatically switch if needed (buttonless). +- Support for both Legacy (SDK <= 11) and Secure (SDK >= 12) bootloader. Before using this utility the nRF5 peripheral device needs to be programmed with a DFU bootloader (see Nordic Semiconductor documentation/examples for instructions on that). ## Prerequisites -* BlueZ 5.4 or above -* Python 3.6 -* Python `pexpect` module (available via pip) -* Python `intelhex` module (available via pip) +- BlueZ 5.4 or above +- Python 3.6 +- Python `pexpect` module (available via pip) +- Python `intelhex` module (available via pip) ## Firmware Build Requirement -* Your nRF5 peripheral firmware build method will produce a firmware file ending with either `*.hex` or `*.bin`. -* Your nRF5 firmware build method will produce an Init file ending with `.dat`. -* The typical naming convention is `application.bin` and `application.dat`, but this utility will accept other names. +- Your nRF5 peripheral firmware build method will produce a firmware file ending with either `*.hex` or `*.bin`. +- Your nRF5 firmware build method will produce an Init file ending with `.dat`. +- The typical naming convention is `application.bin` and `application.dat`, but this utility will accept other names. ## Generating init files @@ -75,14 +75,13 @@ You can use the `hcitool lescan` to figure out the address of a DFU target, for CD:E3:4A:47:1C:E4 CD:E3:4A:47:1C:E4 (unknown) - ## Example Output ================================ == == == DFU Server == == == - ================================ + ================================ Sending file application.bin to CD:E3:4A:47:1C:E4 bin array size: 60788 @@ -105,14 +104,14 @@ You can use the `hcitool lescan` to figure out the address of a DFU target, for ## TODO: -* Implement link-loss procedure for Legacy Controller. -* Update example output in readme. -* Add makefile examples. -* More code cleanup. +- Implement link-loss procedure for Legacy Controller. +- Update example output in readme. +- Add makefile examples. +- More code cleanup. ## Info & References -* [Nordic Legacy DFU Service](http://infocenter.nordicsemi.com/topic/com.nordic.infocenter.sdk5.v11.0.0/bledfu_transport_bleservice.html?cp=4_0_3_4_3_1_4_1) -* [Nordic Legacy DFU sequence diagrams](http://infocenter.nordicsemi.com/topic/com.nordic.infocenter.sdk5.v11.0.0/bledfu_transport_bleprofile.html?cp=4_0_3_4_3_1_4_0_1_6#ota_profile_pkt_rcpt_notif) -* [Nordic Secure DFU bootloader](http://infocenter.nordicsemi.com/topic/com.nordic.infocenter.sdk5.v12.2.0/lib_dfu_transport_ble.html?cp=4_0_1_3_5_2_2) -* [nrfutil](https://github.com/NordicSemiconductor/pc-nrfutil) +- [Nordic Legacy DFU Service](http://infocenter.nordicsemi.com/topic/com.nordic.infocenter.sdk5.v11.0.0/bledfu_transport_bleservice.html?cp=4_0_3_4_3_1_4_1) +- [Nordic Legacy DFU sequence diagrams](http://infocenter.nordicsemi.com/topic/com.nordic.infocenter.sdk5.v11.0.0/bledfu_transport_bleprofile.html?cp=4_0_3_4_3_1_4_0_1_6#ota_profile_pkt_rcpt_notif) +- [Nordic Secure DFU bootloader](http://infocenter.nordicsemi.com/topic/com.nordic.infocenter.sdk5.v12.2.0/lib_dfu_transport_ble.html?cp=4_0_1_3_5_2_2) +- [nrfutil](https://github.com/NordicSemiconductor/pc-nrfutil) -- cgit v1.2.3