amiro-blt / README.md @ 01c0bf56
History | View | Annotate | Download (8.54 KB)
1 |
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 |
3. Compiling the Source Code |
55 |
1. Host Software |
56 |
2. Target Software |
57 |
|
58 |
-------------------------------------------------------------------------------- |
59 |
|
60 |
1 Required Software |
61 |
===================== |
62 |
|
63 |
In order to compile and flash the AMiRo bootloader, some additional software is |
64 |
required, all of which are described in detail in the following. |
65 |
|
66 |
|
67 |
1.1 Git |
68 |
--------- |
69 |
|
70 |
Since all main- and subprojects are available as Git repositories, installing a |
71 |
recent version of the tool is mandatory. Most Linux distributions like Ubuntu |
72 |
provide a sufficient version in their software repositories. |
73 |
|
74 |
|
75 |
1.2 GNU Make |
76 |
-------------- |
77 |
|
78 |
GNU Make usually comes as preinstalled tool on Ubuntu based operating systems. |
79 |
If your system is missing GNU Make, it is recommended to install it from the |
80 |
standard repositories since no special requirements (i.e. features of a very |
81 |
recent version) are required. |
82 |
|
83 |
|
84 |
1.3 GCC |
85 |
--------- |
86 |
|
87 |
In order to build some required tools from source, GCC is required. It usually |
88 |
comes as preinstalled tool on Ubuntu based operating systems. If your system is |
89 |
missing GCC, it is recommended to install it from the standard repositories |
90 |
since no special requirements (e.g. features of a very recent version) are |
91 |
required. |
92 |
|
93 |
|
94 |
1.4 stm32flash |
95 |
---------------- |
96 |
|
97 |
This tool is required to flash the bootloader binaries to the microcontrollers |
98 |
of the AMiRo base modules. Since it is included in this project as a Git |
99 |
submodule, you can just run the setup script in the project root directory: |
100 |
|
101 |
>$ ./setup.sh |
102 |
|
103 |
Follow the instructions to download the source code and compile the tool. The |
104 |
resulting binary path is `./Host/Source/stm32flash/stm32flash`. Other scripts |
105 |
that require `stm32flash` will search for the binary at this location by |
106 |
default. |
107 |
The setup script does not install the tool to your system path, though, since |
108 |
this usually requires root permissions. However, `stm32flash` provides a |
109 |
`Makefile` with installation capabilities. Just Follow the instructions given in |
110 |
the file `./Host/Source/stm32flash/INSTALL`. |
111 |
|
112 |
|
113 |
1.5 GNU ARM Embedded Toolchain |
114 |
-------------------------------- |
115 |
|
116 |
Various versions of the GCC for ARM embedded devices can be found at |
117 |
<https://developer.arm.com/open-source/gnu-toolchain/gnu-rm> (old versions are |
118 |
available at <https://launchpad.net/gcc-arm-embedded>). For installation of the |
119 |
compiler toolchain and managing of multiple versions, it is highly recommended |
120 |
to use the provided setup script. Alternatively you can install the compiler |
121 |
manually by following the instructions that can be found on the web page. |
122 |
|
123 |
If you are going to install an old version, which is not available as 64-bit |
124 |
package, but your are running a 64-bit operating system, you have to install |
125 |
several 32-bit libraries. The required packages are `libc6`, `libstdc++6`, and |
126 |
`libncurses5`. You can run the following shell commands to install the according |
127 |
32-bit versions of the packages: |
128 |
|
129 |
>$ sudo dpkg --add-architecture i386 |
130 |
>$ sudo apt-get update |
131 |
>$ sudo apt-get install libc6:i386 libstdc++6:i386 libncurses5:i386 |
132 |
|
133 |
|
134 |
1.6 CMake |
135 |
----------- |
136 |
|
137 |
In order to build the `SerialBoot` host application, `CMake` version 2.8 or |
138 |
later is required. If possible, it is recommended to instal it from the standard |
139 |
repositories of your operating system. |
140 |
|
141 |
|
142 |
|
143 |
2 Recommended Software |
144 |
======================== |
145 |
|
146 |
AMiRo-BLT provides support for the QtCreator IDE. In order to setup according |
147 |
projects, use the setup script and follow the instructions. It will |
148 |
automatically generate the required files and you can import the projects by |
149 |
opening the `.creator` files with QtCreator IDE. |
150 |
|
151 |
|
152 |
|
153 |
3 Compiling the Source Code |
154 |
============================= |
155 |
|
156 |
The AMiRo-BLT project is separated into two major parts: target- and host- |
157 |
related software. The former comprises the bootloaders for the three base |
158 |
modules of the AMiRo platform. The latter is the `SerialBoot` tool, which can be |
159 |
used to flash further binaries (e.g. an operating system) to the |
160 |
microcontrollers without connecting to the module directly (data is passed |
161 |
through via CAN bus). Since the programming connector of the lowermost AMiRo |
162 |
module is the only one accessible when the robot is fully set up, this enables |
163 |
to update the firmware even for other modules. |
164 |
|
165 |
|
166 |
3.1 Host Software |
167 |
------------------- |
168 |
|
169 |
The `stm32flash` tool is requried to flash bootloader binaries to the MCUs. |
170 |
Instructions for builing the tool are given in chapter 1.4 of this file. |
171 |
|
172 |
The `SerialBoot` tool can be built by using `cmake`. The according |
173 |
`CMakeLists.txt` file can be found in the `./Host/Source/SerialBoot/` directory. |
174 |
To ensure compatibility with other software (e.g. AMiRo-OS) it is higly |
175 |
recommended to use the provided setup script to build `SerialBoot`. In the end, |
176 |
the binary path should be `./Host/Source/SerialBoot/build/SerialBoot`, which is |
177 |
the default for any scripts and tools that use `SerialBoot`. |
178 |
|
179 |
|
180 |
3.2 Target Software |
181 |
--------------------- |
182 |
|
183 |
Module specific code for the several AMiRo base modules is located in the |
184 |
individual subfolders in the `./Target/Modules/` directory. To compile |
185 |
(and flash; please read further) the bootloaders, it is recommended to run |
186 |
`make` in the `./Target/` folder. |
187 |
|
188 |
In order to flash the bootloader to a microcontroller, you first have to set |
189 |
full read and write permissions to the USB ports of your system. To do so, first |
190 |
create a new file by executing the following command: |
191 |
|
192 |
>$ sudo touch /etc/udev/rules.d/50-usb-serial.rules |
193 |
|
194 |
Open the file in a text editor of your choice (root permissions required!) and |
195 |
add the following lines: |
196 |
|
197 |
# Future Technology Devices International Ltd. - TTL-232RG |
198 |
SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*", SYMLINK+="ttyAMiRo%n", |
199 |
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0666" |
200 |
|
201 |
# Future Technology Devices International Ltd. - FT231X |
202 |
SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*", SYMLINK+="ttyAMiRo%n", |
203 |
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", MODE="0666" |
204 |
|
205 |
Now connect the module you want to flash directly to your system (note that |
206 |
indirect flashing is not possible for the bootloader itself) and run the command |
207 |
|
208 |
>$ make flash |
209 |
|
210 |
If the procedure was not successful, the following hints might help: |
211 |
|
212 |
* Did your system apply the new `udev` rules? |
213 |
Reboot and try again! |
214 |
* Could the makefile execute the stm32flash tool? |
215 |
Reinitialize the submodule and try again! |
216 |
* Are the permissions for USB ports set correctly? |
217 |
Check the udev rules! |
218 |
* Are there any other applications using the serial connection? |
219 |
Close any other applications using the serial connection! |
220 |
* Is the AMiRo module connected to your system? |
221 |
Use the programming cable to connect the module to your system. |
222 |
* Is the AMiRo module powered up? |
223 |
Keep a charger plugged in during flashing. |
224 |
|
225 |
**Attention**: Never flash a bootloader to the wrong module! Doing so might |
226 |
cause severe errors and damage the robot. |
227 |
|