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

Sphinx: Simulation Documentation (#2886)

Browse Source 
* Adds guidance and stabilization file with initial structure

* added vision

* added simulation file, not finished

* continued documentation simulation

* added last bit of simulation docs from wiki

* implemented feedback on PR #1

Co-authored-by: matteobarbera <matteo.barbera97@gmail.com>
This commit is contained in:
Pietro Campolucci
2022-06-21 10:48:34 +02:00
committed by GitHub
parent d7cd169b40
commit 6b5bba4284
21 changed files with 1011 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.vscode/settings.json vendored
View File

@@ -12,4 +12,5 @@
"Makefile.*": "makefile"
},
"C_Cpp.dimInactiveRegions": false,
"esbonio.sphinx.confDir": "",
}

2
doc/sphinx/source/quickstart/gcs_tour.rst
View File

@@ -1,5 +1,7 @@
.. quickstart gcs_tour
.. _gcs:
====
GCS
====

2
doc/sphinx/source/quickstart/paparazzi_center_tour.rst
View File

@@ -1,5 +1,7 @@
.. quickstart paparazzi_center_tour
.. _paparazzicenter:
=================
Paparazzi Center
=================

2
doc/sphinx/source/user_guide/flight_plans.rst
View File

@@ -1,5 +1,7 @@
.. user_guide flight_plan
.. _flightplans:
============
Flight Plans
============

1
doc/sphinx/source/user_guide/index_user_guide.rst
View File

@@ -16,5 +16,6 @@ Start conquering the wolrd, by making incredible :doc:`flight_plans`!
communication
radio
gcs_graphics
simulation_main
directories_structure

151
doc/sphinx/source/user_guide/simulation/gazebo.rst Normal file
View File

@@ -0,0 +1,151 @@
.. user_guide simulation gazebo
.. _gazebo:
===========================
Gazebo
===========================
The nice sim framework Gazebo from here http://gazebosim.org/ can now be use from within Paparazzi.
Are you doing work on UAS in combination with e.g. Vision based navigation? Then check it out. I might make testing your new work so much simpler.
Be warned, using it can be highly addictive, and might tempt you into buying a new computer with high specifications.
To be able to use Gazebo a very good Video card is needed, consider upgrading you hardware if everything runs slowly.
Note that from stable version 5.14 onwards, only version 8 and 9 of Gazebo work in Paparazzi on Ubuntu 16.04 or higher.
Installation
-------------------
Make sure Gazebo is installed, version 9 if you are on Ubuntu 18 and higher
.. code-block:: php
sudo apt install gazebo9 libgazebo9-dev
If for some reason this doesn't work, you can find some additional instructions here: http://gazebosim.org/tutorials?cat=install&tut=install_ubuntu&ver=9.0
Setup and Configure
-----------------------
This section shows what and how to configure to run a simulation in Gazebo through paparazzi.
Vehicle Model
^^^^^^^^^^^^^^^
Prepare your Gazebo aircraft model (example see ``conf/simulator/gazebo/models/ardrone/``):
Place the aircraft model in the ``conf/simulator/gazebo/models/`` folder, this folder is added to the search path of Gazebo when NPS is launched.
Gazebo uses a **Front, Left, Up** coordinate system for aircraft, so make sure the **+x** axis points forwards.
The model should include a link for each motor with the same names as those listed in ``NPS_ACTUATOR_NAMES`` (see below), e.g. 'nw_motor'.
Camera links should have the name specified in ``.dev_name`` in the
.. code-block:: php
corresponding video_config_t struct, see sw/airborne/boards/pc_sim.h and sw/airborne/modules/computer_vision/video_thread_nps.c
Additional models can be found in the ``sw/ext/tudelft_gazebo_models``. You will have to run ``git submodule init``, ``git submodule update`` to pull in the models.
World
^^^^^^^^^^^^^^^^
Prepare the world (see conf/simulator/gazebo/worlds/ardrone.world or any other world file you might find there).
.. note::
The real-time update rate should be set to zero, as the simulation back-end is already handled by Paparazzi:
.. code-block:: php
<physics type="ode">
<max_step_size>0.001</max_step_size>
<real_time_update_rate>0</real_time_update_rate><!-- Handled by Paparazzi! -->
</physics>
Spherical coordinates should be provided for navigation. At this moment, there is an issue where Gazebo incorrectly uses a **WSU** coordinate system instead of **ENU**.
This can be fixed by setting the heading to 180 degrees as shown below:
.. code-block:: php
<spherical_coordinates>
<surface_model>EARTH_WGS84</surface_model>
<latitude_deg>51.9906</latitude_deg>
<longitude_deg>4.37679</longitude_deg>
<elevation>0</elevation>
<heading_deg>180</heading_deg><!-- Temporary fix for issue https://bitbucket.org/osrf/gazebo/issues/2022/default-sphericalcoordinates-frame-should -->
</spherical_coordinates>
Additional world models can be found in the ``sw/ext/tudelft_gazebo_models``. You will have to run git submodule init, git submodule update to pull in the models.
Airframe
^^^^^^^^^^^
Enhance your Paparzazzi airframe file to be able to use Gazebo (see ``examples/ardrone2_gazebo.xml``):
Select Gazebo as the FDM (Flight Dynamics Model) by adding it to the aircraft file
.. code-block:: php
<target name="nps" board="pc">
<module name="fdm" type="gazebo"/>
</target>
Add actuator thrusts and torques to the ``SIMULATOR`` section:
.. code-block:: php
<section name="SIMULATOR" prefix="NPS_">
<define name="ACTUATOR_NAMES" value="nw_motor, ne_motor, se_motor, sw_motor" type="string[]"/>
<define name="ACTUATOR_THRUSTS" value="1.55, 1.55, 1.55, 1.55" type="double[]"/>
<define name="ACTUATOR_TORQUES" value="0.155, -0.155, 0.155, -0.155" type="double[]"/>
...
<section>
The thrusts and torques are expressed in SI units (N, Nm) and should be in the same order as the ``ACTUATOR_NAMES``.
In the same section, bypass the AHRS and INS as these are not supported yet, so add this
.. code-block:: php
<section name="SIMULATOR" prefix="NPS_">
...
<define name="BYPASS_AHRS" value="1"/>
<define name="BYPASS_INS" value="1"/>
...
<section>
If you want to use visual based behavior, enable video thread simulation:
.. code-block:: php
<section name="SIMULATOR" prefix="NPS_">
...
<define name="SIMULATE_VIDEO" value="1"/>
...
<section>
Specify the Gazebo world and aircraft name:
.. code-block:: php
<section name="SIMULATOR" prefix="NPS_">
...
<define name="GAZEBO_WORLD" value="my_world.world"/>
<define name="GAZEBO_AC_NAME" value="my_uav"/>
<section>
.. note:: Make sure all included modules work with NS.
At the current state of Paparazzi code (20180206), most of the modules that depend on video_thread are
only built when the target ap (autopilot hardware) is selected as the target.
As a quick 'n dirty fix, try to remove the target attribute from the makefile element in the module xml, e.g.:
.. code-block:: php
<makefile target="ap"> ---> <makefile>
It would be great if as a user you would improve this and make a Pull request of your code improvements
to the main Paparazzi codebase, TIA

