Statistics
| Branch: | Tag: | Revision:

amiro-os / README.txt @ 4b8243d7

History | View | Annotate | Download (18.757 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 96621a83 Thomas Schöpping
Copyright (C) 2016..2020  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 8fd2fd44 Thomas Schöpping
  1  Required Software
59 e545e620 Thomas Schöpping
    1.1  Git
60
    1.2  Bootloader & Tools
61
    1.3  System Kernel
62
    1.4  Low-Level Drivers
63 8fd2fd44 Thomas Schöpping
  2  Recommended Software
64 e545e620 Thomas Schöpping
    2.1  gtkterm and hterm
65
    2.2  QtCreator IDE
66
    2.3  Doxygen & Graphviz
67 8fd2fd44 Thomas Schöpping
  3  Building and Flashing
68
  4  Developer Guides
69
    4.1  Adding a New Module
70
    4.2  Handling a Custom I/O Event in the Main Thread
71
    4.3  Implementing a New Low-Level Driver
72 d796dcdf Thomas Schöpping
    4.4  Writing a Test
73 58fe0e0b Thomas Schöpping
74 3dcad54e Thomas Schöpping
================================================================================
75
76
77 58fe0e0b Thomas Schöpping
78
1 - REQUIRED SOFTWARE
79 8fd2fd44 Thomas Schöpping
=====================
80 58fe0e0b Thomas Schöpping
81 e545e620 Thomas Schöpping
In order to compile the source code, you need to install the GNU ARM Embedded
82
Toolchain. Since this project uses GNU Make for configuring and calling the
83
compiler, this tool is requried too. AMiRo-OS uses ChibiOS as system kernel,
84
so you need a copy of that project as well.
85 3dcad54e Thomas Schöpping
86
87 ea4d1c60 Thomas Schöpping
1.1 - Git
88
---------
89
90
Since all main- and subprojects are available as Git repositories, installing a
91
recent version of the tool is mandatory.
92
93
94 e545e620 Thomas Schöpping
1.2 Bootloader & Tools
95
----------------------
96 3dcad54e Thomas Schöpping
97 e545e620 Thomas Schöpping
AMiRo-OS can take advantage of an installed bootloader if such exists and
98
provides an interface. By default, AMiRo-BLT is included as a Git submodule and
99
can easily be initialized via the ./setup.sh script. If requried, you can
100
replace the used bootloader by adding an according subfolder in the ./bootloader
101
directory. Note that you will have to adapt the makefiles and scripts, and
102
probably the operating system as well.
103
AMiRo-BLT furthermore has its own required and recommended software tools as
104 d796dcdf Thomas Schöpping
described in its README.txt file. Follow the instructions to initialize the
105 e545e620 Thomas Schöpping
development environment manually or use the ./setup.sh script.
106 ea4d1c60 Thomas Schöpping
107 58fe0e0b Thomas Schöpping
108 e545e620 Thomas Schöpping
1.3 System Kernel
109
-----------------
110 58fe0e0b Thomas Schöpping
111 3dcad54e Thomas Schöpping
Since AMiRo-OS uses ChibiOS as underlying system kernel, you need to acquire a
112 e545e620 Thomas Schöpping
copy of it as well. For the sake of compatibility, it is included in AMiRo-OS as
113
a Git submodule. It is highly recommended to use the ./setup.sh script for
114
initialization. Moreover, you have to apply the patches to ChibiOS in order to
115 d796dcdf Thomas Schöpping
make AMiRo-OS work properly. It is recommended to use the ./setup.sh script for
116 d8ed8c1c Thomas Schöpping
this purpose.
117 e545e620 Thomas Schöpping
If you would like to use a different kernel, you can add a subfolder in the
118
./kernel/ directory and adapt the scripts and operating system source code.
119
120
121
1.4 Low-Level Drivers
122
---------------------
123
124 d8ed8c1c Thomas Schöpping
Any required low-level drivers for the AMiRo hardware are available in an
125 e545e620 Thomas Schöpping
additional project: AMiRo-LLD. It is included as a Git subodule and can be
126
initialized via the ./setup.sh script.
127 3dcad54e Thomas Schöpping
128 58fe0e0b Thomas Schöpping
129
130
2 - RECOMMENDED SOFTWARE
131 8fd2fd44 Thomas Schöpping
========================
132 58fe0e0b Thomas Schöpping
133 d8ed8c1c Thomas Schöpping
AMiRo-OS can take advantage of an installed bootloader, which is recommended for
134 e545e620 Thomas Schöpping
the best experience. In order to use all features of AMiRo-OS it is also
135
recommended to install either the 'hterm' or 'gtkterm' application for accessing
136
the robot. To ease further development, this project offers support for the
137
QtCreator IDE.
138 3dcad54e Thomas Schöpping
139 58fe0e0b Thomas Schöpping
140
2.1 - gtkterm and hterm
141 3dcad54e Thomas Schöpping
-----------------------
142 58fe0e0b Thomas Schöpping
143 e545e620 Thomas Schöpping
Depending on your operating system it is recommended to install 'gtkterm' for
144 3dcad54e Thomas Schöpping
Linux (available in the Ubuntu repositories), or 'hterm' for Windows. For
145 e545e620 Thomas Schöpping
gtkterm you need to modify the configuration file ~/.gtktermrc (generated
146 d443a2ff Thomas Schöpping
automatically when you start the application for the first time). For the AMiRo
147
modules the configuration is:
148 58fe0e0b Thomas Schöpping
149 9f224ade Thomas Schöpping
  port	= /dev/ttyAMiRo0
150 58fe0e0b Thomas Schöpping
  speed	= 115200
151
  bits	= 8
152
  stopbits	= 1
153
  parity	= none
154
  flow	= none
155
  wait_delay	= 0
156
  wait_char	= -1
157
  rs485_rts_time_before_tx	= 30
158
  rs485_rts_time_after_tx	= 30
159
  echo	= False
160
  crlfauto	= True
161
162 d443a2ff Thomas Schöpping
The according configuration for all NUCLEO boards is:
163
164
  port	= /dev/ttyACM0
165
  speed	= 115200
166
  bits	= 8
167
  stopbits	= 1
168
  parity	= none
169
  flow	= none
170
  wait_delay	= 0
171
  wait_char	= -1
172
  rs485_rts_time_before_tx	= 30
173
  rs485_rts_time_after_tx	= 30
174
  echo	= False
175
  crlfauto	= True
176
177 e545e620 Thomas Schöpping
For hterm you need to configure the tool analogously. With either tool the robot
178
can be reset by toggling the RTS signal on and off again, and you can access the
179 9f224ade Thomas Schöpping
system shell of AMiRo-OS. If you need legacy support for older version of
180
AMiRo-BLT, you can replace the port value by '/dev/ttyUSB0'.
181 d8ed8c1c Thomas Schöpping
Advanced users can use several connections to multiple modules simultaneously.
182
Each additional programmer will be available as '/dev/ttyAMiRo<N>' (and
183 d796dcdf Thomas Schöpping
'/dev/ttyUSB<N>' respectively) with <N> being an integer number starting from
184
zero. Please note: Those interfaces are ordered by the time when they have been
185
detected by the operating system, so detaching a cable and plugging it in again
186
may result in a different port name.
187 58fe0e0b Thomas Schöpping
188 3dcad54e Thomas Schöpping
189 e545e620 Thomas Schöpping
2.2 - QtCreator IDE
190
-------------------
191 3dcad54e Thomas Schöpping
192 d796dcdf Thomas Schöpping
In order to setup QtCreator projects any supported module, you can use the
193
provided ./setup.sh script. Further instructions for a more advanced
194 e545e620 Thomas Schöpping
configuration of the IDE are provided in the ./tools/qtcreator/README.txt file.
195
196
197
2.3  Doxygen & Graphviz
198
-----------------------
199
200
In order to generate the documentation from the source code, Doxygen and
201
Graphviz are requried. It is recommended to install these tool using the
202
default versions for your system. Ubuntu users should simply run
203
  >$ sudo apt-get install doxygen graphviz
204 3dcad54e Thomas Schöpping
205 58fe0e0b Thomas Schöpping
206
207
3 - BUILDING AND FLASHING
208 8fd2fd44 Thomas Schöpping
=========================
209 58fe0e0b Thomas Schöpping
210 3dcad54e Thomas Schöpping
Each time you modify any part of AMiRo-OS, you need to recompile the whole
211 e545e620 Thomas Schöpping
project for the according AMiRo module. Therefore you can use the ./Makefile by
212
simply executing 'make' and follow the instructions. Alternatively, you can
213 d796dcdf Thomas Schöpping
either use the makefiles provided per module in ./os/modules/<module_to_compile>
214 e545e620 Thomas Schöpping
or - if you want to compile all modules at once - the makefile in the
215
./os/modules folder. After the build process has finished successfully, you
216 d796dcdf Thomas Schöpping
always have to flash the generated program to the module. Therefore you need an
217 e545e620 Thomas Schöpping
appropriate tool, such as stm32flash (if you don't use a bootloader) or
218
SerialBoot (highly recommended; provided by AMiRo-BLT). Similarly to the
219
compilation procedure as described above, you can flash either each module
220
separately, or all modules at once by executing 'make flash' from the according
221
directory.
222
223
When using SerialBoot, please note that you must connect the programming cable
224
either to the DiWheelDrive or the PowerManagement module for flashing the
225
operating system. All other modules are powered off after reset so that only
226
these two offer a running bootloader, which is required for flashing.
227 58fe0e0b Thomas Schöpping
228 8fd2fd44 Thomas Schöpping
229
230
4 - DEVELOPER GUIDES
231
====================
232
233
Due to the complexity of AMiRo-OS it can be quite troublesome to get started
234
with the framework at the beginning. The guides in this chapter will help you
235
getting things done, without thorough knowledge of the software structure.
236 dc688a9f Thomas Schöpping
Whereas the textual descriptions of the guides provide additional information
237 8fd2fd44 Thomas Schöpping
about the underlying concepts and mechanisms, a short summary is provided at the
238
end of each chapter.
239
240
241
4.1  Adding a New Module
242
------------------------
243
244
The very first thing to do when adding a new module to support AMiRo-OS is to
245
create an according folder in the modules/ directory. The name of this folder
246
should be as unambiguous as possible (e.g. containing name and version number).
247
All files, which directly depent on the hardware, and thus are not portable,
248
belong here. Conversely, any code that can be reused on diferent hardware must
249 d796dcdf Thomas Schöpping
not be put in this module folder.
250 8fd2fd44 Thomas Schöpping
251
In a second step you have to initialize all requried files (see below) in the
252 d796dcdf Thomas Schöpping
newly created module directory. It is recommended to use another module as
253 8fd2fd44 Thomas Schöpping
template for your configuration:
254
- alldconf.h
255
  Configuration header for the AMiRo-LLD project, which is part of AMiRo-OS.
256 d796dcdf Thomas Schöpping
  There are probably only very few configurations done here, since most setting
257
  depend on the content of aosconf.h and are handled modue unspecifically in in
258
  modules/aos_alldconf.h
259 8fd2fd44 Thomas Schöpping
- aosconf.h
260
  Configuration header for the AMiRo-OS project.
261
- board.h & board.c
262
  Contains definitions of GPIO names and initialization setting of those, as
263
  well as initialization functions.
264
- chconf.h
265
  Configuration header for the ChibiOS/RT system kernel. There are probably only
266 d796dcdf Thomas Schöpping
  very few configurations done here, since most settings depend on the content
267
  of aosconf.h and are handled module unspecifically in modules/aos_chconf.h
268 8fd2fd44 Thomas Schöpping
- halconf.h
269
  Configuration header for ChibiOS/HAL (hardware abstraction layer).
270
- Makefile
271
  The GNU make script to build and flash AMiRo-OS for the module.
272
- mcuconf.h
273 d796dcdf Thomas Schöpping
  Configuration file for ChibiOS/HAL to initialize the microcontroller (MCU). It
274 8fd2fd44 Thomas Schöpping
  is recommended to check the kernel/ChibiOS/demos/ directory for an example
275
  using the according MCU and copy the mcuconf.h from there. Depending on your
276
  hardware you may have to modify it nevertheless, though.
277
- module.h & module.c
278
  These files act as some sort of container, where all module specific aliases
279
  for interfaces and GPIOs, configurations, hooks, low-level drivers, and unit
280
  tests are defined. These are most probably the most comprehensive files in the
281
  module folder.
282
- <mcu>.ld
283
  Linker script, defining the memory layout and region aliases. It is
284
  recommended to check ChibiOS (kernel/ChibiOS/os/common/startup/) whether a
285
  linker script for the according MCU already exists.
286
287
Since all these files are specific to the module hardware, youl will have to
288
modify the contents according to your setup in a third step. Most settings are
289
described in detail within the configuration files, but for others you will have
290
to consult the datasheet of your MCU and even take a closer look at how certain
291
settings are used in other modules.
292
293
Finally, you need to build and flash the project. The compiler might even help
294 d796dcdf Thomas Schöpping
you getting everything set up correctly. Take the time needed to understand
295
compilation errors and warnings and get rid of all of those (warnings should not
296
be ignored since they are hints that something might be amiss and the program
297
will not act as intended).
298 8fd2fd44 Thomas Schöpping
299
Summing up, you have to
300
1) create a module directory.
301
2) initialize all files (use an existing module or a ChibiOS demo as template).
302
3) configure all files according to your hardware setup and preferences.
303
4) compile, flash and check for issues.
304
305 dc688a9f Thomas Schöpping
306 8fd2fd44 Thomas Schöpping
4.2  Handling a Custom I/O Event in the Main Thread
307
---------------------------------------------------
308
309
In order to handle custom I/O events in the main thread, AMiRo-OS offers several
310
hooks to be used. First of all, you need to configure and enable the interrupt
311 d796dcdf Thomas Schöpping
for the according GPIO. This can be done by implementing the
312 8fd2fd44 Thomas Schöpping
MODULE_INIT_INTERRUPTS() hook in the module.h file. For information how to use
313
this hook, please have a look at existing modules. In the end, the interrupt
314
callback functions has to emit an I/O event with the according bit in the flags
315 d796dcdf Thomas Schöpping
mask set (like the _gpioCallback() function in aos_system.c). As result,
316
whenever a rising or falling edge (depends on configuration) is detected on that
317
particular GPIO, the interrupt service routine is executed and hence an I/O
318
event is fired, which can be catched by any thread in the system.
319 8fd2fd44 Thomas Schöpping
320
Next, you have to configure the main thread to whitelist the event flag (all I/O
321
events are blacklisted by default). While system relevant events like power down
322 d796dcdf Thomas Schöpping
are imlicitely whitelisted by the OS, any custom events need to be added
323
exlplicitely. This is done via the optional
324
AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK macro, which should be defined in the
325
module.h file. Example:
326 cda14729 Thomas Schöpping
327
  #define AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK         \
