Statistics
| Branch: | Tag: | Revision:

amiro-os / README.txt @ 8376530c

History | View | Annotate | Download (7.989 KB)

1 e545e620 Thomas Schöpping
AMiRo-OS is an operating system for the base version of the Autonomous Mini
2 3dcad54e Thomas Schöpping
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 e545e620 Thomas Schöpping
system kernel and extends it with platform specific configurations and further
5
functionalities and abstractions.
6 58fe0e0b Thomas Schöpping
7 e545e620 Thomas Schöpping
Copyright (C) 2016..2018  Thomas Schöpping et al.
8 58fe0e0b Thomas Schöpping
(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 074e10d7 Thomas Schöpping
This research/work was supported by the Cluster of Excellence
24
Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld
25
University, which is funded by the German Research Foundation (DFG).
26 58fe0e0b Thomas Schöpping
27
Authors:
28 e545e620 Thomas Schöpping
 - Thomas Schöpping          <tschoepp[at]cit-ec.uni-bielefeld.de>
29
 - Marc Rothmann
30 58fe0e0b Thomas Schöpping
31
References:
32 3dcad54e Thomas Schöpping
 [1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A
33
     modular & customizable open-source mini robot platform," 2016 20th
34
     International Conference on System Theory, Control and Computing (ICSTCC),
35
     Sinaia, 2016, pp. 687-692.
36
37
38
39
################################################################################
40
#                                                                              #
41
#        RRRRRRRR   EEEEEEEE     AAA     DDDDDDDD   MM     MM  EEEEEEEE        #
42
#        RR     RR  EE          AA AA    DD     DD  MMM   MMM  EE              #
43
#        RR     RR  EE         AA   AA   DD     DD  MMMM MMMM  EE              #
44
#        RRRRRRRR   EEEEEE    AA     AA  DD     DD  MM MMM MM  EEEEEE          #
45
#        RR   RR    EE        AAAAAAAAA  DD     DD  MM     MM  EE              #
46
#        RR    RR   EE        AA     AA  DD     DD  MM     MM  EE              #
47
#        RR     RR  EEEEEEEE  AA     AA  DDDDDDDD   MM     MM  EEEEEEEE        #
48
#                                                                              #
49
################################################################################
50
51
This file will help you to setup all required software on your system, compile
52
the source code, and flash it to the AMiRo modules.
53
54
================================================================================
55 58fe0e0b Thomas Schöpping
56
CONTENTS:
57 e545e620 Thomas Schöpping
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
68 58fe0e0b Thomas Schöpping
69 3dcad54e Thomas Schöpping
================================================================================
70
71
72 58fe0e0b Thomas Schöpping
73
1 - REQUIRED SOFTWARE
74
---------------------
75
76 e545e620 Thomas Schöpping
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.
80 3dcad54e Thomas Schöpping
81
82 ea4d1c60 Thomas Schöpping
1.1 - Git
83
---------
84
85
Since all main- and subprojects are available as Git repositories, installing a
86
recent version of the tool is mandatory.
87
88
89 e545e620 Thomas Schöpping
1.2 Bootloader & Tools
90
----------------------
91 3dcad54e Thomas Schöpping
92 e545e620 Thomas Schöpping
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.
101 ea4d1c60 Thomas Schöpping
102 58fe0e0b Thomas Schöpping
103 e545e620 Thomas Schöpping
1.3 System Kernel
104
-----------------
105 58fe0e0b Thomas Schöpping
106 3dcad54e Thomas Schöpping
Since AMiRo-OS uses ChibiOS as underlying system kernel, you need to acquire a
107 e545e620 Thomas Schöpping
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.
122 3dcad54e Thomas Schöpping
123 58fe0e0b Thomas Schöpping
124
125
2 - RECOMMENDED SOFTWARE
126
------------------------
127
128 e545e620 Thomas Schöpping
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.
133 3dcad54e Thomas Schöpping
134 58fe0e0b Thomas Schöpping
135
2.1 - gtkterm and hterm
136 3dcad54e Thomas Schöpping
-----------------------
137 58fe0e0b Thomas Schöpping
138 e545e620 Thomas Schöpping
Depending on your operating system it is recommended to install 'gtkterm' for
139 3dcad54e Thomas Schöpping
Linux (available in the Ubuntu repositories), or 'hterm' for Windows. For
140 e545e620 Thomas Schöpping
gtkterm you need to modify the configuration file ~/.gtktermrc (generated
141 3dcad54e Thomas Schöpping
automatically when you start the application for the first time) as follows:
142 58fe0e0b Thomas Schöpping
143 9f224ade Thomas Schöpping
  port	= /dev/ttyAMiRo0
144 58fe0e0b Thomas Schöpping
  speed	= 115200
145
  bits	= 8
146
  stopbits	= 1
147
  parity	= none
148
  flow	= none
149
  wait_delay	= 0
150
  wait_char	= -1
151
  rs485_rts_time_before_tx	= 30
152
  rs485_rts_time_after_tx	= 30
153
  echo	= False
154
  crlfauto	= True
155
156 e545e620 Thomas Schöpping
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 9f224ade Thomas Schöpping
system shell of AMiRo-OS. If you need legacy support for older version of
159
AMiRo-BLT, you can replace the port value by '/dev/ttyUSB0'.
160 58fe0e0b Thomas Schöpping
161 3dcad54e Thomas Schöpping
162 e545e620 Thomas Schöpping
2.2 - QtCreator IDE
163
-------------------
164 3dcad54e Thomas Schöpping
165 e545e620 Thomas Schöpping
In order to setup QtCreator projects for the three AMiRo base modules, you can
166
use the provided ./setup.sh script. Further instructions for a more advanced
167
configuration of the IDE are provided in the ./tools/qtcreator/README.txt file.
168
169
170
2.3  Doxygen & Graphviz
171
-----------------------
172
173
In order to generate the documentation from the source code, Doxygen and
174
Graphviz are requried. It is recommended to install these tool using the
175
default versions for your system. Ubuntu users should simply run
176
  >$ sudo apt-get install doxygen graphviz
177 3dcad54e Thomas Schöpping
178 58fe0e0b Thomas Schöpping
179
180
3 - BUILDING AND FLASHING
181
-------------------------
182
183 3dcad54e Thomas Schöpping
Each time you modify any part of AMiRo-OS, you need to recompile the whole
184 e545e620 Thomas Schöpping
project for the according AMiRo module. Therefore you can use the ./Makefile by
185
simply executing 'make' and follow the instructions. Alternatively, you can
186
either use the makefiles provided per module in ./os/modules/<ModuleToCompile>
187
or - if you want to compile all modules at once - the makefile in the
188
./os/modules folder. After the build process has finished successfully, you
189
always have to flash the generated program to the robot. Therefore you need an
190
appropriate tool, such as stm32flash (if you don't use a bootloader) or
191
SerialBoot (highly recommended; provided by AMiRo-BLT). Similarly to the
192
compilation procedure as described above, you can flash either each module
193
separately, or all modules at once by executing 'make flash' from the according
194
directory.
195
196
When using SerialBoot, please note that you must connect the programming cable
197
either to the DiWheelDrive or the PowerManagement module for flashing the
198
operating system. All other modules are powered off after reset so that only
199
these two offer a running bootloader, which is required for flashing.
200 58fe0e0b Thomas Schöpping
201 3dcad54e Thomas Schöpping
================================================================================