306
doc/sphinx/source/user_guide/simulation/hitl.rst Normal file
View File

@@ -0,0 +1,306 @@
.. user_guide simulation hitl
.. _hitl:
===========================
Hardware in the Loop
===========================
Hardware In The Loop (HITL) simulation is a way to test an embedded system (the real hardware and software) by simulating its environment,
ie. sensor inputs, and comparing its output, ie. actuator outputs, to expected output values.
It is the closest to an actual flight without actually flying. Using Paparazzi's Software In The Loop (SITL) and HITL for validation of a
flight dynamics of a fixed wing UAV is in detail described in a paper "Software-and hardware-in-the-loop verification of flight dynamics
model and flight control simulationof a fixed-wing unmanned aerial vehicle" by Cal Coopmans and Michal Podhradsky. Refer to the paper for more details.
Principle
-----------
While the SITL simulation executes the airborne code on the ground host, HITL is a way to run the autopilot code on the actual hardware in an
environment where sensors and actuators are simulated. The difference is shown in diagrams below: SITL generates the physical behavior of
the airplane from the Flight DynaMics (FDM) Block, then feeds the generated values into virtual sensors, the sensor inputs are processed in
the autopilot and the autopilot control ouputs are captured and fed back into the FDM. HITL does the same, except it communicates with the autopilot over serial ports.
In HITL, two separate processes are involved:
- The real autopilot code on the control board with its own IO (for example battery voltage, etc);
- A flight model combined with a model of the actuators and the sensors.
Commands computed by the autopilot are sent to the flight model which sends back simulated values of the sensors output.
.. figure:: images/600px-Hitl.png
Hardware-in-the-loop (HITL) autopilot testing block diagram
.. figure:: images/550px-Sitl.png
Software-in-the-loop (SITL) autopilot testing block diagram
Limitations
-----------------
.. warning::
HITL currently works only with Pprzlink 1.0, which is not supported anymore. The code might not work as desired yet.
For practical reasons (it is very difficult to simulate SPI/I2C devices such as accelerometer, gyroscope etc.),
Paparazzi HITL simulates only sensors that connect to the autopilot via serial port (for example GPS unit, or an external AHRS/INS).
Currently implemented is Vectornav VN-200 in INS mode, but other sensors and modes can be added (i.e. VN-200 as IMU, Xsens INS etc.).
Because the benefit of HITL is to test the autopilot code that is identical to the actual flight code, no other means of transporting
sensor data to the autopilot are currently supported (such as sending them through uplink).
Another consideration is the bandwidth of the system - the sensor data and the actuator values have to be send/received at ``PERIODIC_FREQUENCY`` (between 40-512 Hz) for HITL to work correctly.
When to use SITL and when HITL?
------------------------------------
The advantage of SITL is that it is easy to deploy and test, because no additional hardware is needed. This means that simulation is very self-contained.
Ideally use for testing flight plans, or initial tuning of airframes. SITL can run faster than real time.
HITL is the simulation closest to real flight, because both the hardware and the code are identical to the set being used in real flight
the autopilot is really flying with artificial sensor data. HITL is used to test the flight hardware, once the flight plan and initial tuning
has been configured. Usually HITL is the last thing to run before going flying.
Prerequisites
--------------------
HITL currently (Ubuntu 16.04) needs the following two steps to run correctly:
- set rtpriority for the uart threads detailes `here <https://stackoverflow.com/questions/8111302/why-does-pthread-setschedparam-produce-eperm-on-opensuse-11-4>`_
by adding these two lines to your ``/etc/security/limits.conf`` file:
.. code-block:: php
domain type item value
$USER soft rtprio 100
$USER hard rtprio 100
where $USER is your username
- install pyserial package (needed for SBUS Fakerator), typically with ``sudo install pyserial``.
Configuration
------------------------
HITL can currently run on any that has:
- Serial port for Vectornav INS input (provides position and orientation data, including GPS coordinates)
- Serial port for additional high-speed telemetry output (so not your regular 57600 telemetry)
- Other serial/io for regular telemetry, RC input etc.
If you have high-speed telemetry (like over WiFi) it should be possible to use only one telemetry link and demux the messages on GCS,
but it is not currently supported. Note that HITL is timing sensitive (at 512Hz you need to receive, process, and send data every ~2ms).
HITL has been tested on:
- Lisa M/MX (exampes for `fixedwing <https://github.com/paparazzi/paparazzi/blob/master/conf/airframes/AGGIEAIR/aggieair_minion_rp3_lia.xml>`_ and
`rotorcraft <https://github.com/paparazzi/paparazzi/blob/master/conf/airframes/AGGIEAIR/aggieair_ark_hexa_1-8.xml>`_)
- Umarim v 2.0 (example for `fixedwing with Unarim <https://github.com/paparazzi/paparazzi/blob/master/conf/airframes/AGGIEAIR/El_Captain.xml>`_)
We recommend a dedicated computer for HITL, with enough CPU power and memory, and a nice graphics card for :ref:`flightgear` visualisation
(see the test station in the picture). HITL can run on a regular laptop too (tested on both Lenovo Thinkpad and Toughbooks).
.. figure:: images/600px-HITL_station.jpg
Hardware-in-the-loop (HITL) test station in simulated flight
There are a few example airframes to choose from. Let's start with a fixed wing airplane and walk you through step by step. Get a fresh copy of the latest paparazzi and do:
.. code-block:: php
# in prrz root dir
./start.py
and choose AggieAir's ``conf`` and ``control panel``:
.. figure:: images/Aggieair_conf.png
Select AggieAir's conf and control panel and then Launch
Choose **Minion_RP3** airframe:
.. figure:: images/900px-Minion_rp3_airfame.png
Minion RP3 airfame
and click on **Edit**. The airframe file is on github: https://github.com/paparazzi/paparazzi/blob/master/conf/airframes/AGGIEAIR/aggieair_minion_rp3_lia.xml For HITL to work, there have to be 4 things:
- `extra_dl <https://github.com/paparazzi/paparazzi/blob/master/conf/modules/extra_dl.xml>`_ telemetry module
- specified ``COMMANDS`` (Fixedwing) or ``ACTUATORS`` (rotorcrafts) Extra telemetry message in the telemetry config file (an example `with AggieAir here <https://github.com/paparazzi/paparazzi/blob/master/conf/telemetry/AGGIEAIR/aggieair_fixedwing.xml#L108>`_)
- HITL target
- Airframe configured to use external INS
Extra_DL Module
^^^^^^^^^^^^^^^^^^^^^^
This is the additiona high speed telemetry link that sends the actuators data back to the FDM.
.. code-block:: php
# in your airframe config file
<module name="extra_dl">
<!-- in order to use uart1 without chibios we need to remap the peripheral-->
<define name="REMAP_UART1" value="TRUE"/>
<configure name="EXTRA_DL_PORT" value="UART1"/>
<configure name="EXTRA_DL_BAUD" value="B921600"/>
</module>
If you have `Umarim <https://wiki.paparazziuav.org/wiki/Umarim_Lite_v2>`_ board or similar, you can also use a usb serial port:
.. code-block:: php
# in your airframe config file
<module name="extra_dl">
<configure name="EXTRA_DL_PORT" value="usb_serial"/>
<configure name="EXTRA_DL_BAUD" value="B921600"/>
</module>
Telemetry config file
^^^^^^^^^^^^^^^^^^^^^^^^
Just add this section to your telemetry config file:
.. code-block:: php
# in your telemetry config file
<process name="Extra">
<mode name="default">
<message name="COMMANDS" period="0.01"/>
</mode>
</process>
The period has to be matching your ``PERIODIC_FREQUENCY`` - best if you explicitly define all the frequencies to avoid ambiguity:
.. code-block::
# in your airfame config file
<!-- NOTE: if you want to use extra_dl module for HITL
you have to set TELEMETRY_FREQUENCY to CONTROL_FREQUENCY -->
<configure name="PERIODIC_FREQUENCY" value="100"/>
<define name="CONTROL_FREQUENCY" value="100"/>
<configure name="TELEMETRY_FREQUENCY" value="100"/>
<define name="SERVO_HZ" value="100"/>
NOTE: the ``TELEMETRY_FREQUENCY`` has to match your ``PERIODIC_FREQUENCY``
HITL Target
^^^^^^^^^^^^^^^
Add the target in your airfame config file:
.. code-block:: php
# in your airfame config file
<target name="hitl" board="pc">
<module name="fdm" type="jsbsim"/>
<configure name="INS_DEV" value="/dev/ttyUSB1"/>
<configure name="INS_BAUD" value="B921600"/>
<configure name="AP_DEV" value="/dev/ttyUSB2"/>
<configure name="AP_BAUD" value="B921600"/>
</target>
What does it mean? First, we have to specify the FDM for the HITL simulation. We recommend :ref:`jsbsim`, but any FDM that :ref:`nps` supports should work (because NPS is the backend for HITL).
Then we have to specify the serial ports to talk to the autopilot. ``INS_DEV`` is the port your external INS (such as Vectornav) is using.
AP_DEV is the port for the extra telemetry. Make sure your baud rates are matching too.
Note that you can either specify the devices in ``/dev/ttyUSB*`` format, which makes it universal across different USB-to-serial converters,
but you have to remember to plug in the ports in the right order (since they enumerate sequentially).
The other option is to specify the ``/dev/serial/by-id/usb-FTDI_*****`` format, in which case it doesn't matter in which order you plug the
devices in, but you can use it only for a particular FTDI converter.
It might be handy to use a simple Lia breakout board for connecting all the serial
ports - `the breakout board files are available here <https://github.com/paparazzi/paparazzi-hardware/tree/master/controller/lia/breakout_board>`_.
.. figure:: images/500px-Liabreakoutboard.jpeg
Lia breakout board
Airframe Configuration for External INS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Indeed, HITL will work only if your aiframe is configured to use external INS of some sort. In our example, we specify using Vectornav:
.. code-block::
# in your airfame config file
<module name="ins" type="vectornav">
<configure name="VN_PORT" value="UART2"/>
<configure name="VN_BAUD" value="B921600"/>
</module>
See the `Minion_RP3 airframe config <https://github.com/paparazzi/paparazzi/blob/master/conf/airframes/AGGIEAIR/aggieair_minion_rp3_lia.xml>`_ for more details.
Running
-------------------
Once you have your setup completed:
- Clean, compile and upload the AP target (HINT: use keyboard shortcuts **Alt+C** to **Clean**, **Alt+B** to **Build** and **Alt+U** to **Upload**)
- Clean and build HITL target
- Choose ``HITL USB-serial@57600`` session and Execute
.. note::
If you want to use your own session, you have to pass ``-t hitl`` flag into ``sw/simulator/pprzsim-launch`` to start in HITL mode.
Have a look at the ``HITL USB-serual@57600`` session for example, or add this to your own:
Messages will pop up and you can verify that you are getting data by looking at the ``VECTORNAV_INFO`` message:
.. figure:: images/300px-Hitl_messages.png
VECTORNAV_INFO message
And once you take-off you will see something like this:
.. figure:: images/1000px-Hitl_flight.png
HITL Flight with fixedwing airplane
Similar steps work for rotorcraft.
SBUS Fakerator
^^^^^^^^^^^^^^^^^^^^^
A simple tool simulating SBUS radio inputs is available. It is useful if you don't have a radio around, and want to test flight in manual mode.
It has to be used with a `Sbus_fakerator radio config file <https://github.com/paparazzi/paparazzi/blob/master/conf/radios/AGGIEAIR/aggieair_sbus_fakerator.xml>`_ and it requires an additional serial port (for example ``/dev/ttyUSB3``).
It can be launched as a tool from the Paparazzi center.
Source code is available at: https://github.com/paparazzi/paparazzi/tree/master/sw/tools/sbus_fakerator
.. figure:: images/300px-Sbus_fakerator.png
SBUS fakerator tool
FlightGear
^^^^^^^^^^^^^
We strongly recommend running HITL with :ref:`flightgear` for visualization. The steps are the same as when running :ref:`nps` targets, please refer for documentation there.
Issues
--------------
If you find a problem that is not mentioned here, please contact out gitter channel or file an issue on github.
Known issues:
setschedparam failed error
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you get "setschedparam failed!" error when running NPS/HITL, you have to change limits.conf - see https://stackoverflow.com/q/10704983/9237888
In short, edit your /etc/security/limits.conf file and add these lines at the bottom:
.. code-block::
domain type item value
YOUR_USERNAME soft rtprio 100
YOUR_USERNAME hard rtprio 100
Then I believe you have to restart your computer in order for limits to refresh.
Happy flying!
.. figure:: images/600px-Minion_HITL.png

