Statistics
| Branch: | Tag: | Revision:

amiro-os / README.txt @ e5606def

History | View | Annotate | Download (8.788 KB)

1 3dcad54e Thomas Schöpping
AMiRo-OS is the operating system for the base version of the Autonomous Mini
2
Robot (AMiRo) [1]. It utilizes ChibiOS (a real-time operating system for
3
embedded devices developed by Giovanni di Sirio; see <http://chibios.org>) as
4
system kernel and extends it with platform specific functionalities.
5 58fe0e0b Thomas Schöpping
6 3dcad54e Thomas Schöpping
Copyright (C) 2016..2017  Thomas Schöpping et al.
7 58fe0e0b Thomas Schöpping
(a complete list of all authors is given below)
8
9
This program is free software: you can redistribute it and/or modify
10
it under the terms of the GNU General Public License as published by
11
the Free Software Foundation, either version 3 of the License, or (at
12
your option) any later version.
13
14
This program is distributed in the hope that it will be useful, but
15
WITHOUT ANY WARRANTY; without even the implied warranty of
16
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17
General Public License for more details.
18
19
You should have received a copy of the GNU General Public License
20
along with this program.  If not, see <http://www.gnu.org/licenses/>.
21
22 074e10d7 Thomas Schöpping
This research/work was supported by the Cluster of Excellence
23
Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld
24
University, which is funded by the German Research Foundation (DFG).
25 58fe0e0b Thomas Schöpping
26
Authors:
27
 - Thomas Schöpping        <tschoepp[at]cit-ec.uni-bielefeld.de>
28
 - Timo Korthals           <tkorthals[at]cit-ec.uni-bielefeld.de>
29 b0675b0b Thomas Schöpping
 - Stefan Herbrechtsmeier  <sherbrec[at]cit-ec.uni-bielefeld.de>
30 58fe0e0b Thomas Schöpping
 - Teerapat Chinapirom     <tchinapirom[at]cit-ec.uni-bielefeld.de>
31
 - Robert Abel
32
 - Marvin Barther
33
 - Claas Braun
34
 - Tristan Kenneweg
35
36
References:
37 3dcad54e Thomas Schöpping
 [1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A
38
     modular & customizable open-source mini robot platform," 2016 20th
39
     International Conference on System Theory, Control and Computing (ICSTCC),
40
     Sinaia, 2016, pp. 687-692.
41
42
43
44
################################################################################
45
#                                                                              #
46
#        RRRRRRRR   EEEEEEEE     AAA     DDDDDDDD   MM     MM  EEEEEEEE        #
47
#        RR     RR  EE          AA AA    DD     DD  MMM   MMM  EE              #
48
#        RR     RR  EE         AA   AA   DD     DD  MMMM MMMM  EE              #
49
#        RRRRRRRR   EEEEEE    AA     AA  DD     DD  MM MMM MM  EEEEEE          #
50
#        RR   RR    EE        AAAAAAAAA  DD     DD  MM     MM  EE              #
51
#        RR    RR   EE        AA     AA  DD     DD  MM     MM  EE              #
52
#        RR     RR  EEEEEEEE  AA     AA  DDDDDDDD   MM     MM  EEEEEEEE        #
53
#                                                                              #
54
################################################################################
55
56
This file will help you to setup all required software on your system, compile
57
the source code, and flash it to the AMiRo modules.
58
59
================================================================================
60 58fe0e0b Thomas Schöpping
61
CONTENTS:
62
 1  Required software
63 ea4d1c60 Thomas Schöpping
   1.1  Git
64
   1.2  GCC ARM Embedded Toolchain
65
   1.3  ChibiOS
66
   1.4  AMiRo-BLT
67 58fe0e0b Thomas Schöpping
 2  Recommended software
68
   2.1  gtkterm and hterm
69
   2.2  QtCreator
70
 3  Building and flashing
71
72 3dcad54e Thomas Schöpping
================================================================================
73
74
75 58fe0e0b Thomas Schöpping
76
1 - REQUIRED SOFTWARE
77
---------------------
78
79 3dcad54e Thomas Schöpping
In order to compile the source code, you need to install the GCC for ARM
80
embedded devices. Since AMiRo-OS requires ChibiOS as system kernel, you need a
81
copy of that project as well. Furthermore, AMiRo-OS requires a compatible
82
bootloader, such as provided by the AMiRo-BLT project.
83
84
85 ea4d1c60 Thomas Schöpping
1.1 - Git
86
---------
87
88
Since all main- and subprojects are available as Git repositories, installing a
89
recent version of the tool is mandatory.
90
91
92
1.2 GCC ARM Embedded Toolchain
93 3dcad54e Thomas Schöpping
------------------------------
94 58fe0e0b Thomas Schöpping
95
Various versions of the GCC for ARM embedded devices can be found at
96 3dcad54e Thomas Schöpping
<https://launchpad.net/gcc-arm-embedded>. It is highly recommended to use the
97
version 4.8 with update 2014-q1 since some others will cause issues. For
98
installation of the compiler toolchain, please follow the instructions that can
99
be found on the web page.
100
101 ea4d1c60 Thomas Schöpping
If you are running a 64-bit operating system, you will have to install several
102
32-bit libraries in order to make the compiler work. The required packages are
103
libc6, libstdc++6, and libncurses5. You can run the following shell commands to
104
install the according 32-bit versions of the packages:
105
  >$ sudo dpkg --add-architecture i386 && sudo apt-get update
106
  >$ sudo apt-get install libc6:i386 libstdc++6:i386 libncurses5:i386
107
108 58fe0e0b Thomas Schöpping
109 ea4d1c60 Thomas Schöpping
1.3 ChibiOS
110 3dcad54e Thomas Schöpping
-----------
111 58fe0e0b Thomas Schöpping
112 3dcad54e Thomas Schöpping
Since AMiRo-OS uses ChibiOS as underlying system kernel, you need to acquire a
113
copy of it as well. First, go to the directory which contains the AMiRo-OS
114
folder (but do not go into the AMiRo-OS directory itself!). Now clone the GIT
115 4270bbde Bastian Steinhagen
repository of ChibiOS and checkout version 2.6.8:
116 58fe0e0b Thomas Schöpping
  >$ git clone https://github.com/ChibiOS/ChibiOS.git ChibiOS
117
  >$ cd ChibiOS
118 4270bbde Bastian Steinhagen
  >$ git checkout ver_2.6.8 
119 3dcad54e Thomas Schöpping
It is highly recommended to use exactly this commit. Although newer commits in
120
the 2.6.x branch might work fine, AMiRo-OS is not compatible with ChibiOS
121
version 3 or newer.
122
123
AMiRo-OS comes with some patches to ChibiOS, which must be applied as well
124
before compiling the project. Therefore you need to copy all files from the
125
./patches directory of AMiRo-OS to the root directory of ChibiOS. You can then
126
apply the patches via the following command:
127 58fe0e0b Thomas Schöpping
  >$ for i in `ls | grep patch`; do git am --ignore-space-change --ignore-whitespace < ${i}; done
128 3dcad54e Thomas Schöpping
If the files could not be patched successfully, you are probably using an
129
incompatible version of ChibiOS (try to checkout the correct commit as denoted
130
above).
131
132 58fe0e0b Thomas Schöpping
133 ea4d1c60 Thomas Schöpping
1.4 AMiRo-BLT
134 3dcad54e Thomas Schöpping
-------------
135
136
AMiRo-BLT is an additional software project, which is developed in parallel with
137
AMiRo-OS. If you did not receive a copy of AMiRo-BLT with AMiRo-OS, you can find
138
all code and documentation at <https://opensource.cit-ec.de/projects/amiro-os>.
139
Instructions for installation and how to use the software provided by AMiRo-BLT
140 6fd5a427 Thomas Schöpping
can be found on the web page or in the project's readme file. It is highly
141
recommended to install AMiRo-BLT in the same directory as AMiRo-OS and ChibiOS
142
and name its root directory 'amiro-blt'.
143 3dcad54e Thomas Schöpping
144 58fe0e0b Thomas Schöpping
145
146
2 - RECOMMENDED SOFTWARE
147
------------------------
148
149 3dcad54e Thomas Schöpping
In order to fully use all features of AMiRo-OS it is recommended to install the
150
'hterm' or 'gtkterm' application for accessing the robot. To ease further
151
development, this project offers support for the QtCreator IDE.
152
153 58fe0e0b Thomas Schöpping
154
2.1 - gtkterm and hterm
155 3dcad54e Thomas Schöpping
-----------------------
156 58fe0e0b Thomas Schöpping
157 3dcad54e Thomas Schöpping
Depending on your operating system, it is recommended to install 'gtkterm' for
158
Linux (available in the Ubuntu repositories), or 'hterm' for Windows. For
159
gtkterm you need to modify the configuration file ~/.gtktermrc (it is generated
160
automatically when you start the application for the first time) as follows:
161 58fe0e0b Thomas Schöpping
162
  port	= /dev/ttyUSB0
163
  speed	= 115200
164
  bits	= 8
165
  stopbits	= 1
166
  parity	= none
167
  flow	= none
168
  wait_delay	= 0
169
  wait_char	= -1
170
  rs485_rts_time_before_tx	= 30
171
  rs485_rts_time_after_tx	= 30
172
  echo	= False
173
  crlfauto	= True
174
175
For hterm you must need to configure the tool analogously.
176
177 3dcad54e Thomas Schöpping
178 58fe0e0b Thomas Schöpping
2.2 - QtCreator
179 3dcad54e Thomas Schöpping
---------------
180
181
In order to setup QtCreator projects for the three AMiRo base modules, a script
182
is provided in the directory ./ide/qtcreator/. It is accompanied by an
183
additional README.txt file, which contains further information.
184
185 58fe0e0b Thomas Schöpping
186
187
3 - BUILDING AND FLASHING
188
-------------------------
189
190 3dcad54e Thomas Schöpping
Each time you modify any part of AMiRo-OS, you need to recompile the whole
191
project for the according AMiRo module. Therefore you have to use the makefiles
192
provided in ./devices/<DeviceToRecompile>/ by simply executing 'make' in the
193
according directory. If you want to compile all modules at once, you can also
194
use the makefile in the ./devices/ folder.
195 58fe0e0b Thomas Schöpping
196 3dcad54e Thomas Schöpping
After compilation, you always have to flash the generated program to the robot.
197
Therefore you need to install the SerialBoot tool provided by the AMiRo-BLT
198 6fd5a427 Thomas Schöpping
project. By default AMiRo-OS assumes AMiRo-BLT to be installed in the same
199
folder and its root directory to be named 'amiro-blt'. If this is the case, it
200
will automatically detect the SerialBoot tool. Otherwise the tool must be
201
accessible globally under the environment variable 'SERIALBOOT'. You can make
202
it so by appending the following line to your ~/.bashrc file:
203 58fe0e0b Thomas Schöpping
204
  export SERIALBOOT=</absolute/path/to/the/SerialBoot/binary>
205
206
You can test the tool by calling it via the variable:
207
  >$ ${SERIALBOOT}
208
This should print some information about the tool.
209
210 3dcad54e Thomas Schöpping
Similar to the compilation procedure as described above, you can flash either
211
each module separately, or all modules at once by executing 'make flash' from
212
the according directory. Note that you must connect the programming cable either
213
to the DiWheelDrive or the PowerManagement module for flashing the operating
214
system. All other modules are powered off after reset so that only these two
215
offer a bootloader that is required for flashing.
216 58fe0e0b Thomas Schöpping
217 3dcad54e Thomas Schöpping
================================================================================