More Sphinx doc (#2583)

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

doc/sphinx/.gitignore

@@ -0,0 +1,2 @@
+build/
+

doc/sphinx/requirements.txt

@@ -0,0 +1,2 @@
+sphinx_rtd_theme
+

doc/sphinx/source/developer_guide/communication.rst

@@ -0,0 +1,29 @@
+.. developer_guide communication
+
+=============
+Communication
+=============
+
+We saw in the User Guide :doc:`../user_guide/communication` section that you can change which messages are sent, and at which rate. We will see in this section how you can define and send your own messages.
+
+Define a new message
+--------------------
+
+By default, PprzLink default message definition is used. You can find it in ``sw/ext/pprzlink/message_definitions/v1.0/messages.xml``. To add your own messages, you first need to copy this file in your ``conf`` directory.
+
+Add your message in that file on the model of the other messages. Make sure to add it in the appropriate message class (telemetry, datalink, ground, ...), and make sure to use
+a free name and a free ``id`` within this class. This *id* being encoded on a uin8_t, it must be comprise between 1 and 255 (0 is reserved). As you can see, there are not much left in the telemetry class...
+
+.. note:: The ids are uniq within the class but the names are uniq in the whole file: you can't have two messages with the same name, even if they are in different classes.
+
+Re-build paparazzi with ``make`` at the root directory. your message should now be present in the ``var/messages.xml`` file.
+
+
+Send a telemetry message
+------------------------
+
+If you defined a new telemetry message, you now want the drone to send it. You can either send it manually from a module or use the Paparazzi periodic telemetry.
+
+.. warning::
+
+    This section is not written yet, go to `http://wiki.paparazziuav.org/wiki/Telemetry <http://wiki.paparazziuav.org/wiki/Telemetry>`_.

doc/sphinx/source/developer_guide/index_developer.rst

@@ -1,4 +1,4 @@
-.. developer_guide main_developer index_developer
+.. developer_guide index_developer
 
 =================
 Developer Guide
@@ -10,5 +10,6 @@ TBD
     :maxdepth: 2
 
     system_overview
-    developer2
+    communication
+    modules
 

doc/sphinx/source/developer_guide/modules.rst

@@ -0,0 +1,9 @@
+.. developer_guide modules
+
+========
+Modules
+========
+
+TBD
+
+

doc/sphinx/source/developer_guide/system_overview.rst

@@ -1,9 +1,43 @@
-.. developer_guide dev_first system_overview
+.. developer_guide system_overview
 
 =========================
-Detailed System Overview
+System Architecture
 =========================
 
-TBD
+The typical configuration constitute of a standard laptop as ground station and one or more drones, possibly with a RC transmitter for each as safety link. The Command and Control link is made by a pair of modems on the ground and in the drones.
 
+.. image:: general_arch.png
 
+Ground architecture
+-------------------
+
+The Gound Control Station (GCS) constits of multiples programs, communicating with each other by the software bus `Ivy <https://www.eei.cena.fr/products/ivy/>`_.
+
+.. note::
+
+    Ivy is a simple protocol and a set of open-source (LGPL) libraries and programs that allows applications to broadcast information through text messages, with a publisher / subscriber mechanism based on regular expressions.
+
+.. image:: agents_arch.png
+
+The core Paparazzi programs are Link, which handle the communication with the drones, the Server, which maintain the state of all aircrafts, and the GCS, the user facing application to control the drones.
+
+Many other tools have been developed for various use cases, they are available in the *Tools* menu of the paparazzi center. But more interesting: you can write your own tools that will interact with Paparazzi via the Ivy bus.
+
+Airborne architecture
+---------------------
+
+In the case of a fixedwing aircraft, the airborne top level architecture is divided in two processes: the *AP* (autopilot) process which does most of the job, and the *FBW* (Fly by Wire) process. FBW manages the radio receiver and control the servos. In the catastrophic event that the AP process crashes, the aircraft can still be controlled via the RC transmitter.
+
+For the rotorcraft, there is only one process called *Main*.
+
+.. note::
+
+    It is planned to make a failsafe process for rotorcraft that will allow basic stabilization and control of the drone.
+
+.. warning::
+
+    TODO: Explain airborne architecture
+
+.. image:: airborne_arch.png
+
+The aircraft is configured by various XML configuration files: *airframe*, *flight_plan*, *radio* and *telemetry*. theses will be covered in the :doc:`../user_guide/index_user_guide` section.

doc/sphinx/source/index.rst

@@ -27,9 +27,9 @@ Contents:
 .. toctree::
     :maxdepth: 2
 
-    quickstart/index_start
-    installation/index_installation
+    quickstart/index_quick_start
     user_guide/index_user_guide
+    installation/index_installation
     developer_guide/index_developer
     tutorials/index_tutorials
     support/index_support

doc/sphinx/source/installation/index_installation.rst

@@ -13,6 +13,10 @@ The steps required to install the software needed to be able to let your UAS fly
 - Compile the Paparazzi software from sourcecode
 - Complete any final configuration
 
+.. note::
+
+    If you run **Ubuntu** 16.04 or higher LTS (18.04, 20.04), go to the :doc:`../quickstart/install` page to get quickly running !
+
 .. toctree::
     :maxdepth: 2
 

doc/sphinx/source/quickstart/first_flight.rst

@@ -1,9 +1,66 @@
-.. quickstart main_quickstart first_flight
+.. quickstart first_flight
 
 ======================
 Experimental Flight
 ======================
 
-Flying a Bebop2 ...
+The easiest drone to fly with paparazzi is the **Bebop 2**, from Parrot. It is no longer produced but can still be found 2nd hand.
+
+Using the Bebop 2 with Paparazzi
+--------------------------------
+
+Make sure to have a bebop with at least firmware v3.3.0. Update it from FreeFlight pro if needed.
+
+- Start the Paparazzi Center (or Stop/remove all processes)
+- Select the *bebop2* A/C and build it for the *ap* target
+- Power up the Bebop
+- Connect your laptop to the Bebop's wifi network
+- Press the on/off button 4 times
+- Press the "Upload" button and wait. The messages in the console should end with "DONE"
+- Select the Flight UDP/Wifi session, then execute.
+
+You should get the telemetry from the bebop.
+
+
+Making the changes permanent
+----------------------------
+
+In the current state, you have to do the process all over again every time you restart the Bebop. However, you can start Paparazzi by default with the following steps:
+
+- Power up the Bebop
+- Connect your laptop to the Bebop's wifi network
+- Press the on/off button 4 times
+- Open a terminal and go to ``paparazzi/sw/tools/parrot``
+
+Launch ``./bebop.py status``. You should get the current status of the drone's configuration. If it does not work, you may need to add the ``--host`` argument with the drone's IP address like so: ``./bebop.py --host 192.168.1.15 status``.
+
+.. note::
+
+    The default IP address of the bebop is ``192.168.42.1``. In this case, you don't need the ``--host`` argument.
+
+Install the autostart script with ``./bebop.py install_autostart``.
+
+
+Change network settings
+-----------------------
+
+You can change the network settings of the drone to make it connect to an existing WiFi network: ``./bebop.py configure_network mySSID managed dhcp``. You can replace ``dhcp`` by a fixed IP address to use static IP instead of getting the address from your external router DHCP in ``managed`` mode.
+
+
+Calibration
+-----------
+
+The default values may be good enough to be able to fly, but it is recommanded that you calibrate the drone before flying. Go to the :doc:`../tutorials/beginner/sensor_calibration` page to learn how to do that.
+
+
+Connect a Joystick
+------------------
+
+.. note::
+    This part is optionnal but it is recommended to connect a joystick to have an easy way to control your drone, if something unexpected should happen.
+
+Learn how to connect a joystick to your laptop to control your drone on this page: :doc:`../tutorials/beginner/use_joystick`
+
+
 
 

doc/sphinx/source/quickstart/first_simulation.rst

@@ -1,4 +1,4 @@
-.. quickstart main_quickstart first_simu
+.. quickstart first_simu
 
 ======================
 Flight Simulation
@@ -19,7 +19,7 @@ The GCS layout can be changed, but in this layout there are 3 very important pan
 
 - 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 feature various widgets. The first of these describe the flight plan.
+- the purple panel features various widgets. The first of these describes the flight plan.
 
 Now, lets launch the drone:
 
@@ -30,8 +30,3 @@ Now, lets launch the drone:
 The drone should now move, and the current block will change to "Standby".
 
 
-The Strip
-=========
-
-
-

doc/sphinx/source/quickstart/gcs_tour.rst

@@ -0,0 +1,103 @@
+.. quickstart gcs_tour
+
+====
+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.
+
+
+
+

doc/sphinx/source/quickstart/index_quick_start.rst

@@ -0,0 +1,22 @@
+.. quickstart index_quick_start
+
+=================
+Quick Start
+=================
+
+Welcome to the Paparazzi UAV user guide!
+
+This section will let you go throught a quick installation and a first use of Paparazzi.
+
+To start, go to the :doc:`install` page!
+
+.. toctree::
+    :maxdepth: 1
+
+    install
+    system_overview
+    paparazzi_center_tour
+    first_simulation
+    gcs_tour
+    first_flight
+