Revision e545e620 README.txt
README.txt | ||
---|---|---|
1 |
AMiRo-OS is the operating system for the base version of the Autonomous Mini
|
|
1 |
AMiRo-OS is an operating system for the base version of the Autonomous Mini
|
|
2 | 2 |
Robot (AMiRo) [1]. It utilizes ChibiOS (a real-time operating system for |
3 | 3 |
embedded devices developed by Giovanni di Sirio; see <http://chibios.org>) as |
4 |
system kernel and extends it with platform specific functionalities. |
|
4 |
system kernel and extends it with platform specific configurations and further |
|
5 |
functionalities and abstractions. |
|
5 | 6 |
|
6 |
Copyright (C) 2016..2017 Thomas Schöpping et al.
|
|
7 |
Copyright (C) 2016..2018 Thomas Schöpping et al.
|
|
7 | 8 |
(a complete list of all authors is given below) |
8 | 9 |
|
9 | 10 |
This program is free software: you can redistribute it and/or modify |
... | ... | |
24 | 25 |
University, which is funded by the German Research Foundation (DFG). |
25 | 26 |
|
26 | 27 |
Authors: |
27 |
- Thomas Schöpping <tschoepp[at]cit-ec.uni-bielefeld.de> |
|
28 |
- Timo Korthals <tkorthals[at]cit-ec.uni-bielefeld.de> |
|
29 |
- Stefan Herbrechtsmeier <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 |
|
28 |
- Thomas Schöpping <tschoepp[at]cit-ec.uni-bielefeld.de> |
|
29 |
- Marc Rothmann |
|
35 | 30 |
|
36 | 31 |
References: |
37 | 32 |
[1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A |
... | ... | |
59 | 54 |
================================================================================ |
60 | 55 |
|
61 | 56 |
CONTENTS: |
62 |
1 Required software |
|
63 |
1.1 Git |
|
64 |
1.2 GCC ARM Embedded Toolchain |
|
65 |
1.3 ChibiOS |
|
66 |
1.4 AMiRo-BLT |
|
67 |
2 Recommended software |
|
68 |
2.1 gtkterm and hterm |
|
69 |
2.2 QtCreator |
|
70 |
3 Building and flashing |
|
57 |
|
|
58 |
1 Required software |
|
59 |
1.1 Git |
|
60 |
1.2 Bootloader & Tools |
|
61 |
1.3 System Kernel |
|
62 |
1.4 Low-Level Drivers |
|
63 |
2 Recommended software |
|
64 |
2.1 gtkterm and hterm |
|
65 |
2.2 QtCreator IDE |
|
66 |
2.3 Doxygen & Graphviz |
|
67 |
3 Building and flashing |
|
71 | 68 |
|
72 | 69 |
================================================================================ |
73 | 70 |
|
... | ... | |
76 | 73 |
1 - REQUIRED SOFTWARE |
77 | 74 |
--------------------- |
78 | 75 |
|
79 |
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.
|
|
76 |
In order to compile the source code, you need to install the GNU ARM Embedded
|
|
77 |
Toolchain. Since this project uses GNU Make for configuring and calling the
|
|
78 |
compiler, this tool is requried too. AMiRo-OS uses ChibiOS as system kernel,
|
|
79 |
so you need a copy of that project as well.
|
|
83 | 80 |
|
84 | 81 |
|
85 | 82 |
1.1 - Git |
... | ... | |
89 | 86 |
recent version of the tool is mandatory. |
90 | 87 |
|
91 | 88 |
|
92 |
1.2 GCC ARM Embedded Toolchain |
|
93 |
------------------------------ |
|
94 |
|
|
95 |
Various versions of the GCC for ARM embedded devices can be found at |
|
96 |
<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. |
|
89 |
1.2 Bootloader & Tools |
|
90 |
---------------------- |
|
100 | 91 |
|
101 |
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 |
|
92 |
AMiRo-OS can take advantage of an installed bootloader if such exists and |
|
93 |
provides an interface. By default, AMiRo-BLT is included as a Git submodule and |
|
94 |
can easily be initialized via the ./setup.sh script. If requried, you can |
|
95 |
replace the used bootloader by adding an according subfolder in the ./bootloader |
|
96 |
directory. Note that you will have to adapt the makefiles and scripts, and |
|
97 |
probably the operating system as well. |
|
98 |
AMiRo-BLT furthermore has its own required and recommended software tools as |
|
99 |
described in its README.txt file. Follow th instructions to initialize the |
|
100 |
development environment manually or use the ./setup.sh script. |
|
107 | 101 |
|
108 | 102 |
|
109 |
1.3 ChibiOS
|
|
110 |
----------- |
|
103 |
1.3 System Kernel
|
|
104 |
-----------------
|
|
111 | 105 |
|
112 | 106 |
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 |
repository of ChibiOS and checkout version 2.6.x: |
|
116 |
>$ git clone https://github.com/ChibiOS/ChibiOS.git ChibiOS |
|
117 |
>$ cd ChibiOS |
|
118 |
>$ git checkout 2e6dfc7364e7551483922ea6afbaea8f3501ab0e |
|
119 |
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 |
>$ for i in `ls | grep patch`; do git am --ignore-space-change --ignore-whitespace < ${i}; done |
|
128 |
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 |
|
|
133 |
1.4 AMiRo-BLT |
|
134 |
------------- |
|
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 |
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'. |
|
107 |
copy of it as well. For the sake of compatibility, it is included in AMiRo-OS as |
|
108 |
a Git submodule. It is highly recommended to use the ./setup.sh script for |
|
109 |
initialization. Moreover, you have to apply the patches to ChibiOS in order to |
|
110 |
make AMiRo-OS work properly. It is recommended to use the .setup.sh script for this |
|
111 |
purpose. |
|
112 |
If you would like to use a different kernel, you can add a subfolder in the |
|
113 |
./kernel/ directory and adapt the scripts and operating system source code. |
|
114 |
|
|
115 |
|
|
116 |
1.4 Low-Level Drivers |
|
117 |
--------------------- |
|
118 |
|
|
119 |
Any required low-level drivers for the AMiRo hardware is available in an |
|
120 |
additional project: AMiRo-LLD. It is included as a Git subodule and can be |
|
121 |
initialized via the ./setup.sh script. |
|
143 | 122 |
|
144 | 123 |
|
145 | 124 |
|
146 | 125 |
2 - RECOMMENDED SOFTWARE |
147 | 126 |
------------------------ |
148 | 127 |
|
149 |
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. |
|
128 |
AMiRo-OS can take advanatge of an installed bootloader, which is recommended for |
|
129 |
the best experience. In order to use all features of AMiRo-OS it is also |
|
130 |
recommended to install either the 'hterm' or 'gtkterm' application for accessing |
|
131 |
the robot. To ease further development, this project offers support for the |
|
132 |
QtCreator IDE. |
|
152 | 133 |
|
153 | 134 |
|
154 | 135 |
2.1 - gtkterm and hterm |
155 | 136 |
----------------------- |
156 | 137 |
|
157 |
Depending on your operating system, it is recommended to install 'gtkterm' for
|
|
138 |
Depending on your operating system it is recommended to install 'gtkterm' for |
|
158 | 139 |
Linux (available in the Ubuntu repositories), or 'hterm' for Windows. For |
159 |
gtkterm you need to modify the configuration file ~/.gtktermrc (it is generated
|
|
140 |
gtkterm you need to modify the configuration file ~/.gtktermrc (generated |
|
160 | 141 |
automatically when you start the application for the first time) as follows: |
161 | 142 |
|
162 | 143 |
port = /dev/ttyUSB0 |
... | ... | |
172 | 153 |
echo = False |
173 | 154 |
crlfauto = True |
174 | 155 |
|
175 |
For hterm you must need to configure the tool analogously. |
|
156 |
For hterm you need to configure the tool analogously. With either tool the robot |
|
157 |
can be reset by toggling the RTS signal on and off again, and you can access the |
|
158 |
system shell of AMiRo-OS. |
|
176 | 159 |
|
177 | 160 |
|
178 |
2.2 - QtCreator |
|
179 |
--------------- |
|
161 |
2.2 - QtCreator IDE
|
|
162 |
-------------------
|
|
180 | 163 |
|
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. |
|
164 |
In order to setup QtCreator projects for the three AMiRo base modules, you can |
|
165 |
use the provided ./setup.sh script. Further instructions for a more advanced |
|
166 |
configuration of the IDE are provided in the ./tools/qtcreator/README.txt file. |
|
167 |
|
|
168 |
|
|
169 |
2.3 Doxygen & Graphviz |
|
170 |
----------------------- |
|
171 |
|
|
172 |
In order to generate the documentation from the source code, Doxygen and |
|
173 |
Graphviz are requried. It is recommended to install these tool using the |
|
174 |
default versions for your system. Ubuntu users should simply run |
|
175 |
>$ sudo apt-get install doxygen graphviz |
|
184 | 176 |
|
185 | 177 |
|
186 | 178 |
|
... | ... | |
188 | 180 |
------------------------- |
189 | 181 |
|
190 | 182 |
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 |
|
|
196 |
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 |
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 |
|
|
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 |
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. |
|
183 |
project for the according AMiRo module. Therefore you can use the ./Makefile by |
|
184 |
simply executing 'make' and follow the instructions. Alternatively, you can |
|
185 |
either use the makefiles provided per module in ./os/modules/<ModuleToCompile> |
|
186 |
or - if you want to compile all modules at once - the makefile in the |
|
187 |
./os/modules folder. After the build process has finished successfully, you |
|
188 |
always have to flash the generated program to the robot. Therefore you need an |
|
189 |
appropriate tool, such as stm32flash (if you don't use a bootloader) or |
|
190 |
SerialBoot (highly recommended; provided by AMiRo-BLT). Similarly to the |
|
191 |
compilation procedure as described above, you can flash either each module |
|
192 |
separately, or all modules at once by executing 'make flash' from the according |
|
193 |
directory. |
|
194 |
|
|
195 |
When using SerialBoot, please note that you must connect the programming cable |
|
196 |
either to the DiWheelDrive or the PowerManagement module for flashing the |
|
197 |
operating system. All other modules are powered off after reset so that only |
|
198 |
these two offer a running bootloader, which is required for flashing. |
|
216 | 199 |
|
217 | 200 |
================================================================================ |
201 |
|
Also available in: Unified diff