amiro-blt / README.md @ 43464dd5
History | View | Annotate | Download (10.2 KB)
1 | 01c0bf56 | Thomas Schöpping | About & License |
---|---|---|---|
2 | =============== |
||
3 | |||
4 | AMiRo-BLT is the bootloader and flashing toolchain for the base version of the |
||
5 | Autonomous Mini Robot (AMiRo) [1]. It is based on OpenBLT developed by Feaser |
||
6 | (see <http://feaser.com/en/openblt.php>). |
||
7 | |||
8 | Copyright (C) 2016..2020 Thomas Schöpping et al. |
||
9 | (a complete list of all authors is given below) |
||
10 | |||
11 | This program is free software: you can redistribute it and/or modify |
||
12 | it under the terms of the GNU General Public License as published by |
||
13 | the Free Software Foundation, either version 3 of the License, or (at |
||
14 | your option) any later version. |
||
15 | |||
16 | This program is distributed in the hope that it will be useful, but |
||
17 | WITHOUT ANY WARRANTY; without even the implied warranty of |
||
18 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
||
19 | General Public License for more details. |
||
20 | |||
21 | You should have received a copy of the GNU General Public License |
||
22 | along with this program. If not, see <http://www.gnu.org/licenses/>. |
||
23 | |||
24 | This research/work was supported by the Cluster of Excellence |
||
25 | Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld |
||
26 | University, which is funded by the German Research Foundation (DFG). |
||
27 | |||
28 | Authors: |
||
29 | |||
30 | - Thomas Schöpping (tschoepp@cit-ec.uni-bielefeld.de) |
||
31 | - Stefan Herbrechtsmeier (sherbrec@cit-ec.uni-bielefeld.de) |
||
32 | - Marvin Barther |
||
33 | |||
34 | References: |
||
35 | |||
36 | [1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A |
||
37 | modular & customizable open-source mini robot platform," 2016 20th |
||
38 | International Conference on System Theory, Control and Computing (ICSTCC), |
||
39 | Sinaia, 2016, pp. 687-692. |
||
40 | |||
41 | -------------------------------------------------------------------------------- |
||
42 | |||
43 | Contents |
||
44 | ======== |
||
45 | |||
46 | 1. Required Software |
||
47 | 1. Git |
||
48 | 2. GNU Make |
||
49 | 3. GCC |
||
50 | 4. stm32flash |
||
51 | 5. GNU ARM Embedded Toolchain |
||
52 | 6. CMake |
||
53 | 2. Recommended Software |
||
54 | 5c8c470f | Thomas Schöpping | 1. PlantUML |
55 | 2. QtCreator IDE |
||
56 | 01c0bf56 | Thomas Schöpping | 3. Compiling the Source Code |
57 | 1. Host Software |
||
58 | 2. Target Software |
||
59 | |||
60 | -------------------------------------------------------------------------------- |
||
61 | |||
62 | 5c8c470f | Thomas Schöpping | 1 Required Software |
63 | =================== |
||
64 | 01c0bf56 | Thomas Schöpping | |
65 | In order to compile and flash the AMiRo bootloader, some additional software is |
||
66 | required, all of which are described in detail in the following. |
||
67 | |||
68 | |||
69 | 5c8c470f | Thomas Schöpping | 1.1 Git |
70 | ------- |
||
71 | 01c0bf56 | Thomas Schöpping | |
72 | Since all main- and subprojects are available as Git repositories, installing a |
||
73 | recent version of the tool is mandatory. Most Linux distributions like Ubuntu |
||
74 | provide a sufficient version in their software repositories. |
||
75 | |||
76 | |||
77 | 5c8c470f | Thomas Schöpping | 1.2 GNU Make |
78 | ------------ |
||
79 | 01c0bf56 | Thomas Schöpping | |
80 | GNU Make usually comes as preinstalled tool on Ubuntu based operating systems. |
||
81 | If your system is missing GNU Make, it is recommended to install it from the |
||
82 | standard repositories since no special requirements (i.e. features of a very |
||
83 | recent version) are required. |
||
84 | |||
85 | |||
86 | 5c8c470f | Thomas Schöpping | 1.3 GCC |
87 | ------- |
||
88 | 01c0bf56 | Thomas Schöpping | |
89 | In order to build some required tools from source, GCC is required. It usually |
||
90 | comes as preinstalled tool on Ubuntu based operating systems. If your system is |
||
91 | missing GCC, it is recommended to install it from the standard repositories |
||
92 | since no special requirements (e.g. features of a very recent version) are |
||
93 | required. |
||
94 | |||
95 | |||
96 | 5c8c470f | Thomas Schöpping | 1.4 stm32flash |
97 | -------------- |
||
98 | 01c0bf56 | Thomas Schöpping | |
99 | This tool is required to flash the bootloader binaries to the microcontrollers |
||
100 | of the AMiRo base modules. Since it is included in this project as a Git |
||
101 | submodule, you can just run the setup script in the project root directory: |
||
102 | |||
103 | >$ ./setup.sh |
||
104 | |||
105 | Follow the instructions to download the source code and compile the tool. The |
||
106 | resulting binary path is `./Host/Source/stm32flash/stm32flash`. Other scripts |
||
107 | that require `stm32flash` will search for the binary at this location by |
||
108 | default. |
||
109 | The setup script does not install the tool to your system path, though, since |
||
110 | this usually requires root permissions. However, `stm32flash` provides a |
||
111 | `Makefile` with installation capabilities. Just Follow the instructions given in |
||
112 | the file `./Host/Source/stm32flash/INSTALL`. |
||
113 | |||
114 | 43464dd5 | Thomas Schöpping | Alternatively, some Linux distributions provide the tool in their software |
115 | repositories. If you do have root permissions on your system, you can install |
||
116 | the tool this way. However, the scripts will always check for a 'local' |
||
117 | installation in `./Host/Source/stm32flash/` first and only try a system-wide |
||
118 | installation afterwards. |
||
119 | |||
120 | 01c0bf56 | Thomas Schöpping | |
121 | 5c8c470f | Thomas Schöpping | 1.5 GNU ARM Embedded Toolchain |
122 | ------------------------------ |
||
123 | 01c0bf56 | Thomas Schöpping | |
124 | Various versions of the GCC for ARM embedded devices can be found at |
||
125 | <https://developer.arm.com/open-source/gnu-toolchain/gnu-rm> (old versions are |
||
126 | available at <https://launchpad.net/gcc-arm-embedded>). For installation of the |
||
127 | compiler toolchain and managing of multiple versions, it is highly recommended |
||
128 | to use the provided setup script. Alternatively you can install the compiler |
||
129 | manually by following the instructions that can be found on the web page. |
||
130 | |||
131 | If you are going to install an old version, which is not available as 64-bit |
||
132 | package, but your are running a 64-bit operating system, you have to install |
||
133 | several 32-bit libraries. The required packages are `libc6`, `libstdc++6`, and |
||
134 | `libncurses5`. You can run the following shell commands to install the according |
||
135 | 32-bit versions of the packages: |
||
136 | |||
137 | >$ sudo dpkg --add-architecture i386 |
||
138 | >$ sudo apt-get update |
||
139 | >$ sudo apt-get install libc6:i386 libstdc++6:i386 libncurses5:i386 |
||
140 | |||
141 | |||
142 | 5c8c470f | Thomas Schöpping | 1.6 CMake |
143 | --------- |
||
144 | 01c0bf56 | Thomas Schöpping | |
145 | In order to build the `SerialBoot` host application, `CMake` version 2.8 or |
||
146 | later is required. If possible, it is recommended to instal it from the standard |
||
147 | repositories of your operating system. |
||
148 | |||
149 | |||
150 | |||
151 | 5c8c470f | Thomas Schöpping | 2 Recommended Software |
152 | ====================== |
||
153 | |||
154 | The software tools named in this section are not essential for simply using or |
||
155 | 43464dd5 | Thomas Schöpping | further development of AMiRo-BLT, but are useful in both scenarios. |
156 | 5c8c470f | Thomas Schöpping | |
157 | |||
158 | 2.1 PlantUML |
||
159 | ------------ |
||
160 | |||
161 | PlantUML is a free and open source Java tool to generate UML diagrams via scrips |
||
162 | (see <https://plantuml.com>). AMiRo-BLT provides according scripts in the |
||
163 | `./Target/Doc/` directory. Please refer to the PlantUML documentation for how to |
||
164 | generate figures from these script files. |
||
165 | |||
166 | |||
167 | 2.2 QtCreator IDE |
||
168 | ----------------- |
||
169 | 01c0bf56 | Thomas Schöpping | |
170 | AMiRo-BLT provides support for the QtCreator IDE. In order to setup according |
||
171 | projects, use the setup script and follow the instructions. It will |
||
172 | automatically generate the required files and you can import the projects by |
||
173 | 5c8c470f | Thomas Schöpping | opening the `.creator` files with QtCreator IDE. |
174 | 43464dd5 | Thomas Schöpping | Please note that you will need to recompile the AMiRo-BLT source code after each |
175 | project generation, since the generator executes a compiler call. |
||
176 | 01c0bf56 | Thomas Schöpping | |
177 | |||
178 | |||
179 | 5c8c470f | Thomas Schöpping | 3 Compiling the Source Code |
180 | =========================== |
||
181 | 01c0bf56 | Thomas Schöpping | |
182 | 43464dd5 | Thomas Schöpping | The AMiRo-BLT project is separated into two major parts: target- and |
183 | host-related software. The former comprises the bootloaders for the base modules |
||
184 | of the AMiRo platform. The latter are the `stm32flash` tool as already mentioned |
||
185 | above and the `SerialBoot` tool, which can be used to flash further binaries |
||
186 | (e.g. an operating system) to the microcontrollers without connecting to the |
||
187 | module directly (data is passed through via CAN bus). Since the programming |
||
188 | connector of the lowermost AMiRo module is the only one accessible when the |
||
189 | robot is fully set up, this enables to update the firmware even for other |
||
190 | modules. |
||
191 | 01c0bf56 | Thomas Schöpping | |
192 | |||
193 | 5c8c470f | Thomas Schöpping | 3.1 Host Software |
194 | ----------------- |
||
195 | 01c0bf56 | Thomas Schöpping | |
196 | The `stm32flash` tool is requried to flash bootloader binaries to the MCUs. |
||
197 | 43464dd5 | Thomas Schöpping | Instructions on how to build and intall the tool are given in chapter 1.4 of |
198 | this file. |
||
199 | 01c0bf56 | Thomas Schöpping | |
200 | The `SerialBoot` tool can be built by using `cmake`. The according |
||
201 | `CMakeLists.txt` file can be found in the `./Host/Source/SerialBoot/` directory. |
||
202 | To ensure compatibility with other software (e.g. AMiRo-OS) it is higly |
||
203 | recommended to use the provided setup script to build `SerialBoot`. In the end, |
||
204 | the binary path should be `./Host/Source/SerialBoot/build/SerialBoot`, which is |
||
205 | the default for any scripts and tools that use `SerialBoot`. |
||
206 | |||
207 | |||
208 | 5c8c470f | Thomas Schöpping | 3.2 Target Software |
209 | ------------------- |
||
210 | 01c0bf56 | Thomas Schöpping | |
211 | Module specific code for the several AMiRo base modules is located in the |
||
212 | individual subfolders in the `./Target/Modules/` directory. To compile |
||
213 | (and flash; please read further) the bootloaders, it is recommended to run |
||
214 | `make` in the `./Target/` folder. |
||
215 | |||
216 | In order to flash the bootloader to a microcontroller, you first have to set |
||
217 | 43464dd5 | Thomas Schöpping | full read and write permissions to the USB ports of your system when a |
218 | programming cable is plugged in. To do so, first create a new file by executing |
||
219 | the following command: |
||
220 | 01c0bf56 | Thomas Schöpping | |
221 | >$ sudo touch /etc/udev/rules.d/50-usb-serial.rules |
||
222 | |||
223 | Open the file in a text editor of your choice (root permissions required!) and |
||
224 | add the following lines: |
||
225 | |||
226 | # Future Technology Devices International Ltd. - TTL-232RG |
||
227 | SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*", SYMLINK+="ttyAMiRo%n", |
||
228 | ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0666" |
||
229 | |||
230 | # Future Technology Devices International Ltd. - FT231X |
||
231 | SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*", SYMLINK+="ttyAMiRo%n", |
||
232 | ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", MODE="0666" |
||
233 | |||
234 | Now connect the module you want to flash directly to your system (note that |
||
235 | 43464dd5 | Thomas Schöpping | indirect flashing using `SerialBoot` is not possible for the bootloader itself) and run the command |
236 | 01c0bf56 | Thomas Schöpping | |
237 | >$ make flash |
||
238 | |||
239 | If the procedure was not successful, the following hints might help: |
||
240 | |||
241 | 43464dd5 | Thomas Schöpping | * Did your system apply the new `udev` rules? |
242 | Re-login (or reboot) and try again! |
||
243 | * Could make execute the stm32flash tool? |
||
244 | Check the stm32flash installation (reinitialize the submodule if required) and try again! |
||
245 | * Are the permissions for USB ports set correctly? |
||
246 | 01c0bf56 | Thomas Schöpping | Check the udev rules! |
247 | 43464dd5 | Thomas Schöpping | * Are there any other applications using the serial connection? |
248 | 01c0bf56 | Thomas Schöpping | Close any other applications using the serial connection! |
249 | 43464dd5 | Thomas Schöpping | * Is the AMiRo module connected to your system? |
250 | Use the programming cable to connect the module to your system! |
||
251 | * Is the AMiRo module powered up? |
||
252 | Keep a charger plugged in during flashing! |
||
253 | * Was there an error when opening the ports? |
||
254 | Please read on! |
||
255 | |||
256 | By default, the scripts use the first matching port (i.e. `/dev/ttyAMiRo0` or |
||
257 | `/dev/ttyUSB0`) for flashing. If you have connected multiple AMiRo boards to |
||
258 | your system, those will be listed with increasing numbers in their identifiers. |
||
259 | Furthermore, other USB devices (also internal components) might be listed as |
||
260 | such as well. In those cases, you have to specify the correct port manually when |
||
261 | calling `make`: |
||
262 | |||
263 | >$ make flash STM32FLASH_PORT=/dev/ttyAMiRo# |
||
264 | |||
265 | where you have to replace the trailing `#` with the according integer. |
||
266 | 01c0bf56 | Thomas Schöpping | |
267 | **Attention**: Never flash a bootloader to the wrong module! Doing so might |
||
268 | 5c8c470f | Thomas Schöpping | cause severe errors and damage the hardware. |