Statistics
| Branch: | Tag: | Revision:

amiro-os / README.txt @ 3940ba8a

History | View | Annotate | Download (19.695 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..2019  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
  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
    4.4  Writing a Unit Test
73

    
74
================================================================================
75

    
76

    
77

    
78
1 - REQUIRED SOFTWARE
79
=====================
80

    
81
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

    
86

    
87
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
1.2 Bootloader & Tools
95
----------------------
96

    
97
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
described in its README.txt file. Follow th instructions to initialize the
105
development environment manually or use the ./setup.sh script.
106

    
107

    
108
1.3 System Kernel
109
-----------------
110

    
111
Since AMiRo-OS uses ChibiOS as underlying system kernel, you need to acquire a
112
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
make AMiRo-OS work properly. It is recommended to use the .setup.sh script for
116
this purpose.
117
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
Any required low-level drivers for the AMiRo hardware are available in an
125
additional project: AMiRo-LLD. It is included as a Git subodule and can be
126
initialized via the ./setup.sh script.
127

    
128

    
129

    
130
2 - RECOMMENDED SOFTWARE
131
========================
132

    
133
AMiRo-OS can take advantage of an installed bootloader, which is recommended for
134
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

    
139

    
140
2.1 - gtkterm and hterm
141
-----------------------
142

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

    
148
  port	= /dev/ttyAMiRo0
149
  speed	= 115200
150
  bits	= 8
151
  stopbits	= 1
152
  parity	= none
153
  flow	= none
154
  wait_delay	= 0
155
  wait_char	= -1
156
  rs485_rts_time_before_tx	= 30
157
  rs485_rts_time_after_tx	= 30
158
  echo	= False
159
  crlfauto	= True
160

    
161
For hterm you need to configure the tool analogously. With either tool the robot
162
can be reset by toggling the RTS signal on and off again, and you can access the
163
system shell of AMiRo-OS. If you need legacy support for older version of
164
AMiRo-BLT, you can replace the port value by '/dev/ttyUSB0'.
165
Advanced users can use several connections to multiple modules simultaneously.
166
Each additional programmer will be available as '/dev/ttyAMiRo<N>' (and
167
'/dev/USB<N>' respectively) with <N> being an integer number starting from zero.
168
Please note: Those interfaces are ordered by the time when they have been
169
detected by the operating system.
170

    
171

    
172
2.2 - QtCreator IDE
173
-------------------
174

    
175
In order to setup QtCreator projects for the three AMiRo base modules, you can
176
use the provided ./setup.sh script. Further instructions for a more advanced
177
configuration of the IDE are provided in the ./tools/qtcreator/README.txt file.
178

    
179

    
180
2.3  Doxygen & Graphviz
181
-----------------------
182

    
183
In order to generate the documentation from the source code, Doxygen and
184
Graphviz are requried. It is recommended to install these tool using the
185
default versions for your system. Ubuntu users should simply run
186
  >$ sudo apt-get install doxygen graphviz
187

    
188

    
189

    
190
3 - BUILDING AND FLASHING
191
=========================
192

    
193
Each time you modify any part of AMiRo-OS, you need to recompile the whole
194
project for the according AMiRo module. Therefore you can use the ./Makefile by
195
simply executing 'make' and follow the instructions. Alternatively, you can
196
either use the makefiles provided per module in ./os/modules/<ModuleToCompile>
197
or - if you want to compile all modules at once - the makefile in the
198
./os/modules folder. After the build process has finished successfully, you
199
always have to flash the generated program to the robot. Therefore you need an
200
appropriate tool, such as stm32flash (if you don't use a bootloader) or
201
SerialBoot (highly recommended; provided by AMiRo-BLT). Similarly to the
202
compilation procedure as described above, you can flash either each module
203
separately, or all modules at once by executing 'make flash' from the according
204
directory.
205

    
206
When using SerialBoot, please note that you must connect the programming cable
207
either to the DiWheelDrive or the PowerManagement module for flashing the
208
operating system. All other modules are powered off after reset so that only
209
these two offer a running bootloader, which is required for flashing.
210

    
211

    
212

    
213
4 - DEVELOPER GUIDES
214
====================
215

    
216
Due to the complexity of AMiRo-OS it can be quite troublesome to get started
217
with the framework at the beginning. The guides in this chapter will help you
218
getting things done, without thorough knowledge of the software structure.
219
Whereas the textual descriptions of the guides provide additional informatio
220
about the underlying concepts and mechanisms, a short summary is provided at the
221
end of each chapter.
222

    
223

    
224
4.1  Adding a New Module
225
------------------------
226

    
227
The very first thing to do when adding a new module to support AMiRo-OS is to
228
create an according folder in the modules/ directory. The name of this folder
229
should be as unambiguous as possible (e.g. containing name and version number).
230
All files, which directly depent on the hardware, and thus are not portable,
231
belong here. Conversely, any code that can be reused on diferent hardware must
232
not be put in the module folder.
233

    
234
In a second step you have to initialize all requried files (see below) in the
235
newlly created module directory. It is recommended to use another module as
236
template for your configuration:
237
- alldconf.h
238
  Configuration header for the AMiRo-LLD project, which is part of AMiRo-OS.
239
- aosconf.h
240
  Configuration header for the AMiRo-OS project.
241
- board.h & board.c
242
  Contains definitions of GPIO names and initialization setting of those, as
243
  well as initialization functions.
244
- chconf.h
245
  Configuration header for the ChibiOS/RT system kernel. There are probably only
246
  very few configurations one here, since most settings depend on the content of
247
  aosconf.h and are handled module unspecific in modules/aos_chconf.h
248
- halconf.h
249
  Configuration header for ChibiOS/HAL (hardware abstraction layer).
250
- Makefile
251
  The GNU make script to build and flash AMiRo-OS for the module.
252
- mcuconf.h
253
  Configuration file for ChibiOS/JAL to initialize the microcontroller (MCU). It
254
  is recommended to check the kernel/ChibiOS/demos/ directory for an example
255
  using the according MCU and copy the mcuconf.h from there. Depending on your
256
  hardware you may have to modify it nevertheless, though.
257
- module.h & module.c
258
  These files act as some sort of container, where all module specific aliases
259
  for interfaces and GPIOs, configurations, hooks, low-level drivers, and unit
260
  tests are defined. These are most probably the most comprehensive files in the
261
  module folder.
262
- <mcu>.ld
263
  Linker script, defining the memory layout and region aliases. It is
264
  recommended to check ChibiOS (kernel/ChibiOS/os/common/startup/) whether a
265
  linker script for the according MCU already exists.
266

    
267
Since all these files are specific to the module hardware, youl will have to
268
modify the contents according to your setup in a third step. Most settings are
269
described in detail within the configuration files, but for others you will have
270
to consult the datasheet of your MCU and even take a closer look at how certain
271
settings are used in other modules.
272

    
273
Finally, you need to build and flash the project. The compiler might even help
274
you getting everything set up correctly. Take time to understand compilation
275
errors and warning and get rid of all of those (warnings should not be ignored
276
since they are hints that something might be amiss and the program will not act
277
as intended).
278

    
279
Summing up, you have to
280
1) create a module directory.
281
2) initialize all files (use an existing module or a ChibiOS demo as template).
282
3) configure all files according to your hardware setup and preferences.
283
4) compile, flash and check for issues.
284

    
285
4.2  Handling a Custom I/O Event in the Main Thread
286
---------------------------------------------------
287

    
288
In order to handle custom I/O events in the main thread, AMiRo-OS offers several
289
hooks to be used. First of all, you need to configure and enable the interrupt
290
in the according GPIO. This can be done by implementing the
291
MODULE_INIT_INTERRUPTS() hook in the module.h file. For information how to use
292
this hook, please have a look at existing modules. In the end, the interrupt
293
callback functions has to emit an I/O event with the according bit in the flags
294
mask set (like the _intCallback() function in aos_system.c). As result, whenever
295
a rising or falling edge (depends on configuration) is detected on that GPIO,
296
the interrupt service routine is executed and hence an I/O event is fired, which
297
can be catched by any thread in the system.
298

    
299
Next, you have to configure the main thread to whitelist the event flag (all I/O
300
events are blacklisted by default). While system relevant events like power down
301
are whitelisted by the OS, any custom events need to be added exl´plicitely.
302
This is done via the optional AMIROOS_CFG_MAIN_LOOP_IOEVENT_MASK macro, which
303
should be defined in the module.h file. Example:
304

    
305
  #define AMIROOS_CFG_MAIN_LOOP_IOEVENT_MASK                \