328
    (AOS_GPIOEVENT_FLAG(padX) | AOS_GPIOEVENT_FLAG(padY) | AOS_GPIOEVENT_FLAG(padZ))
329
330
When AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK has been defined correctly, the
331
main thread will be notified by the according events and execute its event
332
handling routine. Hence you have to implement another macro in module.h to
333 d796dcdf Thomas Schöpping
handle the custom event(s) appropriately:
334
MODULE_MAIN_LOOP_GPIOEVENT(eventflags). As you can see, the variable
335
'eventflags' is propagated to the hook. This variable is a mask, that allows to
336
identify the GPIO pad(s), which caused the event, by the individually set bits.
337
Following the example above, you can check which GPIOs have caused events by
338
using if-clauses in the implementation of the hook:
339 cda14729 Thomas Schöpping
340
  #define MODULE_MAIN_LOOP_GPIOEVENT(eventflags) {          \
341
    if (eventflags & AOS_GPIOEVENT_FLAG(padX)) {            \
342 8fd2fd44 Thomas Schöpping
      /* handle event */                                    \
343
    }                                                       \
344
    if (eventflags & (AOS_IOEVENT_FLAG(padY) |              \
345 cda14729 Thomas Schöpping
          AOS_GPIOEVENT_FLAG(padZ))) {                      \
346 8fd2fd44 Thomas Schöpping
      /* handle combined event */                           \
347
    }                                                       \
