commit d796dcdf8b8795e1cdf70e8811ac19c1d1ae0b31
Author: Thomas Schöpping <tschoepp@cit-ec.uni-bielefeld.de>
Date:   Wed Nov 13 14:49:56 2019 +0100

    documentation updated

diff --git a/README.txt b/README.txt
index 0757c3f..fa44345 100644
--- a/README.txt
+++ b/README.txt
@@ -69,7 +69,7 @@ CONTENTS:
     4.1  Adding a New Module
     4.2  Handling a Custom I/O Event in the Main Thread
     4.3  Implementing a New Low-Level Driver
-    4.4  Writing a Unit Test
+    4.4  Writing a Test
 
 ================================================================================
 
@@ -101,7 +101,7 @@ 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.
 AMiRo-BLT furthermore has its own required and recommended software tools as
-described in its README.txt file. Follow th instructions to initialize the
+described in its README.txt file. Follow the instructions to initialize the
 development environment manually or use the ./setup.sh script.
 
 
@@ -112,7 +112,7 @@ Since AMiRo-OS uses ChibiOS as underlying system kernel, you need to acquire a
 copy of it as well. For the sake of compatibility, it is included in AMiRo-OS as
 a Git submodule. It is highly recommended to use the ./setup.sh script for
 initialization. Moreover, you have to apply the patches to ChibiOS in order to
-make AMiRo-OS work properly. It is recommended to use the .setup.sh script for
+make AMiRo-OS work properly. It is recommended to use the ./setup.sh script for
 this purpose.
 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.
@@ -164,16 +164,17 @@ system shell of AMiRo-OS. If you need legacy support for older version of
 AMiRo-BLT, you can 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/USB<N>' respectively) with <N> being an integer number starting from zero.
-Please note: Those interfaces are ordered by the time when they have been
-detected by the operating system.
+'/dev/ttyUSB<N>' respectively) with <N> being an integer number starting from
+zero. 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.
 
 
 2.2 - QtCreator IDE
 -------------------
 
-In order to setup QtCreator projects for the three AMiRo base modules, you can
-use the provided ./setup.sh script. Further instructions for a more advanced
+In order to setup QtCreator projects any supported module, you can use the
+provided ./setup.sh script. Further instructions for a more advanced
 configuration of the IDE are provided in the ./tools/qtcreator/README.txt file.
 
 
@@ -193,10 +194,10 @@ default versions for your system. Ubuntu users should simply run
 Each time you modify any part of AMiRo-OS, you need to recompile the whole
 project for the according AMiRo module. Therefore you can use the ./Makefile by
 simply executing 'make' and follow the instructions. Alternatively, you can
-either use the makefiles provided per module in ./os/modules/<ModuleToCompile>
+either use the makefiles provided per module in ./os/modules/<module_to_compile>
 or - if you want to compile all modules at once - the makefile in the
 ./os/modules folder. After the build process has finished successfully, you
-always have to flash the generated program to the robot. Therefore you need an
+always have to flash the generated program to the module. Therefore you need an
 appropriate tool, such as stm32flash (if you don't use a bootloader) or
 SerialBoot (highly recommended; provided by AMiRo-BLT). Similarly to the
 compilation procedure as described above, you can flash either each module
@@ -229,13 +230,16 @@ create an according folder in the modules/ directory. The name of this folder
 should be as unambiguous as possible (e.g. containing name and version number).
 All files, which directly depent on the hardware, and thus are not portable,
 belong here. Conversely, any code that can be reused on diferent hardware must
-not be put in the module folder.
+not be put in this module folder.
 
 In a second step you have to initialize all requried files (see below) in the
-newlly created module directory. It is recommended to use another module as
+newly created module directory. It is recommended to use another module as
 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 modue unspecifically in in
+  modules/aos_alldconf.h
 - aosconf.h
   Configuration header for the AMiRo-OS project.
 - board.h & board.c
@@ -243,14 +247,14 @@ template for your configuration:
   well as initialization functions.
 - chconf.h
   Configuration header for the ChibiOS/RT system kernel. There are probably only
-  very few configurations one here, since most settings depend on the content of
-  aosconf.h and are handled module unspecific in modules/aos_chconf.h
+  very few configurations done here, since most settings depend on the content
+  of aosconf.h and are handled module unspecifically in modules/aos_chconf.h
 - halconf.h
   Configuration header for ChibiOS/HAL (hardware abstraction layer).
 - Makefile
   The GNU make script to build and flash AMiRo-OS for the module.
 - mcuconf.h
-  Configuration file for ChibiOS/JAL to initialize the microcontroller (MCU). It
+  Configuration file for ChibiOS/HAL to initialize the microcontroller (MCU). It
   is recommended to check the kernel/ChibiOS/demos/ directory for an example
   using the according MCU and copy the mcuconf.h from there. Depending on your
   hardware you may have to modify it nevertheless, though.
@@ -271,10 +275,10 @@ to consult the datasheet of your MCU and even take a closer look at how certain
 settings are used in other modules.
 
 Finally, you need to build and flash the project. The compiler might even help
-you getting everything set up correctly. Take time to understand compilation
-errors and warning 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).
+you getting everything set up correctly. Take the time needed to understand
+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).
 
 Summing up, you have to
 1) create a module directory.