306
    (AOS_IOEVENT_FLAG(padX) | AOS_IOEVENT_FLAG(padY) | AOS_IOEVENT_FLAG(padZ))
307

    
308
When AMIROOS_CFG_MAIN_LOOP_IOEVENT_MASK has been defined correctly, the main
309
thread will be notified by the according events and execute its event handling
310
routine. Hence you have to implement another macro in module.h to handle the
311
custom event(s) appropriately: MODULE_MAIN_LOOP_IO_EVENT(eventflags). As you can
312
see, the variable 'eventflags' is propagated to the hook. This variable is a
313
mask, that allows to identify the GPIO pad(s), which caused the event, by the
314
bits set. Following the example above, you can check which GPIOs have caused
315
events by using if-clauses in the implementation of the hook:
316

    
317
  #define MODULE_MAIN_LOOP_IO_EVENT(eventflags) {           \
318
    if (eventflags & AOS_IOEVENT_FLAG(padX)) {              \
319
      /* handle event */                                    \
320
    }                                                       \
321
    if (eventflags & (AOS_IOEVENT_FLAG(padY) |              \
322
          AOS_IOEVENT_FLAG(padZ))) {                        \
323
      /* handle combined event */                           \
324
    }                                                       \
325
  }
326

    
327
Summing up, you have to
328
1) configure and enable the GPIO interrupt.
329
2) define the AMIROOS_CFG_MAIN_LOOP_IOEVENT_MASK macro.
330
3) implement the MODULE_MAIN_LOOP_IO_EVENT(eventflags) hook.
331

    
332
4.3  Implementing a New Low-Level Driver
333
----------------------------------------
334

    
335
In the AMiRo-OS framework, low-level drivers are located in the additional Git
336
project AMiRo-LLD, which is included in AMiRo-OS as Git submodule at
337
periphery-lld/AMiRo-LLD/ and acts similar to a static library. When adding a new
338
low-level driver to the framework, you have to implement it, providing a
339
(single) header file in periphery-lld/AMiRo-LLD/include/ and the required C
340
sources in periphery-lld/AMiRo-LLD/source/. By convention, all filenames use the
341
prefix 'alld_' to avoid ambiguities. Furthermore, files should be named by the
342
exact designation of the hardware (e.g. 'alld_vcnl4020' instead of
343
'alld_proximitysensor'). Since AMiRo-LLD is intended to be usable with other
344
operating systems than AMiRo-OS, it provides an interface for accessing
345
communication interfaces and basic functionalities of the operating system. On
346
the one hand, several types are defined in periphery-lld/AMiRo-LLD/periphALtypes.h.
347
The interface functions, on the other hand, are defined by AMiRo-LLD (cf.
348
periphery-lld/AMiRo-LLD/templates/periphAL.h), but implemented by the operating
349
system (cf. periphery-lld/periphAL.h). For the implementation of the driver, you
350
must only use those types and functions to interact with the operating system.
351
If you need further functionality, which is not provided by the interface yet,
352
you are encouraged to extend periphAL.
353

    
354
Furthermore, all files must define a guard, so that the whole driver is
355
disabled, when the guard is not set explicitely. These guard again are named
356
following a convention, but instead of explaning it here, just have a look at
357
one of the existing drivers and look for lines like
358

    
359
  #if defined(AMIROLLD_CFG_USE_VCNL4020) || defined(__DOXYGEN__)
