Modules

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

See FirmwareArchitecture and Subsystems for the differences of modules to subsystems.

Available modules

See the list of modules.

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">
  <define name="BLA" value="1"/>
  <define name="BLUB"/>
  <configure name="FOO" value="BAR"/>
 </load>
</modules>

• The main_freq parameter (in Hz) is optional. If present, it allows to specify the frequency of the main loop. Default is 60 Hz. If not needed to be specified, then the first line is: <modules>
• The children "define" generate compilation defines for all the targets of a module and can be used with or without value. It allows to keep the module description more generic add to place the airframe dependent parameters in the airframe xml file.
• The child "configure" generates a makefile variable.

In the module file

The modules description files are located in conf/modules.

<!DOCTYPE module SYSTEM "module.dtd">
<module name="demo_module" dir="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>
  <define name="DEMO_MODULE_LED" value="2"/>
  <file name="demo_module.c"/>
 </makefile>
</module>

• module
  • name : this parameter is the name of the module (mandatory)
  • dir : the name of the directory in sw/airborne/modules where the source code is located (in the above exemple: sw/airborne/modules/demo_module), if not specified, the name of the module is used as default directory name

• 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")
  • define : each define node specifies a CFLAGS for the current targets
    • name : name of the define (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 define, 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 (located in "sw/airborne/modules/<dir_name>") to add in the Makefile (ex: name="demo_module.c" -> target.srcs += modules/<dir_name>/demo_module.c)
  • file_arch (hardware related code)
    • name : the name of the c file (located in "sw/airborne/arch/<ARCH>/modules/<dir_name>") add in the Makefile (ex: name="demo_module_hw.c" -> target.srcs += arch/<ARCH>/modules/<dir_name>/demo_module_hw.c)
  • raw : allows to define a raw makefile section

If the compilation target is not supported by the module, it will be automatically unloaded. This may require a 'clean_ac' to work.

In the airborne code

The code corresponding to a module should be placed in the directory "sw/airborne/modules/<dir_name>" where dir_name must match the one in your conf file (attribute "dir" if specified, "name" otherwise).

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.

Telemetry

In the telemetry file, if a module name is specified in a field message, it will be included in the telemetry messages only if the corresponding module is loaded.

<message name="SOME_MODULE_MSG" period="2" module="module_name"/>