amiro-os / README.txt @ 2dd2e257
History | View | Annotate | Download (19.7 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 | 84f0ce9e | Thomas Schöpping | Copyright (C) 2016..2019 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 | 4.4 Writing a Unit 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 | described in its README.txt file. Follow th instructions to initialize the |
||
105 | 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 | d8ed8c1c | Thomas Schöpping | make AMiRo-OS work properly. It is recommended to use the .setup.sh script for |
116 | 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 | 3dcad54e | Thomas Schöpping | automatically when you start the application for the first time) as follows: |
147 | 58fe0e0b | Thomas Schöpping | |
148 | 9f224ade | Thomas Schöpping | port = /dev/ttyAMiRo0 |
149 | 58fe0e0b | Thomas Schöpping | 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 | e545e620 | Thomas Schöpping | 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 | 9f224ade | Thomas Schöpping | 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 | d8ed8c1c | Thomas Schöpping | Advanced users can use several connections to multiple modules simultaneously. |
166 | Each additional programmer will be available as '/dev/ttyAMiRo<N>' (and |
||
167 | '/dev/USB<N>' respectively) with <N> being an integer number starting from zero. |
||
168 | Please note: Those interfaces are ordered by the time when they have been |
||
169 | detected by the operating system. |
||
170 | 58fe0e0b | Thomas Schöpping | |
171 | 3dcad54e | Thomas Schöpping | |
172 | e545e620 | Thomas Schöpping | 2.2 - QtCreator IDE |
173 | ------------------- |
||
174 | 3dcad54e | Thomas Schöpping | |
175 | e545e620 | Thomas Schöpping | In order to setup QtCreator projects for the three AMiRo base modules, you can |
176 | use the provided ./setup.sh script. Further instructions for a more advanced |
||
177 | configuration of the IDE are provided in the ./tools/qtcreator/README.txt file. |
||
178 | |||
179 | |||
180 | 2.3 Doxygen & Graphviz |
||
181 | ----------------------- |
||
182 | |||
183 | In order to generate the documentation from the source code, Doxygen and |
||
184 | Graphviz are requried. It is recommended to install these tool using the |
||
185 | default versions for your system. Ubuntu users should simply run |
||
186 | >$ sudo apt-get install doxygen graphviz |
||
187 | 3dcad54e | Thomas Schöpping | |
188 | 58fe0e0b | Thomas Schöpping | |
189 | |||
190 | 3 - BUILDING AND FLASHING |
||
191 | 8fd2fd44 | Thomas Schöpping | ========================= |
192 | 58fe0e0b | Thomas Schöpping | |
193 | 3dcad54e | Thomas Schöpping | Each time you modify any part of AMiRo-OS, you need to recompile the whole |
194 | e545e620 | Thomas Schöpping | project for the according AMiRo module. Therefore you can use the ./Makefile by |
195 | simply executing 'make' and follow the instructions. Alternatively, you can |
||
196 | either use the makefiles provided per module in ./os/modules/<ModuleToCompile> |
||
197 | or - if you want to compile all modules at once - the makefile in the |
||
198 | ./os/modules folder. After the build process has finished successfully, you |
||
199 | always have to flash the generated program to the robot. Therefore you need an |
||
200 | appropriate tool, such as stm32flash (if you don't use a bootloader) or |
||
201 | SerialBoot (highly recommended; provided by AMiRo-BLT). Similarly to the |
||
202 | compilation procedure as described above, you can flash either each module |
||
203 | separately, or all modules at once by executing 'make flash' from the according |
||
204 | directory. |
||
205 | |||
206 | When using SerialBoot, please note that you must connect the programming cable |
||
207 | either to the DiWheelDrive or the PowerManagement module for flashing the |
||
208 | operating system. All other modules are powered off after reset so that only |
||
209 | these two offer a running bootloader, which is required for flashing. |
||
210 | 58fe0e0b | Thomas Schöpping | |
211 | 8fd2fd44 | Thomas Schöpping | |
212 | |||
213 | 4 - DEVELOPER GUIDES |
||
214 | ==================== |
||
215 | |||
216 | Due to the complexity of AMiRo-OS it can be quite troublesome to get started |
||
217 | with the framework at the beginning. The guides in this chapter will help you |
||
218 | getting things done, without thorough knowledge of the software structure. |
||
219 | Whereas the textual descriptions of the guides provide additional informatio |
||
220 | about the underlying concepts and mechanisms, a short summary is provided at the |
||
221 | end of each chapter. |
||
222 | |||
223 | |||
224 | 4.1 Adding a New Module |
||
225 | ------------------------ |
||
226 | |||
227 | The very first thing to do when adding a new module to support AMiRo-OS is to |
||
228 | create an according folder in the modules/ directory. The name of this folder |
||
229 | should be as unambiguous as possible (e.g. containing name and version number). |
||
230 | All files, which directly depent on the hardware, and thus are not portable, |
||
231 | belong here. Conversely, any code that can be reused on diferent hardware must |
||
232 | not be put in the module folder. |
||
233 | |||
234 | In a second step you have to initialize all requried files (see below) in the |
||
235 | newlly created module directory. It is recommended to use another module as |
||
236 | template for your configuration: |
||
237 | - alldconf.h |
||
238 | Configuration header for the AMiRo-LLD project, which is part of AMiRo-OS. |
||
239 | - aosconf.h |
||
240 | Configuration header for the AMiRo-OS project. |
||
241 | - board.h & board.c |
||
242 | Contains definitions of GPIO names and initialization setting of those, as |
||
243 | well as initialization functions. |
||
244 | - chconf.h |
||
245 | Configuration header for the ChibiOS/RT system kernel. There are probably only |
||
246 | very few configurations one here, since most settings depend on the content of |
||
247 | aosconf.h and are handled module unspecific in modules/aos_chconf.h |
||
248 | - halconf.h |
||
249 | Configuration header for ChibiOS/HAL (hardware abstraction layer). |
||
250 | - Makefile |
||
251 | The GNU make script to build and flash AMiRo-OS for the module. |
||
252 | - mcuconf.h |
||
253 | Configuration file for ChibiOS/JAL to initialize the microcontroller (MCU). It |
||
254 | is recommended to check the kernel/ChibiOS/demos/ directory for an example |
||
255 | using the according MCU and copy the mcuconf.h from there. Depending on your |
||
256 | hardware you may have to modify it nevertheless, though. |
||
257 | - module.h & module.c |
||
258 | These files act as some sort of container, where all module specific aliases |
||
259 | for interfaces and GPIOs, configurations, hooks, low-level drivers, and unit |
||
260 | tests are defined. These are most probably the most comprehensive files in the |
||
261 | module folder. |
||
262 | - <mcu>.ld |
||
263 | Linker script, defining the memory layout and region aliases. It is |
||
264 | recommended to check ChibiOS (kernel/ChibiOS/os/common/startup/) whether a |
||
265 | linker script for the according MCU already exists. |
||
266 | |||
267 | Since all these files are specific to the module hardware, youl will have to |
||
268 | modify the contents according to your setup in a third step. Most settings are |
||
269 | described in detail within the configuration files, but for others you will have |
||
270 | to consult the datasheet of your MCU and even take a closer look at how certain |
||
271 | settings are used in other modules. |
||
272 | |||
273 | Finally, you need to build and flash the project. The compiler might even help |
||
274 | you getting everything set up correctly. Take time to understand compilation |
||
275 | errors and warning and get rid of all of those (warnings should not be ignored |
||
276 | since they are hints that something might be amiss and the program will not act |
||
277 | as intended). |
||
278 | |||
279 | Summing up, you have to |
||
280 | 1) create a module directory. |
||
281 | 2) initialize all files (use an existing module or a ChibiOS demo as template). |
||
282 | 3) configure all files according to your hardware setup and preferences. |
||
283 | 4) compile, flash and check for issues. |
||
284 | |||
285 | 4.2 Handling a Custom I/O Event in the Main Thread |
||
286 | --------------------------------------------------- |
||
287 | |||
288 | In order to handle custom I/O events in the main thread, AMiRo-OS offers several |
||
289 | hooks to be used. First of all, you need to configure and enable the interrupt |
||
290 | in the according GPIO. This can be done by implementing the |
||
291 | MODULE_INIT_INTERRUPTS() hook in the module.h file. For information how to use |
||
292 | this hook, please have a look at existing modules. In the end, the interrupt |
||
293 | callback functions has to emit an I/O event with the according bit in the flags |
||
294 | mask set (like the _intCallback() function in aos_system.c). As result, whenever |
||
295 | a rising or falling edge (depends on configuration) is detected on that GPIO, |
||
296 | the interrupt service routine is executed and hence an I/O event is fired, which |
||
297 | can be catched by any thread in the system. |
||
298 | |||
299 | Next, you have to configure the main thread to whitelist the event flag (all I/O |
||
300 | events are blacklisted by default). While system relevant events like power down |
||
301 | are whitelisted by the OS, any custom events need to be added exl´plicitely. |
||
302 | This is done via the optional AMIROOS_CFG_MAIN_LOOP_IOEVENT_MASK macro, which |
||
303 | should be defined in the module.h file. Example: |
||
304 | |||
305 | #define AMIROOS_CFG_MAIN_LOOP_IOEVENT_MASK \ |
||
306 | (AOS_IOEVENT_FLAG(padX) | AOS_IOEVENT_FLAG(padY) | AOS_IOEVENT_FLAG(padZ)) |
||
307 | |||
308 | When AMIROOS_CFG_MAIN_LOOP_IOEVENT_MASK has been defined correctly, the main |
||
309 | thread will be notified by the according events and execute its event handling |
||
310 | routine. Hence you have to implement another macro in module.h to handle the |
||
311 | custom event(s) appropriately: MODULE_MAIN_LOOP_IO_EVENT(eventflags). As you can |
||
312 | see, the variable 'eventflags' is propagated to the hook. This variable is a |
||
313 | mask, that allows to identify the GPIO pad(s), which caused the event, by the |
||
314 | bits set. Following the example above, you can check which GPIOs have caused |
||
315 | events by using if-clauses in the implementation of the hook: |
||
316 | |||
317 | #define MODULE_MAIN_LOOP_IO_EVENT(eventflags) { \ |
||
318 | if (eventflags & AOS_IOEVENT_FLAG(padX)) { \ |
||
319 | /* handle event */ \ |
||
320 | } \ |
||
321 | if (eventflags & (AOS_IOEVENT_FLAG(padY) | \ |
||
322 | AOS_IOEVENT_FLAG(padZ))) { \ |
||
323 | /* handle combined event */ \ |
||
324 | } \ |
||
325 | } |
||
326 | |||
327 | Summing up, you have to |
||
328 | 1) configure and enable the GPIO interrupt. |
||
329 | 2) define the AMIROOS_CFG_MAIN_LOOP_IOEVENT_MASK macro. |
||
330 | 3) implement the MODULE_MAIN_LOOP_IO_EVENT(eventflags) hook. |
||
331 | |||
332 | 4.3 Implementing a New Low-Level Driver |
||
333 | ---------------------------------------- |
||
334 | |||
335 | In the AMiRo-OS framework, low-level drivers are located in the additional Git |
||
336 | project AMiRo-LLD, which is included in AMiRo-OS as Git submodule at |
||
337 | periphery-lld/AMiRo-LLD/ and acts similar to a static library. When adding a new |
||
338 | low-level driver to the framework, you have to implement it, providing a |
||
339 | (single) header file in periphery-lld/AMiRo-LLD/include/ and the required C |
||
340 | sources in periphery-lld/AMiRo-LLD/source/. By convention, all filenames use the |
||
341 | prefix 'alld_' to avoid ambiguities. Furthermore, files should be named by the |
||
342 | exact designation of the hardware (e.g. 'alld_vcnl4020' instead of |
||
343 | 'alld_proximitysensor'). Since AMiRo-LLD is intended to be usable with other |
||
344 | operating systems than AMiRo-OS, it provides an interface for accessing |
||
345 | communication interfaces and basic functionalities of the operating system. On |
||
346 | the one hand, several types are defined in periphery-lld/AMiRo-LLD/periphALtypes.h. |
||
347 | The interface functions, on the other hand, are defined by AMiRo-LLD (cf. |
||
348 | periphery-lld/AMiRo-LLD/templates/periphAL.h), but implemented by the operating |
||
349 | system (cf. periphery-lld/periphAL.h). For the implementation of the driver, you |
||
350 | must only use those types and functions to interact with the operating system. |
||
351 | If you need further functionality, which is not provided by the interface yet, |
||
352 | you are encouraged to extend periphAL. |
||
353 | |||
354 | Furthermore, all files must define a guard, so that the whole driver is |
||
355 | disabled, when the guard is not set explicitely. These guard again are named |
||
356 | following a convention, but instead of explaning it here, just have a look at |
||
357 | one of the existing drivers and look for lines like |
||
358 | |||
359 | #if defined(AMIROLLD_CFG_USE_VCNL4020) || defined(__DOXYGEN__) |
||
360 | |||
361 | With these guards in place, the driver will be omitted by default and needs to |
||
362 | be enabled explicitely. In order to do so, you need to add an according #define |
||
363 | in the alldconf.h file of any module, which shall use the new driver. |
||
364 | |||
365 | Now the new driver is available and enabled, but not actually used yet. |
||
366 | Therefore you have to add according memory structures to the module.h and |
||
367 | module.c files - just have a look at existing modules how this is done. In some |
||
368 | cases you will have to configure additional interrupts and/or alter the |
||
369 | configuration of a communication interface (e.g. I²C). Once again, you should |
||
370 | take a look at existing modules and search the module.h for the hooks |
||
371 | MODULE_INIT_INTERRUPTS() and MODULE_INIT_PERIPHERY_COMM(). |
||
372 | |||
373 | Finally, you will probably want to validate your implementation via a unit test. |
||
374 | How this can be done is explained in detail in the next guide. |
||
375 | |||
376 | Summing up, you have to |
||
377 | 1) implement the driver in AMiRo-LLD using periphAL only. |
||
378 | 2) fence all code in all files by a guard. |
||
379 | 3) set the guard in alldconf.h to enable the driver. |
||
380 | 4) add the driver to a module. |
||
381 | 5) configure interrupts and interfaces as required. |
||
382 | 6) write a unit test. |
||
383 | |||
384 | 4.4 Writing a Unit Test |
||
385 | ------------------------ |
||
386 | |||
387 | AMiRo-OS provides a unit test framework for conventient testing and the ability |
||
388 | to opt-out all unit tests via the aosconf.h configuration file. There is also a |
||
389 | dedicated folder, where all unit test code belongs to. In case you want to |
||
390 | implement a unit test for a newly developed low-level driver, you should use the |
||
391 | folders unittests/periphery-lld/inc and unittests/periphery-lld/src |
||
392 | respectively. As with the low-level drivers, unit test files should use a prefix |
||
393 | in their name, namely 'ut_' and all code should be fenced via guards that |
||
394 | disable it by default (have a look at existing unit tests). Before you implement |
||
395 | a vast test, however, it is highly recommended to start with some sceleton code |
||
396 | (just copy an existing unit test, scoop out the test function, and rename |
||
397 | according variables etc.) and make it compile and run. |
||
398 | |||
399 | After you have initialized the unit test sceleton, you have to add the according |
||
400 | aos_unittest_t (cf. core/inc/aos_unittest.h) object to the module.h and module.c |
||
401 | files. These objects again require an shell command, so the unit test can be run |
||
402 | via the AMiRo-OS shell. As with existing unit tests, this shell command callback |
||
403 | function as well as any further required data should be implemented directly in |
||
404 | module.c, so it not accessable from any other context. In most cases this |
||
405 | callback function is trivial, anyway. |
||
406 | |||
407 | In order to make the shell command, which executes the unit test, available in |
||
408 | shell so a user can run it, it has to be associated with the shell. AMiRo-OS |
||
409 | provides the hook MODULE_INIT_TESTS() for this purpose, which has to be |
||
410 | implemented in the module.h file. Once again I recommend to have a look at an |
||
411 | existing module, how to use this hook. |
||
412 | |||
413 | Since the execution pipeline is set up now, you can fille your unit test with |
||
414 | life. Remember that the test is executed by the shell thread, so you can access |
||
415 | any functionality of the system, but might encounter race conditions, depending |
||
416 | on what other applications run concurrently. |
||
417 | |||
418 | Summing up, you have to |
||
419 | 1) initialize a unit test sceleton in the unittests/ folder. |
||
420 | 2) introduce an according object and configuration in module.h and module.c. |
||
421 | 3) associate the shell command to a shell via the hook in module.h. |
||
422 | 4) implement the full unit test in the prevously created sceleton files. |
||
423 | |||
424 | 3dcad54e | Thomas Schöpping | ================================================================================ |