348
  }
349
350
Summing up, you have to
351
1) configure and enable the GPIO interrupt.
352 cda14729 Thomas Schöpping
2) define the AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK macro.
353
3) implement the MODULE_MAIN_LOOP_GPIOEVENT(eventflags) hook.
354 8fd2fd44 Thomas Schöpping
355 dc688a9f Thomas Schöpping
356 8fd2fd44 Thomas Schöpping
4.3  Implementing a New Low-Level Driver
357
----------------------------------------
358
359
In the AMiRo-OS framework, low-level drivers are located in the additional Git
360
project AMiRo-LLD, which is included in AMiRo-OS as Git submodule at
361
periphery-lld/AMiRo-LLD/ and acts similar to a static library. When adding a new
362 d796dcdf Thomas Schöpping
low-level driver to the framework, you have to implement it, following the
363
instructions given in periphery-lld/AMiRo-LLD/README.txt
364
365
Now the new driver is available and can be enbled by simply including the
366
driver's makefile script in the module makefile. In order to make actuale use of
367
the driver you have to add according memory structures to the module.h and
368 8fd2fd44 Thomas Schöpping
module.c files - just have a look at existing modules how this is done. In some
369
cases you will have to configure additional interrupts and/or alter the
370
configuration of a communication interface (e.g. I²C). Once again, you should
371
take a look at existing modules and search the module.h for the hooks
372 d796dcdf Thomas Schöpping
MODULE_INIT_INTERRUPTS(), MODULE_INIT_PERIPHERY_IF and
373
MODULE_SHUTDOWN_PERIPHERY_IF().
374 8fd2fd44 Thomas Schöpping
375 d796dcdf Thomas Schöpping
Finally, you will probably want to validate your implementation via a test. How
376
this can be done is explained in detail in the next guide.
377 8fd2fd44 Thomas Schöpping
378
Summing up, you have to
379
1) implement the driver in AMiRo-LLD using periphAL only.
380 d796dcdf Thomas Schöpping
4) add the driver to a module (Makefile, module.h and module.c).
381 8fd2fd44 Thomas Schöpping
5) configure interrupts and interfaces as required.
382 d796dcdf Thomas Schöpping
6) write a test.
383 8fd2fd44 Thomas Schöpping
384 dc688a9f Thomas Schöpping
385 d796dcdf Thomas Schöpping
4.4  Writing a Test
386 8fd2fd44 Thomas Schöpping
------------------------
387
388 d796dcdf Thomas Schöpping
AMiRo-OS provides a test framework for conventient testing and the ability to
389
opt-out all tests via the aosconf.h configuration file. There is also a
390
dedicated folder, where all test code belongs to. In case you want to implement
391
a test for a newly developed low-level driver, you should have a look at the
392
folder test/periphery-lld/. As with the low-level drivers, tests are placed in
393
individual subfolders (e.g. test/periphery-lld/DEVICE1234_v1) and all should use
394
the prefix 'aos_test_' in their name. Moreover, all code must be fenced by
395
guards that disable it completely if the AMIROOS_CFG_TESTS_ENABLE flag is set to
396
false in the aosconf.h configuration file.
397
398
Now you will need to add the test to a specific module. Therefore, you should
399
create a new test/ directory in the module folder, if such does not exist yet.
400
In this directory, you create another subfolder, e.g. DEVICE1234/ and three
401
additional files in there:
402
 - module_test_DEVICE1234.mk
