Revision 2fc92540

View differences:

README.md
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

  
README.txt
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..2020  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 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 the 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). For the AMiRo
147
modules the configuration is:
148

  
149
  port	= /dev/ttyAMiRo0
150
  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
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
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
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
Advanced users can use several connections to multiple modules simultaneously.
182
Each additional programmer will be available as '/dev/ttyAMiRo<N>' (and
183
'/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

  
188

  
189
2.2 - QtCreator IDE
190
-------------------
191

  
192
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
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

  
205

  
206

  
207
3 - BUILDING AND FLASHING
208
=========================
209

  
210
Each time you modify any part of AMiRo-OS, you need to recompile the whole
211
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
either use the makefiles provided per module in ./os/modules/<module_to_compile>
214
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
always have to flash the generated program to the module. Therefore you need an
217
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

  
228

  
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
Whereas the textual descriptions of the guides provide additional information
237
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
not be put in this module folder.
250

  
251
In a second step you have to initialize all requried files (see below) in the
252
newly created module directory. It is recommended to use another module as
253
template for your configuration:
254
- alldconf.h
255
  Configuration header for the AMiRo-LLD project, which is part of AMiRo-OS.
256
  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
- 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
  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
- 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
  Configuration file for ChibiOS/HAL to initialize the microcontroller (MCU). It
274
  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
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

  
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

  
306
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
for the according GPIO. This can be done by implementing the
312
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
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

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

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

  
340
  #define MODULE_MAIN_LOOP_GPIOEVENT(eventflags) {          \
341
    if (eventflags & AOS_GPIOEVENT_FLAG(padX)) {            \
342
      /* handle event */                                    \
343
    }                                                       \
344
    if (eventflags & (AOS_IOEVENT_FLAG(padY) |              \
345
          AOS_GPIOEVENT_FLAG(padZ))) {                      \
346
      /* handle combined event */                           \
347
    }                                                       \
348
  }
349

  
350
Summing up, you have to
351
1) configure and enable the GPIO interrupt.
352
2) define the AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK macro.
353
3) implement the MODULE_MAIN_LOOP_GPIOEVENT(eventflags) hook.
354

  
355

  
356
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
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
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
MODULE_INIT_INTERRUPTS(), MODULE_INIT_PERIPHERY_IF and
373
MODULE_SHUTDOWN_PERIPHERY_IF().
374

  
375
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

  
378
Summing up, you have to
379
1) implement the driver in AMiRo-LLD using periphAL only.
380
4) add the driver to a module (Makefile, module.h and module.c).
381
5) configure interrupts and interfaces as required.
382
6) write a test.
383

  
384

  
385
4.4  Writing a Test
386
------------------------
387

  
388
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

  
420
Summing up, you have to
421
1) implement the test in the test/ folder.
422
2) implement a module specific wrapper in the module/test/ folder.
423
3) associate the shell command to a shell via the hook in module.h.
424

  
425
================================================================================
426

  

Also available in: Unified diff