BIN
doc/sphinx/source/user_guide/simulation/images/1000px-Hitl_flight.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 229 KiB

BIN
doc/sphinx/source/user_guide/simulation/images/300px-Hitl_messages.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 93 KiB

BIN
doc/sphinx/source/user_guide/simulation/images/300px-Sbus_fakerator.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
doc/sphinx/source/user_guide/simulation/images/500px-Liabreakoutboard.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
doc/sphinx/source/user_guide/simulation/images/550px-Sitl.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
doc/sphinx/source/user_guide/simulation/images/600px-HITL_station.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 71 KiB

BIN
doc/sphinx/source/user_guide/simulation/images/600px-Hitl.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
doc/sphinx/source/user_guide/simulation/images/600px-Minion_HITL.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 172 KiB

BIN
doc/sphinx/source/user_guide/simulation/images/900px-Minion_rp3_airfame.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 83 KiB

BIN
doc/sphinx/source/user_guide/simulation/images/Aggieair_conf.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 43 KiB

BIN
doc/sphinx/source/user_guide/simulation/images/PPRZ_Environment_settings_Gaia_GUI_up.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

365
doc/sphinx/source/user_guide/simulation/nps.rst Normal file
View File

@@ -0,0 +1,365 @@
.. user_guide simulation nps
.. _nps:
===========================
NPS
===========================
NPS (New Paparazzi Simulator) is a simulator with sensor and vehicle models that can use different FDM backends.
By default, :ref:`jsbsim` is used as FDM (FlightDynamicModel), which allows for fairly complex airframes. JSBSim can be replaced by the FDM of your choice,
such as :ref:`gazebo`, for better visualization.
NPS is capable of simulating rotorcraft and fixedwing airframes, with the possibility to add more complex aircrafts/hybrids if a proper model
is built using one of the FDM backends.
Configure and Build
--------------------------
Add the nps target to your airframe with the fdm you want to use:
.. code-block:: xml
<firmware name="rotorcraft or fixedwing">
<target name="nps" board="pc">
<module name="fdm" type="jsbsim"/>
</target>
...
</firmware>
Then depending on the aircraft you want to simulate add a NPS simulator section which defines the model, actuators and sensor parameters used:
E.g for a simple quadrotor:
.. code-block:: xml
<section name="SIMULATOR" prefix="NPS_">
<define name="ACTUATOR_NAMES" value="front_motor, right_motor, back_motor, left_motor" type="string[]"/>
<define name="JSBSIM_MODEL" value="simple_quad" type="string"/>
<define name="SENSORS_PARAMS" value="nps_sensors_params_default.h" type="string"/>
</section>
The full list of available parameters for the simulator is:
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| PARAMETER | DESCRIPTION |
+========================+================================================================================================================================================================================================================================================================================================================+
| NPS_ACTUATOR_NAMES | mapping of the motors defined in the ``MOTOR_MIXING`` section to the actuators in the JSBSim model (the order is important, also make sure that your motors in JSBSim spin in the same direction as your real ones) |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| NPS_SENSORS_PARAMS | the parameter file for the sensor simulation (noise/delay) under ``conf/simulator/nps/`` |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| NPS_JSBSIM_MODEL | name of the JSBSim model in ``conf/simulator/jsbsim/aircraft/`` (e.g. simple_quad), if not defined it defaults to AIRCRAFT_NAME |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| NPS_JSBSIM_INIT | the xml file containing the initial conditions (location, attitude, wind) for JSBSim in ``conf/simulator/jsbsim/aircraft/``. This define is optional and if not specified the initial position of the aircraft will be set to the flight plan location. Prior to v5.1 this was called ``INITIAL_CONDITITONS``. |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| NPS_JSBSIM_LAUNCHSPEED | if defined this sets an initial launchspeed in m/s for fixedwings, available since ``v5.1.0_testing-54-g2ac094f``. |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| NPS_JS_* | Joystick mappings |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Running the Simulation
--------------------------
The most convenient way to start the simulation is via the Simulation session from the :ref:`paparazzicenter`.
Just select e.g. the Quad_LisaM_2 example airframe and start the Simulation session with the simulator, GCS and server.
If you have added ``PAPARAZZI_HOME`` AND ``PAPARAZZI_SRC`` to the environmental variables of your terminal (See Setting up environment variables),
you can also start it via the generic simulation launcher:
.. code-block:: C
sw/simulator/pprzsim-launch --aircraft Quad_LisaM_2 --type nps
Options
^^^^^^^^^^^^^^^^^^^^^
Start the simulator with the *--help* option to list them all.
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| OPTION | DESCRIPTION |
+====================+=================================================================================================================================================================================================================+
| ``--ivy_bus`` | Set ivy bus broadcast address to use (default 127.255.255.255, 224.255.255.255 on OSX) |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--rc_script`` | Execute script with specified number to emulate RC input. |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--js_dev`` | Use joystick for radio control (specify index, normally 0), |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--spektrum_dev`` | Spektrum device to use for radio control (e.g. ``/dev/ttyUSB0``) |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--fg_host`` | Host for FlightGear visualization (e.g. 127.0.0.1) |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--fg_port`` | Port on FlightGear host to connect to (Default: 5501) |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``--ivy_bus`` | FlightGear time offset in seconds (e.g. 21600 for 6h), this is useful if it is currently night at the location you are flying and you want to add an offset to fly in daylight. (Since v4.9_devel_413-g9d55d6f) |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Typical Simulation
^^^^^^^^^^^^^^^^^^^^^
In general you go through the same steps as with the real aircraft:
- It should start on the ground and you have to wait a few seconds until the AHRS is aligned.
- If you have a (simulated) RC, you can now arm the motors and fly around in manual.
- To fly autonomously, make sure your AUTO2 mode is NAV, you can change it in the GCS->settings->system->auto2.
- Switch to it if you are using an RC, otherwise you should already be in this mode.
- Arm your motors: either via the resurrect button or by going to the Start Motors block of the Flight Plan.
- Takeoff: via the takeoff button or the corresponding flight plan block.
- Execute your flight code.
Pausing or running the sim at a different speed
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you start the simulation from a terminal, hit CTRL-z to pause it. You can then enter a different time factor (default 1.0)
to make the simulation run slower or faster than real-time. Hit enter to resume the simulation or CTRL-z again to suspend it
like any normal Unix process (use the fg (foreground) command to un-suspend it again).
Use a Joystick
^^^^^^^^^^^^^^^^^
You can use a joystick (or connect your RC transmitter as a joystick) to control the quad in the simulator.
.. code-block:: C
sw/simulator/pprzsim-launch --aircraft Quad_LisaM_2 --type nps --js_dev 0
or directly calling the nps simsitl binary:
.. code-block:: C
./var/Quad_LisaM_2/nps/simsitl --js_dev 0
Joystick support uses the Simple DirectMedia Layer (SDL) library. Rather than specifying an input device name as one normally does on Linux,
you just supply an index value (0, 1, 2,...) of the device you wish to use. Typically, the order of devices is the order in which you plugged
them into your computer. The sim will display the name of the device being used to double check. If the -j option is used with no argument,
the sim defaults to using device on index 0 (which is usually correct if you have only one joystick attached).
Also see Joystick#Calibration.
Troubleshooting
^^^^^^^^^^^^^^^^^^
- If you get an error like "JSBSim failed to open the configuration file: ``(null)/conf/simulator/jsbsim/aircraft/BOOZ2_A1.xml"``, you need to set
your ``$PAPARAZZI_SRC`` and ``$PAPARAZZI_HOME`` environment variables. Add the following to your .bashrc, change paths according to where you put Paparazzi.
Open a new terminal and launch the sim again.
.. code-block:: C
export PAPARAZZI_SRC=~/paparazzi
export PAPARAZZI_HOME=~/paparazzi
- If you did not install the jsbsim package your JSBSim installation under ``/opt/jsbsim`` will be used and you will have to set your
library path (either in your shell startup file or when running the sim on the command line), e.g.:
.. code-block:: C
LD_LIBRARY_PATH=/opt/jsbsim/lib ./var/Quad_LisaM_2/nps/simsitl --fg_host 127.0.0.1
- If you get an error like ``"fatal error: gsl/gsl_rng.h: No such file or directory"``, you need to install the GNU Scientific Library and corresponding development packages (libgsl).
- If you get an error like ``"undefined reference to `pcre_compile'", edit file conf/Makefile.nps``, look for the line that begins with ``LDFLAGS`` and add ``-lpcre``, e.g.:
.. code-block:: C
LDFLAGS += $($(TARGET).LDFLAGS) -lpcre
Simulating Multiple Aircraft
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When simulating multiple aircraft, the ``-udp_broadcast`` argument needs to be specified as part of the datalink invocation:
.. code-block:: C
$PAPARAZZI_HOME/sw/ground_segment/tmtc/link -udp -udp_broadcast
In the case of Mac OS X, the IP ADDR must also be specified:
.. code-block:: C
$PAPARAZZI_HOME/sw/ground_segment/tmtc/link -udp -udp_broadcast -udp_broadcast_addr <your_network_broadcast_ip_addr>
You can determine the ``IP ADDR`` for your network using ifconfig command:
.. code-block:: C
$ ifconfig
...
en0: flags=8863<UP,BROADCAST,SMART,RUNNING,SIMPLEX,MULTICAST> mtu 1500
ether 60:03:08:8e:14:9e
inet6 fe80::6203:8ff:fe8e:149e%en0 prefixlen 64 scopeid 0x4
inet 192.168.1.59 netmask 0xffffff00 broadcast 192.168.1.255
nd6 options=1<PERFORMNUD>
media: autoselect
status: active
...
Based on the above sample output, the invocation would look like the following:
.. code-block:: C
$PAPARAZZI_HOME/sw/ground_segment/tmtc/link -udp -udp_broadcast -udp_broadcast_addr 192.168.1.255
.. _flightgear:
FlightGear
--------------------------
FlightGear Flight Simulator which can be used to visualize an aircraft and scenery. For the actual simulation, see Simulation.
See http://www.flightgear.org/
Installation
^^^^^^^^^^^^^^^
Debian/Ubuntu
~~~~~~~~~~~~~~~
The standard Debian/Ubuntu repositories contain mostly older FlightGear versions.
A lot has improved and changed over the years. To get the latest greatest Flightgear, as of writing this iv vv2020.3.6 and enjoy the
improvements one can easily get that version by add in a PPA
For Ubuntu the latest edition of FlightGear is available from Launchpad PPA (contributed by Saikrishna Arcot),
to add the PPA an install the latest Flightgear, this in your terminal:
.. code-block:: C
sudo add-apt-repository ppa:saiarcot895/flightgear
sudo apt-get update
sudo apt-get install flightgear
This will install v2020.3.1 or newer
Tip:
Not a Paparazzi issue but if you get a message box saying "zone.tab" missing copy an paste this in you terminal to fix it:
.. code-block:: C
sudo apt-get install --reinstall flightgear-data-base
From source
~~~~~~~~~~~~~~~
A great page to read in case you want to install Flightgear from source can be found here
Adding Paparazzi 3D models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are a few 3D UAV models that come with paparazzi:
+-----------------------+---------------------------------------------------+
| AIRFRAME | DESCRIPTION |
+=======================+===================================================+
| ``mikrokopter.xml`` | quadrotor frame |
+-----------------------+---------------------------------------------------+
| ``hexa.xml`` | hexacopter |
+-----------------------+---------------------------------------------------+
| ``easystar.xml`` | Multiplex EasyStar fixedwing |
+-----------------------+---------------------------------------------------+
| ``simple_bipe.xml`` | biplane/quadrotor hybrid (transitioning vehicle) |
+-----------------------+---------------------------------------------------+
To make them available in flightgear, make a link from ``/usr/share/games/flightgear/Models/Aircraft/paparazzi`` to ``<paparazzi_dir>/conf/simulator/flightgear/``
.. code-block:: C
sudo ln -s $PAPARAZZI_SRC/conf/simulator/flightgear/ /usr/share/games/flightgear/Models/Aircraft/paparazzi
Using FlightGear for Visualization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For Flight Gear visualization of the simulation, version 2018.2.2 or higher is best.
NOTE: Only if you still wish to use version **v2.4** or lower for some reason, you must add the following to the firmware section of your airframe file:
.. code-block:: C
<firmware name="fixedwing or rotorcraft">
...
<define name="FG_2_4" value="1"/>
...
</firmware>
Launch Flight Gear with the following command:
.. code-block:: C
fgfs --fdm=null --native-gui=socket,in,30,,5501,udp
or to e.g. use the mikrokopter quadrotor model:
.. code-block:: C
fgfs --fdm=null --native-gui=socket,in,30,,5501,udp --prop:/sim/model/path=Models/Aircraft/paparazzi/mikrokopter.xml
.. _jsbsim:
JSBSim
-----------
`JSBSim FDM <http://jsbsim.sourceforge.net/>`_ is an open source flight dynamics model (FDM) used in NPS.
Installation
^^^^^^^^^^^^^^
Debian Package
~~~~~~~~~~~~~~~~~~~~~
On Debian/Ubuntu you can install the ``paparazzi-jsbsim`` package.
.. code-block:: php
sudo apt-get install paparazzi-jsbsim
If you don't have that in your sources, see Installation/Linux#Adding_the_APT_repository.
From Source
~~~~~~~~~~~~~~~
Compile JSBSIM from source (with specified date to make sure it works and API hasn't changed)
.. code-block:: php
cvs -z3 -d:pserver:anonymous@jsbsim.cvs.sourceforge.net:/cvsroot/jsbsim co -D "23 Feb 2015" -P JSBSim
cd JSBSim
./autogen.sh
./configure --enable-libraries --enable-shared --prefix=/opt/jsbsim
make
sudo make install
When building a NPS simulator target, the build system will first try to find JSBSim via ``pkg-config`` and fall back to ``/opt/jsbsim``.
If you want to install to a different location, change the prefix to your liking. And you need to add a ``<makefile>``
section to your airframe file and add the correct flags to point to the include files and libraries, depending on where it is installed.
With the default installation to /usr/local/, this would look like
.. code-block:: php
<makefile location="after">
nps.CFLAGS += -I/usr/local/include/JSBSim
nps.LDFLAGS += -L/usr/local/lib
</makefile>
On OSX
~~~~~~~~~~~~~~~
Install the JSBSim libraries onto your system. This should already be installed with paparazzi-tools, but if it isn't:
.. code-block:: php
sudo port install jsbsim
It uses code from the cvs repo, so it should be the most up-to-date source.
Troubleshooting
^^^^^^^^^^^^^^^^^^
If you get an error like "undefined reference to ``pcre_compile``, edit file ``conf/Makefile.jsbsim``, look for the line that begins with ``LDFLAGS`` and add ``-lpcre``, e.g.:
.. code-block:: php
LDFLAGS += $($(TARGET).LDFLAGS) -lpcre

158
doc/sphinx/source/user_guide/simulation/sim.rst Normal file
View File

@@ -0,0 +1,158 @@
.. user_guide simulation sim
.. _sim:
===========================
SIM
===========================
This describes the basic fixedwing sim, for rotorcraft or advanced fixedwing simulation, see **NPS**.
Configure and Build
^^^^^^^^^^^^^^^^^^^^^^^^^^
From the :ref:`paparazzicenter` select the Microjet aircraft (from the A/C combo box) which is configured with the ``basic.xml`` flight plan.
From the **Target** combo box, select **sim** and click the **Build** button to compile the airborne code to be run on your Linux box.
From the **Session** combo box, select **Simulation** entry and click **Execute** to start the simulation. It will start three processes which are listed in the window below:
- **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.
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).
Start the Simulation
^^^^^^^^^^^^^^^^^^^^^^^^^^
The aircraft has automatically been booted, as if the autopilot board had been powered. Its position and its flight parameters are displayed in the GCS window.
If you omit the ``-boot`` option of the sim the aircraft is not automatically booted and you can first place the aircraft where you want it to start from and then boot.
If the ``--norc`` option is omitted, a window for a virtual remote control (including on/off switch and a mode-switch) is started, see: Virtual Joystick
In the **GCS** the map widget is able to use many map formats and display them according to many projections.
To make things simple, we start by using images from Google. From the toolbar in the top right corner of the GCS,
click the **Google Earth** icon (Google maps fill). The program attempts to download the required satellite images from the Google servers.
If it succeeds, you should now see the nice countryside of Muret (a city close to Toulouse, France). Navigation and other features of the map are described on the GCS page.
The lower part of the GCS displays the flight plan in a tree view. You see that the current flight plan is composed of several blocks:
- **wait GPS** and **geo init** which are instructions to run this flight plan anywhere in the world, by translating the waypoints around the
current location of aircraft as soon as it is reported by the GPS.
- **Holding point** (it should be the current active block) which instructs the autopilot to wait for launch.
- **Takeoff** which will instruct the aircraft to climb full throttle to a security altitude
- **Standby** which is a simple circle around the ``STDBY`` waypoint.
Switch to the **Takeoff** block by a double click on the line or using the corresponding button (an icon figuring an airway) on the left side of the strip.
Fly
^^^^^^^^^^^^
In the Simulator (Microjet window), press the Launch button to simulate a hand launch or click the launch button in the GCS
(the green aircraft icon). The autopilot detects the launch by monitoring the groundspeed. The flight time (in the aircraft label on the GCS) then starts to count.
Position of the aircraft is displayed on the map: the aircraft goes to the ``CLIMB`` waypoint (to the north-west) and then around the ``STDBY`` waypoint.
Current block also changes accordingly in the flight plan display.
The orange triangle (the carrot) on the map is the point that the aircraft is navigating toward.
Line
^^^^^^^^
Jump to this block with double-click on the Line 1-2 line in the flight plan or using the corresponding button in the strip
(figuring a blue line between two white points). The aircraft will try to follow a line joining the waypoints 1 and 2, doing nice U-turns at both ends.
Move waypoints
~~~~~~~~~~~~~~~~~~~
While the aircraft is flying (or here while the simulator is integrating differential equations), you can move the waypoints on the
GCS interface by clicking and dragging (with the left button). When the mouse button is released, a popup window allows you to change the
altitude of the waypoint. After validation, the waypoint changes are sent to the autopilot and the followed track is changed accordingly.
Coming back around
~~~~~~~~~~~~~~~~~~~~
Select the Standby block (the home blue icon) to instruct the aircraft to fly around the ``STDBY`` waypoint.
Fly too far
^^^^^^^^^^^^^^^^^^
If you unzoom the map (using the PageDown key or he mouse wheel), you will see a large circle around the waypoints.
This circle show the allowed flying zone that the autopilot must not leave or it will enter an emergency navigation
mode and circles the ``HOME`` waypoint until the further direction is received.
Move the waypoint 2 out of this circle (close to the circle in the north-east corner) and switch back to the 'Line 1-2 **block to force the plane to get out of this safety zone**.
The aircraft flies to the 2 waypoint, cross the protection envelope and switches to home mode: the AP mode in the aircraft strip switches from ``AUTO2`` to ``HOME``.
To get out of this mode and switch back to the default ``AUTO2``, click on the AUTO2 button in the aircraft strip.
The aircraft then flies again towards too far and again switches to ``HOME`` mode.
Change the environment
^^^^^^^^^^^^^^^^^^^^^^^^^^
Launch the **Environment Simulator** from the Tools' menu in the Paparazzi Center.
.. image:: images/PPRZ_Environment_settings_Gaia_GUI_up.png
This interface, also known as Gaia, allows the user to change:
- **The time-scale**: This make the simulation of the flight speed up time, good if you have a extensive flightplan and you do not want to wait the real
time it would take to fly the aircraft in a real life flight. It is best not use a timescale higher than 2x for a first tryout.
- **The Wind speed**: Set the wind speed while simulating. Try to set it to e.g. 5m/s and observe the trajectory and the speed evolution
in the aircraft strip and in the PFD page of the notebook
- **The Wind direction**: Set the direction the wind come from. For fun try to take of with strong wind from the side.
- **Wind up**: Simulates updraft (e.g. by thermals) or downdraft wind (beside thunderstorms or in mountains), which could e.g. shift the
UAS higher than permitted, which can be counteracted by exceptions in the flightplan.
- **A GPS failure**: Simulate GPS loss on the aircraft (``GPS OFF``) and observe the resulting mode (``NO_GPS``) and trajectory.
In this mode, the autopilot can for example use a the failsafe roll, pitch and throttle settings defined in the airframe file.
Note that in a real flight, an aircraft without GPS won't be able to send it's position ... The simulation is cheating here!
It must, otherwise not possible to show the path in the simulator, of course.
Environment Simulator, Gaia can also be started with initial values set by command line option.
.. code-block:: php
-b Bus Default is 127.255.255.255:2010
-t Set time scale (default: 1.0)
-w Set wind speed (0-30m/s)
-d Set wind direction 0-359 deg
-g Turn off GPS
-help Display this list of options
--help Display this list of options
If you are in the test field and forgot the parameters, just use the "help"
.. code-block:: php
./gaia --help
This make testing more convenient since on can save a session with this parameters and on restart immediately have the same settings again.
Example
~~~~~~~~~~~~
Starting gaia with the following parameters on the command line:
.. code-block:: php
sw/simulator/gaia -t 3 -d 340 -w 11
This sets a 3x speedup of the time with wind coming from 340 degrees with a windspeed of 11m/s.
Other Navigation Patterns
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using the buttons in the strip, you can play with other navigation patterns: figure of eights, oval,
survey of a rectangle (with a north-south sweeping), Circle around here (which sets a waypoint to the current
location of the plane and flies a circle around).
Landing
^^^^^^^^^^^^^^^
To automatically land the aircraft:
- Set the ``TD`` (Touch Down) waypoint where you want to land. Be sure that the waypoint is on the ground (185m in Muret)
- Set the ``AF`` (Approach Fix) waypoint where you want to start the final descent (the glide). If you have set some wind with Gaia,
you probably want to fly ``AF-TD`` upwind (an estimation of the wind experienced by the aircraft is displayed in the left-upper corner of the map).
- Switch to the Land right or the Land left block (icons in the strip) according to the direction of the last turn
you want to do (for example, if ``AF`` is on the east side of TD and you want to manoeuver from the north, choose a Land right)

23
doc/sphinx/source/user_guide/simulation_main.rst Normal file
View File

@@ -0,0 +1,23 @@
.. user_guide simulation_main
===========================
Simulation
===========================
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.
- **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 CRRCSIM, YASIM and JSBSIM are tried as FDM backend.
- **gazebo**: There is someting brand new developed going, using laters Master you can start using the Gazebo engine in Paparazzi.
Take a look on that page to see if it offers what you are looking for.
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.
.. toctree::
:maxdepth: 1
simulation/sim
simulation/nps
simulation/gazebo
simulation/hitl