Statistics
| Branch: | Tag: | Revision:

amiro-blt / README.txt @ f3866909

History | View | Annotate | Download (9.373 KB)

1 4cce70a8 Thomas Schöpping
AMiRo-BLT is the bootloader and flashing toolchain for the base version of the
2 9c219069 Thomas Schöpping
Autonomous Mini Robot (AMiRo) [1]. It is based on OpenBLT developed by Feaser
3 4cce70a8 Thomas Schöpping
(see <http://feaser.com/en/openblt.php>).
4 69661903 Thomas Schöpping
5 4f07e80a Thomas Schöpping
Copyright (C) 2016..2018  Thomas Schöpping et al.
6 69661903 Thomas Schöpping
(a complete list of all authors is given below)
7
8 4cce70a8 Thomas Schöpping
This program is free software: you can redistribute it and/or modify
9
it under the terms of the GNU General Public License as published by
10
the Free Software Foundation, either version 3 of the License, or (at
11
your option) any later version.
12
13
This program is distributed in the hope that it will be useful, but
14
WITHOUT ANY WARRANTY; without even the implied warranty of
15
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16
General Public License for more details.
17
18
You should have received a copy of the GNU General Public License
19
along with this program.  If not, see <http://www.gnu.org/licenses/>.
20 69661903 Thomas Schöpping
21 da350eab Thomas Schöpping
This research/work was supported by the Cluster of Excellence
22
Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld
23
University, which is funded by the German Research Foundation (DFG).
24 69661903 Thomas Schöpping
25
Authors:
26
 - Thomas Schöpping        <tschoepp[at]cit-ec.uni-bielefeld.de>
27 d91fca20 Thomas Schöpping
 - Stefan Herbrechtsmeier  <sherbrec[at]cit-ec.uni-bielefeld.de>
28 69661903 Thomas Schöpping
 - Marvin Barther
29
30
References:
31 9c219069 Thomas Schöpping
 [1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A
32
     modular & customizable open-source mini robot platform," 2016 20th
33
     International Conference on System Theory, Control and Computing (ICSTCC),
34
     Sinaia, 2016, pp. 687-692.
35
36 69661903 Thomas Schöpping
37
38 4cce70a8 Thomas Schöpping
################################################################################
39
#                                                                              #
40
#        RRRRRRRR   EEEEEEEE     AAA     DDDDDDDD   MM     MM  EEEEEEEE        #
41
#        RR     RR  EE          AA AA    DD     DD  MMM   MMM  EE              #
42
#        RR     RR  EE         AA   AA   DD     DD  MMMM MMMM  EE              #
43
#        RRRRRRRR   EEEEEE    AA     AA  DD     DD  MM MMM MM  EEEEEE          #
44
#        RR   RR    EE        AAAAAAAAA  DD     DD  MM     MM  EE              #
45
#        RR    RR   EE        AA     AA  DD     DD  MM     MM  EE              #
46
#        RR     RR  EEEEEEEE  AA     AA  DDDDDDDD   MM     MM  EEEEEEEE        #
47
#                                                                              #
48
################################################################################
49 69661903 Thomas Schöpping
50 4cce70a8 Thomas Schöpping
This file will help you to setup all required software on your system, compile
51
the source code, and use the tools and flash the bootloader software to the
52
AMiRo base modules.
53 69661903 Thomas Schöpping
54 4cce70a8 Thomas Schöpping
================================================================================
55 69661903 Thomas Schöpping
56
CONTENTS:
57
58 4cce70a8 Thomas Schöpping
  1  Required software
59 3fbc2ae9 Thomas Schöpping
    1.1  Git
60 75f9dc42 Thomas Schöpping
    1.2  GNU Make
61
    1.3  GCC
62
    1.4  stm32flash
63
    1.5  GCC ARM Embedded Toolchain
64
    1.6  CMake
65 4cce70a8 Thomas Schöpping
  2  Recommended Software
66
  3  Compiling the source code
67 75f9dc42 Thomas Schöpping
    3.1  host software
68
    3.2  target software
69 4cce70a8 Thomas Schöpping
70
================================================================================
71
72
73 69661903 Thomas Schöpping
74
1 - REQUIRED SOFTWARE
75
---------------------
76
77 4cce70a8 Thomas Schöpping
The only third party software required are stm32flash and GCC for ARM embedded
78
devices. While the latter is a compiler to build binaries that are compatible
79
with the microcontrollers (MCUs) of AMiRo, the former is used to write this data
80
to the hardware.
81
82
83 3fbc2ae9 Thomas Schöpping
1.1 - Git
84
---------
85
86
Since all main- and subprojects are available as Git repositories, installing a
87
recent version of the tool is mandatory.
88
89
90 75f9dc42 Thomas Schöpping
1.2 - GNU Make
91
--------------
92
93
GNU Make usually comes as preinstalled tool on Ubuntu based operating systems.
94
If your system is missing GNU Make, it is recommended to install it from the
95
standard repositories since no special requirements (e.g. features of a very
96
recent version) are required.
97
98
99
1.3 - GCC
100
---------
101
102
In order to build some required tools from source, GCC is required. It usually
103
comes as preinstalled tool on Ubuntu based operating systems. If your system is
104
missing GCC, it is recommended to install it from the standard repositories
105
since no special requirements (e.g. features of a very recent version) are
106
required.
107
108
109
1.4 - stm32flash
110 4cce70a8 Thomas Schöpping
----------------
111 69661903 Thomas Schöpping
112 6feb961b Thomas Schöpping
This tool is required to flash the bootloader binaries to the microcontrollers.
113
Since it is included in this project as a submodule, you can just run the setup
114
script in the root directory:
115
  >$ ./setup.sh
116
Follow the instructions to download the source code and compile the tool. The
117 75f9dc42 Thomas Schöpping
resulting binary path is ./Host/Source/stm32flash/stm32flash. Other scripts that
118
require stm32flash will search for the binary at this location by default.
119 6feb961b Thomas Schöpping
120
The setup script does not install the tool to your system path, though, since
121
this usually requires root permissions. However, stm32flash provides a Makefile
122
with installation capabilities. Just Follow the instructions given in the file
123 8446a3a1 Thomas Schöpping
./Host/Source/stm32flash/INSTALL.
124 69661903 Thomas Schöpping
125 4cce70a8 Thomas Schöpping
126 75f9dc42 Thomas Schöpping
1.5 - GCC ARM Embedded Toolchain
127 4cce70a8 Thomas Schöpping
--------------------------------
128 69661903 Thomas Schöpping
129
Various versions of the GCC for ARM embedded devices can be found at
130 4cce70a8 Thomas Schöpping
<https://launchpad.net/gcc-arm-embedded>. For installation of the compiler
131 75f9dc42 Thomas Schöpping
toolchain and managing of multiple versions, it is highly recommended to use the
132
provided setup script. Alternatively you can install the compiler manually by
133
following the instructions that can be found on the web page.
134 4cce70a8 Thomas Schöpping
135 75f9dc42 Thomas Schöpping
If you are running a 64-bit operating system, you may have to install several
136 3fbc2ae9 Thomas Schöpping
32-bit libraries in order to make the compiler work. The required packages are
137
libc6, libstdc++6, and libncurses5. You can run the following shell commands to
138
install the according 32-bit versions of the packages:
139
  >$ sudo dpkg --add-architecture i386 && sudo apt-get update
140
  >$ sudo apt-get install libc6:i386 libstdc++6:i386 libncurses5:i386
141
142 4cce70a8 Thomas Schöpping
143 75f9dc42 Thomas Schöpping
1.6 - CMake
144 4cce70a8 Thomas Schöpping
-----------
145 69661903 Thomas Schöpping
146 4cce70a8 Thomas Schöpping
In order to build the SerialBoot host application, CMake version 2.8 or later is
147
required. If possible, it is recommended to instal it from the standard
148
repositories of your operating system.
149
150
151
152
2 - RECOMMENDED SOFTWARE
153
------------------------
154
155
AMiRo-BLT provides support for the QtCreator IDE. In order to setup according
156
projects, use the ./setup.sh script and follow the instructions. It will
157
automatically generate the required files and you can import the projects by
158
opening the .creator files with Qtcreator IDE.
159
160
161
162
3 - COMPILING THE SOURCE CODE
163 69661903 Thomas Schöpping
-----------------------------
164
165 4cce70a8 Thomas Schöpping
The AMiRo-BLT project is separated into two major parts: target- and host-
166
related software. The former comprises the bootloaders for the three base
167
modules of the AMiRo. The latter is the SerialBoot tool, which can be used to
168
flash further binaries (e.g. a complex operating system) to the microcontrollers
169
without connecting to the module directly (data is passed through via CAN bus).
170
Since the programming connector of the lowermost AMiRo module is the only one
171
accessible when the robot is fully set up, this enables to update the firmware
172
even for other modules.
173
174
175 75f9dc42 Thomas Schöpping
3.1 - host software
176
-------------------
177
178
The stm32flash tool is requried to flash bootloader binaries to the MCUs.
179
Instructions for builing the tool are given in chapter 1.4 of this file.
180
181
The SerialBoot tool can be built by using cmake. The according CMakeLists.txt
182
file can be found in the ./Host/Source/SerialBoot/ directory. To ensure
183
compatibility with other software (e.g. AMiRo-OS) it is higly recommended to use
184
the provided ./setup.sh script to build SerialBoot. In the end the binary path
185
should be ./Host/Source/SerialBoot/build/SerialBoot, which is the default for
186
any scripts and tools that use SerialBoot.
187
188
189
3.2 - target software
190 4cce70a8 Thomas Schöpping
---------------------
191
192
In the ./Target/Demo/ directory there are three subfolders, one for each AMiRo
193
base module. Within each of these is an additional Boot/ folder
194
(./Target/Demo/<device>/Boot/), which contains a makefile. Each bootloader can
195
be compiled by executing 'make' in these directories.
196
197
In order to flash the bootloader to a microcontroller, you first have to set
198 332fd270 Thomas Schöpping
full read and write permissions to the USB ports of your system. To do so, first
199
create a new file by executing the following command:
200
  >$ sudo touch /etc/udev/rules.d/50-usb-serial.rules
201 75f9dc42 Thomas Schöpping
Open the file in a text editor of your choice (sudo required) and add the
202
following lines:
203 332fd270 Thomas Schöpping
204
  # Future Technology Devices International Ltd. - TTL-232RG
205
  SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*",
206
  ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0666"
207
208
  # Future Technology Devices International Ltd. - FT231X
209
  SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*",
210
  ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", MODE="0666"
211
212 4cce70a8 Thomas Schöpping
Now connect the module you want to flash directly to your system (note that
213
indirect flashing is not possible for the bootloader itself) and run the command
214 69661903 Thomas Schöpping
  >$ make flash
215
If the procedure was not successful, the following hints might help:
216 75f9dc42 Thomas Schöpping
  - Did your system apply the new udev rules?
217 332fd270 Thomas Schöpping
    Reboot and try again!
218 4cce70a8 Thomas Schöpping
  - Could the makefile execute the stm32flash tool?
219 332fd270 Thomas Schöpping
    Reinitialize the submodule and try again!
220 4cce70a8 Thomas Schöpping
  - Are the permissions for USB ports set correctly?
221 332fd270 Thomas Schöpping
    Check the udev rules!
222 4cce70a8 Thomas Schöpping
  - Are there any other applications using the serial connection?
223 332fd270 Thomas Schöpping
    Close any other applications using the serial connection!
224 4cce70a8 Thomas Schöpping
  - Is the AMiRo module connected to your system?
225 332fd270 Thomas Schöpping
    Use the programming cable to connect the module to your system.
226 4cce70a8 Thomas Schöpping
  - Is the AMiRo module powered up?
227 332fd270 Thomas Schöpping
    Keep a charger plugged in during flashing.
228 4cce70a8 Thomas Schöpping
229
ATTENTION:
230
Never flash a bootloader to the wrong module! Doing so might cause severe errors
231
and damage the robot.
232 69661903 Thomas Schöpping
233 4cce70a8 Thomas Schöpping
================================================================================