Difference between revisions of "Modules"

From PaparazziUAV
Jump to navigation Jump to search
(link to generated modules docs)
Line 7: Line 7:


There is a special page listing all currently available modules to simply extend your Paparazzi autopilot board possibilities. [[Modules_list| Go here to inspect this list of modules]].
There is a special page listing all currently available modules to simply extend your Paparazzi autopilot board possibilities. [[Modules_list| Go here to inspect this list of modules]].
The auto-generated list for all modules in the master branch can be found in the [http://paparazzi.github.com/docs/latest/onboard_modules.html doxygen docs/latest/onboard_modules.html]


=== In the airframe file ===
=== In the airframe file ===

Revision as of 06:00, 30 December 2012

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

There is a special page listing all currently available modules to simply extend your Paparazzi autopilot board possibilities. Go here to inspect this list of modules.

The auto-generated list for all modules in the master branch can be found in the doxygen docs/latest/onboard_modules.html

In the airframe file

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

File: conf/airframes/myplane.xml
 <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.

File: conf/modules/mymodule.xml
 <!DOCTYPE module SYSTEM "module.dtd">
 <module name="demo_module" dir="demo_module">
  <doc>
   <description>Demo module</description>
   <configure name="SOMETHING" value="S1|S2|S3" description="The thing to use"/>
   <define name="DEMO_MODULE_LED" value="LED_X" description="LED Selection"/>
  </doc>
  <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="USE_SOMETHING" value="$(SOMETHING)"/>
   <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
  • doc (0 or 1 'doc' node)
    • description: a description of the module
    • define: describe the possible define flags for this module with default values and a short description (usually called from the airframe firmware section)
    • configure: describe the possible configuration options for this module with default values and a short description (usually called from the airframe firmware section)
    • section: describe the parameters that can be added as a section in the airframe configuration file
  • 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)
      • dir : select a directory for this file only (overrides the default directory)
    • 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)
      • dir : select a directory for this file only (overrides the default directory)
    • 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). There are also defines generated for the frequency and period of every periodic functions of the module that can be used in the code: <PERIODIC_FUNCTION_NAME>_FREQ and <PERIODIC_FUNCTION_NAME>_PERIOD.

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"/>