Difference between revisions of "Modules"

From PaparazziUAV
Jump to navigation Jump to search
(added info about x_FREQ and x_PERIOD defines)
(add autoload)
 
(18 intermediate revisions by 4 users not shown)
Line 6: Line 6:
=== Available modules ===
=== Available modules ===


See the [[Modules_list|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 and short doc for all modules in the master branch can be found at the [http://docs.paparazziuav.org/latest/onboard_modules.html 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 even easier there is a helper tool called "create_module" in the main Paparazzi directory. Try it, you'll be surprised how easy it is to start your own module with the help of this tool.  


=== In the airframe file ===
=== In the airframe file ===
Line 23: Line 29:
</source>
</source>
}}
}}
* 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 main_freq parameter (in Hz) is optional. If present, it allows to specify the frequency of the main loop. Default is the ''main periodic frequency'' of the autopilot. 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 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.
* The child "configure" generates a makefile variable.
{| class="wikitable"
|-
| Since '''v5.8''' it is possible to safely replace ''subsystem'' by ''module'' in your airframe file. The roadmap of Paparazzi is to convert existing [[subsystems]] to modules.
As a result, modules can be loaded using the same format than subsystems, as children of the '''firmware''' node.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="...">
  <module name="demo_module"/>
  <module name="dummy">
  <define name="BLA" value="1"/>
  <define name="BLUB"/>
  <configure name="FOO" value="BAR"/>
  </module>
  <target name="..." board="...">
  <module name="something" type="sometype"/>
  </target>
</modules>
</source>
}}
The '''modules''' node is then only needed if a custom ''main_freq'' parameter need to be specified.
|}


=== In the module file ===
=== In the module file ===
Line 34: Line 64:
  <!DOCTYPE module SYSTEM "module.dtd">
  <!DOCTYPE module SYSTEM "module.dtd">
  <module name="demo_module" dir="demo_module">
  <module name="demo_module" dir="demo_module">
   <depend require="bla.xml" conflict="boo"/>
   <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>
  <settings>
    <dl_settings name="bla">
      <dl_setting min="0" max="5" step="1" var="bla_bla" shortname="bb"/>
    </dl_settings>
  <settings>
  <depends>foo.xml,bar|baz</depends>
  <conficts>boo</conflicts>
   <header>
   <header>
   <file name="demo_module.h"/>
   <file name="demo_module.h"/>
Line 45: Line 89:
     #Raw makefile section
     #Raw makefile section
   </raw>
   </raw>
  <define name="USE_SOMETHING" value="$(SOMETHING)"/>
   <define name="DEMO_MODULE_LED" value="2"/>
   <define name="DEMO_MODULE_LED" value="2"/>
   <file name="demo_module.c"/>
   <file name="demo_module.c"/>
Line 54: Line 99:
* module
* module
** name : this parameter is the name of the module (mandatory)
** 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
** dir : the name of the directory in '''sw/airborne/modules''' where the source code is located (in the above example: 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 [http://paparazzi.github.com/docs/latest/onboard_modules.html generated docs] (mandatory).
** define: describe the possible define flags for this module with default values and a short description (usually called from the [[Airframe_Configuration|airframe firmware section]])
** configure: describe the possible configuration options for this module with default values and a short description (usually called from the [[Airframe_Configuration|airframe firmware section]])
** section: describe the parameters that can be added as a section in the [[Airframe_Configuration|airframe configuration file]]
* settings_file (0 or more)
** file name of a settings xml file
* settings (0 or more): use the same format than systems [[Settings]]
** target: a list of targets allowed or forbidden for which embedded settings should be used
** dl_settings node with a tab name
*** dl_setting: setting description, see [[Settings]] page for details
* depends (0 or 1 'depends' node)
** comma separated list of required modules
** allows to specify OR dependencies with pipe (|) similar to Debian depends, ex: <code>foo,bar|baz</code> would 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)
<div class="toccolours mw-collapsible mw-collapsed" style="width:800px">
Prior to '''v5.3.0_testing''' we had one <tt>depend</tt> node instead of <tt>depends</tt> and <tt>conflicts</tt>:
<div class="mw-collapsible-content">'depend' node used prior to '''v5.3_devel-438-g8be5c42'''):
* depend (0 or 1 'depend' node)
* depend (0 or 1 'depend' node)
** require : the list of required modules
** require : the list of required modules
Line 61: Line 127:
** the elements of a list are separated with a pipe (|), ex: "bla|boo"
** 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)
** the elements can be a xml file (in conf/modules) or a module name (in sw/airborne/modules)
</div></div>
* 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)
* autoload (0 or 1 'autoload' node)
** name : the name of the module which should also be automatically loaded


* header (0 or 1 'header' node)
* header (0 or 1 'header' node)
Line 85: Line 158:


* makefile (0 or more 'makefile' node)
* makefile (0 or more 'makefile' node)
** target : a list of build targets separated with pipes (ex: <makefile target="tunnel|foo">) (default is "ap|sim")
** 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
** 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)
*** name : name of the define (ex: name="USE_MODULE_LED" -> target.CFLAGS += -DUSE_MODULE_LED) (mandatory)
Line 92: Line 165:
** file
** 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)
*** 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)
** 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)
*** 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
** raw : allows to define a raw makefile section


Line 115: Line 190:
  <message name="SOME_MODULE_MSG" period="2" module="module_name"/>
  <message name="SOME_MODULE_MSG" period="2" module="module_name"/>
</source>
</source>
This functionality was removed again in v5.9 ([https://github.com/paparazzi/paparazzi/pull/1678 #1678]), since it is not needed anymore with the <tt>register_periodic_telemetry</tt> functionality we have since v5.0.


[[Category:Developer_Documentation]] [[Category:Modules]]
[[Category:Developer_Documentation]] [[Category:Modules]]

Latest revision as of 15:23, 17 June 2016

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 even easier there is a helper tool called "create_module" in the main Paparazzi directory. Try it, you'll be surprised 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 the main periodic frequency of the autopilot. 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.
Since v5.8 it is possible to safely replace subsystem by module in your airframe file. The roadmap of Paparazzi is to convert existing subsystems to modules.

As a result, modules can be loaded using the same format than subsystems, as children of the firmware node.

File: conf/airframes/myplane.xml
 <firmware name="...">
  <module name="demo_module"/>
  <module name="dummy">
   <define name="BLA" value="1"/>
   <define name="BLUB"/>
   <configure name="FOO" value="BAR"/>
  </module>
  <target name="..." board="...">
   <module name="something" type="sometype"/>
  </target>
 </modules>

The modules node is then only needed if a custom main_freq parameter need to be specified.

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>
  <settings>
    <dl_settings name="bla">
      <dl_setting min="0" max="5" step="1" var="bla_bla" shortname="bb"/>
    </dl_settings>
  <settings>
  <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 example: 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
  • settings_file (0 or more)
    • file name of a settings xml file
  • settings (0 or more): use the same format than systems Settings
    • target: a list of targets allowed or forbidden for which embedded settings should be used
    • dl_settings node with a tab name
      • dl_setting: setting description, see Settings page for details
  • 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|baz would 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' node used prior to v5.3_devel-438-g8be5c42):
  • 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)
  • autoload (0 or 1 'autoload' node)
    • name : the name of the module which should also be automatically loaded
  • 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"/>

This functionality was removed again in v5.9 (#1678), since it is not needed anymore with the register_periodic_telemetry functionality we have since v5.0.