Statistics
| Branch: | Tag: | Revision:

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