mbed-os-examples / Mbed OS mbed-os-example-mbed5-bootloader

.

README.md@71:f65271241611, 2019-11-20 (annotated)

Committer:
mbed_official
Date:
Wed Nov 20 14:01:42 2019 +0000
Revision:
71:f65271241611
Parent:
69:af449f5fffdb 
Merge pull request #125 from amq/patch-1



Fix a compiler warning

.

Commit copied from https://github.com/ARMmbed/mbed-os-example-bootloader

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mbed_official 0:8df79c088b12 1 # Getting started with bootloader on mbed OS
mbed_official 0:8df79c088b12 2
mbed_official 5:d57adfa16284 3 This example shows how to create a bootloader.
mbed_official 0:8df79c088b12 4
mbed_official 35:dc886a2245ff 5 To read more about the bootloader, please visit the [bootloader tutorial](https://os.mbed.com/docs/latest/tutorials/bootloader.html).
mbed_official 2:fc74f70b51c3 6
mbed_official 0:8df79c088b12 7 ## Required hardware
mbed_official 35:dc886a2245ff 8
mbed_official 35:dc886a2245ff 9 * A supported target - [u-blox EVK-ODIN-W2](https://os.mbed.com/platforms/ublox-EVK-ODIN-W2/), [Nucleo F429ZI](https://os.mbed.com/platforms/ST-Nucleo-F429ZI/) or [K64F](https://os.mbed.com/platforms/FRDM-K64F/).
mbed_official 0:8df79c088b12 10 * SD card.
mbed_official 14:9476f399341e 11 * If your supported target does not have an SD card port, you need a shield or breakout board with an SD card port that uses SPI pins.
mbed_official 0:8df79c088b12 12
mbed_official 0:8df79c088b12 13 ## Import the example application
mbed_official 0:8df79c088b12 14
mbed_official 0:8df79c088b12 15 From the command-line, import the example:
mbed_official 0:8df79c088b12 16
mbed_official 0:8df79c088b12 17 ```
mbed_official 2:fc74f70b51c3 18 mbed import mbed-os-example-bootloader
mbed_official 2:fc74f70b51c3 19 cd mbed-os-example-bootloader
mbed_official 0:8df79c088b12 20 ```
mbed_official 0:8df79c088b12 21
mbed_official 14:9476f399341e 22 ## Connecting the SD card
mbed_official 35:dc886a2245ff 23
mbed_official 35:dc886a2245ff 24 This example uses the **onboard SD card port** for the K64F and the u-blox EVK-ODIN-W2.
mbed_official 14:9476f399341e 25
mbed_official 14:9476f399341e 26 Other targets use the following Arduino form-factor SPI pins by default:
mbed_official 35:dc886a2245ff 27
mbed_official 14:9476f399341e 28 - `D11` - `MOSI`
mbed_official 14:9476f399341e 29 - `D12` - `MISO`
mbed_official 14:9476f399341e 30 - `D13` - `SCK`
mbed_official 14:9476f399341e 31 - `D10` - `CS`
mbed_official 14:9476f399341e 32
mbed_official 14:9476f399341e 33 To use different SPI pins, you need to modify the `mbed_app.json` file. Add a key for your target to the `target_overrides` section with the following data (replace `<TARGET_NAME>` with your target's name):
mbed_official 0:8df79c088b12 34
mbed_official 14:9476f399341e 35 ```
mbed_official 14:9476f399341e 36 {
mbed_official 14:9476f399341e 37 ...
mbed_official 14:9476f399341e 38 "target_overrides": {
mbed_official 14:9476f399341e 39 ...
mbed_official 14:9476f399341e 40 "<TARGET_NAME>": {
mbed_official 14:9476f399341e 41 "sd_card_mosi": "<MOSI_PIN>",
mbed_official 14:9476f399341e 42 "sd_card_miso": "<MISO_PIN>",
mbed_official 14:9476f399341e 43 "sd_card_sck": "<SCK_PIN>",
mbed_official 14:9476f399341e 44 "sd_card_cs": "<CS_PIN>"
mbed_official 14:9476f399341e 45 }
mbed_official 14:9476f399341e 46 ...
mbed_official 14:9476f399341e 47 }
mbed_official 14:9476f399341e 48 ...
mbed_official 14:9476f399341e 49 }
mbed_official 14:9476f399341e 50 ```
mbed_official 4:0daf612a367a 51
mbed_official 14:9476f399341e 52 ## Preparing the bootloader
mbed_official 14:9476f399341e 53
mbed_official 14:9476f399341e 54 All supported targets mentioned above are set up to build as a bootloader image. To add support for a new target, you must specify the size of the bootloader.
mbed_official 14:9476f399341e 55
mbed_official 14:9476f399341e 56 To do this, set the target value `restrict_size` to the maximum bootloader size in `mbed_app.json` (replace `<TARGET_NAME>` with your target name):
mbed_official 0:8df79c088b12 57
mbed_official 0:8df79c088b12 58 ```
mbed_official 0:8df79c088b12 59 "target_overrides": {
mbed_official 0:8df79c088b12 60 ...
mbed_official 2:fc74f70b51c3 61 "<TARGET_NAME>": {
mbed_official 0:8df79c088b12 62 "target.restrict_size": "0x20000"
mbed_official 0:8df79c088b12 63 },
mbed_official 0:8df79c088b12 64 ...
mbed_official 0:8df79c088b12 65 ```
mbed_official 0:8df79c088b12 66
mbed_official 14:9476f399341e 67 <span class="tips">**Note:** `restrict_size` pads the build image to the requested size.</span>
mbed_official 0:8df79c088b12 68
mbed_official 14:9476f399341e 69 ## Building the bootloader
mbed_official 0:8df79c088b12 70
mbed_official 14:9476f399341e 71 Invoke `mbed compile`, and specify the name of your target and your favorite toolchain (`GCC_ARM`, `ARM`, `IAR`). For example, for the ARM Compiler:
mbed_official 0:8df79c088b12 72
mbed_official 0:8df79c088b12 73 ```
mbed_official 2:fc74f70b51c3 74 mbed compile -m <TARGET_NAME> -t ARM
mbed_official 0:8df79c088b12 75 ```
mbed_official 0:8df79c088b12 76
mbed_official 0:8df79c088b12 77 Your PC may take a few minutes to compile your code. At the end, you see the following result:
mbed_official 0:8df79c088b12 78
mbed_official 0:8df79c088b12 79 ```
mbed_official 0:8df79c088b12 80 Merging Regions:
mbed_official 2:fc74f70b51c3 81 Filling region application with .\BUILD\<TARGET_NAME>\ARM\mbed-os-example-bootloader_application.bin
mbed_official 0:8df79c088b12 82 Padding region application with 0x11420 bytes
mbed_official 0:8df79c088b12 83 Space used after regions merged: 0x20000
mbed_official 0:8df79c088b12 84 +-----------------------------+-------+-------+-------+
mbed_official 0:8df79c088b12 85 | Module | .text | .data | .bss |
mbed_official 0:8df79c088b12 86 +-----------------------------+-------+-------+-------+
mbed_official 0:8df79c088b12 87 | Misc | 18481 | 24 | 1268 |
mbed_official 0:8df79c088b12 88 | drivers | 2132 | 8 | 184 |
mbed_official 0:8df79c088b12 89 | features/FEATURE_LWIP | 46 | 0 | 12560 |
mbed_official 0:8df79c088b12 90 | features/filesystem | 12756 | 12 | 540 |
mbed_official 0:8df79c088b12 91 | hal | 414 | 8 | 0 |
mbed_official 0:8df79c088b12 92 | hal/TARGET_FLASH_CMSIS_ALGO | 520 | 28 | 0 |
mbed_official 0:8df79c088b12 93 | platform | 2759 | 32 | 380 |
mbed_official 0:8df79c088b12 94 | rtos | 144 | 8 | 0 |
mbed_official 0:8df79c088b12 95 | rtos/rtx | 6954 | 100 | 8396 |
mbed_official 0:8df79c088b12 96 | targets/TARGET_STM | 15560 | 568 | 736 |
mbed_official 0:8df79c088b12 97 | Subtotals | 59766 | 788 | 24064 |
mbed_official 0:8df79c088b12 98 +-----------------------------+-------+-------+-------+
mbed_official 0:8df79c088b12 99 Allocated Heap: unknown
mbed_official 0:8df79c088b12 100 Allocated Stack: unknown
mbed_official 0:8df79c088b12 101 Total Static RAM memory (data + bss): 24852 bytes
mbed_official 0:8df79c088b12 102 Total RAM memory (data + bss + heap + stack): 24852 bytes
mbed_official 0:8df79c088b12 103 Total Flash memory (text + data + misc): 60554 bytes
mbed_official 0:8df79c088b12 104
mbed_official 2:fc74f70b51c3 105 Image: .\BUILD\<TARGET_NAME>\ARM\mbed-os-example-bootloader.bin
mbed_official 0:8df79c088b12 106 ```
mbed_official 0:8df79c088b12 107
mbed_official 14:9476f399341e 108 After the build completes, the build system creates two binary images in the `BUILD/<TARGET_NAME>/<TOOLCHAIN_NAME>` directory: `<project-name>.bin` and `<project-name>_application.bin`. `<project-name>.bin` is the padded bootloader (used for combining with applications). `<project-name>_application.bin` is the original unpadded bootloader.
mbed_official 2:fc74f70b51c3 109
mbed_official 49:f0f86f5bed62 110 In this example, `main.cpp` defines the update binary for the bootloader as `mbed-os-example-blinky_application.bin` (specified under the config `update_file` in `mbed_app.json`). The bootloader looks for this file in the root of the SD card, flashes it to memory and then jumps to the application.
mbed_official 3:01d11bcf86eb 111
mbed_official 14:9476f399341e 112 ## Building the application with the bootloader
mbed_official 11:d396becb5d76 113
mbed_official 49:f0f86f5bed62 114 The next step is to build an application you can combine with your bootloader to create a loadable image.
mbed_official 49:f0f86f5bed62 115
mbed_official 49:f0f86f5bed62 116 <span class="tips">**Note:** Updating an application to use a bootloader currently does not work with the Arm Mbed Online Compiler because .bin and .hex files can't be uploaded.</span>
mbed_official 3:01d11bcf86eb 117
mbed_official 14:9476f399341e 118 1. Instruct the build system to use the newly created padded bootloader image (named `<project-name>.bin` in the previous section). To do this, create a `target_overrides` section in your application's `mbed_app.json` file, and add a key for your target (see `<TARGET_NAME>` in the example below). If `mbed_app.json` does not already exist in your application, create one.
mbed_official 14:9476f399341e 119
mbed_official 14:9476f399341e 120 2. Set the target value `bootloader_img` in `mbed_app.json` to the file path of the padded bootloader image. For the below example, copy the padded bootloader image to the project directory.
mbed_official 3:01d11bcf86eb 121
mbed_official 3:01d11bcf86eb 122 ```
mbed_official 14:9476f399341e 123 {
mbed_official 3:01d11bcf86eb 124 "target_overrides": {
mbed_official 3:01d11bcf86eb 125 ...
mbed_official 3:01d11bcf86eb 126 "<TARGET_NAME>": {
mbed_official 14:9476f399341e 127 "target.bootloader_img": "<path to padded bootloader binary>"
mbed_official 3:01d11bcf86eb 128 },
mbed_official 3:01d11bcf86eb 129 ...
mbed_official 14:9476f399341e 130 }
mbed_official 3:01d11bcf86eb 131 ```
mbed_official 3:01d11bcf86eb 132
mbed_official 14:9476f399341e 133 2. Invoke `mbed compile`, and specify the name of your target and the toolchain you are using (`GCC_ARM`, `ARM`, `IAR`). For example, for the ARM Compiler:
mbed_official 3:01d11bcf86eb 134
mbed_official 3:01d11bcf86eb 135 ```
mbed_official 3:01d11bcf86eb 136 mbed compile -m <TARGET_NAME> -t ARM
mbed_official 3:01d11bcf86eb 137 ```
mbed_official 3:01d11bcf86eb 138
mbed_official 49:f0f86f5bed62 139 After the build completes, the build system creates two binary images in the `BUILD/<TARGET_NAME>/<TOOLCHAIN_NAME>` directory: `<project-name>.bin` and `<project-name>_application.bin`. `<project-name>.bin` is the combined bootloader and application (suitable for flashing to the device's ROM directly). `<project-name>_application.bin` is the update binary (the one you place on the SD card). By default the bootloader built in the previous step looks for an application built from the project `from mbed-os-example-blinky` and having the name `mbed-os-example-blinky_application.bin`.
mbed_official 14:9476f399341e 140
mbed_official 14:9476f399341e 141 ### Program the application with the bootloader included
mbed_official 14:9476f399341e 142
mbed_official 14:9476f399341e 143 Follow these steps to program the target with the combined bootloader and application image. You then can update the application from the SD card.
mbed_official 3:01d11bcf86eb 144
mbed_official 35:dc886a2245ff 145 1. Connect your Mbed device to the computer over USB.
mbed_official 35:dc886a2245ff 146 1. Copy the combined bootloader and application binary file (named `<project-name>.bin` in the previous section) to the Mbed device.
mbed_official 3:01d11bcf86eb 147 1. Press the reset button to start the program.
mbed_official 3:01d11bcf86eb 148
mbed_official 14:9476f399341e 149 ### Program the application from the bootloader (load from SD card)
mbed_official 14:9476f399341e 150
mbed_official 14:9476f399341e 151 <span class="tips">**Note:** You must first flash the combined bootloader and application image or just the bootloader image (padded or unpadded) before proceeding with the following steps.</span>
mbed_official 3:01d11bcf86eb 152
mbed_official 3:01d11bcf86eb 153 1. Connect the SD card to your computer.
mbed_official 14:9476f399341e 154 1. Copy the update application binary (named `<project-name>_application.bin` in the previous section) to the root of the SD card.
mbed_official 35:dc886a2245ff 155 1. Remove the SD card from your PC, and connect it to your Mbed board (see the above section [Connecting the SD card](#connecting-the-sd-card)).
mbed_official 3:01d11bcf86eb 156 1. Press the reset button to start the firmware update.
mbed_official 3:01d11bcf86eb 157
mbed_official 14:9476f399341e 158 If a terminal is open, the following prints at a baud rate of 9600:
mbed_official 3:01d11bcf86eb 159
mbed_official 3:01d11bcf86eb 160 ```
mbed_official 3:01d11bcf86eb 161 Firmware update found
mbed_official 3:01d11bcf86eb 162 Starting application
mbed_official 3:01d11bcf86eb 163 ```
mbed_official 0:8df79c088b12 164
mbed_official 0:8df79c088b12 165 ## Troubleshooting
mbed_official 0:8df79c088b12 166
mbed_official 35:dc886a2245ff 167 If you have problems, you can review the [documentation](https://os.mbed.com/docs/latest/tutorials/debugging.html) for suggestions on what could be wrong and how to fix it.
mbed_official 69:af449f5fffdb 168
mbed_official 69:af449f5fffdb 169
mbed_official 69:af449f5fffdb 170 ## License and contributions
mbed_official 69:af449f5fffdb 171
mbed_official 69:af449f5fffdb 172 The software is provided under Apache-2.0 license. Contributions to this project are accepted under the same license. Please see [contributing.md](CONTRIBUTING.md) for more info.
mbed_official 69:af449f5fffdb 173
mbed_official 69:af449f5fffdb 174 This project contains code from other projects. The original license text is included in those source files. They must comply with our license guide.
mbed_official 69:af449f5fffdb 175