360

    
361
With these guards in place, the driver will be omitted by default and needs to
362
be enabled explicitely. In order to do so, you need to add an according #define
363
in the alldconf.h file of any module, which shall use the new driver.
364

    
365
Now the new driver is available and enabled, but not actually used yet.
366
Therefore you have to add according memory structures to the module.h and
367
module.c files - just have a look at existing modules how this is done. In some
368
cases you will have to configure additional interrupts and/or alter the
369
configuration of a communication interface (e.g. I²C). Once again, you should
370
take a look at existing modules and search the module.h for the hooks
371
MODULE_INIT_INTERRUPTS() and MODULE_INIT_PERIPHERY_COMM().
372

    
373
Finally, you will probably want to validate your implementation via a unit test.
374
How this can be done is explained in detail in the next guide.
375

    
376
Summing up, you have to
377
1) implement the driver in AMiRo-LLD using periphAL only.
378
2) fence all code in all files by a guard.
379
3) set the guard in alldconf.h to enable the driver.
380
4) add the driver to a module.
381
5) configure interrupts and interfaces as required.
382
6) write a unit test.
383

    
384
4.4  Writing a Unit Test
385
------------------------
386

    
387
AMiRo-OS provides a unit test framework for conventient testing and the ability
388
to opt-out all unit tests via the aosconf.h configuration file. There is also a
389
dedicated folder, where all unit test code belongs to. In case you want to
390
implement a unit test for a newly developed low-level driver, you should use the
391
folders unittests/periphery-lld/inc and unittests/periphery-lld/src
392
respectively. As with the low-level drivers, unit test files should use a prefix
393
in their name, namely 'ut_' and all code should be fenced via guards that
394
disable it by default (have a look at existing unit tests). Before you implement
395
a vast test, however, it is highly recommended to start with some sceleton code
396
(just copy an existing unit test, scoop out the test function, and rename
397
according variables etc.) and make it compile and run.
398

    
399
After you have initialized the unit test sceleton, you have to add the according
400
aos_unittest_t (cf. core/inc/aos_unittest.h) object to the module.h and module.c
401
files. These objects again require an shell command, so the unit test can be run
402
via the AMiRo-OS shell. As with existing unit tests, this shell command callback
403
function as well as any further required data should be implemented directly in
404
module.c, so it not accessable from any other context. In most cases this
405
callback function is trivial, anyway.
406

    
407
In order to make the shell command, which executes the unit test, available in
408
shell so a user can run it, it has to be associated with the shell. AMiRo-OS
409
provides the hook MODULE_INIT_TESTS() for this purpose, which has to be
410
implemented in the module.h file. Once again I recommend to have a look at an
411
existing module, how to use this hook.
412

    
413
Since the execution pipeline is set up now, you can fille your unit test with
414
life. Remember that the test is executed by the shell thread, so you can access
415
any functionality of the system, but might encounter race conditions, depending
416
on what other applications run concurrently.
417

    
418
Summing up, you have to
419
1) initialize a unit test sceleton in the unittests/ folder.
420
2) introduce an according object and configuration in module.h and module.c.
421
3) associate the shell command to a shell via the hook in module.h.
422
4) implement the full unit test in the prevously created sceleton files.
423

    
424
================================================================================
425