@@ -288,20 +292,21 @@ Summing up, you have to
 
 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
-in the according GPIO. This can be done by implementing the
+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 (like the _intCallback() function in aos_system.c). As result, whenever
-a rising or falling edge (depends on configuration) is detected on that GPIO,
-the interrupt service routine is executed and hence an I/O event is fired, which
-can be catched by any thread in the system.
+mask set (like the _gpioCallback() function in 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 fired, which can be catched by any thread in the system.
 
 Next, you have to configure the main thread to whitelist the event flag (all I/O
 events are blacklisted by default). While system relevant events like power down
-are whitelisted by the OS, any custom events need to be added exl´plicitely.
-This is done via the optional AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK macro,
-which should be defined in the module.h file. Example:
+are imlicitely whitelisted by the OS, any custom events need to be added
+exlplicitely. This is done via the optional
+AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK macro, which should be defined in the
+module.h file. Example:
 
   #define AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK         \
     (AOS_GPIOEVENT_FLAG(padX) | AOS_GPIOEVENT_FLAG(padY) | AOS_GPIOEVENT_FLAG(padZ))
@@ -309,11 +314,12 @@ which should be defined in the module.h file. Example:
 When AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK has been defined correctly, the
 main thread will be notified by the according events and execute its event
 handling routine. Hence you have to implement another macro in module.h to
-handle the custom event(s) appropriately: MODULE_MAIN_LOOP_GPIOEVENT(eventflags).
-As you can see, the variable 'eventflags' is propagated to the hook. This
-variable is a mask, that allows to identify the GPIO pad(s), which caused the
-event, by the bits set. Following the example above, you can check which GPIOs
-have caused events by using if-clauses in the implementation of the hook:
+handle the custom event(s) appropriately:
+MODULE_MAIN_LOOP_GPIOEVENT(eventflags). As you can see, the variable
+'eventflags' is propagated to the hook. This variable is a mask, that allows to
+identify the GPIO pad(s), which caused the event, by the individually set bits.
+Following the example above, you can check which GPIOs have caused events by
+using if-clauses in the implementation of the hook:
 
   #define MODULE_MAIN_LOOP_GPIOEVENT(eventflags) {          \
     if (eventflags & AOS_GPIOEVENT_FLAG(padX)) {            \
@@ -337,92 +343,68 @@ Summing up, you have to
 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 have to implement it, providing a
-(single) header file in periphery-lld/AMiRo-LLD/include/ and the required C
-sources in periphery-lld/AMiRo-LLD/source/. By convention, all filenames use the
-prefix 'alld_' to avoid ambiguities. Furthermore, files should be named by the
-exact designation of the hardware (e.g. 'alld_vcnl4020' instead of
-'alld_proximitysensor'). Since AMiRo-LLD is intended to be usable with other
-operating systems than AMiRo-OS, it provides an interface for accessing
-communication interfaces and basic functionalities of the operating system. On
-the one hand, several types are defined in periphery-lld/AMiRo-LLD/periphALtypes.h.
-The interface functions, on the other hand, are defined by AMiRo-LLD (cf.
-periphery-lld/AMiRo-LLD/templates/periphAL.h), but implemented by the operating
-system (cf. periphery-lld/periphAL.h). For the implementation of the driver, you
-must only use those types and functions to interact with the operating system.
-If you need further functionality, which is not provided by the interface yet,
-you are encouraged to extend periphAL.
-
-Furthermore, all files must define a guard, so that the whole driver is
-disabled, when the guard is not set explicitely. These guard again are named
-following a convention, but instead of explaning it here, just have a look at
-one of the existing drivers and look for lines like
-
-  #if defined(AMIROLLD_CFG_USE_VCNL4020) || defined(__DOXYGEN__)
-
-With these guards in place, the driver will be omitted by default and needs to
-be enabled explicitely. In order to do so, you need to add an according #define
-in the alldconf.h file of any module, which shall use the new driver.
-
-Now the new driver is available and enabled, but not actually used yet.
-Therefore you have to add according memory structures to the module.h and
+low-level driver to the framework, you have to implement it, following the
+instructions given in periphery-lld/AMiRo-LLD/README.txt
+
+Now the new driver is available and can be enbled by simply including the
+driver's makefile script in the module makefile. 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. I²C). Once again, you should
 take a look at existing modules and search the module.h for the hooks
-MODULE_INIT_INTERRUPTS() and MODULE_INIT_PERIPHERY_COMM().
+MODULE_INIT_INTERRUPTS(), MODULE_INIT_PERIPHERY_IF and
+MODULE_SHUTDOWN_PERIPHERY_IF().
 
-Finally, you will probably want to validate your implementation via a unit test.
-How this can be done is explained in detail in the next guide.
+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.
 
 Summing up, you have to
 1) implement the driver in AMiRo-LLD using periphAL only.
-2) fence all code in all files by a guard.
-3) set the guard in alldconf.h to enable the driver.
-4) add the driver to a module.
+4) add the driver to a module (Makefile, module.h and module.c).
 5) configure interrupts and interfaces as required.
