commit 8ba3c06be5dc9248fe26a417531d86a3fef0a0ab
Author: Thomas Schöpping <tschoepp@cit-ec.uni-bielefeld.de>
Date:   Fri Jul 3 12:05:41 2020 +0200

    Readme updated and enhanced

diff --git a/README.md b/README.md
index 5c99dbb..c3a74be 100644
--- a/README.md
+++ b/README.md
@@ -46,13 +46,13 @@ Contents
 
 1.  Required Software
     1.  Git
-    2.  Bootloader & Tools (AMiRi-BLT)
+    2.  Bootloader & Tools (AMiRo-BLT)
     3.  System Kernel (ChibiOS)
     4.  Low-Level Drivers (AMiRo-LLD)
     5.  OpenOCD
 2.  Recommended Software
     1.  gtkterm and hterm
-    2.  Plantuml
+    2.  PlantUML
     3.  Doxygen & Graphviz
     4.  QtCreator IDE
 3.  Building and Flashing
@@ -93,7 +93,7 @@ initialized via the provided `./setup.sh` script. Simply run
 
 from a command line.
 
-If requried, is is possible to replace the used bootloader by adding an
+If requried, it is possible to replace the used bootloader by adding an
 according subfolder in the `./bootloader/` directory. Note that you will have to
 adapt the makefiles and scripts, and probably the operating system as well.
 
@@ -116,8 +116,8 @@ If you would like to use a different kernel, you can add a subfolder in the
 `./kernel/` directory and adapt the scripts and operating system source code.
 
 
-1.4 Low-Level Drivers
----------------------
+1.4 Low-Level Drivers (AMiRo-LLD)
+---------------------------------
 
 Any required low-level drivers for the AMiRo hardware are available in an
 additional project: AMiRo-LLD. It is included as Git subodule and can be
@@ -140,7 +140,7 @@ For a list of supported boards, please refer to the OpcenOCD documentation.
 ======================
 
 The software tools named in this section are not essential for simply using or
-further development of AMiRo-BLT, but can help for both scenarios.
+further development of AMiRo-BLT, but are useful in both scenarios.
 
 
 2.1 gtkterm and hterm
@@ -191,16 +191,24 @@ configuration via the `-c` option:
 For `hterm` you need to configure the tool analogously. With either tool the
 robot can be reset by toggling the RTS signal on and off again, and you can
 access the system shell of AMiRo-OS.  
-If you are using an old version of AMiRo-BLT, the `/dev/ttyAMiRo` devices might
+If you are using an old version of AMiRo-BLT, the `/dev/ttyAMiRo#` devices might
 not be available. In order to enable legacy support, replace the port value by
 `/dev/ttyUSB0`.
 
-Advanced users can use several connections to multiple modules simultaneously.
-Each additional programmer will be available as `/dev/ttyAMiRo<N>` (and
-`/dev/ttyUSB<N>` respectively) with `<N>` being an integer starting from 0.
-Please note: Those interfaces are ordered by the time when they have been
-detected by the operating system, so detaching a cable and plugging it in again
-may result in a different port name.
+The configurations above use the first matching port (i.e. `/dev/ttyAMiRo0`,
+`/dev/ttyUSB0` or `/dev/ttyACM0`). If you have connected multiple devices to
+your system, those will be listed with increasing numbers in their identifiers.
+Furthermore, other USB devices (also internal components) might be listed as
+such as well. In those cases you can either adapt the configuration, or specify
+the correct port manually. For gtkterm the according call on the command line
+would be:
+
+    >$ gtkterm -c AMiRo -p=/dev/ttyAMiRo#
+
+where you have to replace the trailing `#` with the according integer.  
+Note that those interfaces are ordered by the time when they have been detected
+by the operating system, so detaching a cable and plugging it in again may
+result in a different port name.
 
 
 2.2 PlantUML
@@ -216,7 +224,7 @@ generate figures from these script files.
 ----------------------
 
 In order to generate the documentation from the source code, Doxygen and
-Graphviz are requried. It is recommended to install these tool using the
+Graphviz are requried. It is recommended to install these tools using the
 default versions for your system. Ubuntu users should simply run
 
     >$ sudo apt-get install doxygen graphviz
@@ -260,6 +268,14 @@ either to the _DiWheelDrive_ or the _PowerManagement_ module for flashing the
 operating system. All other modules are powered off after reset so that only
 these two offer a running bootloader, which is required for flashing.
 
