Revision 3dcad54e README.txt

View differences:

README.txt
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.
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.
6 5

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

  
10 9
This program is free software: you can redistribute it and/or modify
......
35 34
 - Tristan Kenneweg
36 35

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

  
47

  
48

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

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

  
64
=====================================================================
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
================================================================================
65 60

  
66 61
CONTENTS:
67 62
 1  Required software
68
   1.1  gcc-arm-none-eabi
63
   1.1  GCC ARM Embedded Toolchain
69 64
   1.2  ChibiOS
70 65
   1.3  AMiRo-BLT
71 66
 2  Recommended software
......
73 68
   2.2  QtCreator
74 69
 3  Building and flashing
75 70

  
76
=====================================================================
71
================================================================================
72

  
73

  
77 74

  
78 75
1 - REQUIRED SOFTWARE
79 76
---------------------
80 77

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

  
86 84

  
87
1.1 gcc-arm-none-eabi
85
1.1 GCC ARM Embedded Toolchain
86
------------------------------
88 87

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

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

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

  
109
AMiRo-OS comes with some patches to ChibiOS, which must be applied as
110
well before compiling the project. Therefore you need to copy all
111
files from the ./patches directory of AMiRo-OS to the root directory
112
of ChibiOS. You can then apply the patches via the following command:
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 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
115
an incompatible version of ChibiOS (try to checkout the correct commit
116
as denoted above).
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

  
117 118

  
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

  
119 128

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

  
127 130
2 - RECOMMENDED SOFTWARE
128 131
------------------------
129 132

  
130
In order to fully use all features of AMiRo-OS it is recommended to
131
install the 'hterm' or 'gtkterm' application for accessing the robot.
132
To ease further development, this project offers support for the 
133
QtCreator IDE.
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

  
134 137

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

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

  
144 146
  port	= /dev/ttyUSB0
145 147
  speed	= 115200
......
156 158

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

  
161

  
159 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

  
160 169

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

  
166 171
3 - BUILDING AND FLASHING
167 172
-------------------------
168 173

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

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

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

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

  
195
=====================================================================
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.
196 198

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

Also available in: Unified diff