[doc] Update pprzcenter and GCS presentation. (#3229)

* [doc] Update pprzcenter and GCS presentation. Simplify install instructions. * [doc] Windows install + some fixes
2026-05-09 14:18:00 +08:00 · 2024-01-26 09:01:13 +01:00
parent 1b345804b4
commit 41998a12b3
36 changed files with 5015 additions and 511 deletions
@@ -0,0 +1,38 @@
+.. quickstart first_simu
+
+======================
+Flight Simulation
+======================
+
+Launch the simulation
+=====================
+
+- In the paparazzi center, select the **conf_example.xml** set (top right), then the **Bixler** aircraft (top left).
+- Go to the **Configuration** tab, select the **nps** target, and click the *Build* button (gear icon). 
+- Go to the Operation tab, select the **Simulation** session and launch it with the *Start session* button (play icon).
+- This aircraft have two simulation target, *sim* and *nps*. Since you just build for *nps*, choose this simulator if asked for.
+
+A new window opens, this is the GCS (Ground Control Station).
+
+.. image:: pprzgcs.png
+
+The GCS layout can be changed, but in this layout:
+
+- The map is largest widget. Buttons opening others widgets are overlayed on the left and right side of the map.
+- On the top right, this is the strip panel. Each aircraft have its own strip, which displays the state of the aircraft.
+  Some icons are buttons changing displayed data. E.g. the altitude can be displayed relative to the ground or sea level.
+  The arrow down button below the aircraft color displays another widget: the **command widget**.
+- On the bottom right, this is the flight plan widget.
+
+Now, lets launch the drone:
+
+- In the flight plan, wait for the drone to be in the *Holding point* block, then put it the *Takeoff* block.
+  You can also do it from the *commands* widget.
+- In real life, we would now launch the drone. In simulation, there is a magic button to do so in the *commands* widget.
+  Open the *commands* widget by clicking on the arrow-down button on the bottom left of the strip, and launch the drone with the *Launch* button (top left).
+
+The drone should now move, and the current block will change to "Standby".
+
+You can observe the status of the drone in the strip.
+
+
@@ -1,8 +1,8 @@
-.. quickstart index_quick_start
+.. quickstart index_getting_started

-=================
-Quick Start
-=================
+===============
+Getting Started
+===============

 Welcome to the Paparazzi UAV user guide!

@@ -17,6 +17,5 @@ To start, go to the :doc:`install` page!
    system_overview
    paparazzi_center_tour
    first_simulation
-    gcs_tour
    first_flight
    
@@ -1,10 +1,12 @@
 .. quickstart install

-======================
-Quick Install
-======================
+============
+Installation
+============

-Paparazzi runs best on **Ubuntu 16.04 or higher**, so this quick installation guide is for Ubuntu users. I you have an other OS or if you want more detailled installation, see the :doc:`../installation/index_installation` page.
+Paparazzi runs best on **Ubuntu 16.04 or higher**, so this quick installation guide is for Ubuntu users.
+
+If you want to run it on windows, see the instructions: `Install on Windows`_.

 Open a terminal and execute each lines below. If one fails, ask for help on gitter.

@@ -72,3 +74,23 @@ Finally, launch Paparazzi with
    ./paparazzi

 If all went well the Paparazzi Center should now be running. Please continue to the next page for a guided tour.
+
+Install on Windows
+------------------
+
+Paparazzi do not run natively on windows, but you can run it in the *Windows Subsystem for Linux*.
+
+Install the Windows Subsystem for Linux and the Ubuntu distribution by following the Microsoft documentation,
+then install paparazzi like on a regular Ubuntu.
+
+In older versions of WLS, you may need to install an X server like `VcXsrv <https://sourceforge.net/projects/vcxsrv/>`_
+or `Xming <https://sourceforge.net/projects/xming/>`_.
+You will then need to set the *DISPLAY* environment variable to point at the X server running on your Windows 10 PC :
+
+.. code-block:: bash
+
+    export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2; exit;}'):0
+
+.. note::
+
+    The **Windows Terminal** application is very usefull as it can have multiple tabs and allows you to easily switch between Bash and Powershell.
@@ -0,0 +1,82 @@
+.. quickstart paparazzi_center_tour
+
+.. _paparazzicenter:
+
+=================
+Paparazzi Center
+=================
+
+The Paparazzi Center is a graphical interface for configuring the drones and managing
+the various paparazzi tools.
+
+The drop-down on the top right corner select which set of aircrafts will be used.
+
+Current aircraft is choosen via the top left drop-down.
+The *id* on the left of the aircraft name is the **uniq** identifier of the aircraft among the set, between 0 and 255.
+
+
+.. image:: pprz_center_conf.svg
+
+
+Configuration tab
+==================
+
+The left side of this tab is dedicated to the configuration of the aircraft.
+
+An aircraft is composed of an airframe, a flight plan, some settings, a radio and a telemetry configuration file. These concepts are explained later.
+
+For now, remember that you can select other files, or edit the current file with the button.
+
+.. note::
+
+    The ``Edit`` button open the file with *gedit* by default. You can change it via ``File->Edit Settings->Text Editor``.
+
+
+Once the aircraft is configured, the firmware can be build for a target. 
+
+Some usual targets are:
+
+- **sim**: This basic fixedwing simulator has no IMU simulation or any sensor models (noise, bias, etc) and is mainly intended to validate your flight plan logic.
+- **nps**: NPS is a more advanced rotorcraft and fixedwing simulator with sensor models and commonly uses JSBSim as FDM (Flight Dynamic Model).
+- **ap**: This is for a *real* autopilot.
+
+
+If the selected target is not a simulator, you can choose how you want to upload the
+firmware to your autopilot, then flash it.
+
+Compilation output is shown in the console below.
+
+
+
+Operation tab
+=============
+
+.. image:: pprz_center_operation.png
+
+Sessions are a collection of tools with their arguments.
+Sessions are saved in ``.*control_panel.xml`` files.
+The left side drop-down select which control panel you are using.
+
+Once a session is launched, the tools are listed below.
+Each tool can be stopped/restarted, and removed from the list.
+
+The buttons above the tools list apply to all tools.
+
+Tools can be added to the current session with the *Add tools* button.
+Don't forget to save the session if you want to keep this tool for next time!
+
+The output of the tools is shown in the text area below.
+
+
+
+
+Console panel
+==============
+
+
+
+Now, lets launch a :doc:`first_simulation`!
+
+
+
+
@@ -27,8 +27,7 @@ Contents:
 .. toctree::
    :maxdepth: 2

