Statistics
| Branch: | Tag: | Revision:

amiro-os / README.md @ ded1ded7

History | View | Annotate | Download (23.2 KB)

1
About & License
2
===============
3

    
4
AMiRo-OS is an operating system for the base version of the Autonomous Mini
5
Robot (AMiRo) [1]. It utilizes ChibiOS (a real-time operating system for
6
embedded devices developed by Giovanni di Sirio; see <http://chibios.org>) as
7
system kernel and extends it with platform specific configurations and further
8
functionalities and abstractions.
9

    
10
Copyright (C) 2016..2020  Thomas Schöpping et al.
11
(a complete list of all authors is given below)
12

    
13
This program is free software: you can redistribute it and/or modify
14
it under the terms of the GNU General Public License as published by
15
the Free Software Foundation, either version 3 of the License, or (at
16
your option) any later version.
17

    
18
This program is distributed in the hope that it will be useful, but
19
WITHOUT ANY WARRANTY; without even the implied warranty of
20
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21
General Public License for more details.
22

    
23
You should have received a copy of the GNU General Public License
24
along with this program.  If not, see <http://www.gnu.org/licenses/>.
25

    
26
This research/work was supported by the Cluster of Excellence
27
Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld
28
University, which is funded by the German Research Foundation (DFG).
29

    
30
Authors:
31

    
32
-   Thomas Schöpping (tschoepp@cit-ec.uni-bielefeld.de)
33
-   Marc Rothmann
34

    
35
References:
36

    
37
[1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A
38
    modular & customizable open-source mini robot platform," 2016 20th
39
    International Conference on System Theory, Control and Computing (ICSTCC),
40
    Sinaia, 2016, pp. 687-692.
41

    
42
--------------------------------------------------------------------------------
43

    
44
Contents
45
========
46

    
47
1.  Required Software
48
    1.  Git
49
    2.  Bootloader & Tools (AMiRi-BLT)
50
    3.  System Kernel (ChibiOS)
51
    4.  Low-Level Drivers (AMiRo-LLD)
52
    5.  OpenOCD
53
2.  Recommended Software
54
    1.  gtkterm and hterm
55
    2.  Plantuml
56
    3.  Doxygen & Graphviz
57
    4.  QtCreator IDE
58
3.  Building and Flashing
59
4.  Developer Guides
60
    1.  Adding a Module
61
    2.  Adding a Shell Command
62
    3.  Handling a Custom I/O Event in the Main Thread
63
    4.  Implementing a Low-Level Driver
64
    5.  Writing a Test
65

    
66
--------------------------------------------------------------------------------
67

    
68
1 Required Software
69
===================
70

    
71
In order to compile the source code, you need to install the GNU ARM Embedded
72
Toolchain. Since this project uses GNU Make for configuring and calling the
73
compiler, this tool is requried too. AMiRo-OS uses ChibiOS as system kernel,
74
so you need a copy of that project as well.
75

    
76

    
77
1.1 Git
78
-------
79

    
80
Since all main- and subprojects are available as Git repositories, installing a
81
recent version of the tool is mandatory. Most Linux distributions like Ubuntu
82
provide a sufficient version in their software repositories.
83

    
84

    
85
1.2 Bootloader & Tools (AMiRo-BLT)
86
----------------------------------
87

    
88
AMiRo-OS can take advantage of an installed bootloader and provides an
89
interface. By default, AMiRo-BLT is included as Git submodule and can easily be
90
initialized via the provided `./setup.sh` script. Simply run
91

    
92
    >$ ./setup.sh
93

    
94
from a command line.
95

    
96
If requried, is is possible to replace the used bootloader by adding an
97
according subfolder in the `./bootloader/` directory. Note that you will have to
98
adapt the makefiles and scripts, and probably the operating system as well.
99

    
100
AMiRo-BLT furthermore has its own required and recommended software & tools as
101
described in its `README.md` file. Follow the instructions to initialize the
102
development environment manually or use the setup script.
103

    
104

    
105
1.3 System Kernel (ChibiOS)
106
---------------------------
107

    
108
Since AMiRo-OS uses ChibiOS as underlying system kernel, you need to acquire a
109
copy of it as well. For the sake of compatibility, it is included in AMiRo-OS as
110
Git submodule. It is highly recommended to use the setup script for
111
initialization. Moreover, you have to apply the patches to ChibiOS in order to
112
make AMiRo-OS work properly. It is recommended to use the setup script for this
113
purpose as well.
114

    
115
If you would like to use a different kernel, you can add a subfolder in the
116
`./kernel/` directory and adapt the scripts and operating system source code.
117

    
118

    
119
1.4 Low-Level Drivers
120
---------------------
121

    
122
Any required low-level drivers for the AMiRo hardware are available in an
123
additional project: AMiRo-LLD. It is included as Git subodule and can be
124
initialized via the setup script. Since AMiRo-LLD is also used for
125
experimentation and prototyping, it contains drivers even for some hardware that
126
is not available on the AMiRo platform.
127

    
128

    
129
1.5 OpenOCD
130
-----------
131

    
132
When running AMiRo-OS on non-AMiRo modules (e.g. NUCLEO development boards),
133
those can be flashed using the OpenOCD toolchain (<http://openocd.org/>). It can
134
be either installed from the software repositories of your operating system
135
(reqiures root permissions) or built from source (no root required).  
136
For a list of supported boards, please refer to the OpcenOCD documentation.
137

    
138

    
139
2 Recommended Software
140
======================
141

    
142
The software tools named in this section are not essential for simply using or
143
further development of AMiRo-BLT, but can help for both scenarios.
144

    
145

    
146
2.1 gtkterm and hterm
147
---------------------
148

    
149
Depending on your operating system, it is recommended to install `gtkterm` for
150
Linux (available in the Ubuntu repositories), or `hterm` for Windows. For
151
`gtkterm` you need to modify the configuration file `~/.gtktermrc` (generated
152
automatically when you start the application for the first time). For the AMiRo
153
modules the configuration is:
154

    
155
    [AMiRo]
156
    port	= /dev/ttyAMiRo0
157
    speed	= 115200
158
    bits	= 8
159
    stopbits	= 1
160
    parity	= none
161
    flow	= none
162
    wait_delay	= 0
163
    wait_char	= -1
164
    rs485_rts_time_before_tx	= 30
165
    rs485_rts_time_after_tx	= 30
166
    echo	= False
167
    crlfauto	= True
168

    
169
The according configuration for all NUCLEO boards is:
170

    
171
    [NUCLEO]
172
    port	= /dev/ttyACM0
173
    speed	= 115200
174
    bits	= 8
175
    stopbits	= 1
176
    parity	= none
177
    flow	= none
178
    wait_delay	= 0
179
    wait_char	= -1
180
    rs485_rts_time_before_tx	= 30
181
    rs485_rts_time_after_tx	= 30
182
    echo	= False
183
    crlfauto	= True
184

    
185
When running `gtkterm` from the command line, you can select a defined
186
configuration via the `-c` option:
187

    
188
    >$ gtkterm -c AMiRo
189
    >$ gtkterm -c NUCLEO
190

    
191
For `hterm` you need to configure the tool analogously. With either tool the
192
robot can be reset by toggling the RTS signal on and off again, and you can
193
access the system shell of AMiRo-OS.  
194
If you are using an old version of AMiRo-BLT, the `/dev/ttyAMiRo` devices might
195
not be available. In order to enable legacy support, replace the port value by
196
`/dev/ttyUSB0`.
197

    
198
Advanced users can use several connections to multiple modules simultaneously.
199
Each additional programmer will be available as `/dev/ttyAMiRo<N>` (and
200
`/dev/ttyUSB<N>` respectively) with `<N>` being an integer starting from 0.
201
Please note: Those interfaces are ordered by the time when they have been
202
detected by the operating system, so detaching a cable and plugging it in again
203
may result in a different port name.
204

    
205

    
206
2.2 PlantUML
207
------------
208

    
209
PlantUML is a free and open source Java tool to generate UML diagrams via scrips
210
(see <https://plantuml.com>). AMiRo-OS provides according scripts in the
211
`./doc/` directory. Please refer to the PlantUML documentation for how to
212
generate figures from these script files.
213

    
214

    
215
2.3 Doxygen & Graphviz
216
----------------------
217

    
218
In order to generate the documentation from the source code, Doxygen and
219
Graphviz are requried. It is recommended to install these tool using the
220
default versions for your system. Ubuntu users should simply run
221

    
222
    >$ sudo apt-get install doxygen graphviz
223

    
224

    
225
2.4 QtCreator IDE
226
-----------------
227

    
228
AMiRo-OS provides support for the QtCreator IDE. In order to setup according
229
projects, use the setup script and follow the instructions. It will
230
automatically generate the required files and you can import the projects by
231
opening the `.creator` files with QtCreator IDE.  
232
Please note that you will need to recompile the AMiRo-OS source code after each
233
project generation, since the generator runs a compiler call.
234

    
235
Further instructions for a more advanced configuration of the IDE are provided
236
in the `./tools/qtcreator/README.txt` file.
237

    
238

    
239

    
240
3 Building and Flashing
241
=======================
242

    
243
Each time you modify any part of AMiRo-OS, you need to recompile the whole
244
project for the according AMiRo module. Therefore you can use the `./Makefile`
245
by simply executing `make` and follow the instructions:
246

    
247
    >$ cd /path/to/AMiRo-OS/root/
248
    >$ make
249

    
250
Alternatively, you can either use the makefiles provided per module in
251
`./modules/<module_to_compile>/` or the makefile in the `./modules/` folder.
252
After the build process has finished successfully, you always have to flash the
253
generated program to the module. Therefore you need an appropriate tool, such as
254
`SerialBoot` for the AMiRo base modules (provided by AMiRo-BLT) or OpenOCD.
255
Similar to the compilation procedure as described above, you can flash either
256
each module individually, or all modules at once by using the same makefiles.
257

    
258
When using `SerialBoot`, please note that you must connect the programming cable
259
either to the _DiWheelDrive_ or the _PowerManagement_ module for flashing the
260
operating system. All other modules are powered off after reset so that only
261
these two offer a running bootloader, which is required for flashing.
262

    
263

    
264

    
265
4 Developer Guides
266
==================
267

    
268
Due to the complexity of AMiRo-OS it can be quite troublesome to get started
269
with the framework at the beginning. The guides in this chapter will help you
270
getting things done, without thorough knowledge of the software structure.
271
Whereas the textual descriptions of the guides provide in-depth information
272
about the underlying concepts and mechanisms, a short summary is provided at the
273
end of each chapter.
274

    
275

    
276
4.1 Adding a Module
277
-------------------
278

    
279
The very first thing to do when adding a new module to support AMiRo-OS, is to
280
create an according folder in the `./modules/` directory. The name of this
281
folder should be as unambiguous as possible (e.g. containing name and version
282
number). All files, which directly depent on the hardware, and thus are not
283
portable, belong here. Conversely, any code that can be reused on diferent
284
hardware should not be placed in this module folder.
285

    
286
In a second step you have to initialize all requried files (see below) in the
287
newly created module directory. It is recommended to use another module as
288
template for your configuration:
289

    
290
*   alldconf.h  
291
    Configuration header for the AMiRo-LLD project, which is part of AMiRo-OS.
292
    There are probably only very few configurations done here, since most
293
    setting depend on the content of aosconf.h and are handled module
294
    unspecifically in the `./modules/aos_alldconf.h` file.
295
*   aosconf.h  
296
    Configuration header for the AMiRo-OS project. Existing cofiguration files
297
    are well documented and name all available settings.
298
*   board.h & board.c  
299
    Contains definitions of GPIO names and initialization setting of those, as
300
    well as initialization functions. These configurations highly depend on the
301
    hardware setup.
302
*   chconf.h  
303
    Configuration header for the ChibiOS/RT system kernel. There are probably
304
    only very few configurations done here, since most settings depend on the
305
    content of aosconf.h and are handled module unspecifically in the
306
    `./modules/aos_chconf.h` file.
307
*   halconf.h  
308
    Configuration header for ChibiOS/HAL (hardware abstraction layer). Existing
309
    files are well documented and name all available settings. Please refer to
310
    ChibiOS for further details.
311
*   Makefile  
312
    The GNU make script to build and flash AMiRo-OS for the module.
313
*   mcuconf.h  
314
    Configuration file for ChibiOS/HAL to initialize the microcontroller (MCU).
315
    It is recommended to check the `./kernel/ChibiOS/demos/` directory for an
316
    example using the according MCU and copy the mcuconf.h from there. Depending
317
    on your hardware setup you may have to modify it nevertheless, though.
318
*   module.h & module.c  
319
    These files act as some sort of container, where all module specific aliases
320
    for interfaces and GPIOs, configurations, hooks, low-level drivers, and
321
    tests are defined. These are the most comprehensive files in the module
322
    folder.
323
*   <mcu\>.ld  
324
    Linker script, defining the memory layout and region aliases. It is
325
    recommended to check ChibiOS (`./kernel/ChibiOS/os/common/startup/`) whether
326
    a linker script for the according MCU already exists.
327

    
328
Since all these files are specific to the module hardware, you will have to
329
modify the contents according to your setup in a third step. Most settings are
330
described in detail within the configuration files, but for others you will have
331
to consult the datasheet of your MCU and even take a closer look at how certain
332
settings are used in other modules.
333

    
334
Finally, you need to build and flash the project. The compiler might even help
335
you getting everything set up correctly. Take the time needed to understand
336
compilation errors and warnings and get rid of all of those (warnings should not
337
be ignored since they are hints that something might be amiss and the program
338
will not act as intended).
339

    
340
As you will probably notice, for most modules there is an additional 'test/'
341
folder. This folder contains module specific wrapper code for tests (e.g. for
342
hardware devices). Since tests are not essential but a more advanced feature,
343
a separate guide describes how to write a test in section 4.5.
344

    
345
**Summing up, you have to**
346

    
347
1.  create a module directory.
348
2.  initialize all files (use an existing module or a ChibiOS demo as template).
349
3.  configure all files according to your hardware setup and preferences.
350
4.  compile, flash and check for issues.
351

    
352

    
353
4.2 Adding a Shell Command
354
--------------------------
355

    
356
Before going into the technical details, how a new shell command is initialized
357
and registered to a shell, some basic concepts of the AMiRo shell should be
358
covered first. Most fundamentally, although for most use cases a single shell
359
instance on a module will suffice, there can be an arbitrary number of shells.
360
Each shell runs in its own thread and has an exclusive list of shell commands.
361
That said, each shell command can be registered to only one (or none) shell.  
362
Another important aspect of the AMiRo shell are the I/O streams. Each shell
363
reads and writes from/to a shell stream. Such a stream may again contain an
364
arbitrary number of channels. Whilst only one of those channels can be selected
365
as input, each and all channels can be configured as output. As a result, if a
366
hardware module features multiple I/O interfaces, according configuration of the
367
shell stream and its channels, allows to still use only a single shell instance.
368
If not disabled in the aosconf.h file, AMiRo-OS already runs a system shell in
369
a thread with minimum priority.
370

    
371
Depending on the configuration, several commands are registered to the system
372
shell by default (e.g. `kernel:test`, `module:info`), which are defined in the
373
AMiRo-OS core. In order to add additional custom command, those should be
374
defined in the module.h and module.c files. First you need to _declare_ the
375
shell command - an instance of the memory structure representing a command - in
376
the module.h file. Second, you have to _define_ that structure in the module.c
377
file via the `AOS_SHELL_COMMAND(var, name, callback)` macro function. This macro
378
takes three arguments:
379

    
380
1.  `var`  
381
    Name of the variable (must be identical to the _declaration_).
382
2.  `name`  
383
    Command string which will be shown and used in the shell. By convention,
384
    command names follow a colon notation, e.g. `module:info`, where the first
385
    part denotes the scope of the command (e.g. kernel, module, tests, etc.) and
386
    the second part specifies the command in this scope.
387
3.  `callback`  
388
    Callback function to be executed by the command.
389

    
390
The callback function is typically defined right before the
391
`AOS_SHELL_COMMAND()` macro is called and should be a mere wrapper, calling
392
another function. Keep in mind, though, that thos callback are executed within
393
the shell thread and thus inherit its (typically very low) priority and there is
394
no way to calling a command in a non-blocking manner.
395

    
396
Finally, you have to register the command to a shell. This is very important and
397
a common mistake, but naturally, a shell can only access commands, which are
398
known to it. Registration is done via the `aosShellAddCommand()` function,
399
preferably before the shell thread is started. Since test commands are the most
400
common use case, AMiRo-OS provides the hook `MODULE_INIT_TESTS()`, which is
401
defined in each module.h file.
402

    
403
**Summing up, you have to**
404

    
405
1.  decllare and define a command.
406
2.  implement a callback function.
407
3.  register the command to a shell.
408

    
409

    
410
4.3 Handling a Custom I/O Event in the Main Thread
411
--------------------------------------------------
412

    
413
In order to handle custom I/O events in the main thread, AMiRo-OS offers several
414
hooks to be used. First of all, you need to configure and enable the interrupt
415
for the according GPIO. This can be done by implementing the
416
`MODULE_INIT_INTERRUPTS()` hook in the module.h file. For information how to use
417
this hook, please have a look at existing modules. In the end, the interrupt
418
callback functions has to emit an I/O event with the according bit in the flags
419
mask set (such as the `_gpioCallback()` function in `./core/src/aos_system.c`).
420
As result, whenever a rising or falling edge (depends on configuration) is
421
detected on that particular GPIO, the interrupt service routine is executed and
422
hence an I/O event is emitted, which can be received by any thread in the
423
system.
424

    
425
Next, you have to explicitely whitelist the event flag for the main thread,
426
because by default it ignores all I/O events other than power down and such.
427
This is done via the optional `AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK` macro,
428
which should be defined in the module.h file, for example:
429

    
430
    #define AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK         \
431
            (AOS_GPIOEVENT_FLAG(padX) | AOS_GPIOEVENT_FLAG(padY) | AOS_GPIOEVENT_FLAG(padZ))
432

    
433
When `AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK` has been defined correctly, the
434
main thread will be notified by the according events and execute its event
435
handling routine. Hence you have to implement another macro in module.h to
436
handle the custom event(s) appropriately:
437
`MODULE_MAIN_LOOP_GPIOEVENT(eventflags)`. As you can see, the variable
438
`eventflags` is propagated to the hook. This variable is a mask, that allows to
439
identify the GPIO pad(s), which caused the event, by the individually set bits.
440
Following the example above, you can check which GPIOs have caused events by
441
using if-clauses in the implementation of the hook:
442

    
443
    #define MODULE_MAIN_LOOP_GPIOEVENT(eventflags) {          \
444
      if (eventflags & AOS_GPIOEVENT_FLAG(padX)) {            \
445
        /* handle event */                                    \
446
      }                                                       \
447
      if (eventflags & (AOS_IOEVENT_FLAG(padY) |              \
448
            AOS_GPIOEVENT_FLAG(padZ))) {                      \
449
        /* handle combined event */                           \
450
      }                                                       \
451
    }
452

    
453
**Summing up, you have to**
454

    
455
1.  configure and enable the GPIO interrupt.
456
2.  define the AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK macro.
457
3.  implement the MODULE_MAIN_LOOP_GPIOEVENT(eventflags) hook.
458

    
459

    
460
4.4 Implementing a Low-Level Driver
461
-----------------------------------
462

    
463
In the AMiRo-OS framework, low-level drivers are located in the additional Git
464
project AMiRo-LLD, which is included in AMiRo-OS as Git submodule at
465
`./periphery-lld/AMiRo-LLD/` and acts similar to a static library. When adding a
466
new low-level driver to the framework, you first have to implement it of course.
467
For details how to do so, please following the instructions givne in the
468
`README.md` file in the AMiRo-LLD root directory.
469

    
470
Now that the new driver is available, it can be enbled by simply including the
471
driver's makefile script in the makefile of the module, you are working on. In
472
order to make actuale use of the driver, you have to add according memory
473
structures to the module.h and module.c files - just have a look at existing
474
modules how this is done. In some cases you will have to configure additional
475
interrupts and/or alter the configuration of a communication interface
476
(e.g. I2C). Once again, you should take a look at existing modules and search
477
the module.h for the hooks `MODULE_INIT_INTERRUPTS()`,
478
`MODULE_INIT_PERIPHERY_IF()` and `MODULE_SHUTDOWN_PERIPHERY_IF()`.
479

    
480
Finally, you will probably want to validate your implementation via a test. How
481
this can be done is explained in detail in the next guide.
482

    
483
**Summing up, you have to**
484

    
485
1.  implement the driver in AMiRo-LLD using periphAL only.
486
2.  add the driver to a module (Makefile, module.h and module.c).
487
3.  configure interrupts and interfaces as required.
488
4.  write a test to verify your setup.
489

    
490

    
491
4.4 Writing a Test
492
------------------
493

    
494
AMiRo-OS provides a test framework for conventient testing and the ability to
495
opt-out all tests via the aosconf.h configuration file. There is also a
496
dedicated folder, where all test code belongs to. In case you want to implement
497
a test for a newly developed low-level driver, you should have a look at the
498
folder `./test/periphery-lld/`. As with the low-level drivers, tests are placed
499
in individual subfolders (e.g. `./test/periphery-lld/DEVICE1234_v1`) and all
500
files should use the prefix `aos_test_` in their name. Moreover, all code must
501
be fenced by guards that disable it completely if the `AMIROOS_CFG_TESTS_ENABLE`
502
flag is set to false in the aosconf.h configuration file.
503

    
504
Now you have to add the test to a specific module. Therefore, you should create
505
a `test/` directory in the module folder, if such does not exist yet. In this
506
directory, you create another subfolder, e.g. `DEVICE1234/` and three additional
507
files in there:
508

    
509
*   module_test_DEVICE1234.mk
510
*   module_test_DEVICE1234.h
511
*   module_test_DEVICE1234.c
512

    
513
The makefile script is not required, but recommended to achieve maintainable
514
code. This script file should add the folder to the `MODULE_INC` variable and
515
all C source files to `MODULE_CSRC`. The header and source files furthermore
516
define module specific data structures and a test function. In order to clearly
517
indicate that these files are module specific wrappers, their names should begin
518
with the `module_test_` prefix.
519

    
520
In order to be able to call such test function as a command via the AMiRo-OS
521
shell, you need to add an according shell command to the module.h and module.c
522
files. Whereas the command itself is typically very simple, just calling the
523
callback function defined in the `./test/DEVICE1234/module_test_DEVICE1234.h`/
524
`.c` files, you have to add the command to a shell. In order to make the command
525
available in a shell so a user can run it, it has to be associated with the
526
shell. AMiRo-OS provides the hook `MODULE_INIT_TESTS()` for this purpose, which
527
has to be implemented in the module.h file. Once again it is recommended to have
528
a look at an existing module, how to use this hook. Furthermore, there is more
529
detailled guide on adding shell commands.
530

    
531
**Summing up, you have to**
532

    
533
1.  implement the common test in the `./test/` folder.
534
2.  implement a module specific wrapper in the `./modules/<module>/test/`
535
    folder.
536
3.  associate the shell command to a shell via the `MODULE_INIT_TESTS()` hook in
537
    module.h.
538