Revision 8ba3c06b README.md

View differences:

README.md
46 46

  
47 47
1.  Required Software
48 48
    1.  Git
49
    2.  Bootloader & Tools (AMiRi-BLT)
49
    2.  Bootloader & Tools (AMiRo-BLT)
50 50
    3.  System Kernel (ChibiOS)
51 51
    4.  Low-Level Drivers (AMiRo-LLD)
52 52
    5.  OpenOCD
53 53
2.  Recommended Software
54 54
    1.  gtkterm and hterm
55
    2.  Plantuml
55
    2.  PlantUML
56 56
    3.  Doxygen & Graphviz
57 57
    4.  QtCreator IDE
58 58
3.  Building and Flashing
......
93 93

  
94 94
from a command line.
95 95

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

  
......
116 116
`./kernel/` directory and adapt the scripts and operating system source code.
117 117

  
118 118

  
119
1.4 Low-Level Drivers
120
---------------------
119
1.4 Low-Level Drivers (AMiRo-LLD)
120
---------------------------------
121 121

  
122 122
Any required low-level drivers for the AMiRo hardware are available in an
123 123
additional project: AMiRo-LLD. It is included as Git subodule and can be
......
140 140
======================
141 141

  
142 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.
143
further development of AMiRo-BLT, but are useful in both scenarios.
144 144

  
145 145

  
146 146
2.1 gtkterm and hterm
......
191 191
For `hterm` you need to configure the tool analogously. With either tool the
192 192
robot can be reset by toggling the RTS signal on and off again, and you can
193 193
access the system shell of AMiRo-OS.  
194
If you are using an old version of AMiRo-BLT, the `/dev/ttyAMiRo` devices might
194
If you are using an old version of AMiRo-BLT, the `/dev/ttyAMiRo#` devices might
195 195
not be available. In order to enable legacy support, replace the port value by
196 196
`/dev/ttyUSB0`.
197 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.
198
The configurations above use the first matching port (i.e. `/dev/ttyAMiRo0`,
199
`/dev/ttyUSB0` or `/dev/ttyACM0`). If you have connected multiple devices to
200
your system, those will be listed with increasing numbers in their identifiers.
201
Furthermore, other USB devices (also internal components) might be listed as
202
such as well. In those cases you can either adapt the configuration, or specify
203
the correct port manually. For gtkterm the according call on the command line
204
would be:
205

  
206
    >$ gtkterm -c AMiRo -p=/dev/ttyAMiRo#
207

  
208
where you have to replace the trailing `#` with the according integer.  
209
Note that those interfaces are ordered by the time when they have been detected
210
by the operating system, so detaching a cable and plugging it in again may
211
result in a different port name.
204 212

  
205 213

  
206 214
2.2 PlantUML
......
216 224
----------------------
217 225

  
218 226
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
227
Graphviz are requried. It is recommended to install these tools using the
220 228
default versions for your system. Ubuntu users should simply run
221 229

  
222 230
    >$ sudo apt-get install doxygen graphviz
......
260 268
operating system. All other modules are powered off after reset so that only
261 269
these two offer a running bootloader, which is required for flashing.
262 270

  
271
As already described for the serial connection via gtkterm or hterm, all scripts
272
use the first matching port (i.e. `/dev/ttyAMiRo0`, `/dev/ttyUSB0` or
273
`/dev/ttyACM0`) by default. If you need to specify a custom port, you can do so
274
by passing an additional argument to the make call:
275

  
276
    >$ make flash FLASH_PORT=/dev/ttyAMiRo#
277

  
278
where you have to replace the trailing `#` with the according integer.
263 279

  
264 280

  
265 281
4 Developer Guides
......
290 306
*   alldconf.h  
291 307
    Configuration header for the AMiRo-LLD project, which is part of AMiRo-OS.
292 308
    There are probably only very few configurations done here, since most
293
    setting depend on the content of aosconf.h and are handled module
309
    settings depend on the content of aosconf.h and are handled module
294 310
    unspecifically in the `./modules/aos_alldconf.h` file.
295 311
*   aosconf.h  
296 312
    Configuration header for the AMiRo-OS project. Existing cofiguration files
297 313
    are well documented and name all available settings.
298 314
*   board.h & board.c  
299
    Contains definitions of GPIO names and initialization setting of those, as
315
    Contains definitions of GPIO names and initialization settings of those, as
300 316
    well as initialization functions. These configurations highly depend on the
301
    hardware setup.
317
    hardware setup. For further information, please refer to the ChibiOS
318
    documentation. ChibiOS also provides demo code for various devices.
302 319
*   chconf.h  
303 320
    Configuration header for the ChibiOS/RT system kernel. There are probably
304 321
    only very few configurations done here, since most settings depend on the
