amiro-lld / README.md @ master
History | View | Annotate | Download (8.52 KB)
1 | 99ca7610 | Thomas Schöpping | About & License |
---|---|---|---|
2 | =============== |
||
3 | |||
4 | AMiRo-LLD is a compilation of low-level hardware drivers for the base version of |
||
5 | the Autonomous Mini Robot (AMiRo) [1]. It provides directional interfaces for an |
||
6 | operating system to access the drivers and for the drivers to access the |
||
7 | communication infrastructure via the operating system. |
||
8 | |||
9 | Copyright (C) 2016..2020 Thomas Schöpping et al. |
||
10 | (a complete list of all authors is given below) |
||
11 | |||
12 | This program is free software: you can redistribute it and/or modify |
||
13 | it under the terms of the GNU Lesser General Public License as published by |
||
14 | the Free Software Foundation, either version 3 of the License, or (at |
||
15 | your option) any later version. |
||
16 | |||
17 | This program is distributed in the hope that it will be useful, but |
||
18 | WITHOUT ANY WARRANTY; without even the implied warranty of |
||
19 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
||
20 | Lesser General Public License for more details. |
||
21 | |||
22 | You should have received a copy of the GNU Lesser General Public License |
||
23 | along with this program. If not, see <http://www.gnu.org/licenses/>. |
||
24 | |||
25 | This research/work was supported by the Cluster of Excellence |
||
26 | Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld |
||
27 | University, which is funded by the German Research Foundation (DFG). |
||
28 | |||
29 | Authors: |
||
30 | |||
31 | - Thomas Schöpping (tschoepp@cit-ec.uni-bielefeld.de) |
||
32 | - Marc Rothmann |
||
33 | |||
34 | References: |
||
35 | |||
36 | [1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A |
||
37 | modular & customizable open-source mini robot platform," 2016 20th |
||
38 | International Conference on System Theory, Control and Computing (ICSTCC), |
||
39 | Sinaia, 2016, pp. 687-692. |
||
40 | |||
41 | -------------------------------------------------------------------------------- |
||
42 | |||
43 | Contents |
||
44 | ======== |
||
45 | |||
46 | 1. About the Project |
||
47 | 2. File Structure |
||
48 | 3. Developer Guides |
||
49 | 1. Adding a Device |
||
50 | 2. Implementing a Driver |
||
51 | |||
52 | -------------------------------------------------------------------------------- |
||
53 | |||
54 | 1 About the Project |
||
55 | =================== |
||
56 | |||
57 | AMiRo-LLD is a compilation of low-level hardware drivers, originally developed |
||
58 | for the Autonomous Mini Robot (AMiRo) [1]. It provides a modular design, so that |
||
59 | 14c96f7f | Thomas Schöpping | each driver can be used and configured individually as required. Interface |
60 | 99ca7610 | Thomas Schöpping | functions allow for bidirectional comunication with an operating system. On the |
61 | one hand drivers access according hardware interfaces via defined interface |
||
62 | functions (which need to be implemented by the operating system), on the other |
||
63 | hand any applications (or the operating system itself) can take advantage of the |
||
64 | drivers by their individual interfaces. The abstraction layer of the hardware |
||
65 | interfaces is called "periphAL", which is defined by this project. In order to |
||
66 | further configure individual drivers, the project expects an according file |
||
67 | "alldconf.h" to be found in the include paths when compiling the drivers. |
||
68 | |||
69 | Although this compilation was originally designed to be used in combination with |
||
70 | the AMiRo operating system (AMiRo-OS; cf. |
||
71 | https://opensource.cit-ec.de/projects/amiro-os/), it is not limited to this use |
||
72 | case. The included drivers may be used for any purpose and contributions of |
||
73 | further drivers, even if the according hardware is not present on the AMiRo |
||
74 | platform, are highly appreciated. |
||
75 | |||
76 | 2 File Structure |
||
77 | ================ |
||
78 | |||
79 | The files are structured as follows: |
||
80 | |||
81 | * `./` |
||
82 | The project root directory contains this file, a `license.html` file as well |
||
83 | 14c96f7f | Thomas Schöpping | as a make script `amiro-lld.mk` that allows to easily integrate the project. |
84 | Furthermore, two interface headers are provided: `amiro-lld.h` and |
||
85 | `periphAL.h`. |
||
86 | 99ca7610 | Thomas Schöpping | * `./docs/` |
87 | UML graphs (using PlantUML; see <https://plantuml.com> for further |
||
88 | information) visualize the structure of the AMiRo-LLD project. Doxygen |
||
89 | related files can be used to gererate a documentation of the whole |
||
90 | project (wip). |
||
91 | * `./drivers/` |
||
92 | For each supported hardware device, there is exactly one directory in |
||
93 | this folder. Further subfolders contain various versions of a driver |
||
94 | (e.g. `v1/`, `v2/`, etc.). By convention, the root directory of a driver |
||
95 | is named by the exact product name of the according hardware, or the |
||
96 | product familiy, if the driver is compatible with all parts. Each driver |
||
97 | 14c96f7f | Thomas Schöpping | must provide a make script, which adds the required include paths to the |
98 | `AMIROLLD_INC` variable and all C source files to the `AMIROLLD_CSRC` |
||
99 | variable. |
||
100 | 99ca7610 | Thomas Schöpping | * `./templates/` |
101 | 14c96f7f | Thomas Schöpping | AMiRo-LLD expects a configuration header file "alldconf.h" to be found |
102 | in the include paths. An according template for such a file can be found |
||
103 | here. There is no template for an implementation of periphAL, though. |
||
104 | The interface header in the root directory (`./periphAL.h`) provides all |
||
105 | 99ca7610 | Thomas Schöpping | required information for an implementation. |
106 | |||
107 | |||
108 | |||
109 | 3 Developer Guides |
||
110 | ================== |
||
111 | |||
112 | In order to keep all code within this project as homogeneous as possible, the |
||
113 | guides in this chapter should help developers to achieve functional and clean |
||
114 | results, which are portable and maintainable for future use. Whereas the textual |
||
115 | descriptions of the guides provide in-depth information about the underlying |
||
116 | concepts and mechanisms, a short summary is provided at the end of each chapter. |
||
117 | |||
118 | |||
119 | 3.1 Adding a Device |
||
120 | ------------------- |
||
121 | |||
122 | When adding a new device to the project, the very first step is to create the |
||
123 | according folder in the `./drivers/` directory. For this guide, we will add the |
||
124 | 14c96f7f | Thomas Schöpping | fictional device "DEVICE1234". The folders to be created in this case are hence |
125 | 99ca7610 | Thomas Schöpping | `./drivers/DEVICE1234/` and `./drivers/DEVICE1234/v1/`. In case there already |
126 | exists a driver implementation for this device, but you want to implement |
||
127 | another version, the version subfolder must be named accordingly (e.g. |
||
128 | `./drivers/DEVICE1234/v2/`). |
||
129 | |||
130 | Most drivers will consist of exactly three files: |
||
131 | |||
132 | * alld_DEVICE1234.mk |
||
133 | * alld_DEVICE1234.h |
||
134 | * alld_DEVICE1234.c |
||
135 | |||
136 | Some drivers, however, may feature multiple header and/or source files or even |
||
137 | come with additional subfolders. In any case, all those required folders, |
||
138 | 14c96f7f | Thomas Schöpping | including the driver root folder (i.e. `./drivers/DEVICE1234/v1/`) as well as |
139 | all source files must be added to the according variables `AMIROLLD_INC` and |
||
140 | `AMIROLLD_CSRC` by the make script. |
||
141 | 99ca7610 | Thomas Schöpping | It is highly recommended that files in the driver root directory (i.e. |
142 | `./drivers/DEVICE1234/v1/`) use the prefix `alld_` in their names. This not only |
||
143 | helps to achieve an easy to understand file structure, but also prevents |
||
144 | compilation issues due to naming conflicts of header files. |
||
145 | |||
146 | **Summing up, you have to** |
||
147 | |||
148 | 1. create device and version folders. |
||
149 | 14c96f7f | Thomas Schöpping | 2. add a make script. |
150 | 99ca7610 | Thomas Schöpping | 3. add header and source files as well as subfulders, implementing the driver. |
151 | |||
152 | |||
153 | 3.2 Implementing a Driver |
||
154 | ------------------------- |
||
155 | |||
156 | Implementation of a new driver usually is very straightforward. You will most |
||
157 | probably start with a comprehensive datasheet of the device, or the manufacturer |
||
158 | even provides a reference driver implementation. |
||
159 | |||
160 | For the former case, you should first write a comprehensive header, containing |
||
161 | all information like constants, register maps, etc. and according abstract |
||
162 | access functions (e.g. for reading and writing registers, and convenient access |
||
163 | to common functionalities). Only then you implement those functions, using |
||
164 | periphAL to interface any hardware interfaces (e.g. I2C, SPI, etc.) in a |
||
165 | separate C source file, or 'inline' in the header file itself. |
||
166 | For the latter case, the reference implementation will specify some interface |
||
167 | functions to interact with the hardware (e.g. I2C, SPI etc.). Even though all |
||
168 | functionality should be covered by the reference driver, you still need to |
||
169 | implement those interface functions and map them to periphAL. |
||
170 | |||
171 | Since AMiRo-LLD does not rely on specific hardware or operating system, the only |
||
172 | valid way to interact with both is through periphAL. Under no circumstances you |
||
173 | must use any function of your operating system directly to interact with the |
||
174 | hardware or the operating system! For your driver, there is no knowledge about |
||
175 | the world beyond periphAL. If periphAL does not provide the functionality you |
||
176 | need, you should do the following: |
||
177 | |||
178 | 1. Think again if you really need that funcionality or whether it can be |
||
179 | replicated by the existing API. |
||
180 | 2. File a feature request to extend periphAL. |
||
181 | 3. Write a custom patch that modifies periphAL to meet your requirements. |
||
182 | |||
183 | **Summing up, you have to** |
||
184 | |||
185 | 1. Get and read the datasheet of the device (A) |
||
186 | or acquire a copy of the reference implementation (B). |
||
187 | 2. Case A: Define constants, register map and access functions in a header |
||
188 | file. |
||
189 | Case B: Identify the interface functions of the reference implementation. |
||
190 | 3. Implement all required functions using periphAL. |