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
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 and short doc for all modules in the master branch can be found at the onboard modules page of the doxygen docs.
Make your own
It is very possible to make your own module and to share it with the world. To make it eaven easier there is a helper tool called "create_module" in the main Paparazzi directory. Try it, you'll be surprized how easy it is to start your own module with the help of this tool.
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 just: <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.
More details about this 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>
<depends>foo.xml,bar|baz</depends>
<conficts>boo</conflicts>
<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
- description: a description of the module. The content of the first line until the dot is treated as the brief description used as the name in the generated docs (mandatory).
- 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
- depends (0 or 1 'depends' node)
- comma separated list of required modules
- allows to specify OR dependencies with pipe (|) similar to Debian depends, ex:
foo,bar|bazwould make it depend on foo AND (bar OR baz) - the elements can be a xml file (in conf/modules) or a module name (as set in the module xml 'name' node)
Prior to v5.3.0_testing we had one depend node instead of depends and conflicts:
- 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)
- conflicts (0 or 1 'conflicts' node)
- comma separated list of conflicting modules
- the elements can be a xml file (in conf/modules) or a module name (as set in the module xml 'name' node)
- 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|nps")
- 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"/>