commit 99ca7610753617020954f4c3abcf72c7ecf63f6a
Author: Thomas Schöpping <tschoepp@cit-ec.uni-bielefeld.de>
Date:   Tue Mar 3 16:27:26 2020 +0100

    README updated and converted to Markdown

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9040198
--- /dev/null
+++ b/README.md
@@ -0,0 +1,190 @@
+About & License
+===============
+
+AMiRo-LLD is a compilation of low-level hardware drivers for the base version of
+the Autonomous Mini Robot (AMiRo) [1]. It provides directional interfaces for an
+operating system to access the drivers and for the drivers to access the
+communication infrastructure via the operating system.
+
+Copyright (C) 2016..2020  Thomas Schöpping et al.
+(a complete list of all authors is given below)
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or (at
+your option) any later version.
+
+This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+This research/work was supported by the Cluster of Excellence
+Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld
+University, which is funded by the German Research Foundation (DFG).
+
+Authors:
+
+-   Thomas Schöpping (tschoepp@cit-ec.uni-bielefeld.de)
+-   Marc Rothmann
+
+References:
+
+[1]  S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A
+     modular & customizable open-source mini robot platform," 2016 20th
+     International Conference on System Theory, Control and Computing (ICSTCC),
+     Sinaia, 2016, pp. 687-692.
+
+--------------------------------------------------------------------------------
+
+Contents
+========
+
+1.  About the Project
+2.  File Structure
+3.  Developer Guides
+    1.  Adding a Device
+    2.  Implementing a Driver
+
+--------------------------------------------------------------------------------
+
+1 About the Project
+===================
+
+AMiRo-LLD is a compilation of low-level hardware drivers, originally developed
+for the Autonomous Mini Robot (AMiRo) [1]. It provides a modular design, so that
+each driver can be unsed and configured individually as required. Interface
+functions allow for bidirectional comunication with an operating system. On the
+one hand drivers access according hardware interfaces via defined interface
+functions (which need to be implemented by the operating system), on the other
+hand any applications (or the operating system itself) can take advantage of the
+drivers by their individual interfaces. The abstraction layer of the hardware
+interfaces is called "periphAL", which is defined by this project. In order to
+further configure individual drivers, the project expects an according file
+"alldconf.h" to be found in the include paths when compiling the drivers.
+
+Although this compilation was originally designed to be used in combination with
+the AMiRo operating system (AMiRo-OS; cf.
+https://opensource.cit-ec.de/projects/amiro-os/), it is not limited to this use
+case. The included drivers may be used for any purpose and contributions of
+further drivers, even if the according hardware is not present on the AMiRo
+platform, are highly appreciated.
+
+2 File Structure
+================
+
+The files are structured as follows:
+
+*   `./`  
+    The project root directory contains this file, a `license.html` file as well
+    as a makefile `amiro-lld.mk` that allows to easily integrate the project.
+    Furthermore, two interface headers are provided: amiro-lld.h and periphALh.
+    *   `./docs/`  
+        UML graphs (using PlantUML; see <https://plantuml.com> for further
+        information) visualize the structure of the AMiRo-LLD project. Doxygen
+        related files can be used to gererate a documentation of the whole
+        project (wip).
+    *   `./drivers/`  
+        For each supported hardware device, there is exactly one directory in
+        this folder. Further subfolders contain various versions of a driver
+        (e.g. `v1/`, `v2/`, etc.). By convention, the root directory of a driver
+        is named by the exact product name of the according hardware, or the
+        product familiy, if the driver is compatible with all parts. Each driver
+        must provide a makefile script, which adds the required include paths to
+        the `AMIROLLD_INC` variable and all C source files to the
+        `AMIROLLD_CSRC` variable.
+    *   `./templates/`  
+        AMiRo-LLD expects a configuration header file "alldconf.h" to be found in
+        the include paths. An according template for such file can be found here.
+        There is no template for an implementation of periphAL, though. The
+        interface header in the root directory (`./periphAL.h`) provides all
+        required information for an implementation.
+
+
+
+3 Developer Guides
+==================
+
+In order to keep all code within this project as homogeneous as possible, the
+guides in this chapter should help developers to achieve functional and clean
+results, which are portable and maintainable for future use. Whereas the textual
+descriptions of the guides provide in-depth information about the underlying
+concepts and mechanisms, a short summary is provided at the end of each chapter.
+
+
+3.1 Adding a Device
+-------------------
+
+When adding a new device to the project, the very first step is to create the
+according folder in the `./drivers/` directory. For this guide, we will add the
+fictional device `DEVICE1234`. The folders to be created in this case are hence
+`./drivers/DEVICE1234/` and `./drivers/DEVICE1234/v1/`. In case there already
+exists a driver implementation for this device, but you want to implement
+another version, the version subfolder must be named accordingly (e.g.
+`./drivers/DEVICE1234/v2/`).
+
+Most drivers will consist of exactly three files:
+
+*   alld_DEVICE1234.mk
+*   alld_DEVICE1234.h
+*   alld_DEVICE1234.c
+
+Some drivers, however, may feature multiple header and/or source files or even
+come with additional subfolders. In any case, all those required folders,
+including the driver root folder (i.e. `./drivers/DEVICE1234/v1/`), as well as
+all source files must be added to the according makefile variables
+`AMIROLLD_INC` and `AMIROLLD_CSRC` by the makefile script.  
+It is highly recommended that files in the driver root directory (i.e.
+`./drivers/DEVICE1234/v1/`) use the prefix `alld_` in their names. This not only
+helps to achieve an easy to understand file structure, but also prevents
+compilation issues due to naming conflicts of header files.
+
+**Summing up, you have to**
+
+1.  create device and version folders.
+2.  add a makefile script.
+3.  add header and source files as well as subfulders, implementing the driver.
+
+
+3.2 Implementing a Driver
+-------------------------
+
+Implementation of a new driver usually is very straightforward. You will most
+probably start with a comprehensive datasheet of the device, or the manufacturer
+even provides a reference driver implementation.
+
+For the former case, you should first write a comprehensive header, containing
+all information like constants, register maps, etc. and according abstract
+access functions (e.g. for reading and writing registers, and convenient access
+to common functionalities). Only then you implement those functions, using
+periphAL to interface any hardware interfaces (e.g. I2C, SPI, etc.) in a
+separate C source file, or 'inline' in the header file itself.  
+For the latter case, the reference implementation will specify some interface
+functions to interact with the hardware (e.g. I2C, SPI etc.). Even though all
+functionality should be covered by the reference driver, you still need to
+implement those interface functions and map them to periphAL.
+
+Since AMiRo-LLD does not rely on specific hardware or operating system, the only
+valid way to interact with both is through periphAL. Under no circumstances you
+must use any function of your operating system directly to interact with the
+hardware or the operating system! For your driver, there is no knowledge about
+the world beyond periphAL. If periphAL does not provide the functionality you
+need, you should do the following:
+
+1.  Think again if you really need that funcionality or whether it can be
+    replicated by the existing API.
+2.  File a feature request to extend periphAL.
+3.  Write a custom patch that modifies periphAL to meet your requirements.
+
+**Summing up, you have to**
+
+1.  Get and read the datasheet of the device (A)  
+    or acquire a copy of the reference implementation (B).
+2.  Case A: Define constants, register map and access functions in a header
+    file.  
+    Case B: Identify the interface functions of the reference implementation.
+3.  Implement all required functions using periphAL.
+
diff --git a/README.txt b/README.txt
deleted file mode 100644
index 1af7762..0000000
--- a/README.txt
+++ /dev/null
@@ -1,207 +0,0 @@
-AMiRo-LLD is a compilation of low-level hardware drivers for the base version of
-the Autonomous Mini Robot (AMiRo) [1]. It provides directional interfaces for an
-operating system to access the drivers and for the drivers to access the
-communication infrastructure via the operating system.
-
-Copyright (C) 2016..2020  Thomas Schöpping et al.
-(a complete list of all authors is given below)
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Lesser General Public License as published by
-the Free Software Foundation, either version 3 of the License, or (at
-your option) any later version.
-
-This program is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-Lesser General Public License for more details.
-
-You should have received a copy of the GNU Lesser General Public License
-along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-This research/work was supported by the Cluster of Excellence
-Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld
-University, which is funded by the German Research Foundation (DFG).
-
-Authors:
- - Thomas Schöpping          <tschoepp[at]cit-ec.uni-bielefeld.de>
- - Marc Rothmann
-
-References:
- [1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A
-     modular & customizable open-source mini robot platform," 2016 20th
-     International Conference on System Theory, Control and Computing (ICSTCC),
-     Sinaia, 2016, pp. 687-692.
-
-
-
-################################################################################
-#                                                                              #
-#        RRRRRRRR   EEEEEEEE     AAA     DDDDDDDD   MM     MM  EEEEEEEE        #
-#        RR     RR  EE          AA AA    DD     DD  MMM   MMM  EE              #
-#        RR     RR  EE         AA   AA   DD     DD  MMMM MMMM  EE              #
-#        RRRRRRRR   EEEEEE    AA     AA  DD     DD  MM MMM MM  EEEEEE          #
-#        RR   RR    EE        AAAAAAAAA  DD     DD  MM     MM  EE              #
-#        RR    RR   EE        AA     AA  DD     DD  MM     MM  EE              #
-#        RR     RR  EEEEEEEE  AA     AA  DDDDDDDD   MM     MM  EEEEEEEE        #
-#                                                                              #
-################################################################################
-
-This file provides information about the purpose of this project, the file
-structure and some helpful guides for development of code.
-
-================================================================================
-
-CONTENTS:
-
-  1  About the Project
-  2  File Structure
-  3  Developer Guides
-    3.1  Adding a Device
-    3.2  Implementing a Driver
-
-================================================================================
-
-
-
-1 - ABOUT THE PROJECT
-=====================
-
-AMiRo-LLD is a compilation of low-level hardware drivers, originally developed
-for the Autonomous Mini Robot (AMiRo) [1]. It provides a modular design, so that
-each driver can be activated individually as required. Interface functions allow
-for bidirectional comunication with an operating system. On the one hand drivers
-access according hardware interfaces via defined interface functions (which need
-to be implemented by the operating system) and any applications (or the
-operating system itself) can take advantage of the drivers by their individual
-interfaces. The abstraction layer of the hardware interfaces is called
-"periphAL", which is defined by this project. In order to configure which
-drivers should be used in which version, the project expects an according file
-"alldconf.h" to be found in the include paths.
-
-Although this compilation was originally designed to be used in combination with
-the AMiRo operating system (AMiRo-OS; cf. https://opensource.cit-ec.de/projects/amiro-os/),
-it is not limited to this use case. The included drivers may be used for any
-purpose and contributions of further drivers, even if the according hardware is
-not present on the AMiRo platform, are highly appreciated.
-
-
-
-2 - FILE STRUCTURE
-==================
-
-The files are structured as follows:
-./
-│ The project root directory contains this file, a license.html file as well as
-│ a makefile that allows to easily integrate the project. Furthermore, two
-│ interface headers are provided: amiro-lld.h and periphALtypes.h. These are
-│ entry points for any utilizing superproject, so it is not required (and not
-│ recommended) to include each driver individually.
-│
-├── docs/
-│     UML graphs (using PlantUML; see plantuml.com for further information)
-│     visualize the structure of the AMiRo-LLD project. Doxygen related files
-│     can be used to gererate a documentation of the whole project (wip).
-│
-├── drivers/
-│     For each supported hardware device, there is exactly one directory in this
-│     folder. Further subfolders may contain various versions of a driver (e.g.
-│     'v1/', 'v2/', etc.). By convention the root directory of a driver is named
-│     by the form
-│     "<product_name>/"
-│     <product_name> is a placeholder for the exact name of the according
-│     hardware, or the product familiy, if the driver is compatible with all
-│     parts.
-│     Each driver must provide a makefile script, which adds the required
-│     include folders to the AMIROLLD_INC variable and all C source files to the
-│     AMIROLLD_CSRC variable.
-│
-└── templates/
-      AMiRo-LLD expects a configuration header "alldconf.h" to be found in the
-      include paths. An according template for such file can be found here.
-      There is no template for an implementation of periphAL, though. The
-      provided interface header in the root directory (periphAL.h) should give
-      you all required information for such an implementation anyway.
-
-
-
-3 - DEVELOPER GUIDES
-====================
-
-In order to keep all code within this project as homogeneous as possible, the
-guides of these chapters should help developers to achieve functional and clean
-results, which are portable and maintainable for future use. Whereas the textual
-descriptions of the guides provide additional information about the underlying
-concepts and mechanisms, a short summary is provided at the end of each chapter.
-
-
-3.1  Adding a Device
---------------------
-
-When adding new device to the project, the very first step is to create the
-according folder in the drivers/ directory. For this guide, we will add the
-fictional DEVICE1234. For this example the folders to be created are
-"drivers/DEVICE1234/" and "drivers/DEVICE1234/v1/". In case there already exists
-a driver implementation for this device, but you want to implement another
-version from scratch (not just an update), the version subfolder must be named
-accordingly (e.g. "drivers/DEVICE1234/v42/").
-
-Most drivers will consist of exactly three files:
- - alld_DEVICE1234.mk
- - alld_DEVICE1234.h
- - alld_DEVICE1234.c
-However, some drivers may feature multiple .h and/or .c files or even come with
-additional subfolders. In any case, all those required folders, including the
-driver root folder (i.e. "drivers/DEVICE1234/v1/"), as well as all C source
-files must be added to the according makefile variables AMIROLLD_INC and
-AMIROLLD_CSRC by the makefile script.
-It is highly recommended that files in the driver root directory (i.e.
-"drivers/DEVICE1234/v1/") use the prefix "alld_" in their names. This not only
-helps to achieve an easy to understand file structure, but also prevents
-compilation issues due to naming conflicts of header files.
-
-Summing up, you have to
-1) create device and version folders.
-2) add a makefile script.
-3) add header- and source files as well as subfulders, implementing the diver
-
-
-3.2  Implementing a Driver
---------------------------
-
-Implementation of a new driver usually is very straightforward. You most
-probably have a comprehensive datasheet of the device, or the manufacturer even
-provides a reference driver implementation.
-
-For the former case, you should first write a comprehensive header, containing
-all information like constants, register maps, etc. and according abstract
-access functions (e.g. for reading and writing registers, and convenient access
-to common functionalities). Only then you implement those functions, using
-periphAL to interface any hardware interfaces (e.g. I2C, SPI, etc.) in a
-separate C source file, or 'inline' in the header file itself.
-
-For the latter case, the reference implementation will specify some interface
-functions to interact with the hardware (e.g. I2C, SPI etc.). Even though all
-functionality should be covered by the reference driver, you still need to
-implement those interface functions and map them to periphAL.
-
-Since AMiRo-LLD does not rely on specific hardware or operating system, the only
-valid way to interact with both is through periphAL. Under no circumstances you
-must use any function of your operating system and directly or indirectly access
-the hardware of your platform. For your driver, there is no knowledge about the
-world beyond periphAL! If periphAL does not provide the function you need, you
-can do one of the following:
-1) Think again if you really need that funcionality or whether it can be
-   replicated by the existing API.
-2) File a feature request to extend periphAL.
-3) Write a custom patch that modifies periphAL to meet your requirements.
-
-Summing up, you have to
-1) Get and read the datasheet of the device (A) or
-   acquire a copy of the reference implementation (B).
-2) Case A: define constants, register map and access functions in a header file.
-   Case B: identify the interface functions of the reference implementation.
-3) Implement the missing functions using periphAL.
-
-================================================================================
-