+As already described for the serial connection via gtkterm or hterm, all scripts
+use the first matching port (i.e. `/dev/ttyAMiRo0`, `/dev/ttyUSB0` or
+`/dev/ttyACM0`) by default. If you need to specify a custom port, you can do so
+by passing an additional argument to the make call:
+
+    >$ make flash FLASH_PORT=/dev/ttyAMiRo#
+
+where you have to replace the trailing `#` with the according integer.
 
 
 4 Developer Guides
@@ -290,15 +306,16 @@ template for your configuration:
 *   alldconf.h  
     Configuration header for the AMiRo-LLD project, which is part of AMiRo-OS.
     There are probably only very few configurations done here, since most
-    setting depend on the content of aosconf.h and are handled module
+    settings depend on the content of aosconf.h and are handled module
     unspecifically in the `./modules/aos_alldconf.h` file.
 *   aosconf.h  
     Configuration header for the AMiRo-OS project. Existing cofiguration files
     are well documented and name all available settings.
 *   board.h & board.c  
-    Contains definitions of GPIO names and initialization setting of those, as
+    Contains definitions of GPIO names and initialization settings of those, as
     well as initialization functions. These configurations highly depend on the
-    hardware setup.
+    hardware setup. For further information, please refer to the ChibiOS
+    documentation. ChibiOS also provides demo code for various devices.
 *   chconf.h  
     Configuration header for the ChibiOS/RT system kernel. There are probably
     only very few configurations done here, since most settings depend on the
@@ -337,7 +354,7 @@ compilation errors and warnings and get rid of all of those (warnings should not
 be ignored since they are hints that something might be amiss and the program
 will not act as intended).
 
-As you will probably notice, for most modules there is an additional 'test/'
+As you will probably notice, for most modules there is an additional `test/`
 folder. This folder contains module specific wrapper code for tests (e.g. for
 hardware devices). Since tests are not essential but a more advanced feature,
 a separate guide describes how to write a test in section 4.5.
@@ -364,13 +381,13 @@ reads and writes from/to a shell stream. Such a stream may again contain an
 arbitrary number of channels. Whilst only one of those channels can be selected
 as input, each and all channels can be configured as output. As a result, if a
 hardware module features multiple I/O interfaces, according configuration of the
-shell stream and its channels, allows to still use only a single shell instance.
+shell stream and its channels allows to still use only a single shell instance.
 If not disabled in the aosconf.h file, AMiRo-OS already runs a system shell in
 a thread with minimum priority.
 
 Depending on the configuration, several commands are registered to the system
 shell by default (e.g. `kernel:test`, `module:info`), which are defined in the
-AMiRo-OS core. In order to add additional custom command, those should be
+AMiRo-OS core. In order to add additional custom commands, those should be
 defined in the module.h and module.c files. First you need to _declare_ the
 shell command - an instance of the memory structure representing a command - in
 the module.h file. Second, you have to _define_ that structure in the module.c
@@ -389,12 +406,15 @@ takes three arguments:
 
 The callback function is typically defined right before the
 `AOS_SHELL_COMMAND()` macro is called and should be a mere wrapper, calling
-another function. Keep in mind, though, that thos callback are executed within
+another function. Keep in mind, though, that those callbacks are executed within
 the shell thread and thus inherit its (typically very low) priority and there is
-no way to calling a command in a non-blocking manner.
+no way to call a command in a non-blocking manner. If you want to use a shell
+command to start/stop other components in your system, those should be
+implemented in dedicated threads and the shell command callbacks have to use
+inter process communication to manage and interface those components.
 
 Finally, you have to register the command to a shell. This is very important and
-a common mistake, but naturally, a shell can only access commands, which are
+a common mistake, but naturally a shell can only access commands, which are
 known to it. Registration is done via the `aosShellAddCommand()` function,
 preferably before the shell thread is started. Since test commands are the most
 common use case, AMiRo-OS provides the hook `MODULE_INIT_TESTS()`, which is
@@ -402,7 +422,7 @@ defined in each module.h file.
 
 **Summing up, you have to**
 
-1.  decllare and define a command.
+1.  declare and define a command.
 2.  implement a callback function.
 3.  register the command to a shell.
 
@@ -414,16 +434,16 @@ In order to handle custom I/O events in the main thread, AMiRo-OS offers several
 hooks to be used. First of all, you need to configure and enable the interrupt
 for the according GPIO. This can be done by implementing the
 `MODULE_INIT_INTERRUPTS()` hook in the module.h file. For information how to use