......
337 354
be ignored since they are hints that something might be amiss and the program
338 355
will not act as intended).
339 356

  
340
As you will probably notice, for most modules there is an additional 'test/'
357
As you will probably notice, for most modules there is an additional `test/`
341 358
folder. This folder contains module specific wrapper code for tests (e.g. for
342 359
hardware devices). Since tests are not essential but a more advanced feature,
343 360
a separate guide describes how to write a test in section 4.5.
......
364 381
arbitrary number of channels. Whilst only one of those channels can be selected
365 382
as input, each and all channels can be configured as output. As a result, if a
366 383
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.
384
shell stream and its channels allows to still use only a single shell instance.
368 385
If not disabled in the aosconf.h file, AMiRo-OS already runs a system shell in
369 386
a thread with minimum priority.
370 387

  
371 388
Depending on the configuration, several commands are registered to the system
372 389
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
390
AMiRo-OS core. In order to add additional custom commands, those should be
374 391
defined in the module.h and module.c files. First you need to _declare_ the
375 392
shell command - an instance of the memory structure representing a command - in
376 393
the module.h file. Second, you have to _define_ that structure in the module.c
......
389 406

  
390 407
The callback function is typically defined right before the
391 408
`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
409
another function. Keep in mind, though, that those callbacks are executed within
393 410
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.
411
no way to call a command in a non-blocking manner. If you want to use a shell
412
command to start/stop other components in your system, those should be
413
implemented in dedicated threads and the shell command callbacks have to use
414
inter process communication to manage and interface those components.
395 415

  
396 416
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
417
a common mistake, but naturally a shell can only access commands, which are
398 418
known to it. Registration is done via the `aosShellAddCommand()` function,
399 419
preferably before the shell thread is started. Since test commands are the most
400 420
common use case, AMiRo-OS provides the hook `MODULE_INIT_TESTS()`, which is
......
402 422

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

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

  
......
414 434
hooks to be used. First of all, you need to configure and enable the interrupt
415 435
for the according GPIO. This can be done by implementing the
416 436
`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.
437
this hook, please have a look at existing modules. In the end, the according
438
interrupt callback function has to emit an I/O event with the according bit in
439
the flags mask set (such as the `_gpioCallback()` function in
440
`./core/src/aos_system.c`). As result, whenever a rising or falling edge
441
(depends on configuration) is detected on that particular GPIO, the interrupt
442
service routine is executed and hence an I/O event is emitted, which can be
443
received by any thread in the system.
424 444

  
425 445
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.
446
because it ignores all I/O events other than power down and such by default.
427 447
This is done via the optional `AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK` macro,
428 448
which should be defined in the module.h file, for example:
429 449

  
......
464 484
project AMiRo-LLD, which is included in AMiRo-OS as Git submodule at
465 485
`./periphery-lld/AMiRo-LLD/` and acts similar to a static library. When adding a
466 486
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
487
For details how to do so, please follow the instructions given in the
468 488
`README.md` file in the AMiRo-LLD root directory.
469 489

  
470 490
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()`.
491
driver's make script in the makefile of the module, you are working on. In order
492
to make actual use of the driver, you have to add according memory structures to
493
the module.h and module.c files - just have a look at existing modules how this
494
is done. In some cases you will have to configure additional interrupts and/or
495
alter the configuration of a communication interface (e.g. I2C). Once again, you
496
should take a look at existing modules and search the module.h for the hooks
497
`MODULE_INIT_INTERRUPTS()`, `MODULE_INIT_PERIPHERY_IF()` and
498
`MODULE_SHUTDOWN_PERIPHERY_IF()`.
479 499

  
480 500
Finally, you will probably want to validate your implementation via a test. How
481 501
this can be done is explained in detail in the next guide.
......
510 530
*   module_test_DEVICE1234.h
511 531
*   module_test_DEVICE1234.c
512 532

  
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.
533
The make script is not required, but recommended to achieve maintainable code.
534
This script should add the folder to the `MODULE_INC` variable and all C source
535
files to `MODULE_CSRC`. The header and source files furthermore define module
536
specific data structures and a test function. In order to clearly indicate that
537
these files are module specific wrappers, their names should begin with the
538
`module_test_` prefix.
519 539

  
520 540
In order to be able to call such test function as a command via the AMiRo-OS
521 541
shell, you need to add an according shell command to the module.h and module.c
522 542
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.
543
callback function defined in the
544
`./test/DEVICE1234/module_test_DEVICE1234.h`/`.c` files, you have to add the
545
command to a shell. In order to make the command available in a shell so a user
546
can run it, it has to be associated with the shell. AMiRo-OS provides the hook
547
`MODULE_INIT_TESTS()` for this purpose, which has to be implemented in the
548
module.h file. Once again it is recommended to have a look at an existing
549
module, how to use this hook. Furthermore, there is more detailled guide on
550
adding shell commands.
530 551

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

  

Also available in: Unified diff