Statistics
| Branch: | Tag: | Revision:

amiro-os / README.txt @ e545e620

History | View | Annotate | Download (7.88 KB)

1
AMiRo-OS is an 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 configurations and further
5
functionalities and abstractions.
6

    
7
Copyright (C) 2016..2018  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
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

    
27
Authors:
28
 - Thomas Schöpping          <tschoepp[at]cit-ec.uni-bielefeld.de>
29
 - Marc Rothmann
30

    
31
References:
32
 [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

    
56
CONTENTS:
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
68

    
69
================================================================================
70

    
71

    
72

    
73
1 - REQUIRED SOFTWARE
74
---------------------
75

    
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.
80

    
81

    
82
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
1.2 Bootloader & Tools
90
----------------------
91

    
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.
101

    
102

    
103
1.3 System Kernel
104
-----------------
105

    
106
Since AMiRo-OS uses ChibiOS as underlying system kernel, you need to acquire a
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.
122

    
123

    
124

    
125
2 - RECOMMENDED SOFTWARE
126
------------------------
127

    
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.
133

    
134

    
135
2.1 - gtkterm and hterm
136
-----------------------
137

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

    
143
  port	= /dev/ttyUSB0
144
  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
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.
159

    
160

    
161
2.2 - QtCreator IDE
162
-------------------
163

    
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
176

    
177

    
178

    
179
3 - BUILDING AND FLASHING
180
-------------------------
181

    
182
Each time you modify any part of AMiRo-OS, you need to recompile the whole
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.
199

    
200
================================================================================
201