-this hook, please have a look at existing modules. In the end, the interrupt
-callback functions has to emit an I/O event with the according bit in the flags
-mask set (such as the `_gpioCallback()` function in `./core/src/aos_system.c`).
-As result, whenever a rising or falling edge (depends on configuration) is
-detected on that particular GPIO, the interrupt service routine is executed and
-hence an I/O event is emitted, which can be received by any thread in the
-system.
+this hook, please have a look at existing modules. In the end, the according
+interrupt callback function has to emit an I/O event with the according bit in
+the flags mask set (such as the `_gpioCallback()` function in
+`./core/src/aos_system.c`). As result, whenever a rising or falling edge
+(depends on configuration) is detected on that particular GPIO, the interrupt
+service routine is executed and hence an I/O event is emitted, which can be
+received by any thread in the system.
 
 Next, you have to explicitely whitelist the event flag for the main thread,
-because by default it ignores all I/O events other than power down and such.
+because it ignores all I/O events other than power down and such by default.
 This is done via the optional `AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK` macro,
 which should be defined in the module.h file, for example:
 
@@ -464,18 +484,18 @@ In the AMiRo-OS framework, low-level drivers are located in the additional Git
 project AMiRo-LLD, which is included in AMiRo-OS as Git submodule at
 `./periphery-lld/AMiRo-LLD/` and acts similar to a static library. When adding a
 new low-level driver to the framework, you first have to implement it of course.
-For details how to do so, please following the instructions givne in the
+For details how to do so, please follow the instructions given in the
 `README.md` file in the AMiRo-LLD root directory.
 
 Now that the new driver is available, it can be enbled by simply including the
-driver's makefile script in the makefile of the module, you are working on. In
-order to make actuale use of the driver, you have to add according memory
-structures to the module.h and module.c files - just have a look at existing
-modules how this is done. In some cases you will have to configure additional
-interrupts and/or alter the configuration of a communication interface
-(e.g. I2C). Once again, you should take a look at existing modules and search
-the module.h for the hooks `MODULE_INIT_INTERRUPTS()`,
-`MODULE_INIT_PERIPHERY_IF()` and `MODULE_SHUTDOWN_PERIPHERY_IF()`.
+driver's make script in the makefile of the module, you are working on. In order
+to make actual use of the driver, you have to add according memory structures to
+the module.h and module.c files - just have a look at existing modules how this
+is done. In some cases you will have to configure additional interrupts and/or
+alter the configuration of a communication interface (e.g. I2C). Once again, you
+should take a look at existing modules and search the module.h for the hooks
+`MODULE_INIT_INTERRUPTS()`, `MODULE_INIT_PERIPHERY_IF()` and
+`MODULE_SHUTDOWN_PERIPHERY_IF()`.
 
 Finally, you will probably want to validate your implementation via a test. How
 this can be done is explained in detail in the next guide.
@@ -510,23 +530,24 @@ files in there:
 *   module_test_DEVICE1234.h
 *   module_test_DEVICE1234.c
 
-The makefile script is not required, but recommended to achieve maintainable
-code. This script file should add the folder to the `MODULE_INC` variable and
-all C source files to `MODULE_CSRC`. The header and source files furthermore
-define module specific data structures and a test function. In order to clearly
-indicate that these files are module specific wrappers, their names should begin
-with the `module_test_` prefix.
+The make script is not required, but recommended to achieve maintainable code.
+This script should add the folder to the `MODULE_INC` variable and all C source
+files to `MODULE_CSRC`. The header and source files furthermore define module
+specific data structures and a test function. In order to clearly indicate that
+these files are module specific wrappers, their names should begin with the
+`module_test_` prefix.
 
 In order to be able to call such test function as a command via the AMiRo-OS
 shell, you need to add an according shell command to the module.h and module.c
 files. Whereas the command itself is typically very simple, just calling the
-callback function defined in the `./test/DEVICE1234/module_test_DEVICE1234.h`/
-`.c` files, you have to add the command to a shell. In order to make the command
-available in a shell so a user can run it, it has to be associated with the
-shell. AMiRo-OS provides the hook `MODULE_INIT_TESTS()` for this purpose, which
-has to be implemented in the module.h file. Once again it is recommended to have
-a look at an existing module, how to use this hook. Furthermore, there is more
-detailled guide on adding shell commands.
+callback function defined in the
+`./test/DEVICE1234/module_test_DEVICE1234.h`/`.c` files, you have to add the
+command to a shell. In order to make the command available in a shell so a user
+can run it, it has to be associated with the shell. AMiRo-OS provides the hook
+`MODULE_INIT_TESTS()` for this purpose, which has to be implemented in the
+module.h file. Once again it is recommended to have a look at an existing
+module, how to use this hook. Furthermore, there is more detailled guide on
+adding shell commands.
 
 **Summing up, you have to**
 
