Mirrors_Framework/paparazzi
1
0
Fork 0
mirror of https://github.com/paparazzi/paparazzi.git synced 2026-05-09 14:18:00 +08:00
Code Issues Actions 27 Packages Projects Releases Wiki Activity

[doc] Update paparazzicenter doc and add airframe doc. (#3398)

Browse Source 
* Update paparazzicenter doc and add airframe doc.
* remove empty files.

---------

Co-authored-by: Fabien-B <fabien.bonneval@gmail.com>
Co-authored-by: Florian Sansou <florian.sansou@enac.fr>
This commit is contained in:
Florian Sansou
2025-02-03 14:11:12 +01:00
committed by GitHub
parent 02b08b08c4
commit aadd2a5c01
12 changed files with 363 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/sphinx/requirements.txt
+1
View File
@@ -1,4 +1,5 @@
Sphinx==4.2 Sphinx==4.2
sphinx_rtd_theme==1.1.1 sphinx_rtd_theme==1.1.1
lxml lxml
myst-parser
doc/sphinx/source/conf.py
+7 -2
View File
@@ -40,17 +40,22 @@ extensions = [
'sphinx.ext.todo', 'sphinx.ext.todo',
'sphinx.ext.viewcode', 'sphinx.ext.viewcode',
'sphinx.ext.githubpages', 'sphinx.ext.githubpages',
'myst_parser',
'modules_parser', 'modules_parser',
] ]
myst_enable_extensions = [
"colon_fence",
]
myst_heading_anchors = 3
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
# The suffix(es) of source filenames. # The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string: # 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. # The encoding of source files.
# #
doc/sphinx/source/tutorials/beginner/airframe_setup.rst
-9
View File
@@ -1,9 +0,0 @@
.. tutorials beginner airframe_setup
======================
Airframe Setup
======================
TBD
doc/sphinx/source/tutorials/beginner/flight_plan_setup.rst
-9
View File
@@ -1,9 +0,0 @@
.. tutorials beginner flight_plan
======================
Flight Plan Setup
======================
TBD
doc/sphinx/source/tutorials/beginner/gcs_setup.rst
-9
View File
@@ -1,9 +0,0 @@
.. tutorials beginner gcs_setup
======================
GCS Setup
======================
TBD
doc/sphinx/source/tutorials/beginner/index_beginner.rst
-4
View File
@@ -8,11 +8,7 @@ TBD
.. toctree :: .. toctree ::
use_joystick use_joystick
gcs_setup
airframe_setup
add_drones add_drones
flight_plan_setup
testing_and_tuning
sensor_calibration sensor_calibration
doc/sphinx/source/tutorials/beginner/testing_and_tuning.rst
-9
View File
@@ -1,9 +0,0 @@
.. tutorials beginner testing_and_tuning
======================
Testing and Tuning
======================
TBD
doc/sphinx/source/tutorials/intermediate/index_intermediate.rst
-1
View File
@@ -7,7 +7,6 @@ Intermediate
TBD TBD
.. toctree :: .. toctree ::
write_module
create_radio create_radio
create_joystick create_joystick
doc/sphinx/source/tutorials/intermediate/write_module.rst
-9
View File
@@ -1,9 +0,0 @@
.. tutorials intermediate
======================
Write a New Module
======================
TBD
doc/sphinx/source/user_guide/airframe.md
+330
View File
@@ -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):
<details>
<summary>Airframe example</summary>
``` XML
<!DOCTYPE airframe SYSTEM "../airframe.dtd">
<airframe name="myAmazingAirframe">
<description>
This is my airframe
</description>
<firmware name="rotorcraft">
<configure name="PERIODIC_FREQUENCY" value="500"/>
<configure name="AHRS_PROPAGATE_FREQUENCY" value="$(PERIODIC_FREQUENCY)"/>
<target name="ap" board="tawaki_2.0">
<module name="radio_control" type="sbus"/>
<configure name="BARO_PERIODIC_FREQUENCY" value="50"/>
<define name="RADIO_KILL_SWITCH" value="RADIO_GAIN1"/>
</target>
<target name="nps" board="pc">
<module name="fdm" type="jsbsim"/>
<module name="radio_control" type="ppm"/>
</target>
<module name="gps" type="ublox">
<configure name="GPS_BAUD" value="B115200"/>
</module>
<module name="telemetry" type="xbee_api"/>
<module name="ins" type="ekf2"/>
<module name="actuators" type="dshot"/>
<module name="stabilization" type="indi"/>
<module name="guidance" type="indi"/>
<module name="motor_mixing"/>
</firmware>
<servos driver="DShot">
<servo name="FR" no="3" min="0" neutral="100" max="2000"/>
<servo name="BR" no="4" min="0" neutral="100" max="2000"/>
<servo name="BL" no="2" min="0" neutral="100" max="2000"/>
<servo name="FL" no="1" min="0" neutral="100" max="2000"/>
</servos>
<commands>
<axis name="ROLL" failsafe_value="0"/>
<axis name="PITCH" failsafe_value="0"/>
<axis name="YAW" failsafe_value="0"/>
<axis name="THRUST" failsafe_value="0"/>
</commands>
<command_laws>
<set servo="FR" value="autopilot_get_motors_on() ? actuators_pprz[0] : -MAX_PPRZ"/>
<set servo="BR" value="autopilot_get_motors_on() ? actuators_pprz[1] : -MAX_PPRZ"/>
<set servo="BL" value="autopilot_get_motors_on() ? actuators_pprz[2] : -MAX_PPRZ"/>
<set servo="FL" value="autopilot_get_motors_on() ? actuators_pprz[3] : -MAX_PPRZ"/>
</command_laws>
<section name="GUIDANCE_H" prefix="GUIDANCE_H_">
<define name="MAX_BANK" value="30" unit="deg"/>
<define name="PGAIN" value="41"/>
<define name="DGAIN" value="108"/>
<define name="IGAIN" value="20"/>
<define name="NGAIN" value="0"/>
<!-- feedforward -->
<define name="AGAIN" value="0"/>
<define name="REF_MAX_SPEED" value="0.5"/>
<define name="REF_MAX_ACCEL" value="2."/>
</section>
<section name="MIXING" prefix="MOTOR_MIXING_">
<define name="TYPE" value="QUAD_X"/>
<define name="REVERSE" value="TRUE"/>
</section>
</airframe>
```
</details>
-------------------
Lets break it up in digestable chunks.
```XML
<!DOCTYPE airframe SYSTEM "../airframe.dtd">
```
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
<airframe name="myAmazingAirframe">
<description> This is my airframe </description>
<firmware name="rotorcraft">
<target name="ap" board="tawaki_2.0">
<module name="radio_control" type="sbus"/>
</target>
<module name="gps" type="ublox">
<configure name="GPS_BAUD" value="B115200"/>
</module>
<module name="telemetry" type="xbee_api"/>
</firmware>
...
</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`. <br/>
The included module is the file `<name>[_<type>].xml` from the `conf/modules` directory.
:::{admonition} Example
The following element will add the `actuators_dshot` module:
```XML
<module name="actuators" type="dshot"/>
```
:::
## 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
<configure name="MODEM_PORT" value="UART2">
```
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
<define name="MAX_ROLL" value="50" unit="deg"/>
```
Some defines do not need a value:
```XML
<define name="DEBUG_ALT_KALMAN">
```
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
<section name="MIXING" prefix="MOTOR_MIXING_">
<define name="TYPE" value="QUAD_X"/>
<define name="REVERSE" value="TRUE"/>
</section>
```
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
<servos driver="DShot">
<servo name="FR" no="3" min="0" neutral="100" max="2000"/>
<servo name="BR" no="4" min="0" neutral="100" max="2000"/>
<servo name="BL" no="2" min="0" neutral="100" max="2000"/>
<servo name="FL" no="1" min="0" neutral="100" max="2000"/>
</servos>
```
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
<firmware name="rotorcraft">
...
<module name="actuators" type="dshot"/>
<module name="actuators" type="pwm"/>
...
</firmware>
<servos driver="DShot">
<servo name="FR" no="3" min="0" neutral="100" max="2000"/>
<servo name="BR" no="4" min="0" neutral="100" max="2000"/>
<servo name="BL" no="2" min="0" neutral="100" max="2000"/>
<servo name="FL" no="1" min="0" neutral="100" max="2000"/>
</servos>
<servos driver="Pwm">
<servo name="SWITCH" no="1" min="1000" neutral="1500" max="2000"/>
</servos>
```
:::
## 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
<commands>
<axis name="ROLL" failsafe_value="0"/>
<axis name="PITCH" failsafe_value="0"/>
<axis name="YAW" failsafe_value="0"/>
<axis name="THRUST" failsafe_value="0"/>
</commands>
```
## 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
<set servo="<servo_name>" value="<value>"/>
```
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
<command_laws>
<set servo="FR" value="autopilot_get_motors_on() ? actuators_pprz[0] : -MAX_PPRZ"/>
<set servo="BR" value="autopilot_get_motors_on() ? actuators_pprz[1] : -MAX_PPRZ"/>
<set servo="BL" value="autopilot_get_motors_on() ? actuators_pprz[2] : -MAX_PPRZ"/>
<set servo="FL" value="autopilot_get_motors_on() ? actuators_pprz[3] : -MAX_PPRZ"/>
</command_laws>
```
Or for a fixedwing:
``` XML
<command_laws>
<let var="aileron" value="@ROLL * 0.3"/>
<let var="elevator" value="@PITCH * 0.7"/>
<set servo="THROTTLE" value="@THROTTLE"/>
<set servo="ELEVON_LEFTSIDE" value="$elevator + $aileron"/>
<set servo="ELEVON_RIGHTSIDE" value="$elevator - $aileron"/>
</command_laws>
```
where transitory variables (**aileron** and **elevator**) are created to assign a control combination to the servo.
doc/sphinx/source/user_guide/index_user_guide.rst
+2 -1
View File
@@ -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`! Start conquering the wolrd, by making incredible :doc:`flight_plans`!
.. toctree:: .. toctree::
:maxdepth: 3 :maxdepth: 1
more_on_paparazzi_center more_on_paparazzi_center
airframe
flight_plans flight_plans
communication communication
radio radio
doc/sphinx/source/user_guide/more_on_paparazzi_center.rst
+23 -17
View File
@@ -4,25 +4,28 @@
More on the Paparazzi Center 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 The set, also called *conf* contains the configuration of each aircrafts (a.k.a. **AC**):
- Id
- airframe
- flight plan
- radio
- telemetry
- settings
- GUI color
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 .. code-block:: xml
@@ -32,7 +35,7 @@ To hold you personnal confs, create a new file with this simple content in *conf
Tools 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. 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 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:: .. warning::