Modules

WARNING: the functionalities described in this section are experimental and have never been fully tested. Use with care !

The modules allow to add new code in a flexible way with initialisation, periodic and event functions without modifying the main AP loop.

In the airframe file

To add a new module for an aircraft, add a section modules in his airframe xml file :

<modules main_freq="60">
 <load name="demo_module.xml"/>
 <load name="dummy.xml"/>
</modules>

• The main_freq parameter (in Hz) allows to specify the frequency of the main loop. Default is 60 Hz.

In the makefile section, add a flag -DUSE_MODULES in order to activate the service.

In the module file

The modules description files are located in conf/modules.

<!DOCTYPE module SYSTEM "module.dtd">
<module name="demo_module">
 <depend require="bla.xml" conflict="boo"/>
 <header>
  <file name="demo_module.h"/>
 </header>
 <init fun="init_demo()"/>
 <periodic fun="periodic_1Hz_demo()" freq="1." start="start_demo()" stop="stop_demo()"/>
 <periodic fun="periodic_10Hz_demo()" period="0.1" start="start_demo()" stop="stop_demo()"/>
 <makefile>
  <raw>
   #Raw makefile section
  </raw>
  <flag name="DEMO_MODULE_LED" value="2"/>
  <file name="demo_module.c"/>
 </makefile>
</module>

• module
  • name : this parameter is the name of the module and must match with the name of the directory in sw/airborne/modules where the source code is located (in the above exemple: sw/airborne/modules/demo_module)

• depend (0 or 1 'depend' node)
  • require : the list of required modules
  • conflict : the list of conflicting modules
  • the elements of a list are separated with a pipe (|), ex: "bla|boo"
  • the elements can be a xml file (in conf/modules) or a module name (in sw/airborne/modules)

• header (0 or 1 'header' node)
  • file : the name of the header to automatically include in modules.h

• init (0 or 1 'init' node)
  • fun : initialization function name, called once at startup

• periodic (0 or more 'periodic' node)
  • fun : periodic function name (mandatory)
  • period : period of the function in seconds, cannot be higher than the main frequency (if not specified, use freq parameter)
  • freq : frequency of the function in Hz, cannot be higher than main frequency (used if period is not defined; if nor period nor freq are defined, the maximum frequency is used by default)
  • delay : integer that can be used to impose a sequence in the periodic functions (use values between 0 and main_freq/function_freq)
  • start : function to be executed before the periodic function starts
  • stop : function to be executed after the periodic function stops (never called if autorun=LOCK)
  • autorun : TRUE to make the periodic function starts automatically after init, FALSE to make it way for a user command to start, LOCK to make it always true (default is LOCK)

• event (0 or more 'event' node)
  • fun : event function name called in each cycle of the main AP loop

• makefile (0 or more 'makefile' node)
  • target : a list of build targets separated with pipes (ex: <makefile target="tunnel|foo">) (default is "ap|sim")
  • flag : each flag node specifies a CFLAGS for the current targets
    • name : name of the flag (ex: name="USE_MODULE_LED" -> target.CFLAGS += -DUSE_MODULE_LED) (mandatory)
    • value : the value to associate (ex: name="DEMO_MODULE_LED" value="2" -> target.CFLAGS += -DDEMO_MODULE_LED=2)
  • file
    • name : the name of the c file to add in the Makefile (ex: name="demo_module.c" -> target.srcs += demo_module.c)
  • raw : allows to define a raw makefile section

In the airborne code

The code corresponding to a module should be placed in the directory "sw/airborne/modules/<module_name>" where module_name must match the one in your conf file.

Starting / stopping a module

To be done. This will be probably possible through some settings automatically added.

For now, anyone that includes the header "modules.h" can start or stop the periodic tasks.