-    quickstart/index_quick_start
-    installation/index_installation
+    getting_started/index_getting_started
    user_guide/index_user_guide
    developer_guide/index_developer
    tutorials/index_tutorials
@@ -1,7 +0,0 @@
-.. installation hardware_installation fixed_wing
-
-======================
-Fixed-Wing
-======================
-
-TBD
@@ -1,13 +0,0 @@
-.. installation hardware_installation airframe airframes
-
-======================
-Airframes
-======================
-
-Airframes ...
-
-.. toctree::	
-	fixed_wing
-	rotorcraft
-	vtol
-
@@ -1,7 +0,0 @@
-.. installation hardware_installation rotorcraft
-
-======================
-Rotorcraft
-======================
-
-TBD
@@ -1,7 +0,0 @@
-.. installation hardware_installation vtol
-
-======================
-VTOL
-======================
-
-TBD
@@ -1,7 +0,0 @@
-.. installation hardware_installation apogee
-
-======================
-Apogee
-======================
-
-TBD
@@ -1,7 +0,0 @@
-.. installation hardware_installation chimera
-
-======================
-Chimera
-======================
-
-TBD
@@ -1,14 +0,0 @@
-.. installation hardware_installation autopilot autopilots
-
-======================
-Autopilots
-======================
-
-Autopilots ...
-
-.. toctree ::
-
-	apogee
-	chimera
-
-
@@ -1,12 +0,0 @@
-.. installation main_installation hardware
-
-======================
-Hardware
-======================
-
-Hardware installation ...
-
-.. toctree ::
-	airframes/index_airframes
-	autopilots/index_autopilots
-
@@ -1,30 +0,0 @@
-.. installation main_installation index_installation
-
-=================
-Installation
-=================
-
-Paparazzi is easily installed on any laptop or workstation running the Ubuntu Linux OS or virtually any Debian based Linux. Apple Macintosh running Mac OS X system are also fairly well supported. Windows is supported through the WSL2 module (running a Linux kernel inside Windows10).
-
-The steps required to install the software needed to be able to let your UAS fly are:
-
- Install tools and prerequisites needed by Paparazzi
- Download the source code from the source repository
- Compile the Paparazzi software from sourcecode
- Complete any final configuration
-
-.. note::
-
-    If you run **Ubuntu** 18.04 or higher LTS (20.04, 22.04), go to the :doc:`../quickstart/install` page to get quickly running !
-
-.. toctree::
-    :maxdepth: 2
-
-    software/index_software
-
-You will also need to configure your aircraft according to your airframe and autopilot board:
-
-.. toctree::
-    :maxdepth: 2
-
-    hardware/index_hardware
@@ -1,46 +0,0 @@
-.. installation main_installation software
-
-======================
-Software
-======================
-
-Downloading the software
-________________________
-
-The Paparazzi source code is hosted on Github. While you can download it as a tarball from https://github.com/paparazzi/paparazzi/releases, it is recommended to clone the repository with git.
-
-From the directory of your choice type:
-
-::
-
-    git clone --origin upstream https://github.com/paparazzi/paparazzi.git
-
-If you don't want to work with the latest master branch (it may contain some unstable features), check out the released stable version branch:
-
-::
-
-    cd paparazzi
-    git checkout v6.3
-
-
-OS-specific instructions
-________________________
-
-After this point, it is required to install the needed libraries. The procedure depends on the operating system you are using.
-Please follow the instruction below:
-
-.. toctree ::
-	:maxdepth: 2
-	
-	linux
-	mac_os
-	windows
-
-Buiding and running the code
-____________________________
-
-Finally, build the ground station tools:
-
-::
-
-    make
@@ -1,132 +0,0 @@
-.. installation software_installation linux
-
-======================
-Linux
-======================
-
-.. warning::
-
-    This guide may be outdated. See http://wiki.paparazziuav.org/wiki/Installation.
-
-Paparazzi is very easily installed on any laptop or workstation running Ubuntu, Debian (or any of their derivatives).
-
-The steps required to install the software needed to be able to let your UAS fly
-
-* Install the basic Paparazzi dependencies and the ARM cross compiling toolchain
-* Download the source code from the source repository
-* Allow access to your PC hardware connection by adding appropriate Udev rules
-* Compile the binaries from the sources and launch the software
-
-Users of other Linux flavors than a recent Ubuntu or Debian and anyone needing manual control of each individual package can install them independently.
-
-For the impatient
-=================
-
-For Ubuntu add the `paparazzi-uav ppa <https://launchpad.net/~paparazzi-uav/+archive/ubuntu/ppa>`_ (*sudo add-apt-repository ppa:paparazzi-uav/ppa*)
-and install the paparazzi-dev package.
-
-
-.. raw:: html
-
-    <iframe width="425" height="239" src="https://www.youtube.com/embed/SshFJrBuku8" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
-
-
-
-Installation of dependencies
-============================
-______
-Ubuntu
-______
-
-Binary packages for Ubuntu are available for the i386, amd64 and armhf architectures.
-
-Add the installation sources for the Paparazzi software packages. Run from a terminal:
-
-::
-
-    sudo add-apt-repository ppa:paparazzi-uav/ppa
-
-Then update the systems package inventory and install the main Paparazzi software dependencies. This will take some time.
-
-::
-
-    sudo apt-get update 
-    sudo apt-get install paparazzi-dev
-
-______
-Debian
-______
-
-Binary packages for Debian are available for the i386 and amd64 architectures. armhf packages seem to be currently not supported by the OpenSUSE build service.
-
-For Debian Wheezy (7.0), Jessie (8.0) and Stretch (9.0) packages are built using the Open Build Service (OBS) on OpenSUSE Build Service project home:flixr:paparazzi-uav
-
-First add the key:
-
-::
-
-    wget -q "http://download.opensuse.org/repositories/home:/flixr:/paparazzi-uav/Debian_9.0/Release.key" -O- | sudo apt-key add -
-
-Add the appropriate repo, depending on your Debian version to sources.list
-
-::
-
-    echo "deb http://download.opensuse.org/repositories/home:/flixr:/paparazzi-uav/Debian_9.0/ ./" | tee -a /etc/apt/sources.list
-    echo "deb http://download.opensuse.org/repositories/home:/flixr:/paparazzi-uav/Debian_8.0/ ./" | tee -a /etc/apt/sources.list
-    echo "deb http://download.opensuse.org/repositories/home:/flixr:/paparazzi-uav/Debian_7.0/ ./" | tee -a /etc/apt/sources.list
-
-Update the systems package inventory and install the main Paparazzi software dependencies.
-
-::
-
-    sudo apt-get update 
-    sudo apt-get install paparazzi-dev
-
-
-______________________
-ARM embedded toolchain
-______________________
-
-For current Paparazzi versions (v5.0 and above) the gcc-arm-embedded toolchain is recommended, which also supports the STM32F4 with FPU (hardware floating point).
-gcc-arm-none-eabi as Debian/Ubuntu package
-
-This is the recommended method
-
-Note that there are actually two different toolchains available!
-
-* ARM gcc-arm-embedded toolchain with Debian package name gcc-arm-embedded
-
-  * includes libstdc++ and newlib-nano
-
-* Debian gcc-arm-none-eabi toolchain
-
-  * does not include libstdc++
-  * does not include newlib-nano
-
-Both toolchains should work for most use-cases (if you don't need C++ or nano specs), although the ARM gcc-arm-embedded toolchain is better tested.
-
-gcc-arm-embedded toolchain
-__________________________
-
-This is the recommended toolchain
-
-On most Ubuntu versions the gcc-arm-embedded toolchain can be installed as a debian package from the ppa:
-
-::
-
-    sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
-    sudo apt-get update
-    sudo apt-get install gcc-arm-embedded
-
-Previously there was a PPA by terry.guo that contained this toolchain under the package name gcc-arm-none-eabi
-
-gcc-arm-none-eabi Debian toolchain
-__________________________________
-
-Current Debian (jessie) and Ubuntu (14.04 trusty and later) releases have the gcc-arm-none-eabi package in the official repositories (universe), and can be installed with:
-
-::
-
-    sudo apt-get update
-    sudo apt-get install gcc-arm-none-eabi gdb-arm-none-eabi
-
@@ -1,7 +0,0 @@
-.. installation software_installation mac_os
-
-======================
-MAC OS
-======================
-
-TBD
@@ -1,7 +0,0 @@
-.. installation software_installation windows
-
-======================
-Windows
-======================
-
-TBD
@@ -1,32 +0,0 @@
-.. quickstart first_simu
-
-======================
-Flight Simulation
-======================
-
-Launch the simulation
-=====================
-
- In the paparazzi center, select the **Microjet** or **Bixler** aircraft in the *A/C* combobox of the configuration panel.
- Select the **sim** target, and click *Build*. This should build without errors in the console panel, and finish with "DONE".
- Select the **Simulation** session in the execution panel, and click *Execute*.
-
-A new window opens, this is the GCS (Ground Control Station).
-
-.. image:: gcs.png
-
-The GCS layout can be changed, but in this layout there are 3 very important panels:
-
- the red one (left) is the strips panel. Each aircraft have its own strip, which display the state of the aircraft, and let you send commands.
- the green panel (top right) is the map. The default background is black. Click on the google earth icon (green circle) to load the tiles.
- the purple panel features various widgets. The first of these describes the flight plan.
-
-Now, lets launch the drone:
-
- On the purple panel, you should see that the "Holding Point" block is highlighted. This is the current block. Wait few seconds if the current block is "Wait GPS" or "Geo init".
- In the strip, click on the button in the blue circle. This is a shortcut button for the "Takeoff" block in the flight plan. You can also double click on the "Takeoff" block in the flight plan.
- In real life, we would now launch the drone. In simulation, there is a magic button to do so in the strip. Click on the button in the red circle.
-
-The drone should now move, and the current block will change to "Standby".
-
-
@@ -1,105 +0,0 @@
-.. quickstart gcs_tour
-
-.. _gcs:
-
-====
-GCS
-====
-
-The GCS is the main app used during the flight. Let's explore the 3 important panels.
-
-.. image:: gcs.png
-
-The Strips
-==========
-
-The strips panel is the red one on the left.
-
-Aircraft status
-+++++++++++++++
-
-Starting from the top left corner to the bottom right we have:
-
-.. image:: gcs_strip_1.png
-
- flight time
- ground speed. Hover on the ground speed to get the airspeed.
- throttle level (red background means throttle is killed. Orange otherwise.)
- name of the current navigation block
- Next line, the battery voltage. This widget also display a graph of the battery voltage over time.
- three status widgets:
-
-    + The navigation mode (AUTO2, AUTO1, MANU, ...),
-    + the radio command status,
-    + the GPS status.
- the height above ground level (AGL) in meters and the vertical speed (in m/s).
- the "Block" group gives:
-
-  + the block time (time since the drone is in the current block),
-  + the stage time (stages are block childs),
-  + the estimated time of arrival to the next waypoint (if applicable).
-  + a "Mark" button to mark on the map the current position of the drone.
-
- Next line, below the *Bat*, this is the *Link* status. If link is lost, the number of seconds since the last message will be displayed here.
- At the right of the GPS status, this is the altitude of the drone compared to the target altitude.
- The next group display the drone altitude and the target altitude (MSL).
-
-*Nav* group
-+++++++++++
-
-This group features some quick operations. From the top left corner:
-
-.. image:: gcs_strip_fixed_settings.png
-
- the "Lauch" button, used for simulation only.
- the "Kill" button. It kills the drone throttle.
- "Resurrect" enables throttle back.
- decrease altitude
- increase altitude
- greatly increase altitude
- shift trajectory to the left
- recenter trajectory
- shift trajectory to the right
-
-
-Commands
-++++++++
-
-.. image:: gcs_strip_fpsets.png
-
-This group features user-defined buttons that can be used to either go to a flight plan block or to sets a specific value to a setting.
-
-
-The map
-=======
-
-The map displays drones and waypoint positions. Waypoints can be moved by dragging them or clicking on them. Change the altitude and confirm the new position in the dialog window that will open.
-
-Mouse position in various reference system is displayed on the top right corner (default is WGS84).
-
-Click the google Earth icon to load the background map.
-
-
-Aircraft panel
-==============
-
-The purple panel at the bottom is the Aircraft panel.
-
-The **Flight Plan** tab display the full flight plan of the aircraft. Double clicking on a block makes the aircraft go to this block.
-
-The **GPS** tab gives you info about GPS state. Its usually a good idea to wait for the *Pos accuracy* to be good enough (around 5 meters or less) before proceeding to a flight.
-
-The **PFD** tab diplay a primary flight display. Very useful for the ground checks before take off, and if the aircraft is out of sight.
-
-The **Link** tab gives detailed info about the link with the drone.
-
-The **Settings** tab features all settings. Settings are hierarchically organised. Each setting is displayed as follow:
-
- name of the setting. 
- its last known value. Click on it to update it. **?** means that the value is unknown.
- a mean to set a new value : it can be a drop-down box, radio buttons, or a slider.
- 2 buttons: the *Commit* button that will send the setting to the drone, and the *Undo* button that will set the setting back to its last value.
-
-
-
-
@@ -1,64 +0,0 @@
-.. quickstart paparazzi_center_tour
-
-.. _paparazzicenter:
-
-=================
-Paparazzi Center
-=================
-
-The Paparazzi Center is composed of 5 panels, as shown in the image below.
-
-.. image:: pprz_center.png
-
-
-Configuration panel
-====================
-
-This panel is dedicated to the configuration of the aircrafts. You can change the current aircraft with the *A/C* combobox.
-
-The *id* field is the **uniq** identifier of the aircraft, between 0 and 255.
-
-An aircraft is composed of an airframe, a flight plan, some settings, a radio and a telemetry configuration file. These concepts are explained later.
-
-For now, remember that you can select other files by hitting the ``...`` button, or edit the current file with the ``Edit`` button.
-
-.. note::
-
-    The ``Edit`` button open the file with *gedit* by default. You can change it by setting the ``EDITOR`` environnement variable.
-
-Building panel
-===============
-
-This panel lets you choose for which target you want to build the firmware with the **Target** combobox. Build and clean the firmware with the *Build* and *Clean* buttons.
-
-Some usual targets are:
-
- **sim**: The basic fixedwing simulator written in OCaml without IMU simulation or any sensor models (noise, bias, etc) and mainly intended to validate your flight plan logic.
- **nps**: NPS is a more advanced rotorcraft and fixedwing simulator with sensor models and commonly uses JSBSim as FDM (Flight Dynamic Model).
- **ap**: This is for a *real* autopilot.
-
-
-If the selected target is not a simulator, you can choose how you want to flash the board by choosing the **Flash mode**. Click on *Upload* to load the firmware on the board.
-
-
-Execution and Running agents panels
-====================================
-
-In the Execution panel, a combo box provides a set of sessions (collections of programs).
-
-The Simulation session runs a server, a GCS and a simulator for the aircraft selected in the configuration panel. Note that *sim* or *nps* target must have been built prior to the simulation.
-
-The launched programs can be stopped and restarted individually (Stop/Redo buttons). All programs can be stopped and removed from the list at once by the *Stop/Remove All Processes* button. A common mistake is to have multiple instances of the same program running. This button is very handy to use!
-
-
-Console panel
-==============
-
-All messages from the programs run from the Paparazzi center will be displayed here. Error messages will be display in red, warnings in orange, and messages in green.
-
-
-Now, lets launch a :doc:`first_simulation`!
-
-
-
-
@@ -27,7 +27,7 @@ Remember the architecture ? Its time to use this *messages* tool at the bottom l

 The *messages* tool allows you to visualize all messages on the ground network.

-First, start a session as explained in the :doc:`../quickstart/first_simulation` page.
+First, start a session as explained in the :doc:`../getting_started/first_simulation` page.

 Then start the *messages* tool by going in the Paparazzi Center menu and hiting *Tools -> Messages*.

@@ -17,7 +17,7 @@ From the **Session** combo box, select **Simulation** entry and click **Execute*

 - **Microjet** is the interface of a simulator program. It runs the same code as the one for the autopilot processor plus a rudimentary flight dynamic model. 
  It allows you to test the interactions with the UAV and the flight plan execution.
- **GCS** (:ref:`gcs`) is the main window. It displays the track of the aircraft, as well as information about the execution of its flight plans. 
+- **GCS** is the main window. It displays the track of the aircraft, as well as information about the execution of its flight plans. 
  This program provide menus for the datalink functions and is able to edit a flight plan.
 - **Server** is a hidden process which won't be described here (see the architecture of the system).

@@ -11,7 +11,7 @@ Simulation
 A FDM is a set of mathematical equations used to calculate the physical forces acting on a simulated aircraft, such as thrust, lift, and drag.
 Paparazzi currently has two different simulator targets with different degrees of realism and intended purpose:

-* **sim**: The basic fixedwing simulator written in OCaml without IMU simulation or any sensor models (noise, bias, etc) and mainly intended to validate your :ref:`flightplans` logic.
+* **sim**: The basic fixedwing simulator without IMU simulation or any sensor models (noise, bias, etc) and mainly intended to validate your :ref:`flightplans` logic.
 * **nps**: NPS is a more advanced rotorcraft and fixedwing simulator with sensor models and commonly uses JSBSim as FDM (Flight Dynamic Model). Other FDM's can be integrated easily. At the moment JSBSIM, CRRCSIM, GAZEBO and PyBullet are supported as FDM backend. It is also possible to implement ad-hoc simulation code, based on Matlab/Simulink generated code for instance.
    * **JSBSim**: a flight dynamic library used by default by various simulation sofware including Flight Gear.
    * **gazebo**: Gazebo can be used as flight dynamic engine, but its main interest is to generate virtual sensor readings (cameras, lidars, ...) from a 3D realistic environment.