Sphinx doc (#2558)

* [Doc] Adds doc about imu congiguration and fix some doc.
* [doc] Edit quick start doc.
* [Doc] Add "interfacing with Paparazzi" page.
* [Doc] Fix radio conf doc.
* [doc] Adds warning about out-of-date doc.

Co-authored-by: Gautier Hattenberger <gautier.hattenberger@enac.fr>

doc/sphinx/source/tutorials/beginner/add_drones.rst

@@ -4,6 +4,50 @@
 Add Drones
 =========================
 
-TBD
+In this quick tutorial, you will learn what is an Aircarft (A/C) in the paparazzi vocabulary, then how to add one.
 
+In the paparazzi center, the left side is the Aircraft configuration area.
+An aircraft is a set of configuration featuring an airframe, a flight plan, some settings and modules, a radio and a telemetry.
+
+.. figure:: configuration_capture.png
+    :alt: The configuration area
+    :align: center
+    
+    The configuration area
+
+We will go throught a quick explainnation of each of these items, then we will see how to create a new A/C.
+
+Configuration items
+===================
+
+* The first thing you see at the top is a drop-down box allowing you to select which A/C configuration you want. The refresh button next to this box allows you to refresh the A/C list in case you change the configuration files while the paparazzi center is running.
+
+* The "id" box set the A/C ID. Each A/C should have a different ID since they are identified by this ID.
+
+* The "GUI color" allows you to change the A/C color on the GCS by clicking the the "..." button.
+
+* The airframe section refers to an airframe file. You can change the file with the "..." button, or edit it with the "Edit" button. To learn more about airframe files, see [link soon].
+
+* The Flight plan section configure which flight plan your drone is going to fly. You can change the file with the "..." button, or edit it with the "Edit" button. To learn more about flight plans, see [link soon].
+
+* The Settings section list all settings and modules you will use. You can add, remove or modify settings with the buttons on the right. The module list is filled according to the airframe and the flight plan files. You can untick modules and settings via the checkbox on the right. To learn more about settings and modules, see [link soon].
+
+* The radio section configure radio settings. Select the file matching your radio. To learn more about radios, see :doc:`../intermediate/create_radio`.
+
+* The telemetry section configure the telemetry settings. Select the file matching your needs. `default_fixedwing.xml` or `default_rotorcraft.xml` is usualy a good choice. To learn more about telemetry, see [link soon].
+
+How to create a new A/C
+=======================
+
+To create a new Aircraft, click on the "A/C" menu, then "New".
+
+.. image:: new_ac.png
+    :alt: New A/C
+    :align: center
+    
+A new window will appear. Give the name of your new aircraft, then click "Ok".
+Your aircraft is created.
+
+Now you have to configure each item saw in the previous section.
+You can change the files by clicking on the "..." buttons, or edit the current one with the "Edit" button.
 

doc/sphinx/source/tutorials/index_tutorials.rst

@@ -6,10 +6,12 @@ Tutorials
 
 TBD
 
-.. toctree ::
-	beginner/index_beginner
-	intermediate/index_intermediate
-	advanced/index_advanced
+.. toctree::
+    :maxdepth: 2
 
+    beginner/index_beginner
+    intermediate/index_intermediate
+    advanced/index_advanced
+    interfacing_with_paparazzi
 	
 

doc/sphinx/source/tutorials/interfacing_with_paparazzi.rst

@@ -0,0 +1,94 @@
+.. tutorials main_tutorials interfacing_with_paparazzi
+
+==========================
+Interfacing with Paparazzi
+==========================
+
+There are four ways to interact with and to extend paparazzi capabilities:
+
+- Using Pprzlink with the current ground station tools
+- Using Pprzlink independently of the ground station tools
+- Adding a dedicated board on the drone and using Pprzlink to communicate directly with the autopilot (usually with the serial transport)
+- Adding a module to the autopilot itself
+
+A combination of these options can be used at the same time to achieve specific goals.
+
+
+Using Pprzlink with the ground station
+--------------------------------------
+
+The easier way to interact with Paparazzi is to create a new agent as part of the ground station. All parameters and configuration files are easily accessible, making it easy to interact with the drone or display new data on the GCS. As example, the Interactive Informatics team of ENAC used it to design novel human-drone interactions for safety pilots and adaptable interactions for pilots with disabilities.
+
+The pprzlink messages that will interest us are those of the `ground` class. Most of those messages are emited by the server that compile the data from all drones and add an abstraction layer.
+
+See the message list here: http://docs.paparazziuav.org/latest/paparazzi_messages.html#GROUND_CLASS.
+
+This python example shows the reception and emission of messages. For the reception, we subscribe to the FLIGHT_PARAM and ENGINE_STATUS messages at lines 25 and 27 to monitor the position of the drone, its throttle level and battery voltage. For the emission, we forge, then emit an INTRUDER message in the `send_dummy_intruder` method to display a dummy intruder on the Ground Control Station.
+
+.. code-block:: python
+    :linenos:
+
+    #!/usr/bin/python3
+    import sys
+    import time
+    import os
+    import math
+    
+    # Make sure to add PAPARAZZI_HOME and PAPARAZZI_SRC to your environment variables.
+    # They must point to your paparazzi directory.
+    PPRZ_HOME = os.getenv("PAPARAZZI_HOME")
+    if PPRZ_HOME is None:
+        raise Exception("PAPARAZZI_HOME environment variable is not set !")
+    sys.path.append(os.path.join(PPRZ_HOME, "var/lib/python"))
+    
+    from pprzlink.ivy import IvyMessagesInterface
+    from pprzlink.message import PprzMessage
+    
+    IVY_APP_NAME = "Basic Interfacing Test"  # This is the name of your app on the Ivy bus
+    DEFAULT_BUS = "127.255.255.255:2010"     # This is your network mask, followed by the port
+    
+    class BasicInterfacing:
+        def __init__(self, ivy_bus=DEFAULT_BUS):
+            # start Ivy interface
+            self.ivy = IvyMessagesInterface(agent_name=IVY_APP_NAME, ivy_bus=ivy_bus)
+            # subscribe to the "FLIGHT_PARAM" message of class "ground"
+            self.ivy.subscribe(self.flight_param_cb, PprzMessage('ground', 'FLIGHT_PARAM'))
+            # subscribe to the "ENGINE_STATUS" message of class "ground"
+            self.ivy.subscribe(self.engine_status_cb, PprzMessage('ground', 'ENGINE_STATUS'))
+
+        def flight_param_cb(self, sender, msg):
+            print("AC {} at pos {}, {} and alt {}".format(msg.ac_id, msg.lat, msg.long, msg.alt))
+
+        def engine_status_cb(self, sender, msg):
+            print("AC {} at {}% throttle, {}V".format(msg.ac_id, msg.throttle, msg.bat))
+        
+        def send_dummy_intruder(self):
+            msg = PprzMessage('ground', 'INTRUDER')
+            msg['id'] = 1
+            msg['name'] = "DUMMY"
+            msg['lat'] = int((43.463 + 0.001*math.sin(0.2*time.time()))*1e7)
+            msg['lon'] = int((1.273 +  0.001*math.cos(0.2*time.time()))*1e7)
+            msg['alt'] = 500
+            msg['course'] = 360 - math.degrees(0.2*time.time())%360
+            msg['speed'] = 10
+            msg['climb'] = 0
+            msg['itow'] = 0
+            self.ivy.send(msg)
+
+
+    if __name__ == '__main__':
+        bi = BasicInterfacing()
+        try:
+            while(True):
+                time.sleep(0.5)
+                bi.send_dummy_intruder()
+                
+        finally:
+            bi.ivy.shutdown()
+
+Using Pprzlink independently of the ground station tools
+--------------------------------------------------------
+
+Do exactly the same thing as above, but listen to messages from the `Telemetry` class.
+
+

doc/sphinx/source/tutorials/intermediate/create_radio.rst

@@ -0,0 +1,96 @@
+.. tutorials main_tutorials intermediate index_intermediate
+
+================================
+Create a new radio configuration
+================================
+
+In this tutotial, you will learn how to create or modify a radio configuration file to use your radio with paparazzi.
+
+For this tutorial, you need to have a working telemetry.
+
+Before starting, you have to bind your radio to the receiver, and configure your radio to send all needed channels. See the documentation of your radio and receiver to do it. For some radios, there is nothing to configure, but for others, you will have to select the channels you want to send. The configuration depend on your radio so it will not be explained here, but you will be able to know if all needed channels are send.
+
+Fist, power-on your radio and your drone, and start a session with the needed processes to fly a drone : you should at least launch the *Server*, the *Data Link* and the *GCS*.
+
+Wait to have link with the drone, then set the telemetry mode to *ppm*.
+
+To change the telemetry mode, go on the *Settings* tab, then *System* and *Telemetry*. Select *ppm* in the drop down box and send this command to the drone by hitting the commit button. Wait for the drone to be in *ppm* mode. (The label at the left of the drop down box should change to *ppm* shortly after hitting the commit button.)
+
+.. image:: ppm_mode.png
+    :alt: Set telemetry in PPM mode.
+    :align: center
+
+Once you are in *ppm* mode, go to the paparazzi center, then launch the "Messages" process (*Tools* -> *Messages*).
+
+You should see a *PPM* section. Click on it to display the values, shown coma separated. If you move the joystick on your radio, the values should change. Check if all needed axis are working, including mode switch and kill switch. If this is not he case, the problem is most probably coming from your radio.
+
+.. image:: ppm_messages.png
+    :alt: PPM messages
+    :align: center
+
+Go in ``$PAPARAZZI_SRC/conf/radio`` and copy the ``dummy.xml`` file with the name of your radio. Edit it, and modify the ``name`` attribute of the ``radio`` tag with your radio name.
+Add as many channel as wanted, based on the following example :
+
+.. code-block:: xml
+
+    <radio name="My own FrSky X9D" data_min="900" data_max="2100" sync_min ="5000" sync_max ="15000" pulse_type="POSITIVE">
+        <channel function="ROLL"     min="987" neutral="1503" max="2011" average="0"/>
+        <channel function="PITCH"    min="987" neutral="1451" max="2011" average="0" reverse="1"/>
+        <channel function="YAW"      min="990" neutral="1500" max="2011" average="0"/>
+        <channel function="THROTTLE" min="998" neutral="998" max="2011" average="0"/>
+        <channel function="MODE"    min="987" neutral="1500" max="2011" average="1"/>
+    </radio>
+
+You should at least have these four channels to control your drone. The last one is for the mode selection.
+
+
+
+It is essential that the order of these lines match the order of the channels in the *Messages* process.
+
+For each channel, move the joystick to its neutral position, then to the extremes positions, and look at the values displayed in the *Messages* process. Write these values in the ``neutral``, ``min`` and ``max`` attributes of the corresponding channel in your radio file. The min value shall be inferior to the max value. If the channel needs to be reversed, set the ``reverse`` attribute to ``1``, such as in the *PITCH* channel of the above example.
+
+.. note::
+
+    For the THROTTLE channel, set the neutral position at the minimum throttle position.
+
+.. warning::
+
+    The old way of reversing a channel was to switch the *min* and *max* attributes. This is still working for compatibility reasons, but it is deprecated and will be an error in the next major release. Please use the *reverse* attibute.
+    
+.. warning::
+
+    There used to be a *ctl* attribute. This is now deprecated, and it have never been used anyway, so remove it if you still have it in your file.
+
+Make sure that the *data_min* and *data_max* attributes are respectively lower and higher than the min and max values you picked up.
+
+See the comments in the radios file for more details.
+
+
+Kill switch configuration
+=========================
+
+For safety reasons, it's a good practise to configure a kill switch before doing any flights with your drone.
+
+To do it, add at the correct position the following channel, and adjust the min, neutral and max values according to your radio.
+
+.. code-block:: xml
+
+    
+    <channel ctl="KILL" function="GEAR"   min="987" neutral="1500" max="2011" average="1"/>
+
+
+Then, in the airframe file, add the following define to the ``radio_control`` module. Create it if necessary :
+
+.. code-block:: xml
+
+    <define name="RADIO_KILL_SWITCH" value="RADIO_GEAR"/>
+    
+
+The result should looks like that, with some differences according to your configuration :
+
+.. code-block:: xml
+
+    <module name="radio_control" type="sbus">
+      <define name="RADIO_KILL_SWITCH" value="RADIO_GEAR"/>
+    </module>
+

doc/sphinx/source/tutorials/intermediate/imu_configuration.rst

@@ -0,0 +1,96 @@
+.. user_guide main_user software airframe airframe_conf imu_configuration
+
+=================
+IMU Configuration
+=================
+
+The IMU is used by the drone to get its attitude and its angular speed around its axis. It is composed of 3 accelerometers and 3 gyroscopes. Some chip also embbed 3 magnetometers. This device needs to be calibrated, and the drone needs to know how it is fixed to its frame.
+
+See http://wiki.paparazziuav.org/wiki/ImuCalibration for more details.
+
+The accelerometers and gyro calibration is relative to the physical device you have. The magneto calibration is relative to the physival device AND the environment, i.e. the drone itself (battery, GPS...).
+
+Accelerometer configuration
+============================
+
+**Add the IMU module**
+
+In your airframe file in the `firmware` section, add the `imu` module corresponding to your hardware (Replace `apogee` in the example below.) :
+
+    .. code-block:: xml
+    
+      <firmware name="fixedwing">
+        ...
+        <module name="imu" type="apogee">
+        ...
+      </firmware>
+
+
+**Get the axis right !**
+
+The drone must know how your IMU is oriented.
+
+.. figure:: pictures_imu/plane_axis.png
+    :alt: Plane axis
+    :align: center
+    
+    Plane axis
+    
+
+
+
+Accelerometer calibration
+==========================
+
+Here is the procedure: 
+
+1. Flash the board with your normal AP firmware (if it is not already on it.)
+2. Switch to the "raw sensors" telemetry mode via GCS->Settings->Telemetry and launch "server" to record a log.
+
+.. figure:: pictures_imu/raw_sensors.jpg
+    :alt: How to set raw sensors telemetry
+    :align: center
+
+    How to set raw sensors telemetry
+
+3. Move your IMU/airframe into different positions to record relevant measurements for each axis.
+
+  + It is important that you get the min/max sensor values on each axis: turn and hold the IMU on all six sides of the 'cube' for about 10 seconds per IMU axis.
+  + During theses 10 seconds, the IMU must be absolutely static. Don't hold it in your hands, you will introduce too much vibrations.
+  + Please note that we talk about the IMU axes here, and not the airframe axes.
+
+.. figure:: pictures_imu/acc_calibration.jpg
+    :alt: Orientations during accelerometer calibration
+    :align: center
+
+    Orientations during accelerometer calibration
+
+
+4. Stop the server so it will write the log file (to var/logs).
+5. Run the Python script on it to get your calibration coefficients and add them to your airframe file.
+    
+    + run the script:
+
+        ``sw/tools/calibration/calibrate.py -s ACCEL -p var/logs/YY_MM_DD__hh_mm_ss.data``
+
+    + If the log file contains logs from more than one aircraft, you will need to use the ``-i <ac_id>`` option, e.g : 
+
+        ``sw/tools/calibration/calibrate.py -i 50 -s ACCEL -p var/logs/YY_MM_DD__hh_mm_ss.data``
+    + If you kept the ``-p`` option, the script will show the plots.
+    + Add (or replace) the output values from this script to the airframe file in the `IMU` section. For example:
+        
+        .. code-block:: xml
+
+          <section name="IMU" prefix="IMU_">
+            <define name="ACCEL_X_NEUTRAL" value="-40"/>
+            <define name="ACCEL_Y_NEUTRAL" value="32"/>
+            <define name="ACCEL_Z_NEUTRAL" value="-33"/>
+            <define name="ACCEL_X_SENS" value="2.45746358482" integer="16"/>
+            <define name="ACCEL_Y_SENS" value="2.46030721866" integer="16"/>
+            <define name="ACCEL_Z_SENS" value="2.46583755829" integer="16"/>
+            ...
+          </section>
+
+
+
+

doc/sphinx/source/tutorials/intermediate/index_intermediate.rst

@@ -8,5 +8,6 @@ TBD
 
 .. toctree ::
 	write_module
-
+	create_radio
+	imu_configuration