Statistics
| Branch: | Tag: | Revision:

amiro-os / README.txt @ d796dcdf

History | View | Annotate | Download (18.5 KB)

1
AMiRo-OS is an operating system for the base version of the Autonomous Mini
2
Robot (AMiRo) [1]. It utilizes ChibiOS (a real-time operating system for
3
embedded devices developed by Giovanni di Sirio; see <http://chibios.org>) as
4
system kernel and extends it with platform specific configurations and further
5
functionalities and abstractions.
6

    
7
Copyright (C) 2016..2019  Thomas Schöpping et al.
8
(a complete list of all authors is given below)
9

    
10
This program is free software: you can redistribute it and/or modify
11
it under the terms of the GNU General Public License as published by
12
the Free Software Foundation, either version 3 of the License, or (at
13
your option) any later version.
14

    
15
This program is distributed in the hope that it will be useful, but
16
WITHOUT ANY WARRANTY; without even the implied warranty of
17
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18
General Public License for more details.
19

    
20
You should have received a copy of the GNU General Public License
21
along with this program.  If not, see <http://www.gnu.org/licenses/>.
22

    
23
This research/work was supported by the Cluster of Excellence
24
Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld
25
University, which is funded by the German Research Foundation (DFG).
26

    
27
Authors:
28
 - Thomas Schöpping          <tschoepp[at]cit-ec.uni-bielefeld.de>
29
 - Marc Rothmann
30

    
31
References:
32
 [1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A
33
     modular & customizable open-source mini robot platform," 2016 20th
34
     International Conference on System Theory, Control and Computing (ICSTCC),
35
     Sinaia, 2016, pp. 687-692.
36

    
37

    
38

    
39
################################################################################
40
#                                                                              #
41
#        RRRRRRRR   EEEEEEEE     AAA     DDDDDDDD   MM     MM  EEEEEEEE        #
42
#        RR     RR  EE          AA AA    DD     DD  MMM   MMM  EE              #
43
#        RR     RR  EE         AA   AA   DD     DD  MMMM MMMM  EE              #
44
#        RRRRRRRR   EEEEEE    AA     AA  DD     DD  MM MMM MM  EEEEEE          #
45
#        RR   RR    EE        AAAAAAAAA  DD     DD  MM     MM  EE              #
46
#        RR    RR   EE        AA     AA  DD     DD  MM     MM  EE              #
47
#        RR     RR  EEEEEEEE  AA     AA  DDDDDDDD   MM     MM  EEEEEEEE        #
48
#                                                                              #
49
################################################################################
50

    
51
This file will help you to setup all required software on your system, compile
52
the source code, and flash it to the AMiRo modules.
53

    
54
================================================================================
55

    
56
CONTENTS:
57

    
58
  1  Required Software
59
    1.1  Git
60
    1.2  Bootloader & Tools
61
    1.3  System Kernel
62
    1.4  Low-Level Drivers
63
  2  Recommended Software
64
    2.1  gtkterm and hterm
65
    2.2  QtCreator IDE
66
    2.3  Doxygen & Graphviz
67
  3  Building and Flashing
68
  4  Developer Guides
69
    4.1  Adding a New Module
70
    4.2  Handling a Custom I/O Event in the Main Thread
71
    4.3  Implementing a New Low-Level Driver
72
    4.4  Writing a Test
73

    
74
================================================================================
75

    
76

    
77

    
78
1 - REQUIRED SOFTWARE
79
=====================
80

    
81
In order to compile the source code, you need to install the GNU ARM Embedded
82
Toolchain. Since this project uses GNU Make for configuring and calling the
83
compiler, this tool is requried too. AMiRo-OS uses ChibiOS as system kernel,
84
so you need a copy of that project as well.
85

    
86

    
87
1.1 - Git
88
---------
89

    
90
Since all main- and subprojects are available as Git repositories, installing a
91
recent version of the tool is mandatory.
92

    
93

    
94
1.2 Bootloader & Tools
95
----------------------
96

    
97
AMiRo-OS can take advantage of an installed bootloader if such exists and
98
provides an interface. By default, AMiRo-BLT is included as a Git submodule and
99
can easily be initialized via the ./setup.sh script. If requried, you can
100
replace the used bootloader by adding an according subfolder in the ./bootloader
101
directory. Note that you will have to adapt the makefiles and scripts, and
102
probably the operating system as well.
103
AMiRo-BLT furthermore has its own required and recommended software tools as
104
described in its README.txt file. Follow the instructions to initialize the
105
development environment manually or use the ./setup.sh script.
106

    
107

    
108
1.3 System Kernel
109
-----------------
110

    
111
Since AMiRo-OS uses ChibiOS as underlying system kernel, you need to acquire a
112
copy of it as well. For the sake of compatibility, it is included in AMiRo-OS as
113
a Git submodule. It is highly recommended to use the ./setup.sh script for
114
initialization. Moreover, you have to apply the patches to ChibiOS in order to
115
make AMiRo-OS work properly. It is recommended to use the ./setup.sh script for
116
this purpose.
117
If you would like to use a different kernel, you can add a subfolder in the
118
./kernel/ directory and adapt the scripts and operating system source code.
119

    
120

    
121
1.4 Low-Level Drivers
122
---------------------
123

    
124
Any required low-level drivers for the AMiRo hardware are available in an
125
additional project: AMiRo-LLD. It is included as a Git subodule and can be
126
initialized via the ./setup.sh script.
127

    
128

    
129

    
130
2 - RECOMMENDED SOFTWARE
131
========================
132

    
133
AMiRo-OS can take advantage of an installed bootloader, which is recommended for
134
the best experience. In order to use all features of AMiRo-OS it is also
135
recommended to install either the 'hterm' or 'gtkterm' application for accessing
136
the robot. To ease further development, this project offers support for the
137
QtCreator IDE.
138

    
139

    
140
2.1 - gtkterm and hterm
141
-----------------------
142

    
143
Depending on your operating system it is recommended to install 'gtkterm' for
144
Linux (available in the Ubuntu repositories), or 'hterm' for Windows. For
145
gtkterm you need to modify the configuration file ~/.gtktermrc (generated
146
automatically when you start the application for the first time) as follows:
147

    
148
  port	= /dev/ttyAMiRo0
149
  speed	= 115200
150
  bits	= 8
151
  stopbits	= 1
152
  parity	= none
153
  flow	= none
154
  wait_delay	= 0
155
  wait_char	= -1
156
  rs485_rts_time_before_tx	= 30
157
  rs485_rts_time_after_tx	= 30
158
  echo	= False
159
  crlfauto	= True
160

    
161
For hterm you need to configure the tool analogously. With either tool the robot
162
can be reset by toggling the RTS signal on and off again, and you can access the
163
system shell of AMiRo-OS. If you need legacy support for older version of
164
AMiRo-BLT, you can replace the port value by '/dev/ttyUSB0'.
165
Advanced users can use several connections to multiple modules simultaneously.
166
Each additional programmer will be available as '/dev/ttyAMiRo<N>' (and
167
'/dev/ttyUSB<N>' respectively) with <N> being an integer number starting from
168
zero. Please note: Those interfaces are ordered by the time when they have been
169
detected by the operating system, so detaching a cable and plugging it in again
170
may result in a different port name.
171

    
172

    
173
2.2 - QtCreator IDE
174
-------------------
175

    
176
In order to setup QtCreator projects any supported module, you can use the
177
provided ./setup.sh script. Further instructions for a more advanced
178
configuration of the IDE are provided in the ./tools/qtcreator/README.txt file.
179

    
180

    
181
2.3  Doxygen & Graphviz
182
-----------------------
183

    
184
In order to generate the documentation from the source code, Doxygen and
185
Graphviz are requried. It is recommended to install these tool using the
186
default versions for your system. Ubuntu users should simply run
187
  >$ sudo apt-get install doxygen graphviz
188

    
189

    
190

    
191
3 - BUILDING AND FLASHING
192
=========================
193

    
194
Each time you modify any part of AMiRo-OS, you need to recompile the whole
195
project for the according AMiRo module. Therefore you can use the ./Makefile by
196
simply executing 'make' and follow the instructions. Alternatively, you can
197
either use the makefiles provided per module in ./os/modules/<module_to_compile>
198
or - if you want to compile all modules at once - the makefile in the
199
./os/modules folder. After the build process has finished successfully, you
200
always have to flash the generated program to the module. Therefore you need an
201
appropriate tool, such as stm32flash (if you don't use a bootloader) or
202
SerialBoot (highly recommended; provided by AMiRo-BLT). Similarly to the
203
compilation procedure as described above, you can flash either each module
204
separately, or all modules at once by executing 'make flash' from the according
205
directory.
206

    
207
When using SerialBoot, please note that you must connect the programming cable
208
either to the DiWheelDrive or the PowerManagement module for flashing the
209
operating system. All other modules are powered off after reset so that only
210
these two offer a running bootloader, which is required for flashing.
211

    
212

    
213

    
214
4 - DEVELOPER GUIDES
215
====================
216

    
217
Due to the complexity of AMiRo-OS it can be quite troublesome to get started
218
with the framework at the beginning. The guides in this chapter will help you
219
getting things done, without thorough knowledge of the software structure.
220
Whereas the textual descriptions of the guides provide additional information
221
about the underlying concepts and mechanisms, a short summary is provided at the
222
end of each chapter.
223

    
224

    
225
4.1  Adding a New Module
226
------------------------
227

    
228
The very first thing to do when adding a new module to support AMiRo-OS is to
229
create an according folder in the modules/ directory. The name of this folder
230
should be as unambiguous as possible (e.g. containing name and version number).
231
All files, which directly depent on the hardware, and thus are not portable,
232
belong here. Conversely, any code that can be reused on diferent hardware must
233
not be put in this module folder.
234

    
235
In a second step you have to initialize all requried files (see below) in the
236
newly created module directory. It is recommended to use another module as
237
template for your configuration:
238
- alldconf.h
239
  Configuration header for the AMiRo-LLD project, which is part of AMiRo-OS.
240
  There are probably only very few configurations done here, since most setting
241
  depend on the content of aosconf.h and are handled modue unspecifically in in
242
  modules/aos_alldconf.h
243
- aosconf.h
244
  Configuration header for the AMiRo-OS project.
245
- board.h & board.c
246
  Contains definitions of GPIO names and initialization setting of those, as
247
  well as initialization functions.
248
- chconf.h
249
  Configuration header for the ChibiOS/RT system kernel. There are probably only
250
  very few configurations done here, since most settings depend on the content
251
  of aosconf.h and are handled module unspecifically in modules/aos_chconf.h
252
- halconf.h
253
  Configuration header for ChibiOS/HAL (hardware abstraction layer).
254
- Makefile
255
  The GNU make script to build and flash AMiRo-OS for the module.
256
- mcuconf.h
257
  Configuration file for ChibiOS/HAL to initialize the microcontroller (MCU). It
258
  is recommended to check the kernel/ChibiOS/demos/ directory for an example
259
  using the according MCU and copy the mcuconf.h from there. Depending on your
260
  hardware you may have to modify it nevertheless, though.
261
- module.h & module.c
262
  These files act as some sort of container, where all module specific aliases
263
  for interfaces and GPIOs, configurations, hooks, low-level drivers, and unit
264
  tests are defined. These are most probably the most comprehensive files in the
265
  module folder.
266
- <mcu>.ld
267
  Linker script, defining the memory layout and region aliases. It is
268
  recommended to check ChibiOS (kernel/ChibiOS/os/common/startup/) whether a
269
  linker script for the according MCU already exists.
270

    
271
Since all these files are specific to the module hardware, youl will have to
272
modify the contents according to your setup in a third step. Most settings are
273
described in detail within the configuration files, but for others you will have
274
to consult the datasheet of your MCU and even take a closer look at how certain
275
settings are used in other modules.
276

    
277
Finally, you need to build and flash the project. The compiler might even help
278
you getting everything set up correctly. Take the time needed to understand
279
compilation errors and warnings and get rid of all of those (warnings should not
280
be ignored since they are hints that something might be amiss and the program
281
will not act as intended).
282

    
283
Summing up, you have to
284
1) create a module directory.
285
2) initialize all files (use an existing module or a ChibiOS demo as template).
286
3) configure all files according to your hardware setup and preferences.
287
4) compile, flash and check for issues.
288

    
289

    
290
4.2  Handling a Custom I/O Event in the Main Thread
291
---------------------------------------------------
292

    
293
In order to handle custom I/O events in the main thread, AMiRo-OS offers several
294
hooks to be used. First of all, you need to configure and enable the interrupt
295
for the according GPIO. This can be done by implementing the
296
MODULE_INIT_INTERRUPTS() hook in the module.h file. For information how to use
297
this hook, please have a look at existing modules. In the end, the interrupt
298
callback functions has to emit an I/O event with the according bit in the flags
299
mask set (like the _gpioCallback() function in aos_system.c). As result,
300
whenever a rising or falling edge (depends on configuration) is detected on that
301
particular GPIO, the interrupt service routine is executed and hence an I/O
302
event is fired, which can be catched by any thread in the system.
303

    
304
Next, you have to configure the main thread to whitelist the event flag (all I/O
305
events are blacklisted by default). While system relevant events like power down
306
are imlicitely whitelisted by the OS, any custom events need to be added
307
exlplicitely. This is done via the optional
308
AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK macro, which should be defined in the
309
module.h file. Example:
310

    
311
  #define AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK         \
