Statistics
| Branch: | Tag: | Revision:

amiro-os / README.txt @ 58fe0e0b

History | View | Annotate | Download (7.891 KB)

1
AMiRo-OS is the operating system for the base version of the
2
Autonomous Mini Robot (AMiRo) [1,2]. It utilizes ChibiOS (a real-time
3
operating system for embedded devices developed by Giovanni di Sirio;
4
see <http://chibios.org>) as system kernel and extends it with
5
platform specific functionalities.
6

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

    
10
This program is free software: you can redistribute it and/or modify
11
it under the terms of the GNU General Public License as published by
12
the Free Software Foundation, either version 3 of the License, or (at
13
your option) any later version.
14

    
15
This program is distributed in the hope that it will be useful, but
16
WITHOUT ANY WARRANTY; without even the implied warranty of
17
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18
General Public License for more details.
19

    
20
You should have received a copy of the GNU General Public License
21
along with this program.  If not, see <http://www.gnu.org/licenses/>.
22

    
23
The development of this software was supported by the Excellence
24
Cluster EXC 227 Cognitive Interaction Technology. The Excellence
25
Cluster EXC 227 is a grant of the Deutsche Forschungsgemeinschaft
26
(DFG) in the context of the German Excellence Initiative.
27

    
28
Authors:
29
 - Thomas Schöpping        <tschoepp[at]cit-ec.uni-bielefeld.de>
30
 - Timo Korthals           <tkorthals[at]cit-ec.uni-bielefeld.de>
31
 - Stefan Herbechtsmeier   <sherbrec[at]cit-ec.uni-bielefeld.de>
32
 - Teerapat Chinapirom     <tchinapirom[at]cit-ec.uni-bielefeld.de>
33
 - Robert Abel
34
 - Marvin Barther
35
 - Claas Braun
36
 - Tristan Kenneweg
37

    
38
References:
39
 [1] Herbrechtsmeier S., Rückert U., & Sitte J. (2012). "AMiRo -
40
     Autonomous Mini Robot for Research and Education". In Advances in
41
     Autonomous Mini Robots (pp. 101-112). Springer Berlin
42
     Heidelberg.
43
 [2] Schöpping T., Korthals T., Herbrechtsmeier S., & Rückert U.
44
     (2015). "AMiRo: A Mini Robot for Scientific Applications" In
45
     Advances in Computational Intelligence (pp. 199-205). Springer
46
     International Publishing.
47

    
48

    
49

    
50
#####################################################################
51
#                                                                   #
52
#     RRRRRRRR  EEEEEEEE    AAA    DDDDDDDD  MM     MM EEEEEEEE     #
53
#     RR     RR EE         AA AA   DD     DD MMM   MMM EE           #
54
#     RR     RR EE        AA   AA  DD     DD MMMM MMMM EE           #
55
#     RRRRRRRR  EEEEEE   AA     AA DD     DD MM MMM MM EEEEEE       #
56
#     RR   RR   EE       AAAAAAAAA DD     DD MM     MM EE           #
57
#     RR    RR  EE       AA     AA DD     DD MM     MM EE           #
58
#     RR     RR EEEEEEEE AA     AA DDDDDDDD  MM     MM EEEEEEEE     #
59
#                                                                   #
60
#####################################################################
61

    
62
This file will help you to setup all required software on your system,
63
compile the source code, and flash it to the AMiRo modules.
64

    
65
=====================================================================
66

    
67
CONTENTS:
68
 1  Required software
69
   1.1  gcc-arm-none-eabi
70
   1.2  ChibiOS
71
   1.3  AMiRo-BLT
72
 2  Recommended software
73
   2.1  gtkterm and hterm
74
   2.2  QtCreator
75
 3  Building and flashing
76

    
77
=====================================================================
78

    
79
1 - REQUIRED SOFTWARE
80
---------------------
81

    
82
In order to compile the source code, you need to install the GCC for
83
ARM embedded devices. Since AMiRo-OS requires ChibiOS as system
84
kernel, you need a copy of that project as well. Furthermore, AMiRo-OS
85
requires a compatible bootloader, such as provided by the AMiRo-BLT
86
project.
87

    
88
1.1 gcc-arm-none-eabi
89

    
90
Various versions of the GCC for ARM embedded devices can be found at
91
<https://launchpad.net/gcc-arm-embedded>. It is highly recommended to
92
use the version 4.8 with update 2014-q1 since some others will cause
93
issues. For installation of the compiler toolchain, please follow the
94
instructions that can be found on the web page.
95

    
96
1.2 ChibiOS
97

    
98
Since AMiRo-OS uses ChibiOS as underlying system kernel, you need to
99
acquire a copy of it as well. First, go to the directory which
100
contains the AMiRo-OS folder (but do not go into the AMiRo-OS
101
directory itself!). Now clone the GIT repository of ChibiOS and
102
checkout version 2.6.x:
103
  >$ git clone https://github.com/ChibiOS/ChibiOS.git ChibiOS
104
  >$ cd ChibiOS
105
  >$ git checkout 2e6dfc7364e7551483922ea6afbaea8f3501ab0e
106
It is highly recommended to use exactly this commit. Although newer
107
commits in the 2.6.x branch might work fine, AMiRo-OS is not
108
compatible with ChibiOS version 3 or newer.
109

    
110
AMiRo-OS comes with some patches to ChibiOS, which must be applied as
111
well before compiling the project. Therefore you need to copy all
112
files from the ./patches directory of AMiRo-OS to the root directory
113
of ChibiOS. You can then apply the patches via the following command:
114
  >$ for i in `ls | grep patch`; do git am --ignore-space-change --ignore-whitespace < ${i}; done
115
If the files could not be patched successfully, you are probably using
116
an incompatible version of ChibiOS (try to checkout the correct commit
117
as denoted above).
118

    
119
1.3 AMiRo-BLT
120

    
121
AMiRo-BLT is an additional software project, which is developed in
122
parallel with AMiRo-OS. If you did not receive a copy of AMiRo-BLT
123
with AMiRo-OS, you can find all code and documentation at
124
<https://opensource.cit-ec.de/projects/amiro-os>. Instructions for
125
installation and how to use the software provided by AMiRo-BLT can be
126
found on the web page or in the project's readme file.
127

    
128
2 - RECOMMENDED SOFTWARE
129
------------------------
130

    
131
In order to fully use all features of AMiRo-OS it is recommended to
132
install the 'hterm' or 'gtkterm' application for accessing the robot.
133
To ease further development, this project offers support for the 
134
QtCreator IDE.
135

    
136
2.1 - gtkterm and hterm
137

    
138
Depending on your operating system, it is recommended to install
139
'gtkterm' for Linux (available in the Ubuntu repositories), or 'hterm'
140
for Windows.
141
For gtkterm you need to modify the configuration file ~/.gtktermrc (it
142
is generated automatically when you start the application for the
143
first time) as follows:
144

    
145
  port	= /dev/ttyUSB0
146
  speed	= 115200
147
  bits	= 8
148
  stopbits	= 1
149
  parity	= none
150
  flow	= none
151
  wait_delay	= 0
152
  wait_char	= -1
153
  rs485_rts_time_before_tx	= 30
154
  rs485_rts_time_after_tx	= 30
155
  echo	= False
156
  crlfauto	= True
157

    
158
For hterm you must need to configure the tool analogously.
159

    
160
2.2 - QtCreator
161

    
162
In order to setup QtCreator projects for the three AMiRo base modules,
163
a script is provided in the directory ./ide/qtcreator/. It is
164
accompanied by an additional README.txt file, which contains further
165
information.
166

    
167
3 - BUILDING AND FLASHING
168
-------------------------
169

    
170
Each time you modify any part of AMiRo-OS, you need to recompile the
171
whole project for the according AMiRo module. Therefore you have to
172
use the makefiles provided in ./devices/<DeviceToRecompile>/ by simply
173
executing 'make' in the according directory. If you want to compile
174
all modules at once, you can also use the makefile in the ./devices/
175
folder.
176

    
177
After compilation, you always have to flash the generated program to
178
the robot. Therefore you need to install the SerialBoot tool provided
179
by the AMiRo-BLT project. Furthermore the tool must be accessible
180
globally under the environment variable 'SERIALBOOT'. You can do this
181
by appending the following line to your ~/.bashrc file:
182

    
183
  export SERIALBOOT=</absolute/path/to/the/SerialBoot/binary>
184

    
185
You can test the tool by calling it via the variable:
186
  >$ ${SERIALBOOT}
187
This should print some information about the tool.
188
Similar to the compilation procedure as described above, you can flash
189
either each module separately, or all modules at once by executing
190
'make flash' from the according directory.
191
Note that you must connect the programming cable either to the
192
DiWheelDrive or the PowerManagement module for flashing the operating
193
system. All other modules are powered off after reset so that only
194
these two offer a bootloader that is required for flashing.
195

    
196
=====================================================================
197