403
 - module_test_DEVICE1234.h
404
 - module_test_DEVICE1234.c
405
The makefile script is not required, but recommended to achieve maintainable
406
code. This script file should add the folder to the MODULE_INC variable and all
407
C source files to MODULE_CSRC. The .h and .c files furthermore define module
408
specific data structures and a test function.
409
410
In order to be able to call this function as a command via the AMiRo-OS shell,
411
you need to add an according shell command to the module.h and module.c files.
412
Whereas the command itself is typically very simple, just calling the callback
413
function defined in the test/DEVICE1234/module_test_DEVICE1234.h/.c files, you
414
have to add the command to a shell. In order to make the shell command, which
415
executes the test, available in a shell so a user can run it, it has to be
416
associated with the shell. AMiRo-OS provides the hook MODULE_INIT_TESTS() for
417
this purpose, which has to be implemented in the module.h file. Once again I
418
recommend to have a look at an existing module, how to use this hook.
419 8fd2fd44 Thomas Schöpping
420
Summing up, you have to
421 d796dcdf Thomas Schöpping
1) implement the test in the test/ folder.
422
2) implement a module specific wrapper in the module/test/ folder.
423 8fd2fd44 Thomas Schöpping
3) associate the shell command to a shell via the hook in module.h.
424
425 3dcad54e Thomas Schöpping
================================================================================