mbed-os-examples
/
mbed-os-example-mbed5-bootloader
.
README.md@69:af449f5fffdb, 2019-04-15 (annotated)
- Committer:
- mbed_official
- Date:
- Mon Apr 15 15:01:37 2019 +0100
- Revision:
- 69:af449f5fffdb
- Parent:
- 49:f0f86f5bed62
add contributing file + license
.
Commit copied from https://github.com/ARMmbed/mbed-os-example-bootloader
Who changed what in which revision?
User | Revision | Line number | New 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 |