Statistics
| Branch: | Tag: | Revision:

amiro-blt / README.txt @ 03906dc3

History | View | Annotate | Download (9.418 KB)

1
AMiRo-BLT is the bootloader and flashing toolchain for the base version of the
2
Autonomous Mini Robot (AMiRo) [1]. It is based on OpenBLT developed by Feaser
3
(see <http://feaser.com/en/openblt.php>).
4

    
5
Copyright (C) 2016..2018  Thomas Schöpping et al.
6
(a complete list of all authors is given below)
7

    
8
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

    
21
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

    
25
Authors:
26
 - Thomas Schöpping        <tschoepp[at]cit-ec.uni-bielefeld.de>
27
 - Stefan Herbrechtsmeier  <sherbrec[at]cit-ec.uni-bielefeld.de>
28
 - Marvin Barther
29

    
30
References:
31
 [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

    
37

    
38
################################################################################
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

    
50
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

    
54
================================================================================
55

    
56
CONTENTS:
57

    
58
  1  Required software
59
    1.1  Git
60
    1.2  GNU Make
61
    1.3  GCC
62
    1.4  stm32flash
63
    1.5  GCC ARM Embedded Toolchain
64
    1.6  CMake
65
  2  Recommended Software
66
  3  Compiling the source code
67
    3.1  host software
68
    3.2  target software
69

    
70
================================================================================
71

    
72

    
73

    
74
1 - REQUIRED SOFTWARE
75
---------------------
76

    
77
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
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
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
----------------
111

    
112
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
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

    
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
./Host/Source/stm32flash/INSTALL.
124

    
125

    
126
1.5 - GCC ARM Embedded Toolchain
127
--------------------------------
128

    
129
Various versions of the GCC for ARM embedded devices can be found at
130
<https://launchpad.net/gcc-arm-embedded>. For installation of the compiler
131
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

    
135
If you are running a 64-bit operating system, you may have to install several
136
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

    
143
1.6 - CMake
144
-----------
145

    
146
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
-----------------------------
164

    
165
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
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
---------------------
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
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
Open the file in a text editor of your choice (sudo required) and add the
202
following lines:
203

    
204
  # Future Technology Devices International Ltd. - TTL-232RG
205
  SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*", SYMLINK+="ttyAMiRo%n",
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]*", SYMLINK+="ttyAMiRo%n",
210
  ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", MODE="0666"
211

    
212
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
  >$ make flash
215
If the procedure was not successful, the following hints might help:
216
  - Did your system apply the new udev rules?
217
    Reboot and try again!
218
  - Could the makefile execute the stm32flash tool?
219
    Reinitialize the submodule and try again!
220
  - Are the permissions for USB ports set correctly?
221
    Check the udev rules!
222
  - Are there any other applications using the serial connection?
223
    Close any other applications using the serial connection!
224
  - Is the AMiRo module connected to your system?
225
    Use the programming cable to connect the module to your system.
226
  - Is the AMiRo module powered up?
227
    Keep a charger plugged in during flashing.
228

    
229
ATTENTION:
230
Never flash a bootloader to the wrong module! Doing so might cause severe errors
231
and damage the robot.
232

    
233
================================================================================
234