mbed-os-examples
/
mbed-os-example-mbed5-bootloader
.
README.md@5:d57adfa16284, 2017-03-28 (annotated)
- Committer:
- mbed_official
- Date:
- Tue Mar 28 10:45:25 2017 +0100
- Revision:
- 5:d57adfa16284
- Parent:
- 4:0daf612a367a
- Child:
- 11:d396becb5d76
Merge pull request #8 from 0xc0170/fix_readme_blinky
Readme: remove blinky app reference
.
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 | 2:fc74f70b51c3 | 5 | To read more about the bootloader, please visit [bootloader tutorial](https://docs.mbed.com/docs/mbed-os-handbook/en/latest/advanced/bootloader/). |
mbed_official | 2:fc74f70b51c3 | 6 | |
mbed_official | 0:8df79c088b12 | 7 | ## Required hardware |
mbed_official | 0:8df79c088b12 | 8 | * A supported board - [u-blox EVK-ODIN-W2](https://developer.mbed.org/platforms/ublox-EVK-ODIN-W2/), [Nucleo F429ZI](https://developer.mbed.org/platforms/ST-Nucleo-F429ZI/) or [K64F](https://developer.mbed.org/platforms/FRDM-K64F/). |
mbed_official | 4:0daf612a367a | 9 | * CI test shield. |
mbed_official | 0:8df79c088b12 | 10 | * SD card. |
mbed_official | 0:8df79c088b12 | 11 | |
mbed_official | 0:8df79c088b12 | 12 | ## Import the example application |
mbed_official | 0:8df79c088b12 | 13 | |
mbed_official | 0:8df79c088b12 | 14 | From the command-line, import the example: |
mbed_official | 0:8df79c088b12 | 15 | |
mbed_official | 0:8df79c088b12 | 16 | ``` |
mbed_official | 2:fc74f70b51c3 | 17 | mbed import mbed-os-example-bootloader |
mbed_official | 2:fc74f70b51c3 | 18 | cd mbed-os-example-bootloader |
mbed_official | 0:8df79c088b12 | 19 | ``` |
mbed_official | 0:8df79c088b12 | 20 | |
mbed_official | 0:8df79c088b12 | 21 | ## Set up application to be a bootloader |
mbed_official | 0:8df79c088b12 | 22 | |
mbed_official | 0:8df79c088b12 | 23 | All supported boards mentioned above are set up to build as a bootloader image. To add support for a new board, you must specify the size of the bootloader. |
mbed_official | 4:0daf612a367a | 24 | |
mbed_official | 4:0daf612a367a | 25 | To do this, set the target (replace `<TARGET_NAME>` with your target name) value `restrict_size` to the maximum bootloader size in mbed_app.json: |
mbed_official | 0:8df79c088b12 | 26 | |
mbed_official | 0:8df79c088b12 | 27 | ``` |
mbed_official | 0:8df79c088b12 | 28 | "target_overrides": { |
mbed_official | 0:8df79c088b12 | 29 | ... |
mbed_official | 2:fc74f70b51c3 | 30 | "<TARGET_NAME>": { |
mbed_official | 0:8df79c088b12 | 31 | "target.restrict_size": "0x20000" |
mbed_official | 0:8df79c088b12 | 32 | }, |
mbed_official | 0:8df79c088b12 | 33 | ... |
mbed_official | 0:8df79c088b12 | 34 | ``` |
mbed_official | 0:8df79c088b12 | 35 | |
mbed_official | 0:8df79c088b12 | 36 | Note - `restrict_size` pads the build image to the requested size. |
mbed_official | 0:8df79c088b12 | 37 | |
mbed_official | 0:8df79c088b12 | 38 | ## Now compile |
mbed_official | 0:8df79c088b12 | 39 | |
mbed_official | 0:8df79c088b12 | 40 | Invoke `mbed compile`, and specify the name of your platform and your favorite toolchain (`GCC_ARM`, `ARM`, `IAR`). For example, for the ARM Compiler 5: |
mbed_official | 0:8df79c088b12 | 41 | |
mbed_official | 0:8df79c088b12 | 42 | ``` |
mbed_official | 2:fc74f70b51c3 | 43 | mbed compile -m <TARGET_NAME> -t ARM |
mbed_official | 0:8df79c088b12 | 44 | ``` |
mbed_official | 0:8df79c088b12 | 45 | |
mbed_official | 0:8df79c088b12 | 46 | Your PC may take a few minutes to compile your code. At the end, you see the following result: |
mbed_official | 0:8df79c088b12 | 47 | |
mbed_official | 0:8df79c088b12 | 48 | ``` |
mbed_official | 0:8df79c088b12 | 49 | Merging Regions: |
mbed_official | 2:fc74f70b51c3 | 50 | Filling region application with .\BUILD\<TARGET_NAME>\ARM\mbed-os-example-bootloader_application.bin |
mbed_official | 0:8df79c088b12 | 51 | Padding region application with 0x11420 bytes |
mbed_official | 0:8df79c088b12 | 52 | Space used after regions merged: 0x20000 |
mbed_official | 0:8df79c088b12 | 53 | +-----------------------------+-------+-------+-------+ |
mbed_official | 0:8df79c088b12 | 54 | | Module | .text | .data | .bss | |
mbed_official | 0:8df79c088b12 | 55 | +-----------------------------+-------+-------+-------+ |
mbed_official | 0:8df79c088b12 | 56 | | Misc | 18481 | 24 | 1268 | |
mbed_official | 0:8df79c088b12 | 57 | | drivers | 2132 | 8 | 184 | |
mbed_official | 0:8df79c088b12 | 58 | | features/FEATURE_LWIP | 46 | 0 | 12560 | |
mbed_official | 0:8df79c088b12 | 59 | | features/filesystem | 12756 | 12 | 540 | |
mbed_official | 0:8df79c088b12 | 60 | | hal | 414 | 8 | 0 | |
mbed_official | 0:8df79c088b12 | 61 | | hal/TARGET_FLASH_CMSIS_ALGO | 520 | 28 | 0 | |
mbed_official | 0:8df79c088b12 | 62 | | platform | 2759 | 32 | 380 | |
mbed_official | 0:8df79c088b12 | 63 | | rtos | 144 | 8 | 0 | |
mbed_official | 0:8df79c088b12 | 64 | | rtos/rtx | 6954 | 100 | 8396 | |
mbed_official | 0:8df79c088b12 | 65 | | targets/TARGET_STM | 15560 | 568 | 736 | |
mbed_official | 0:8df79c088b12 | 66 | | Subtotals | 59766 | 788 | 24064 | |
mbed_official | 0:8df79c088b12 | 67 | +-----------------------------+-------+-------+-------+ |
mbed_official | 0:8df79c088b12 | 68 | Allocated Heap: unknown |
mbed_official | 0:8df79c088b12 | 69 | Allocated Stack: unknown |
mbed_official | 0:8df79c088b12 | 70 | Total Static RAM memory (data + bss): 24852 bytes |
mbed_official | 0:8df79c088b12 | 71 | Total RAM memory (data + bss + heap + stack): 24852 bytes |
mbed_official | 0:8df79c088b12 | 72 | Total Flash memory (text + data + misc): 60554 bytes |
mbed_official | 0:8df79c088b12 | 73 | |
mbed_official | 2:fc74f70b51c3 | 74 | Image: .\BUILD\<TARGET_NAME>\ARM\mbed-os-example-bootloader.bin |
mbed_official | 0:8df79c088b12 | 75 | ``` |
mbed_official | 0:8df79c088b12 | 76 | |
mbed_official | 4:0daf612a367a | 77 | It creates two binary files. The original uncombined image is in the output directory, <project-name>_application.bin, and the bootloader image is <project-name>.bin. |
mbed_official | 2:fc74f70b51c3 | 78 | |
mbed_official | 4:0daf612a367a | 79 | When the build succeeds, you have created a bootloader for your target. This bootloader defines the update file to be located at `/sd/mbed-os-example-bootloader-blinky_application.bin`. This is the binary bootloader flashes and then jumps to. |
mbed_official | 2:fc74f70b51c3 | 80 | |
mbed_official | 3:01d11bcf86eb | 81 | ## Set up application to use bootloader |
mbed_official | 3:01d11bcf86eb | 82 | |
mbed_official | 3:01d11bcf86eb | 83 | The next step is to build an application you can combine with your bootloader to create a loadable image. |
mbed_official | 3:01d11bcf86eb | 84 | |
mbed_official | 4:0daf612a367a | 85 | 1. Update your board to use the newly created bootloader image. To do this, set the target (replace `<TARGET_NAME>` with your target name) value `bootloader_img` to the file path of the bootloader image. |
mbed_official | 3:01d11bcf86eb | 86 | |
mbed_official | 3:01d11bcf86eb | 87 | ``` |
mbed_official | 3:01d11bcf86eb | 88 | "target_overrides": { |
mbed_official | 3:01d11bcf86eb | 89 | ... |
mbed_official | 3:01d11bcf86eb | 90 | "<TARGET_NAME>": { |
mbed_official | 3:01d11bcf86eb | 91 | "target.bootloader_img": "bootloader/<TARGET_NAME>.bin" |
mbed_official | 3:01d11bcf86eb | 92 | }, |
mbed_official | 3:01d11bcf86eb | 93 | ... |
mbed_official | 3:01d11bcf86eb | 94 | ``` |
mbed_official | 3:01d11bcf86eb | 95 | |
mbed_official | 3:01d11bcf86eb | 96 | 2. Invoke `mbed compile`, and specify the name of your platform and the toolchain you are using (`GCC_ARM`, `ARM`, `IAR`). For example, for the ARM Compiler 5: |
mbed_official | 3:01d11bcf86eb | 97 | |
mbed_official | 3:01d11bcf86eb | 98 | ``` |
mbed_official | 3:01d11bcf86eb | 99 | mbed compile -m <TARGET_NAME> -t ARM |
mbed_official | 3:01d11bcf86eb | 100 | ``` |
mbed_official | 3:01d11bcf86eb | 101 | |
mbed_official | 3:01d11bcf86eb | 102 | ### Program bootloader and application |
mbed_official | 3:01d11bcf86eb | 103 | |
mbed_official | 3:01d11bcf86eb | 104 | 1. Connect your mbed device to the computer over USB. |
mbed_official | 3:01d11bcf86eb | 105 | 1. Copy the application binary file to the mbed device. |
mbed_official | 3:01d11bcf86eb | 106 | 1. Press the reset button to start the program. |
mbed_official | 3:01d11bcf86eb | 107 | |
mbed_official | 3:01d11bcf86eb | 108 | ### Program application using SD card |
mbed_official | 3:01d11bcf86eb | 109 | |
mbed_official | 3:01d11bcf86eb | 110 | 1. Connect the SD card to your computer. |
mbed_official | 3:01d11bcf86eb | 111 | 1. Copy the application binary to the root of the SD card. |
mbed_official | 3:01d11bcf86eb | 112 | 1. Remove the SD card from your PC, and plug it into the mbed board. |
mbed_official | 3:01d11bcf86eb | 113 | 1. Press the reset button to start the firmware update. |
mbed_official | 3:01d11bcf86eb | 114 | |
mbed_official | 3:01d11bcf86eb | 115 | If a terminal is open, the following prints: |
mbed_official | 3:01d11bcf86eb | 116 | |
mbed_official | 3:01d11bcf86eb | 117 | ``` |
mbed_official | 3:01d11bcf86eb | 118 | Firmware update found |
mbed_official | 3:01d11bcf86eb | 119 | Starting application |
mbed_official | 3:01d11bcf86eb | 120 | ``` |
mbed_official | 0:8df79c088b12 | 121 | |
mbed_official | 0:8df79c088b12 | 122 | ## Troubleshooting |
mbed_official | 0:8df79c088b12 | 123 | |
mbed_official | 0:8df79c088b12 | 124 | 1. Make sure `mbed-cli` is working correctly and its version is `>1.0.0`. |
mbed_official | 0:8df79c088b12 | 125 | |
mbed_official | 0:8df79c088b12 | 126 | ``` |
mbed_official | 0:8df79c088b12 | 127 | mbed --version |
mbed_official | 0:8df79c088b12 | 128 | ``` |
mbed_official | 0:8df79c088b12 | 129 | |
mbed_official | 0:8df79c088b12 | 130 | If not, you can update it: |
mbed_official | 0:8df79c088b12 | 131 | |
mbed_official | 0:8df79c088b12 | 132 | ``` |
mbed_official | 0:8df79c088b12 | 133 | pip install mbed-cli --upgrade |
mbed_official | 0:8df79c088b12 | 134 | ``` |
mbed_official | 0:8df79c088b12 | 135 | |
mbed_official | 2:fc74f70b51c3 | 136 | 2. If using Keil MDK, make sure you have a license installed. [MDK-Lite](http://www.keil.com/arm/mdk.asp) has a 32 KB restriction on code size. |