Statistics
| Branch: | Tag: | Revision:

amiro-blt / README.txt @ 449d916a

History | View | Annotate | Download (9.53 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..2019  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://developer.arm.com/open-source/gnu-toolchain/gnu-rm> (old versions are
131
available at <https://launchpad.net/gcc-arm-embedded>). For installation of the
132
compiler toolchain and managing of multiple versions, it is highly recommended
133
to use the provided setup script. Alternatively you can install the compiler
134
manually by following the instructions that can be found on the web page.
135

    
136
If you are running a 64-bit operating system, you may have to install several
137
32-bit libraries in order to make older versions of the compiler work. The
138
required packages are libc6, libstdc++6, and libncurses5. You can run the
139
following shell commands to install the according 32-bit versions of the
140
packages:
141
  >$ sudo dpkg --add-architecture i386
142
  >$ sudo apt-get update
143
  >$ sudo apt-get install libc6:i386 libstdc++6:i386 libncurses5:i386
144

    
145

    
146
1.6 - CMake
147
-----------
148

    
149
In order to build the SerialBoot host application, CMake version 2.8 or later is
150
required. If possible, it is recommended to instal it from the standard
151
repositories of your operating system.
152

    
153

    
154

    
155
2 - RECOMMENDED SOFTWARE
156
------------------------
157

    
158
AMiRo-BLT provides support for the QtCreator IDE. In order to setup according
159
projects, use the ./setup.sh script and follow the instructions. It will
160
automatically generate the required files and you can import the projects by
161
opening the .creator files with Qtcreator IDE.
162

    
163

    
164

    
165
3 - COMPILING THE SOURCE CODE
166
-----------------------------
167

    
168
The AMiRo-BLT project is separated into two major parts: target- and host-
169
related software. The former comprises the bootloaders for the three base
170
modules of the AMiRo. The latter is the SerialBoot tool, which can be used to
171
flash further binaries (e.g. a complex operating system) to the microcontrollers
172
without connecting to the module directly (data is passed through via CAN bus).
173
Since the programming connector of the lowermost AMiRo module is the only one
174
accessible when the robot is fully set up, this enables to update the firmware
175
even for other modules.
176

    
177

    
178
3.1 - host software
179
-------------------
180

    
181
The stm32flash tool is requried to flash bootloader binaries to the MCUs.
182
Instructions for builing the tool are given in chapter 1.4 of this file.
183

    
184
The SerialBoot tool can be built by using cmake. The according CMakeLists.txt
185
file can be found in the ./Host/Source/SerialBoot/ directory. To ensure
186
compatibility with other software (e.g. AMiRo-OS) it is higly recommended to use
187
the provided ./setup.sh script to build SerialBoot. In the end the binary path
188
should be ./Host/Source/SerialBoot/build/SerialBoot, which is the default for
189
any scripts and tools that use SerialBoot.
190

    
191

    
192
3.2 - target software
193
---------------------
194

    
195
In the ./Target/Demo/ directory there are multiple subfolders, one for each
196
AMiRo base module. Within each of these is an additional Boot/ folder
197
(./Target/Demo/<device>/Boot/), which contains a makefile. Each bootloader can
198
be compiled by executing 'make' in these directories.
199

    
200
In order to flash the bootloader to a microcontroller, you first have to set
201
full read and write permissions to the USB ports of your system. To do so, first
202
create a new file by executing the following command:
203
  >$ sudo touch /etc/udev/rules.d/50-usb-serial.rules
204
Open the file in a text editor of your choice (sudo required) and add the
205
following lines:
206

    
207
  # Future Technology Devices International Ltd. - TTL-232RG
208
  SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*", SYMLINK+="ttyAMiRo%n",
209
  ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0666"
210

    
211
  # Future Technology Devices International Ltd. - FT231X
212
  SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*", SYMLINK+="ttyAMiRo%n",
213
  ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", MODE="0666"
214

    
215
Now connect the module you want to flash directly to your system (note that
216
indirect flashing is not possible for the bootloader itself) and run the command
217
  >$ make flash
218
If the procedure was not successful, the following hints might help:
219
  - Did your system apply the new udev rules?
220
    Reboot and try again!
221
  - Could the makefile execute the stm32flash tool?
222
    Reinitialize the submodule and try again!
223
  - Are the permissions for USB ports set correctly?
224
    Check the udev rules!
225
  - Are there any other applications using the serial connection?
226
    Close any other applications using the serial connection!
227
  - Is the AMiRo module connected to your system?
228
    Use the programming cable to connect the module to your system.
229
  - Is the AMiRo module powered up?
230
    Keep a charger plugged in during flashing.
231

    
232
ATTENTION:
233
Never flash a bootloader to the wrong module! Doing so might cause severe errors
234
and damage the robot.
235

    
236
================================================================================
237