Statistics
| Branch: | Tag: | Revision:

amiro-lld / README.txt @ 119ec0d2

History | View | Annotate | Download (9.43 KB)

1 d6728c5b Thomas Schöpping
AMiRo-LLD is a compilation of low-level hardware drivers for the base version of
2
the Autonomous Mini Robot (AMiRo) [1]. It provides directional interfaces for an
3
operating system to access the drivers and for the drivers to access the
4
communication infrastructure via the operating system.
5
6 f125ae07 Thomas Schöpping
Copyright (C) 2016..2019  Thomas Schöpping et al.
7 d6728c5b Thomas Schöpping
(a complete list of all authors is given below)
8
9
This program is free software: you can redistribute it and/or modify
10 f0ca400f Thomas Schöpping
it under the terms of the GNU Lesser General Public License as published by
11 d6728c5b Thomas Schöpping
the Free Software Foundation, either version 3 of the License, or (at
12
your option) any later version.
13
14
This program is distributed in the hope that it will be useful, but
15
WITHOUT ANY WARRANTY; without even the implied warranty of
16
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 f0ca400f Thomas Schöpping
Lesser General Public License for more details.
18 d6728c5b Thomas Schöpping
19 f0ca400f Thomas Schöpping
You should have received a copy of the GNU Lesser General Public License
20 d6728c5b Thomas Schöpping
along with this program.  If not, see <http://www.gnu.org/licenses/>.
21
22
This research/work was supported by the Cluster of Excellence
23
Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld
24
University, which is funded by the German Research Foundation (DFG).
25
26
Authors:
27
 - Thomas Schöpping          <tschoepp[at]cit-ec.uni-bielefeld.de>
28
 - Marc Rothmann