312
    (AOS_GPIOEVENT_FLAG(padX) | AOS_GPIOEVENT_FLAG(padY) | AOS_GPIOEVENT_FLAG(padZ))
313

    
314
When AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK has been defined correctly, the
315
main thread will be notified by the according events and execute its event
316
handling routine. Hence you have to implement another macro in module.h to
317
handle the custom event(s) appropriately:
318
MODULE_MAIN_LOOP_GPIOEVENT(eventflags). As you can see, the variable
319
'eventflags' is propagated to the hook. This variable is a mask, that allows to
320
identify the GPIO pad(s), which caused the event, by the individually set bits.
321
Following the example above, you can check which GPIOs have caused events by
322
using if-clauses in the implementation of the hook:
323

    
324
  #define MODULE_MAIN_LOOP_GPIOEVENT(eventflags) {          \
325
    if (eventflags & AOS_GPIOEVENT_FLAG(padX)) {            \
326
      /* handle event */                                    \
327
    }                                                       \
328
    if (eventflags & (AOS_IOEVENT_FLAG(padY) |              \
329
          AOS_GPIOEVENT_FLAG(padZ))) {                      \
330
      /* handle combined event */                           \
331
    }                                                       \
332
  }
333

    
334
Summing up, you have to
335
1) configure and enable the GPIO interrupt.
336
2) define the AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK macro.
337
3) implement the MODULE_MAIN_LOOP_GPIOEVENT(eventflags) hook.
338

    
339

    
340
4.3  Implementing a New Low-Level Driver
341
----------------------------------------
342

    
343
In the AMiRo-OS framework, low-level drivers are located in the additional Git
344
project AMiRo-LLD, which is included in AMiRo-OS as Git submodule at
345
periphery-lld/AMiRo-LLD/ and acts similar to a static library. When adding a new
346
low-level driver to the framework, you have to implement it, following the
347
instructions given in periphery-lld/AMiRo-LLD/README.txt
348

    
349
Now the new driver is available and can be enbled by simply including the
350
driver's makefile script in the module makefile. In order to make actuale use of
351
the driver you have to add according memory structures to the module.h and
352
module.c files - just have a look at existing modules how this is done. In some
353
cases you will have to configure additional interrupts and/or alter the
354
configuration of a communication interface (e.g. I²C). Once again, you should
355
take a look at existing modules and search the module.h for the hooks
356
MODULE_INIT_INTERRUPTS(), MODULE_INIT_PERIPHERY_IF and
357
MODULE_SHUTDOWN_PERIPHERY_IF().
358

    
359
Finally, you will probably want to validate your implementation via a test. How
360
this can be done is explained in detail in the next guide.
361

    
362
Summing up, you have to
363
1) implement the driver in AMiRo-LLD using periphAL only.
364
4) add the driver to a module (Makefile, module.h and module.c).
365
5) configure interrupts and interfaces as required.
366
6) write a test.
367

    
368

    
369
4.4  Writing a Test
370
------------------------
371

    
372
AMiRo-OS provides a test framework for conventient testing and the ability to
373
opt-out all tests via the aosconf.h configuration file. There is also a
374
dedicated folder, where all test code belongs to. In case you want to implement
375
a test for a newly developed low-level driver, you should have a look at the
376
folder test/periphery-lld/. As with the low-level drivers, tests are placed in
377
individual subfolders (e.g. test/periphery-lld/DEVICE1234_v1) and all should use
378
the prefix 'aos_test_' in their name. Moreover, all code must be fenced by
379
guards that disable it completely if the AMIROOS_CFG_TESTS_ENABLE flag is set to
380
false in the aosconf.h configuration file.
381

    
382
Now you will need to add the test to a specific module. Therefore, you should
383
create a new test/ directory in the module folder, if such does not exist yet.
384
In this directory, you create another subfolder, e.g. DEVICE1234/ and three
385
additional files in there:
386
 - module_test_DEVICE1234.mk
387
 - module_test_DEVICE1234.h
388
 - module_test_DEVICE1234.c
389
The makefile script is not required, but recommended to achieve maintainable
390
code. This script file should add the folder to the MODULE_INC variable and all
391
C source files to MODULE_CSRC. The .h and .c files furthermore define module
392
specific data structures and a test function.
393

    
394
In order to be able to call this function as a command via the AMiRo-OS shell,
395
you need to add an according shell command to the module.h and module.c files.
396
Whereas the command itself is typically very simple, just calling the callback
397
function defined in the test/DEVICE1234/module_test_DEVICE1234.h/.c files, you
398
have to add the command to a shell. In order to make the shell command, which
399
executes the test, available in a shell so a user can run it, it has to be
400
associated with the shell. AMiRo-OS provides the hook MODULE_INIT_TESTS() for
401
this purpose, which has to be implemented in the module.h file. Once again I
402
recommend to have a look at an existing module, how to use this hook.
403

    
404
Summing up, you have to
405
1) implement the test in the test/ folder.
406
2) implement a module specific wrapper in the module/test/ folder.
407
3) associate the shell command to a shell via the hook in module.h.
408

    
409
================================================================================
410