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..2019 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 . 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 - 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 │ "/" │ 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. ================================================================================