commit de56f8141cdd48e456d57bd732a29f005ca8bad4
Author: Thomas Schöpping <tschoepp@cit-ec.uni-bielefeld.de>
Date:   Mon Feb 11 11:32:13 2019 +0100

    Enhanced the README.txt file:
    - updated the description of the file structure
    - added two developer guides

diff --git a/README.txt b/README.txt
index 83715e8..f9cf003 100644
--- a/README.txt
+++ b/README.txt
@@ -47,6 +47,26 @@ References:
 #                                                                              #
 ################################################################################
 
+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
@@ -55,7 +75,9 @@ 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.
+"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/),
@@ -63,6 +85,11 @@ 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
@@ -72,18 +99,25 @@ The files are structured as follows:
 │ recommended) to include each driver individually.
 │
 ├── include/
-│     Each driver defines exactly one include header in this directory. By
-│     convention these files are named by the form
-│     alld_<product_name>.h
+│     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.
+│     The root header consequently follows the naming scheme
+│     "alld_<product_name>.h"
+│     and header files within the version folders shall be named like
+│     "alld<product_name>_<driver_version>.h"
 │
 ├── source/
-│     Any source files are placed in this directory. Usually there is a single
-│     file for each driver. If multiple files are necessary, these should be
-│     placed in an accordingly named subfolder. Names of folders and files
-│     should comply to the aforementioned convention.
+│     Any source files are placed in this directory. Naming conventions for
+│     folders and files are the same as described before for the include
+│     directory, as is the file structure. There is a dedicated folder for each
+│     device and further subfolders for multiple driver versions. Source files
+│     should only be put in these version folders.
 │
 └── templates/
       AMiRo-LLD requires an implementation of the defined interface and an
@@ -92,5 +126,76 @@ The files are structured as follows:
       recommended to place according implementations of these templated not in
       the AMiRo-LLD project, but the superproject which includes AMiRo-LLD.
 
+
+
+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 folders in the include/ and source/ directories. For this guide, we
+will add the fictional DEVICE1234. For this example the folders to be created
+are "include/DEVICE1234/" and "source/DEVICE1234/".
+
+The first file should be the root header: "include/DEVICE1234/alld_DEVICE1234.h"
+Have a look at existing drivers and use one of those as template. This header
+should introduce a new configuration to be set in the alldconf.h file and check
+it using the preprocessor. Eventually, another header is included, pointing to
+the selected driver version/implementation.
+
+Such implementations are to be put in further subfolders, e.g.
+"include/DEVICE1234/v1/" and "source/DEVICE1234/v1/". The header and C-source
+files in those folders do not follow a strict scheme, although there are some
+conventions to consider (i.e. naming conventions, cf. chapter 2).
+
+Summing up, you have to
+1) create device folders.
+2) add a root header.
+3) add further subfolders and implement the driver there.
+
+
+3.2  Implementing a Driver
+--------------------------
+
+Implementation of a new driver usually is very straight-forward. 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 the you implement those functions, using
+periphAL to interface any hardware interfaces (e.g. I2C, SPI, etc.).
+
+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.
+
+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 the following: 1) Think again if you really need that funcionality or
+whether it can be replicated by existing functions. 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.
+
 ================================================================================
 
