Statistics
| Branch: | Tag: | Revision:

amiro-blt / README.txt @ 1446566f

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