-6) write a unit test.
+6) write a test.
 
 
-4.4  Writing a Unit Test
+4.4  Writing a Test
 ------------------------
 
-AMiRo-OS provides a unit test framework for conventient testing and the ability
-to opt-out all unit tests via the aosconf.h configuration file. There is also a
-dedicated folder, where all unit test code belongs to. In case you want to
-implement a unit test for a newly developed low-level driver, you should use the
-folders unittests/periphery-lld/inc and unittests/periphery-lld/src
-respectively. As with the low-level drivers, unit test files should use a prefix
-in their name, namely 'ut_' and all code should be fenced via guards that
-disable it by default (have a look at existing unit tests). Before you implement
-a vast test, however, it is highly recommended to start with some sceleton code
-(just copy an existing unit test, scoop out the test function, and rename
-according variables etc.) and make it compile and run.
-
-After you have initialized the unit test sceleton, you have to add the according
-aos_unittest_t (cf. core/inc/aos_unittest.h) object to the module.h and module.c
-files. These objects again require an shell command, so the unit test can be run
-via the AMiRo-OS shell. As with existing unit tests, this shell command callback
-function as well as any further required data should be implemented directly in
-module.c, so it not accessable from any other context. In most cases this
-callback function is trivial, anyway.
-
-In order to make the shell command, which executes the unit test, available in
-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 I recommend to have a look at an
-existing module, how to use this hook.
-
-Since the execution pipeline is set up now, you can fille your unit test with
-life. Remember that the test is executed by the shell thread, so you can access
-any functionality of the system, but might encounter race conditions, depending
-on what other applications run concurrently.
+AMiRo-OS provides a test framework for conventient testing and the ability to
+opt-out all tests via the aosconf.h configuration file. There is also a
+dedicated folder, where all test code belongs to. In case you want to implement
+a test for a newly developed low-level driver, you should have a look at the
+folder test/periphery-lld/. As with the low-level drivers, tests are placed in
+individual subfolders (e.g. test/periphery-lld/DEVICE1234_v1) and all should use
+the prefix 'aos_test_' in their name. Moreover, all code must be fenced by
+guards that disable it completely if the AMIROOS_CFG_TESTS_ENABLE flag is set to
+false in the aosconf.h configuration file.
+
+Now you will need to add the test to a specific module. Therefore, you should
+create a new test/ directory in the module folder, if such does not exist yet.
+In this directory, you create another subfolder, e.g. DEVICE1234/ and three
+additional files in there:
+ - module_test_DEVICE1234.mk
+ - 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 .h and .c files furthermore define module
+specific data structures and a test function.
+
+In order to be able to call this 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 shell command, which
+executes the test, 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 I
+recommend to have a look at an existing module, how to use this hook.
 
 Summing up, you have to
-1) initialize a unit test sceleton in the unittests/ folder.
-2) introduce an according object and configuration in module.h and module.c.
+1) implement the test in the test/ folder.
+2) implement a module specific wrapper in the module/test/ folder.
 3) associate the shell command to a shell via the hook in module.h.
-4) implement the full unit test in the prevously created sceleton files.
 
 ================================================================================
 
