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/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