From aadd2a5c01a82911cb92510e718b191a16619415 Mon Sep 17 00:00:00 2001 From: Florian Sansou Date: Mon, 3 Feb 2025 14:11:12 +0100 Subject: [PATCH] [doc] Update paparazzicenter doc and add airframe doc. (#3398) * Update paparazzicenter doc and add airframe doc. * remove empty files. --------- Co-authored-by: Fabien-B Co-authored-by: Florian Sansou --- doc/sphinx/requirements.txt | 1 + doc/sphinx/source/conf.py | 9 +- .../tutorials/beginner/airframe_setup.rst | 9 - .../tutorials/beginner/flight_plan_setup.rst | 9 - .../source/tutorials/beginner/gcs_setup.rst | 9 - .../tutorials/beginner/index_beginner.rst | 4 - .../tutorials/beginner/testing_and_tuning.rst | 9 - .../intermediate/index_intermediate.rst | 1 - .../tutorials/intermediate/write_module.rst | 9 - doc/sphinx/source/user_guide/airframe.md | 330 ++++++++++++++++++ .../source/user_guide/index_user_guide.rst | 3 +- .../user_guide/more_on_paparazzi_center.rst | 40 ++- 12 files changed, 363 insertions(+), 70 deletions(-) delete mode 100644 doc/sphinx/source/tutorials/beginner/airframe_setup.rst delete mode 100644 doc/sphinx/source/tutorials/beginner/flight_plan_setup.rst delete mode 100644 doc/sphinx/source/tutorials/beginner/gcs_setup.rst delete mode 100644 doc/sphinx/source/tutorials/beginner/testing_and_tuning.rst delete mode 100644 doc/sphinx/source/tutorials/intermediate/write_module.rst create mode 100644 doc/sphinx/source/user_guide/airframe.md diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt index bb0544bfde..5a845f4a21 100644 --- a/doc/sphinx/requirements.txt +++ b/doc/sphinx/requirements.txt @@ -1,4 +1,5 @@ Sphinx==4.2 sphinx_rtd_theme==1.1.1 lxml +myst-parser diff --git a/doc/sphinx/source/conf.py b/doc/sphinx/source/conf.py index bada94b8e5..96bddc6195 100644 --- a/doc/sphinx/source/conf.py +++ b/doc/sphinx/source/conf.py @@ -40,17 +40,22 @@ extensions = [ 'sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.githubpages', + 'myst_parser', 'modules_parser', ] +myst_enable_extensions = [ + "colon_fence", +] +myst_heading_anchors = 3 + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = ['.rst'] # The encoding of source files. # diff --git a/doc/sphinx/source/tutorials/beginner/airframe_setup.rst b/doc/sphinx/source/tutorials/beginner/airframe_setup.rst deleted file mode 100644 index ad93fb81db..0000000000 --- a/doc/sphinx/source/tutorials/beginner/airframe_setup.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. tutorials beginner airframe_setup - -====================== -Airframe Setup -====================== - -TBD - - diff --git a/doc/sphinx/source/tutorials/beginner/flight_plan_setup.rst b/doc/sphinx/source/tutorials/beginner/flight_plan_setup.rst deleted file mode 100644 index 1326d4bb06..0000000000 --- a/doc/sphinx/source/tutorials/beginner/flight_plan_setup.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. tutorials beginner flight_plan - -====================== -Flight Plan Setup -====================== - -TBD - - diff --git a/doc/sphinx/source/tutorials/beginner/gcs_setup.rst b/doc/sphinx/source/tutorials/beginner/gcs_setup.rst deleted file mode 100644 index 29467f9088..0000000000 --- a/doc/sphinx/source/tutorials/beginner/gcs_setup.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. tutorials beginner gcs_setup - -====================== -GCS Setup -====================== - -TBD - - diff --git a/doc/sphinx/source/tutorials/beginner/index_beginner.rst b/doc/sphinx/source/tutorials/beginner/index_beginner.rst index c6ddf41ebd..6110370297 100644 --- a/doc/sphinx/source/tutorials/beginner/index_beginner.rst +++ b/doc/sphinx/source/tutorials/beginner/index_beginner.rst @@ -8,11 +8,7 @@ TBD .. toctree :: use_joystick - gcs_setup - airframe_setup add_drones - flight_plan_setup - testing_and_tuning sensor_calibration diff --git a/doc/sphinx/source/tutorials/beginner/testing_and_tuning.rst b/doc/sphinx/source/tutorials/beginner/testing_and_tuning.rst deleted file mode 100644 index e213f181b3..0000000000 --- a/doc/sphinx/source/tutorials/beginner/testing_and_tuning.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. tutorials beginner testing_and_tuning - -====================== -Testing and Tuning -====================== - -TBD - - diff --git a/doc/sphinx/source/tutorials/intermediate/index_intermediate.rst b/doc/sphinx/source/tutorials/intermediate/index_intermediate.rst index 28f0c340f5..b0675a46d0 100644 --- a/doc/sphinx/source/tutorials/intermediate/index_intermediate.rst +++ b/doc/sphinx/source/tutorials/intermediate/index_intermediate.rst @@ -7,7 +7,6 @@ Intermediate TBD .. toctree :: - write_module create_radio create_joystick diff --git a/doc/sphinx/source/tutorials/intermediate/write_module.rst b/doc/sphinx/source/tutorials/intermediate/write_module.rst deleted file mode 100644 index 1efa3301ae..0000000000 --- a/doc/sphinx/source/tutorials/intermediate/write_module.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. tutorials intermediate - -====================== -Write a New Module -====================== - -TBD - - diff --git a/doc/sphinx/source/user_guide/airframe.md b/doc/sphinx/source/user_guide/airframe.md new file mode 100644 index 0000000000..e935435dc3 --- /dev/null +++ b/doc/sphinx/source/user_guide/airframe.md @@ -0,0 +1,330 @@ +# Airframe + +The airframe file is the most important configuration file and contains all the hardware and software settings for your airframe. It describes what hardware you have and which firmware, sensors, algorithms, etc. you want to use and also holds your configuration parameters. All gains, trims, and behavior settings are defined with standard XML elements. + +The XML airframe configuration file is located in `conf/airframes/**/`, and it looks like this (this is *not* a complete example): + +
+ +Airframe example + +``` XML + + + + + + This is my airframe + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + +
+ +
+ + +
+ + +``` + +
+ +------------------- + +Lets break it up in digestable chunks. + + +```XML + +``` + +This first line is always a doctype declaration. It specifies the relative path to `airframe.dtd`, which is located in the `conf/airframe` directory. In the above example, our airframe file is located in a subdirectory of `conf/airframe`, which explains the `../`. + +The root element `airframe` has the `name` attribute. You can add a description of your airframe is the `description` element. + +```XML + + + This is my airframe + + + + + + + + + + + + + + + ... + + +``` + +## Firmware + +The next element is the `firmware` node. Its `name` attribute can take two values: `fixedwing` or `rotorcraft`. + +### Target + +The `target` tag define what autopilot hardware you will be using. + +The `name` attribute can be `sim` or `nps` for simulation, or `ap` for real hardware. + +When using `ap`, the `board` attribute specifies which board you are using, e.g. `tawaki_2.0`, `apogee_1.0_chibios`, `cube_orangeplus`, ... +All boards can be found in `/conf/boards`. + +You can have multiple targets in an airframe file. Its common to have a simulation target along with the `ap` target. + +### Modules + +**Modules** are the building block of paparazzi. They include code and configuration for that code. + +Include modules in you firmware with the `module` element. Modules can be restricted to a particular target by including it as a child element of this target. + +The `module` element has a mandatory attribute `name` and an optionnal attribute `type`.
+The included module is the file `[_].xml` from the `conf/modules` directory. + +:::{admonition} Example +The following element will add the `actuators_dshot` module: +```XML + +``` +::: + + + + +## Defines, configures and sections + +Firmware and modules are configured in two ways: defines and configures. +The documentation associated with each module list the available configurations. + +### Configures + +Configures can only be used in the *firmware* element, either as direct child of the *firmware* node or as child of a *target* or *module*. + +Configures have this syntax: + +```XML + +``` + +There is generaly a default value. If the default value suits you, its not needed to redefine it. + +:::{note} Configures create a makefile variable that can later be used in the build process, e.g. `$(MODEM_PORT)` +::: + + +### Defines + +Defines have a similar syntax. A unit can optionaly be specified to automatically convert from this unit to the standard unit: + +```XML + +``` + +Some defines do not need a value: + +```XML + +``` + +Defines can be used as child of the *firmware* node as well as in a *section* node. In a *section* node, the section prefix in prefixed to the define name. + +:::{admonition} Example + ```XML +
+ + +
+ ``` + + This part of the airframe will produce this code in `airframe.h`: + + ```C + #define MOTOR_MIXING_TYPE QUAD_X + #define MOTOR_MIXING_REVERSE TRUE + ``` +::: + +:::{note} + - A define in the *firmware* node will produce a compilation flag for GCC, e.g. `-DUSE_INS_NAV_INIT=TRUE`. + - A define in a *section* node will produce `#define` directives in the generated `airframe.h` file. +::: + +:::{warning} Although syntax is similar, defines and configures are not interchangeable +::: + +### Sections + +A section is a group of defines with an optional prefix. See above. + +(servo_section)= +## Servos + +Actuators are configured in the *servos* element. The *driver* attribute is related to the loaded actuator module. + +For each *servo* is configured: +- **name**: name by which it will be referenced in later part of the airframe +- **no**: servo number. Usually related to the autopilot board +- **min**, **neutral**, **max**: values in the driver's unit. + +```XML + + + + + + +``` + +If you have multiple actuators modules, there should be a *servos* node for each of them + + +:::{admonition} Example + + In this example, two actuator modules are loaded: **dshot** for the 4 motors, et **pwm** for a servomotor. + + ```XML + + ... + + + ... + + + + + + + + + + + + + + ``` + +::: + + +## Commands + +The commands lists the abstract commands you need to control the aircraft. + +Each command is also associated with a failsafe value which will be used if no controller is active, for example during initialization of the autopilot board. The range of these values is [-9600, 9600]. For *THROTTLE*, the range is [0, 9600] and in the corresponding servo definition the neutral and min are usually the same for PWM based servos (see below). + + +``` XML + + + + + + +``` + + + +## Command laws + +The command laws section acts as the interface between the commands, which are calculated by the stabilisation module, and the servos, which are the physical actuators. The operation of the line +```XML + +``` +can be understood as we apply the **value** in the servo name **servo_name**. +From this, we can deduce that the servo definition (see section {ref}`servo_section`) must contain a corresponding **name**. + +Regarding the values attributed to actuators, when employing the INDI method or a control law utilising **actuators_pprz**, the following line should be used: +```XML +autopilot_get_motors_on() ? actuators_pprz[0] : -MAX_PPRZ +``` +This allows the value calculated by the control law to be assigned only when the motors are started, otherwise the motors are stopped (-MAX_PPRZ). In the case of servomotors, it may be necessary to assign the value 0, which corresponds to a neutral value. + +**actuators_pprz** is an array in which the control law assigns the values calculated at each iteration. + +This gives us a similar block for a quadcopter: +``` XML + + + + + + +``` + +Or for a fixedwing: +``` XML + + + + + + + +``` + +where transitory variables (**aileron** and **elevator**) are created to assign a control combination to the servo. diff --git a/doc/sphinx/source/user_guide/index_user_guide.rst b/doc/sphinx/source/user_guide/index_user_guide.rst index 30e1807e4b..a92a2f3a37 100644 --- a/doc/sphinx/source/user_guide/index_user_guide.rst +++ b/doc/sphinx/source/user_guide/index_user_guide.rst @@ -9,9 +9,10 @@ Welcome to the second level of the Paparazzi UAV user guide! It will explain how Start conquering the wolrd, by making incredible :doc:`flight_plans`! .. toctree:: - :maxdepth: 3 + :maxdepth: 1 more_on_paparazzi_center + airframe flight_plans communication radio diff --git a/doc/sphinx/source/user_guide/more_on_paparazzi_center.rst b/doc/sphinx/source/user_guide/more_on_paparazzi_center.rst index c95b1f3297..4e8c87fe6d 100644 --- a/doc/sphinx/source/user_guide/more_on_paparazzi_center.rst +++ b/doc/sphinx/source/user_guide/more_on_paparazzi_center.rst @@ -4,25 +4,28 @@ More on the Paparazzi Center ============================ -The Paparazzi Center is configured by two files : the aircrafts configuration file and the control panel file. +The Paparazzi Center is configured by two files : the aircrafts configuration file (a.k.a. "the set") and the control panel file. -These files are located at ``conf/conf.xml`` and ``conf/control_panel.xml``. To make configuration easier, these files are often symbolic links to actual files, usually located in ``conf/userconf/``. +Select the ones you use in the paparazzi center: select the *set* in the top right drop-down, +and the control panel in the top left drop-down of the *Operation* tab. -Conf ----- -``conf.xml`` contains the configuration of each aircrafts: +Set +--- -- Name -- Id -- airframe -- flight plan -- radio -- telemetry -- settings -- GUI color +The set, also called *conf* contains the configuration of each aircrafts (a.k.a. **AC**): -To hold you personnal confs, create a new file with this simple content in *conf/userconf/*, and use the *start.py* configuration utility to use it in Paparazzi : +- **Name** +- **Id**: a uniq number within the set, in the range [1-255]. +- **GUI color** +- **airframe**: Describes nearly all the configuration. +- **flight plan** +- **radio**: configuration of the RC channels +- **telemetry**: Describes which messages will be send to the ground and/or recorded on board. +- **settings**: values that can be changed during the flight. + + +Make your own set by creating a new file with this simple content in *conf/userconf/*, and selecting it in the paparazzi center: .. code-block:: xml @@ -32,7 +35,7 @@ To hold you personnal confs, create a new file with this simple content in *conf Tools ----- -The *Tools* in the Paparazzi Center come from the ``conf/tools`` directory. Each xml file produce a new entry in the *Tools* menu. You can add you own tools by creating a new xml file in this directory, and restarting the Paparazzi Center. +The *Tools* in the Paparazzi Center come from the ``conf/tools`` directory. Each xml file produce a new entry in the *Add tool* menu. You can add you own tools by creating a new xml file in this directory, and restarting the Paparazzi Center. There are many tools that you will probably never use. You can remove these from the menu by adding their name to the ``blacklisted`` file. @@ -40,9 +43,12 @@ There are many tools that you will probably never use. You can remove these from Sessions & Control panel ------------------------ -``control_panel.xml`` contains the sessions. A session is a set of programs with arguments. +The *control panel* contains the sessions. A session is a set of programs with their arguments. -To define a new session, go to *Session->New* and give it a name. Start all the programs you want, with their correct arguments, then *Session->Save*. +Once all the needed tools are started, either by launching a session or by starting them individually, +you can save them as a session (hamburger button) + +To define a new session, go to the *Operation* tab, start all the tools you want .. warning::