29
30
References:
31
 [1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A
32
     modular & customizable open-source mini robot platform," 2016 20th
33
     International Conference on System Theory, Control and Computing (ICSTCC),
34
     Sinaia, 2016, pp. 687-692.
35
36
37
38
################################################################################
39
#                                                                              #
40
#        RRRRRRRR   EEEEEEEE     AAA     DDDDDDDD   MM     MM  EEEEEEEE        #
41
#        RR     RR  EE          AA AA    DD     DD  MMM   MMM  EE              #
42
#        RR     RR  EE         AA   AA   DD     DD  MMMM MMMM  EE              #
43
#        RRRRRRRR   EEEEEE    AA     AA  DD     DD  MM MMM MM  EEEEEE          #
44
#        RR   RR    EE        AAAAAAAAA  DD     DD  MM     MM  EE              #
45
#        RR    RR   EE        AA     AA  DD     DD  MM     MM  EE              #
46
#        RR     RR  EEEEEEEE  AA     AA  DDDDDDDD   MM     MM  EEEEEEEE        #
47
#                                                                              #
48
################################################################################
49
50 de56f814 Thomas Schöpping
This file provides information about the purpose of this project, the file
51
structure and some helpful guides for development of code.
52
53
================================================================================
54
55
CONTENTS:
56
57
  1  About the Project
58
  2  File Structure
59
  3  Developer Guides
60
    3.1  Adding a Device
61
    3.2  Implementing a Driver
62
63
================================================================================
64
65
66
67
1 - ABOUT THE PROJECT
68
=====================
69
70 d6728c5b Thomas Schöpping
AMiRo-LLD is a compilation of low-level hardware drivers, originally developed
71
for the Autonomous Mini Robot (AMiRo) [1]. It provides a modular design, so that
72 bb46c559 Thomas Schöpping
each driver can be activated individually as required. Interface functions allow
73
for bidirectional comunication with an operating system. On the one hand drivers
74
access according hardware interfaces via defined interface functions (which need
75
to be implemented by the operating system) and any applications (or the
76
operating system itself) can take advantage of the drivers by their individual
77
interfaces. The abstraction layer of the hardware interfaces is called
78 de56f814 Thomas Schöpping
"periphAL", which is defined by this project. In order to configure which
79
drivers should be used in which version, the project expects an according file
80
"alldconf.h" to be found in the include paths.
81 d6728c5b Thomas Schöpping
82
Although this compilation was originally designed to be used in combination with
83
the AMiRo operating system (AMiRo-OS; cf. https://opensource.cit-ec.de/projects/amiro-os/),
84
it is not limited to this use case. The included drivers may be used for any
85
purpose and contributions of further drivers, even if the according hardware is
86
not present on the AMiRo platform, are highly appreciated.
87
88 de56f814 Thomas Schöpping
89
90
2 - FILE STRUCTURE
91
==================
92
93 d6728c5b Thomas Schöpping
The files are structured as follows:
94 bb46c559 Thomas Schöpping
./
95
│ The project root directory contains this file, a license.html file as well as
96
│ a Makefile that allows to easily integrate the project. Furthermore, two
97
│ interface headers are provided: amiro-lld.h and periphALtypes.h. These are
98
│ entry points for any utilizing superproject, so it is not required (and not
99
│ recommended) to include each driver individually.
100
101
├── include/
102 de56f814 Thomas Schöpping
│     For each supported hardware device, there is exactly one directory in this
103
│     folder. Further subfolders may contain various versions of a driver (e.g.
104
│     'v1/', 'v2/', etc.). By convention the root directory of a driver is named
105
│     by the form
106
│     "<product_name>/"
107 bb46c559 Thomas Schöpping
│     <product_name> is a placeholder for the exact name of the according
108
│     hardware, or the product familiy, if the driver is compatible with all
109
│     parts.
110 de56f814 Thomas Schöpping
│     The root header consequently follows the naming scheme
111
│     "alld_<product_name>.h"
112
│     and header files within the version folders shall be named like
113
│     "alld<product_name>_<driver_version>.h"
114 bb46c559 Thomas Schöpping
115
├── source/
116 de56f814 Thomas Schöpping
│     Any source files are placed in this directory. Naming conventions for
117
│     folders and files are the same as described before for the include
118
│     directory, as is the file structure. There is a dedicated folder for each
119
│     device and further subfolders for multiple driver versions. Source files
120
│     should only be put in these version folders.
121 bb46c559 Thomas Schöpping
122
└── templates/
123
      AMiRo-LLD requires an implementation of the defined interface and an
124
      configuration header to be accessible in the include paths at compile
125
      time. Template files for both can be found in this folder. It is
126
      recommended to place according implementations of these templated not in
127
      the AMiRo-LLD project, but the superproject which includes AMiRo-LLD.
128 d6728c5b Thomas Schöpping
129 de56f814 Thomas Schöpping
130
131
3 - DEVELOPER GUIDES
132
====================
133
134
In order to keep all code within this project as homogeneous as possible, the
135
guides of these chapters should help developers to achieve functional and clean
136
results, which are portable and maintainable for future use. Whereas the textual
137
descriptions of the guides provide additional information about the underlying
138
concepts and mechanisms, a short summary is provided at the end of each chapter.
139
140
3.1  Adding a Device
141
--------------------
142
143
When adding new device to the project, the very first step is to create the
144
according folders in the include/ and source/ directories. For this guide, we
145
will add the fictional DEVICE1234. For this example the folders to be created
146
are "include/DEVICE1234/" and "source/DEVICE1234/".
147
148
The first file should be the root header: "include/DEVICE1234/alld_DEVICE1234.h"
149
Have a look at existing drivers and use one of those as template. This header
150
should introduce a new configuration to be set in the alldconf.h file and check
151
it using the preprocessor. Eventually, another header is included, pointing to
152
the selected driver version/implementation.
153
154
Such implementations are to be put in further subfolders, e.g.
155
"include/DEVICE1234/v1/" and "source/DEVICE1234/v1/". The header and C-source
156
files in those folders do not follow a strict scheme, although there are some
157
conventions to consider (i.e. naming conventions, cf. chapter 2).
158
159
Summing up, you have to
160
1) create device folders.
161
2) add a root header.
162
3) add further subfolders and implement the driver there.
163
164
165
3.2  Implementing a Driver
166
--------------------------
167
168
Implementation of a new driver usually is very straight-forward. You most
169
probably have a comprehensive datasheet of the device, or the manufacturer even
170
provides a reference driver implementation.
171
172
For the former case, you should first write a comprehensive header, containing
173
all information like constants, register maps, etc. and according abstract
174
access functions (e.g. for reading and writing registers, and convenient access
175
to common functionalities). Only the you implement those functions, using
176
periphAL to interface any hardware interfaces (e.g. I2C, SPI, etc.).
177
178
For the latter case, the reference implementation will specify some interface
179
functions to interact with the hardware (e.g. I2C, SPI etc.). Even though all
180
functionality should be covered by the reference driver, you still need to
181
implement those interface functions.
182
183
Since AMiRo-LLD does not rely on specific hardware or operating system, the only
184
valid way to interact with both is through periphAL. Under no circumstances you
185
must use any function of your operating system and directly or indirectly access
186
the hardware of your platform. For your driver, there is no knowledge about the
187
world beyond periphAL! If periphAL does not provide the function you need, you
188
can do the following: 1) Think again if you really need that funcionality or
189
whether it can be replicated by existing functions. 2) File a feature request
190
to extend periphAL. 3) Write a custom patch that modifies periphAL to meet your
191
requirements.
192
193
Summing up, you have to
194
1) Get and read the datasheet of the device (A) or
195
   acquire a copy of the reference implementation (B).
196
2) Case A: define constants, register map and access functions in a header file.
197
   Case B: identify the interface functions of the reference implementation.
198
3) Implement the missing functions using periphAL.
199
200 d6728c5b Thomas Schöpping
================================================================================