amiro-blt / README.md @ 5c8c470f
History | View | Annotate | Download (9.154 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 | |||
115 | 5c8c470f | Thomas Schöpping | 1.5 GNU ARM Embedded Toolchain |
116 | ------------------------------ |
||
117 | 01c0bf56 | Thomas Schöpping | |
118 | Various versions of the GCC for ARM embedded devices can be found at |
||
119 | <https://developer.arm.com/open-source/gnu-toolchain/gnu-rm> (old versions are |
||
120 | available at <https://launchpad.net/gcc-arm-embedded>). For installation of the |
||
121 | compiler toolchain and managing of multiple versions, it is highly recommended |
||
122 | to use the provided setup script. Alternatively you can install the compiler |
||
123 | manually by following the instructions that can be found on the web page. |
||
124 | |||
125 | If you are going to install an old version, which is not available as 64-bit |
||
126 | package, but your are running a 64-bit operating system, you have to install |
||
127 | several 32-bit libraries. The required packages are `libc6`, `libstdc++6`, and |
||
128 | `libncurses5`. You can run the following shell commands to install the according |
||
129 | 32-bit versions of the packages: |
||
130 | |||
131 | >$ sudo dpkg --add-architecture i386 |
||
132 | >$ sudo apt-get update |
||
133 | >$ sudo apt-get install libc6:i386 libstdc++6:i386 libncurses5:i386 |
||
134 | |||
135 | |||
136 | 5c8c470f | Thomas Schöpping | 1.6 CMake |
137 | --------- |
||
138 | 01c0bf56 | Thomas Schöpping | |
139 | In order to build the `SerialBoot` host application, `CMake` version 2.8 or |
||
140 | later is required. If possible, it is recommended to instal it from the standard |
||
141 | repositories of your operating system. |
||
142 | |||
143 | |||
144 | |||
145 | 5c8c470f | Thomas Schöpping | 2 Recommended Software |
146 | ====================== |
||
147 | |||
148 | The software tools named in this section are not essential for simply using or |
||
149 | further development of AMiRo-BLT, but can help for both scenarios. |
||
150 | |||
151 | |||
152 | 2.1 PlantUML |
||
153 | ------------ |
||
154 | |||
155 | PlantUML is a free and open source Java tool to generate UML diagrams via scrips |
||
156 | (see <https://plantuml.com>). AMiRo-BLT provides according scripts in the |
||
157 | `./Target/Doc/` directory. Please refer to the PlantUML documentation for how to |
||
158 | generate figures from these script files. |
||
159 | |||
160 | |||
161 | 2.2 QtCreator IDE |
||
162 | ----------------- |
||
163 | 01c0bf56 | Thomas Schöpping | |
164 | AMiRo-BLT provides support for the QtCreator IDE. In order to setup according |
||
165 | projects, use the setup script and follow the instructions. It will |
||
166 | automatically generate the required files and you can import the projects by |
||
167 | 5c8c470f | Thomas Schöpping | opening the `.creator` files with QtCreator IDE. |
168 | Please note that you will need to recompile the AMiRo-OS source code after each |
||
169 | project generation, since the generator runs a compiler call. |
||
170 | 01c0bf56 | Thomas Schöpping | |
171 | |||
172 | |||
173 | 5c8c470f | Thomas Schöpping | 3 Compiling the Source Code |
174 | =========================== |
||
175 | 01c0bf56 | Thomas Schöpping | |
176 | The AMiRo-BLT project is separated into two major parts: target- and host- |
||
177 | related software. The former comprises the bootloaders for the three base |
||
178 | modules of the AMiRo platform. The latter is the `SerialBoot` tool, which can be |
||
179 | used to flash further binaries (e.g. an operating system) to the |
||
180 | microcontrollers without connecting to the module directly (data is passed |
||
181 | through via CAN bus). Since the programming connector of the lowermost AMiRo |
||
182 | module is the only one accessible when the robot is fully set up, this enables |
||
183 | to update the firmware even for other modules. |
||
184 | |||
185 | |||
186 | 5c8c470f | Thomas Schöpping | 3.1 Host Software |
187 | ----------------- |
||
188 | 01c0bf56 | Thomas Schöpping | |
189 | The `stm32flash` tool is requried to flash bootloader binaries to the MCUs. |
||
190 | Instructions for builing the tool are given in chapter 1.4 of this file. |
||
191 | |||
192 | The `SerialBoot` tool can be built by using `cmake`. The according |
||
193 | `CMakeLists.txt` file can be found in the `./Host/Source/SerialBoot/` directory. |
||
194 | To ensure compatibility with other software (e.g. AMiRo-OS) it is higly |
||
195 | recommended to use the provided setup script to build `SerialBoot`. In the end, |
||
196 | the binary path should be `./Host/Source/SerialBoot/build/SerialBoot`, which is |
||
197 | the default for any scripts and tools that use `SerialBoot`. |
||
198 | |||
199 | |||
200 | 5c8c470f | Thomas Schöpping | 3.2 Target Software |
201 | ------------------- |
||
202 | 01c0bf56 | Thomas Schöpping | |
203 | Module specific code for the several AMiRo base modules is located in the |
||
204 | individual subfolders in the `./Target/Modules/` directory. To compile |
||
205 | (and flash; please read further) the bootloaders, it is recommended to run |
||
206 | `make` in the `./Target/` folder. |
||
207 | |||
208 | In order to flash the bootloader to a microcontroller, you first have to set |
||
209 | full read and write permissions to the USB ports of your system. To do so, first |
||
210 | create a new file by executing the following command: |
||
211 | |||
212 | >$ sudo touch /etc/udev/rules.d/50-usb-serial.rules |
||
213 | |||
214 | Open the file in a text editor of your choice (root permissions required!) and |
||
215 | add the following lines: |
||
216 | |||
217 | # Future Technology Devices International Ltd. - TTL-232RG |
||
218 | SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*", SYMLINK+="ttyAMiRo%n", |
||
219 | ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0666" |
||
220 | |||
221 | # Future Technology Devices International Ltd. - FT231X |
||
222 | SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*", SYMLINK+="ttyAMiRo%n", |
||
223 | ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", MODE="0666" |
||
224 | |||
225 | Now connect the module you want to flash directly to your system (note that |
||
226 | indirect flashing is not possible for the bootloader itself) and run the command |
||
227 | |||
228 | >$ make flash |
||
229 | |||
230 | If the procedure was not successful, the following hints might help: |
||
231 | |||
232 | * Did your system apply the new `udev` rules? |
||
233 | Reboot and try again! |
||
234 | * Could the makefile execute the stm32flash tool? |
||
235 | Reinitialize the submodule and try again! |
||
236 | * Are the permissions for USB ports set correctly? |
||
237 | Check the udev rules! |
||
238 | * Are there any other applications using the serial connection? |
||
239 | Close any other applications using the serial connection! |
||
240 | * Is the AMiRo module connected to your system? |
||
241 | Use the programming cable to connect the module to your system. |
||
242 | * Is the AMiRo module powered up? |
||
243 | Keep a charger plugged in during flashing. |
||
244 | |||
245 | **Attention**: Never flash a bootloader to the wrong module! Doing so might |
||
246 | 5c8c470f | Thomas Schöpping | cause severe errors and damage the hardware. |