Revision 8ba3c06b README.md
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