Statistics
| Branch: | Tag: | Revision:

amiro-blt / README.md @ master

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.