Statistics
| Branch: | Tag: | Revision:

amiro-os / README.txt @ 3dcad54e

History | View | Annotate | Download (7.932 KB)

1
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

    
6
Copyright (C) 2016..2017  Thomas Schöpping et al.
7
(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
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

    
26
Authors:
27
 - Thomas Schöpping        <tschoepp[at]cit-ec.uni-bielefeld.de>
28
 - Timo Korthals           <tkorthals[at]cit-ec.uni-bielefeld.de>
29
 - Stefan Herbechtsmeier   <sherbrec[at]cit-ec.uni-bielefeld.de>
30
 - 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
 [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

    
61
CONTENTS:
62
 1  Required software
63
   1.1  GCC ARM Embedded Toolchain
64
   1.2  ChibiOS
65
   1.3  AMiRo-BLT
66
 2  Recommended software
67
   2.1  gtkterm and hterm
68
   2.2  QtCreator
69
 3  Building and flashing
70

    
71
================================================================================
72

    
73

    
74

    
75
1 - REQUIRED SOFTWARE
76
---------------------
77

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

    
83

    
84

    
85
1.1 GCC ARM Embedded Toolchain
86
------------------------------
87

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

    
94

    
95
1.2 ChibiOS
96
-----------
97

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

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

    
118

    
119
1.3 AMiRo-BLT
120
-------------
121

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

    
128

    
129

    
130
2 - RECOMMENDED SOFTWARE
131
------------------------
132

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

    
137

    
138
2.1 - gtkterm and hterm
139
-----------------------
140

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

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

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

    
161

    
162
2.2 - QtCreator
163
---------------
164

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

    
169

    
170

    
171
3 - BUILDING AND FLASHING
172
-------------------------
173

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

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

    
186
  export SERIALBOOT=</absolute/path/to/the/SerialBoot/binary>
187

    
188
You can test the tool by calling it via the variable:
189
  >$ ${SERIALBOOT}
190
This should print some information about the tool.
191

    
192
Similar to the compilation procedure as described above, you can flash either
193
each module separately, or all modules at once by executing 'make flash' from
194
the according directory. Note that you must connect the programming cable either
195
to the DiWheelDrive or the PowerManagement module for flashing the operating
196
system. All other modules are powered off after reset so that only these two
197
offer a bootloader that is required for flashing.
198

    
199
================================================================================