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 more '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

• datalink (0 or more 'datalink' node)
  • message : name of the datalink (uplink) message to be parsed
  • fun : name of the function called when a message arrived

• 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)
    • type : the type of flag, possible values are "define" or "D", "include" or "I" (ex: name="$(ARCH_SRC)" type="include" -> target.CFLAGS += -I$(ARCH_SRC) ) (default is "define")
  • 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

If modules are loaded with periodical functions that are not locked, a new tab will automatically appear in the setting page of the GCS that allows you to start and stop them.

An other possibility is that any file that includes the header "modules.h" can start or stop the periodic tasks.