AMiRo-OS

    4.4  Writing a Unit Test

described in its README.txt file. Follow th instructions to initialize the

make AMiRo-OS work properly. It is recommended to use the .setup.sh script for

'/dev/USB<N>' respectively) with <N> being an integer number starting from zero.

Please note: Those interfaces are ordered by the time when they have been

detected by the operating system.

In order to setup QtCreator projects for the three AMiRo base modules, you can

use the provided ./setup.sh script. Further instructions for a more advanced

either use the makefiles provided per module in ./os/modules/<ModuleToCompile>

always have to flash the generated program to the robot. Therefore you need an

not be put in the module folder.

newlly created module directory. It is recommended to use another module as

  very few configurations one here, since most settings depend on the content of

  aosconf.h and are handled module unspecific in modules/aos_chconf.h

  Configuration file for ChibiOS/JAL to initialize the microcontroller (MCU). It

you getting everything set up correctly. Take time to understand compilation

errors and warning and get rid of all of those (warnings should not be ignored

since they are hints that something might be amiss and the program will not act

as intended).

in the according GPIO. This can be done by implementing the

mask set (like the _intCallback() function in aos_system.c). As result, whenever

a rising or falling edge (depends on configuration) is detected on that GPIO,

the interrupt service routine is executed and hence an I/O event is fired, which

can be catched by any thread in the system.

are whitelisted by the OS, any custom events need to be added exl´plicitely.

This is done via the optional AMIROOS_CFG_MAIN_LOOP_GPIOEVENT_FLAGSMASK macro,

which should be defined in the module.h file. Example:

handle the custom event(s) appropriately: MODULE_MAIN_LOOP_GPIOEVENT(eventflags).

As you can see, the variable 'eventflags' is propagated to the hook. This

variable is a mask, that allows to identify the GPIO pad(s), which caused the

event, by the bits set. Following the example above, you can check which GPIOs

have caused events by using if-clauses in the implementation of the hook:

low-level driver to the framework, you have to implement it, providing a

(single) header file in periphery-lld/AMiRo-LLD/include/ and the required C

sources in periphery-lld/AMiRo-LLD/source/. By convention, all filenames use the

prefix 'alld_' to avoid ambiguities. Furthermore, files should be named by the

exact designation of the hardware (e.g. 'alld_vcnl4020' instead of

'alld_proximitysensor'). Since AMiRo-LLD is intended to be usable with other

operating systems than AMiRo-OS, it provides an interface for accessing

communication interfaces and basic functionalities of the operating system. On

the one hand, several types are defined in periphery-lld/AMiRo-LLD/periphALtypes.h.

The interface functions, on the other hand, are defined by AMiRo-LLD (cf.

periphery-lld/AMiRo-LLD/templates/periphAL.h), but implemented by the operating

system (cf. periphery-lld/periphAL.h). For the implementation of the driver, you

must only use those types and functions to interact with the operating system.

If you need further functionality, which is not provided by the interface yet,

you are encouraged to extend periphAL.

Furthermore, all files must define a guard, so that the whole driver is

disabled, when the guard is not set explicitely. These guard again are named

following a convention, but instead of explaning it here, just have a look at

one of the existing drivers and look for lines like

  #if defined(AMIROLLD_CFG_USE_VCNL4020) || defined(__DOXYGEN__)

With these guards in place, the driver will be omitted by default and needs to

be enabled explicitely. In order to do so, you need to add an according #define

in the alldconf.h file of any module, which shall use the new driver.

Now the new driver is available and enabled, but not actually used yet.

Therefore you have to add according memory structures to the module.h and

MODULE_INIT_INTERRUPTS() and MODULE_INIT_PERIPHERY_COMM().

Finally, you will probably want to validate your implementation via a unit test.

How this can be done is explained in detail in the next guide.

2) fence all code in all files by a guard.

3) set the guard in alldconf.h to enable the driver.

4) add the driver to a module.

6) write a unit test.

4.4  Writing a Unit Test

AMiRo-OS provides a unit test framework for conventient testing and the ability

to opt-out all unit tests via the aosconf.h configuration file. There is also a

dedicated folder, where all unit test code belongs to. In case you want to

implement a unit test for a newly developed low-level driver, you should use the

folders unittests/periphery-lld/inc and unittests/periphery-lld/src

respectively. As with the low-level drivers, unit test files should use a prefix

in their name, namely 'ut_' and all code should be fenced via guards that

disable it by default (have a look at existing unit tests). Before you implement

a vast test, however, it is highly recommended to start with some sceleton code

(just copy an existing unit test, scoop out the test function, and rename

according variables etc.) and make it compile and run.

After you have initialized the unit test sceleton, you have to add the according

aos_unittest_t (cf. core/inc/aos_unittest.h) object to the module.h and module.c

files. These objects again require an shell command, so the unit test can be run

via the AMiRo-OS shell. As with existing unit tests, this shell command callback

function as well as any further required data should be implemented directly in

module.c, so it not accessable from any other context. In most cases this

callback function is trivial, anyway.

In order to make the shell command, which executes the unit test, available in

shell so a user can run it, it has to be associated with the shell. AMiRo-OS

provides the hook MODULE_INIT_TESTS() for this purpose, which has to be

implemented in the module.h file. Once again I recommend to have a look at an

existing module, how to use this hook.

Since the execution pipeline is set up now, you can fille your unit test with

life. Remember that the test is executed by the shell thread, so you can access

any functionality of the system, but might encounter race conditions, depending

on what other applications run concurrently.

1) initialize a unit test sceleton in the unittests/ folder.

2) introduce an according object and configuration in module.h and module.c.

4) implement the full unit test in the prevously created sceleton files.