amiro-os / README.txt @ 4b8243d7
History | View | Annotate | Download (18.757 KB)
1 | e545e620 | Thomas Schöpping | AMiRo-OS is an operating system for the base version of the Autonomous Mini |
---|---|---|---|
2 | 3dcad54e | Thomas Schöpping | 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 | e545e620 | Thomas Schöpping | system kernel and extends it with platform specific configurations and further |
5 | functionalities and abstractions. |
||
6 | 58fe0e0b | Thomas Schöpping | |
7 | 96621a83 | Thomas Schöpping | Copyright (C) 2016..2020 Thomas Schöpping et al. |
8 | 58fe0e0b | Thomas Schöpping | (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 | 074e10d7 | Thomas Schöpping | 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 | 58fe0e0b | Thomas Schöpping | |
27 | Authors: |
||
28 | e545e620 | Thomas Schöpping | - Thomas Schöpping <tschoepp[at]cit-ec.uni-bielefeld.de> |
29 | - Marc Rothmann |
||
30 | 58fe0e0b | Thomas Schöpping | |
31 | References: |
||
32 | 3dcad54e | Thomas Schöpping | [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 | 58fe0e0b | Thomas Schöpping | |
56 | CONTENTS: |
||
57 | e545e620 | Thomas Schöpping | |
58 | 8fd2fd44 | Thomas Schöpping | 1 Required Software |
59 | e545e620 | Thomas Schöpping | 1.1 Git |
60 | 1.2 Bootloader & Tools |
||
61 | 1.3 System Kernel |
||
62 | 1.4 Low-Level Drivers |
||
63 | 8fd2fd44 | Thomas Schöpping | 2 Recommended Software |
64 | e545e620 | Thomas Schöpping | 2.1 gtkterm and hterm |
65 | 2.2 QtCreator IDE |
||
66 | 2.3 Doxygen & Graphviz |
||
67 | 8fd2fd44 | Thomas Schöpping | 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 | d796dcdf | Thomas Schöpping | 4.4 Writing a Test |
73 | 58fe0e0b | Thomas Schöpping | |
74 | 3dcad54e | Thomas Schöpping | ================================================================================ |
75 | |||
76 | |||
77 | 58fe0e0b | Thomas Schöpping | |
78 | 1 - REQUIRED SOFTWARE |
||
79 | 8fd2fd44 | Thomas Schöpping | ===================== |
80 | 58fe0e0b | Thomas Schöpping | |
81 | e545e620 | Thomas Schöpping | 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 | 3dcad54e | Thomas Schöpping | |
86 | |||
87 | ea4d1c60 | Thomas Schöpping | 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 | e545e620 | Thomas Schöpping | 1.2 Bootloader & Tools |
95 | ---------------------- |
||
96 | 3dcad54e | Thomas Schöpping | |
97 | e545e620 | Thomas Schöpping | 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 | d796dcdf | Thomas Schöpping | described in its README.txt file. Follow the instructions to initialize the |
105 | e545e620 | Thomas Schöpping | development environment manually or use the ./setup.sh script. |
106 | ea4d1c60 | Thomas Schöpping | |
107 | 58fe0e0b | Thomas Schöpping | |
108 | e545e620 | Thomas Schöpping | 1.3 System Kernel |
109 | ----------------- |
||
110 | 58fe0e0b | Thomas Schöpping | |
111 | 3dcad54e | Thomas Schöpping | Since AMiRo-OS uses ChibiOS as underlying system kernel, you need to acquire a |
112 | e545e620 | Thomas Schöpping | 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 | d796dcdf | Thomas Schöpping | make AMiRo-OS work properly. It is recommended to use the ./setup.sh script for |
116 | d8ed8c1c | Thomas Schöpping | this purpose. |
117 | e545e620 | Thomas Schöpping | 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 | d8ed8c1c | Thomas Schöpping | Any required low-level drivers for the AMiRo hardware are available in an |
125 | e545e620 | Thomas Schöpping | additional project: AMiRo-LLD. It is included as a Git subodule and can be |
126 | initialized via the ./setup.sh script. |
||
127 | 3dcad54e | Thomas Schöpping | |
128 | 58fe0e0b | Thomas Schöpping | |
129 | |||
130 | 2 - RECOMMENDED SOFTWARE |
||
131 | 8fd2fd44 | Thomas Schöpping | ======================== |
132 | 58fe0e0b | Thomas Schöpping | |
133 | d8ed8c1c | Thomas Schöpping | AMiRo-OS can take advantage of an installed bootloader, which is recommended for |
134 | e545e620 | Thomas Schöpping | 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 | 3dcad54e | Thomas Schöpping | |
139 | 58fe0e0b | Thomas Schöpping | |
140 | 2.1 - gtkterm and hterm |
||
141 | 3dcad54e | Thomas Schöpping | ----------------------- |
142 | 58fe0e0b | Thomas Schöpping | |
143 | e545e620 | Thomas Schöpping | Depending on your operating system it is recommended to install 'gtkterm' for |
144 | 3dcad54e | Thomas Schöpping | Linux (available in the Ubuntu repositories), or 'hterm' for Windows. For |
145 | e545e620 | Thomas Schöpping | gtkterm you need to modify the configuration file ~/.gtktermrc (generated |
146 | d443a2ff | Thomas Schöpping | automatically when you start the application for the first time). For the AMiRo |
147 | modules the configuration is: |
||
148 | 58fe0e0b | Thomas Schöpping | |
149 | 9f224ade | Thomas Schöpping | port = /dev/ttyAMiRo0 |
150 | 58fe0e0b | Thomas Schöpping | speed = 115200 |
151 | bits = 8 |
||
152 | stopbits = 1 |
||
153 | parity = none |
||
154 | flow = none |
||
155 | wait_delay = 0 |
||
156 | wait_char = -1 |
||
157 | rs485_rts_time_before_tx = 30 |
||
158 | rs485_rts_time_after_tx = 30 |
||
159 | echo = False |
||
160 | crlfauto = True |
||
161 | |||
162 | d443a2ff | Thomas Schöpping | The according configuration for all NUCLEO boards is: |
163 | |||
164 | port = /dev/ttyACM0 |
||
165 | speed = 115200 |
||
166 | bits = 8 |
||
167 | stopbits = 1 |
||
168 | parity = none |
||
169 | flow = none |
||
170 | wait_delay = 0 |
||
171 | wait_char = -1 |
||
172 | rs485_rts_time_before_tx = 30 |
||
173 | rs485_rts_time_after_tx = 30 |
||
174 | echo = False |
||
175 | crlfauto = True |
||
176 | |||
177 | e545e620 | Thomas Schöpping | For hterm you need to configure the tool analogously. With either tool the robot |
178 | can be reset by toggling the RTS signal on and off again, and you can access the |
||
179 | 9f224ade | Thomas Schöpping | system shell of AMiRo-OS. If you need legacy support for older version of |
180 | AMiRo-BLT, you can replace the port value by '/dev/ttyUSB0'. |
||
181 | d8ed8c1c | Thomas Schöpping | Advanced users can use several connections to multiple modules simultaneously. |
182 | Each additional programmer will be available as '/dev/ttyAMiRo<N>' (and |
||
183 | d796dcdf | Thomas Schöpping | '/dev/ttyUSB<N>' respectively) with <N> being an integer number starting from |
184 | zero. Please note: Those interfaces are ordered by the time when they have been |
||
185 | detected by the operating system, so detaching a cable and plugging it in again |
||
186 | may result in a different port name. |
||
187 | 58fe0e0b | Thomas Schöpping | |
188 | 3dcad54e | Thomas Schöpping | |
189 | e545e620 | Thomas Schöpping | 2.2 - QtCreator IDE |
190 | ------------------- |
||
191 | 3dcad54e | Thomas Schöpping | |
192 | d796dcdf | Thomas Schöpping | In order to setup QtCreator projects any supported module, you can use the |
193 | provided ./setup.sh script. Further instructions for a more advanced |
||
194 | e545e620 | Thomas Schöpping | configuration of the IDE are provided in the ./tools/qtcreator/README.txt file. |
195 | |||
196 | |||
197 | 2.3 Doxygen & Graphviz |
||
198 | ----------------------- |
||
199 | |||
200 | In order to generate the documentation from the source code, Doxygen and |
||
201 | Graphviz are requried. It is recommended to install these tool using the |
||
202 | default versions for your system. Ubuntu users should simply run |
||
203 | >$ sudo apt-get install doxygen graphviz |
||
204 | 3dcad54e | Thomas Schöpping | |
205 | 58fe0e0b | Thomas Schöpping | |
206 | |||
207 | 3 - BUILDING AND FLASHING |
||
208 | 8fd2fd44 | Thomas Schöpping | ========================= |
209 | 58fe0e0b | Thomas Schöpping | |
210 | 3dcad54e | Thomas Schöpping | Each time you modify any part of AMiRo-OS, you need to recompile the whole |
211 | e545e620 | Thomas Schöpping | project for the according AMiRo module. Therefore you can use the ./Makefile by |
212 | simply executing 'make' and follow the instructions. Alternatively, you can |
||
213 | d796dcdf | Thomas Schöpping | either use the makefiles provided per module in ./os/modules/<module_to_compile> |
214 | e545e620 | Thomas Schöpping | or - if you want to compile all modules at once - the makefile in the |
215 | ./os/modules folder. After the build process has finished successfully, you |
||
216 | d796dcdf | Thomas Schöpping | always have to flash the generated program to the module. Therefore you need an |
217 | e545e620 | Thomas Schöpping | appropriate tool, such as stm32flash (if you don't use a bootloader) or |
218 | SerialBoot (highly recommended; provided by AMiRo-BLT). Similarly to the |
||
219 | compilation procedure as described above, you can flash either each module |
||
220 | separately, or all modules at once by executing 'make flash' from the according |
||
221 | directory. |
||
222 | |||
223 | When using SerialBoot, please note that you must connect the programming cable |
||
224 | either to the DiWheelDrive or the PowerManagement module for flashing the |
||
225 | operating system. All other modules are powered off after reset so that only |
||
226 | these two offer a running bootloader, which is required for flashing. |
||
227 | 58fe0e0b | Thomas Schöpping | |
228 | 8fd2fd44 | Thomas Schöpping | |
229 | |||
230 | 4 - DEVELOPER GUIDES |
||
231 | ==================== |
||
232 | |||
233 | Due to the complexity of AMiRo-OS it can be quite troublesome to get started |
||
234 | with the framework at the beginning. The guides in this chapter will help you |
||
235 | getting things done, without thorough knowledge of the software structure. |
||
236 | dc688a9f | Thomas Schöpping | Whereas the textual descriptions of the guides provide additional information |
237 | 8fd2fd44 | Thomas Schöpping | about the underlying concepts and mechanisms, a short summary is provided at the |
238 | end of each chapter. |
||
239 | |||
240 | |||
241 | 4.1 Adding a New Module |
||
242 | ------------------------ |
||
243 | |||
244 | The very first thing to do when adding a new module to support AMiRo-OS is to |
||
245 | create an according folder in the modules/ directory. The name of this folder |
||
246 | should be as unambiguous as possible (e.g. containing name and version number). |
||
247 | All files, which directly depent on the hardware, and thus are not portable, |
||
248 | belong here. Conversely, any code that can be reused on diferent hardware must |
||
249 | d796dcdf | Thomas Schöpping | not be put in this module folder. |
250 | 8fd2fd44 | Thomas Schöpping | |
251 | In a second step you have to initialize all requried files (see below) in the |
||
252 | d796dcdf | Thomas Schöpping | newly created module directory. It is recommended to use another module as |
253 | 8fd2fd44 | Thomas Schöpping | template for your configuration: |
254 | - alldconf.h |
||
255 | Configuration header for the AMiRo-LLD project, which is part of AMiRo-OS. |
||
256 | d796dcdf | Thomas Schöpping | There are probably only very few configurations done here, since most setting |
257 | depend on the content of aosconf.h and are handled modue unspecifically in in |
||
258 | modules/aos_alldconf.h |
||
259 | 8fd2fd44 | Thomas Schöpping | - aosconf.h |
260 | Configuration header for the AMiRo-OS project. |
||
261 | - board.h & board.c |
||
262 | Contains definitions of GPIO names and initialization setting of those, as |
||
263 | well as initialization functions. |
||
264 | - chconf.h |
||
265 | Configuration header for the ChibiOS/RT system kernel. There are probably only |
||
266 | d796dcdf | Thomas Schöpping | very few configurations done here, since most settings depend on the content |
267 | of aosconf.h and are handled module unspecifically in modules/aos_chconf.h |
||
268 | 8fd2fd44 | Thomas Schöpping | - halconf.h |
269 | Configuration header for ChibiOS/HAL (hardware abstraction layer). |
||
270 | - Makefile |
||
271 | The GNU make script to build and flash AMiRo-OS for the module. |
||
272 | - mcuconf.h |
||
273 | d796dcdf | Thomas Schöpping | Configuration file for ChibiOS/HAL to initialize the microcontroller (MCU). It |
274 | 8fd2fd44 | Thomas Schöpping | is recommended to check the kernel/ChibiOS/demos/ directory for an example |
275 | using the according MCU and copy the mcuconf.h from there. Depending on your |
||
276 | hardware you may have to modify it nevertheless, though. |
||
277 | - module.h & module.c |
||
278 | These files act as some sort of container, where all module specific aliases |
||
279 | for interfaces and GPIOs, configurations, hooks, low-level drivers, and unit |
||
280 | tests are defined. These are most probably the most comprehensive files in the |
||
281 | module folder. |
||
282 | - <mcu>.ld |
||
283 | Linker script, defining the memory layout and region aliases. It is |
||
284 | recommended to check ChibiOS (kernel/ChibiOS/os/common/startup/) whether a |
||
285 | linker script for the according MCU already exists. |
||
286 | |||
287 | Since all these files are specific to the module hardware, youl will have to |
||
288 | modify the contents according to your setup in a third step. Most settings are |
||
289 | described in detail within the configuration files, but for others you will have |
||
290 | to consult the datasheet of your MCU and even take a closer look at how certain |
||
291 | settings are used in other modules. |
||
292 | |||
293 | Finally, you need to build and flash the project. The compiler might even help |
||
294 | d796dcdf | Thomas Schöpping | you getting everything set up correctly. Take the time needed to understand |
295 | compilation errors and warnings and get rid of all of those (warnings should not |
||
296 | be ignored since they are hints that something might be amiss and the program |
||
297 | will not act as intended). |
||
298 | 8fd2fd44 | Thomas Schöpping | |
299 | Summing up, you have to |
||
300 | 1) create a module directory. |
||
301 | 2) initialize all files (use an existing module or a ChibiOS demo as template). |
||
302 | 3) configure all files according to your hardware setup and preferences. |
||
303 | 4) compile, flash and check for issues. |
||
304 | |||
305 | dc688a9f | Thomas Schöpping | |
306 | 8fd2fd44 | Thomas Schöpping | 4.2 Handling a Custom I/O Event in the Main Thread |
307 | --------------------------------------------------- |
||
308 | |||
309 | In order to handle custom I/O events in the main thread, AMiRo-OS offers several |
||
310 | hooks to be used. First of all, you need to configure and enable the interrupt |
||
311 | d796dcdf | Thomas Schöpping | for the according GPIO. This can be done by implementing the |
312 | 8fd2fd44 | Thomas Schöpping | MODULE_INIT_INTERRUPTS() hook in the module.h file. For information how to use |
313 | this hook, please have a look at existing modules. In the end, the interrupt |
||
314 | callback functions has to emit an I/O event with the according bit in the flags |
||
315 | d796dcdf | Thomas Schöpping | mask set (like the _gpioCallback() function in aos_system.c). As result, |
316 | whenever a rising or falling edge (depends on configuration) is detected on that |
||
317 | particular GPIO, the interrupt service routine is executed and hence an I/O |
||
318 | event is fired, which can be catched by any thread in the system. |
||
319 | 8fd2fd44 | Thomas Schöpping | |
320 | Next, you have to configure the main thread to whitelist the event flag (all I/O |
||
321 | events are blacklisted by default). While system relevant events like power down |
||
322 | d796dcdf | Thomas Schöpping | are imlicitely whitelisted by the OS, any custom events need to be added |
323 | exlplicitely. This is done via the optional |
||
324 | AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK macro, which should be defined in the |
||
325 | module.h file. Example: |
||
326 | cda14729 | Thomas Schöpping | |
327 | #define AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK \ |
||
328 | (AOS_GPIOEVENT_FLAG(padX) | AOS_GPIOEVENT_FLAG(padY) | AOS_GPIOEVENT_FLAG(padZ)) |
||
329 | |||
330 | When AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK has been defined correctly, the |
||
331 | main thread will be notified by the according events and execute its event |
||
332 | handling routine. Hence you have to implement another macro in module.h to |
||
333 | d796dcdf | Thomas Schöpping | handle the custom event(s) appropriately: |
334 | MODULE_MAIN_LOOP_GPIOEVENT(eventflags). As you can see, the variable |
||
335 | 'eventflags' is propagated to the hook. This variable is a mask, that allows to |
||
336 | identify the GPIO pad(s), which caused the event, by the individually set bits. |
||
337 | Following the example above, you can check which GPIOs have caused events by |
||
338 | using if-clauses in the implementation of the hook: |
||
339 | cda14729 | Thomas Schöpping | |
340 | #define MODULE_MAIN_LOOP_GPIOEVENT(eventflags) { \ |
||
341 | if (eventflags & AOS_GPIOEVENT_FLAG(padX)) { \ |
||
342 | 8fd2fd44 | Thomas Schöpping | /* handle event */ \ |
343 | } \ |
||
344 | if (eventflags & (AOS_IOEVENT_FLAG(padY) | \ |
||
345 | cda14729 | Thomas Schöpping | AOS_GPIOEVENT_FLAG(padZ))) { \ |
346 | 8fd2fd44 | Thomas Schöpping | /* handle combined event */ \ |
347 | } \ |
||
348 | } |
||
349 | |||
350 | Summing up, you have to |
||
351 | 1) configure and enable the GPIO interrupt. |
||
352 | cda14729 | Thomas Schöpping | 2) define the AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK macro. |
353 | 3) implement the MODULE_MAIN_LOOP_GPIOEVENT(eventflags) hook. |
||
354 | 8fd2fd44 | Thomas Schöpping | |
355 | dc688a9f | Thomas Schöpping | |
356 | 8fd2fd44 | Thomas Schöpping | 4.3 Implementing a New Low-Level Driver |
357 | ---------------------------------------- |
||
358 | |||
359 | In the AMiRo-OS framework, low-level drivers are located in the additional Git |
||
360 | project AMiRo-LLD, which is included in AMiRo-OS as Git submodule at |
||
361 | periphery-lld/AMiRo-LLD/ and acts similar to a static library. When adding a new |
||
362 | d796dcdf | Thomas Schöpping | low-level driver to the framework, you have to implement it, following the |
363 | instructions given in periphery-lld/AMiRo-LLD/README.txt |
||
364 | |||
365 | Now the new driver is available and can be enbled by simply including the |
||
366 | driver's makefile script in the module makefile. In order to make actuale use of |
||
367 | the driver you have to add according memory structures to the module.h and |
||
368 | 8fd2fd44 | Thomas Schöpping | module.c files - just have a look at existing modules how this is done. In some |
369 | cases you will have to configure additional interrupts and/or alter the |
||
370 | configuration of a communication interface (e.g. I²C). Once again, you should |
||
371 | take a look at existing modules and search the module.h for the hooks |
||
372 | d796dcdf | Thomas Schöpping | MODULE_INIT_INTERRUPTS(), MODULE_INIT_PERIPHERY_IF and |
373 | MODULE_SHUTDOWN_PERIPHERY_IF(). |
||
374 | 8fd2fd44 | Thomas Schöpping | |
375 | d796dcdf | Thomas Schöpping | Finally, you will probably want to validate your implementation via a test. How |
376 | this can be done is explained in detail in the next guide. |
||
377 | 8fd2fd44 | Thomas Schöpping | |
378 | Summing up, you have to |
||
379 | 1) implement the driver in AMiRo-LLD using periphAL only. |
||
380 | d796dcdf | Thomas Schöpping | 4) add the driver to a module (Makefile, module.h and module.c). |
381 | 8fd2fd44 | Thomas Schöpping | 5) configure interrupts and interfaces as required. |
382 | d796dcdf | Thomas Schöpping | 6) write a test. |
383 | 8fd2fd44 | Thomas Schöpping | |
384 | dc688a9f | Thomas Schöpping | |
385 | d796dcdf | Thomas Schöpping | 4.4 Writing a Test |
386 | 8fd2fd44 | Thomas Schöpping | ------------------------ |
387 | |||
388 | d796dcdf | Thomas Schöpping | AMiRo-OS provides a test framework for conventient testing and the ability to |
389 | opt-out all tests via the aosconf.h configuration file. There is also a |
||
390 | dedicated folder, where all test code belongs to. In case you want to implement |
||
391 | a test for a newly developed low-level driver, you should have a look at the |
||
392 | folder test/periphery-lld/. As with the low-level drivers, tests are placed in |
||
393 | individual subfolders (e.g. test/periphery-lld/DEVICE1234_v1) and all should use |
||
394 | the prefix 'aos_test_' in their name. Moreover, all code must be fenced by |
||
395 | guards that disable it completely if the AMIROOS_CFG_TESTS_ENABLE flag is set to |
||
396 | false in the aosconf.h configuration file. |
||
397 | |||
398 | Now you will need to add the test to a specific module. Therefore, you should |
||
399 | create a new test/ directory in the module folder, if such does not exist yet. |
||
400 | In this directory, you create another subfolder, e.g. DEVICE1234/ and three |
||
401 | additional files in there: |
||
402 | - module_test_DEVICE1234.mk |
||
403 | - module_test_DEVICE1234.h |
||
404 | - module_test_DEVICE1234.c |
||
405 | The makefile script is not required, but recommended to achieve maintainable |
||
406 | code. This script file should add the folder to the MODULE_INC variable and all |
||
407 | C source files to MODULE_CSRC. The .h and .c files furthermore define module |
||
408 | specific data structures and a test function. |
||
409 | |||
410 | In order to be able to call this function as a command via the AMiRo-OS shell, |
||
411 | you need to add an according shell command to the module.h and module.c files. |
||
412 | Whereas the command itself is typically very simple, just calling the callback |
||
413 | function defined in the test/DEVICE1234/module_test_DEVICE1234.h/.c files, you |
||
414 | have to add the command to a shell. In order to make the shell command, which |
||
415 | executes the test, available in a shell so a user can run it, it has to be |
||
416 | associated with the shell. AMiRo-OS provides the hook MODULE_INIT_TESTS() for |
||
417 | this purpose, which has to be implemented in the module.h file. Once again I |
||
418 | recommend to have a look at an existing module, how to use this hook. |
||
419 | 8fd2fd44 | Thomas Schöpping | |
420 | Summing up, you have to |
||
421 | d796dcdf | Thomas Schöpping | 1) implement the test in the test/ folder. |
422 | 2) implement a module specific wrapper in the module/test/ folder. |
||
423 | 8fd2fd44 | Thomas Schöpping | 3) associate the shell command to a shell via the hook in module.h. |
424 | |||
425 | 3dcad54e | Thomas Schöpping | ================================================================================ |