diff --git a/doc/sphinx/.gitignore b/doc/sphinx/.gitignore new file mode 100644 index 00000000000..dc84959d1dc --- /dev/null +++ b/doc/sphinx/.gitignore @@ -0,0 +1,2 @@ +build/ + diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt new file mode 100644 index 00000000000..5add663ec40 --- /dev/null +++ b/doc/sphinx/requirements.txt @@ -0,0 +1,2 @@ +sphinx_rtd_theme + diff --git a/doc/sphinx/source/developer_guide/agents_arch.png b/doc/sphinx/source/developer_guide/agents_arch.png new file mode 100644 index 00000000000..5b239ed3e39 Binary files /dev/null and b/doc/sphinx/source/developer_guide/agents_arch.png differ diff --git a/doc/sphinx/source/developer_guide/airborne_arch.png b/doc/sphinx/source/developer_guide/airborne_arch.png new file mode 100644 index 00000000000..d09cb473e76 Binary files /dev/null and b/doc/sphinx/source/developer_guide/airborne_arch.png differ diff --git a/doc/sphinx/source/developer_guide/communication.rst b/doc/sphinx/source/developer_guide/communication.rst new file mode 100644 index 00000000000..64785560786 --- /dev/null +++ b/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 `_. diff --git a/doc/sphinx/source/developer_guide/developer2.rst b/doc/sphinx/source/developer_guide/developer2.rst deleted file mode 100644 index c6c3766675b..00000000000 --- a/doc/sphinx/source/developer_guide/developer2.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. developer_guide dev_second developer2 - -====================== -Developer 2 -====================== - -TBD - - diff --git a/doc/sphinx/source/developer_guide/general_arch.png b/doc/sphinx/source/developer_guide/general_arch.png new file mode 100644 index 00000000000..c2f9b214724 Binary files /dev/null and b/doc/sphinx/source/developer_guide/general_arch.png differ diff --git a/doc/sphinx/source/developer_guide/index_developer.rst b/doc/sphinx/source/developer_guide/index_developer.rst index 7ccfab5335a..30a2cee1f72 100644 --- a/doc/sphinx/source/developer_guide/index_developer.rst +++ b/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 diff --git a/doc/sphinx/source/developer_guide/modules.rst b/doc/sphinx/source/developer_guide/modules.rst new file mode 100644 index 00000000000..bd6c5693f3b --- /dev/null +++ b/doc/sphinx/source/developer_guide/modules.rst @@ -0,0 +1,9 @@ +.. developer_guide modules + +======== +Modules +======== + +TBD + + diff --git a/doc/sphinx/source/developer_guide/system_overview.rst b/doc/sphinx/source/developer_guide/system_overview.rst index e1313d90a52..51fe3d6a408 100644 --- a/doc/sphinx/source/developer_guide/system_overview.rst +++ b/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 `_. + +.. 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. diff --git a/doc/sphinx/source/index.rst b/doc/sphinx/source/index.rst index 5190ce4495e..85e595c89ce 100644 --- a/doc/sphinx/source/index.rst +++ b/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 diff --git a/doc/sphinx/source/installation/index_installation.rst b/doc/sphinx/source/installation/index_installation.rst index 524d89e9759..202b039a0ab 100644 --- a/doc/sphinx/source/installation/index_installation.rst +++ b/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 diff --git a/doc/sphinx/source/quickstart/agents_arch.png b/doc/sphinx/source/quickstart/agents_arch.png new file mode 100644 index 00000000000..5b239ed3e39 Binary files /dev/null and b/doc/sphinx/source/quickstart/agents_arch.png differ diff --git a/doc/sphinx/source/quickstart/first_flight.rst b/doc/sphinx/source/quickstart/first_flight.rst index b6c4ccc57a7..64728fb282d 100644 --- a/doc/sphinx/source/quickstart/first_flight.rst +++ b/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` + + diff --git a/doc/sphinx/source/quickstart/first_simulation.rst b/doc/sphinx/source/quickstart/first_simulation.rst index b7fb1310b7c..ae7759cfcf0 100644 --- a/doc/sphinx/source/quickstart/first_simulation.rst +++ b/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 -========= - - - diff --git a/doc/sphinx/source/quickstart/gcs_strip_1.png b/doc/sphinx/source/quickstart/gcs_strip_1.png new file mode 100644 index 00000000000..d1447001fbb Binary files /dev/null and b/doc/sphinx/source/quickstart/gcs_strip_1.png differ diff --git a/doc/sphinx/source/quickstart/gcs_strip_fixed_settings.png b/doc/sphinx/source/quickstart/gcs_strip_fixed_settings.png new file mode 100644 index 00000000000..d098bf30bba Binary files /dev/null and b/doc/sphinx/source/quickstart/gcs_strip_fixed_settings.png differ diff --git a/doc/sphinx/source/quickstart/gcs_strip_fpsets.png b/doc/sphinx/source/quickstart/gcs_strip_fpsets.png new file mode 100644 index 00000000000..b849cd2e17f Binary files /dev/null and b/doc/sphinx/source/quickstart/gcs_strip_fpsets.png differ diff --git a/doc/sphinx/source/quickstart/gcs_tour.rst b/doc/sphinx/source/quickstart/gcs_tour.rst new file mode 100644 index 00000000000..4456df5f588 --- /dev/null +++ b/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. + + + + diff --git a/doc/sphinx/source/quickstart/general_arch.png b/doc/sphinx/source/quickstart/general_arch.png new file mode 100644 index 00000000000..c2f9b214724 Binary files /dev/null and b/doc/sphinx/source/quickstart/general_arch.png differ diff --git a/doc/sphinx/source/quickstart/index_quick_start.rst b/doc/sphinx/source/quickstart/index_quick_start.rst new file mode 100644 index 00000000000..028485e8b6f --- /dev/null +++ b/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 + diff --git a/doc/sphinx/source/quickstart/index_start.rst b/doc/sphinx/source/quickstart/index_start.rst deleted file mode 100644 index b4d2be895de..00000000000 --- a/doc/sphinx/source/quickstart/index_start.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. quickstart main_quickstart index_start - -================= -QuickStart -================= - -This guide will let you to throught a quick installation and a first use of Paparazzi. - -To start, go to the :doc:`install` page! - -.. toctree:: - :maxdepth: 3 - - install - paparazzi_center_tour - first_simulation - first_flight diff --git a/doc/sphinx/source/quickstart/install.rst b/doc/sphinx/source/quickstart/install.rst index 839e824787f..599d811eb2f 100644 --- a/doc/sphinx/source/quickstart/install.rst +++ b/doc/sphinx/source/quickstart/install.rst @@ -1,4 +1,4 @@ -.. quickstart main_quickstart install +.. quickstart install ====================== Quick Install @@ -8,46 +8,64 @@ Paparazzi runs best on **Ubuntu 16.04 or higher**, so this quick installation gu Open a terminal and execute each lines below. If one fails, ask for help on gitter. -Add paparazzi repositories and install dependencies: +Version specific prerequisites +------------------------------ + +**If you have Ubuntu 20.04:** + +.. code-block:: bash + + sudo apt-get install python-is-python3 gcc-arm-none-eabi gdb-multiarch + +**If you have Ubuntu 18.04 or lower:** + +.. code-block:: bash + + sudo add-apt-repository -y ppa:team-gcc-arm-embedded/ppa + sudo apt-get install gcc-arm-embedded + sudo apt-get update + +Install Paparazzi +----------------- + +Add paparazzi apt-repository and install dependencies: .. code-block:: bash - sudo add-apt-repository -y ppa:paparazzi-uav/ppa - sudo add-apt-repository -y ppa:team-gcc-arm-embedded/ppa - sudo apt-get update - sudo apt-get -f -y install paparazzi-dev paparazzi-jsbsim gcc-arm-embedded + sudo add-apt-repository -y ppa:paparazzi-uav/ppa + sudo apt-get update + sudo apt-get -f -y install paparazzi-dev paparazzi-jsbsim dfu-util Clone the repository: .. code-block:: bash - cd ~ - git clone --origin upstream https://github.com/paparazzi/paparazzi.git - cd ~/paparazzi - git remote update -p - sudo cp conf/system/udev/rules/*.rules /etc/udev/rules.d/ - sudo udevadm control --reload-rules - + cd ~ + git clone --origin upstream https://github.com/paparazzi/paparazzi.git + cd ~/paparazzi + git remote update -p + sudo cp conf/system/udev/rules/*.rules /etc/udev/rules.d/ + sudo udevadm control --reload-rules + *Optionnal:* checkout on a stable version: .. code-block:: bash - git checkout -b v5.16 upstream/v5.16 + git checkout -b v5.16 upstream/v5.16 Get the submodules and build Paparazzi. This step might take a long time the first time you launch it: .. code-block:: bash - make - - + make -j1 + +.. note:: + The ``-j1`` argument may not be necessary, but if you are not familiar with paparazzi, its safer to use it. However, it will make paparazzi build much slower. + Finally, launch Paparazzi with .. code-block:: bash ./paparazzi - -.. note:: - If it doesn't work, the previous step might have failed. In that case, recompile with with ``make -j1``, then try again to launch Paparazzi. If all went well the Paparazzi Center should now be running. Please continue to the next page for a guided tour. diff --git a/doc/sphinx/source/quickstart/paparazzi_center_tour.rst b/doc/sphinx/source/quickstart/paparazzi_center_tour.rst index 80cd0a5df69..15a02e40476 100644 --- a/doc/sphinx/source/quickstart/paparazzi_center_tour.rst +++ b/doc/sphinx/source/quickstart/paparazzi_center_tour.rst @@ -1,4 +1,4 @@ -.. quickstart main_quickstart paparazzi_center_tour +.. quickstart paparazzi_center_tour ================= Paparazzi Center @@ -16,13 +16,18 @@ This panel is dedicated to the configuration of the aircrafts. You can change th 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 in the :doc:`../user_guide/index_user_guide`. +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 wich target you want to build the firmware with the **Target** combobox. Build and clean the firmware with the *Build* and *Clean* buttons. +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: @@ -37,11 +42,11 @@ If the selected target is not a simulator, you can choose how you want to flash Execution and Running agents panels ==================================== -In the Execution panel, a combo box provide a set of predefined and user sessions (collections of programs). +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 (Stop/Redo buttons). +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 diff --git a/doc/sphinx/source/quickstart/system_overview.rst b/doc/sphinx/source/quickstart/system_overview.rst new file mode 100644 index 00000000000..c49dac9f654 --- /dev/null +++ b/doc/sphinx/source/quickstart/system_overview.rst @@ -0,0 +1,18 @@ +.. quickstart system_overview + +======================== +Overall System Overview +======================== + +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 + +The Gound Control Station (GCS) constitute of multiples programs, communicating with each other by a software bus. + +.. image:: agents_arch.png + +The core Paparazzi ground 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 case, they are available in the *Tools* menu of the paparazzi center. + diff --git a/doc/sphinx/source/tutorials/intermediate/pictures_imu/acc_calibration.jpg b/doc/sphinx/source/tutorials/beginner/acc_calibration.jpg similarity index 100% rename from doc/sphinx/source/tutorials/intermediate/pictures_imu/acc_calibration.jpg rename to doc/sphinx/source/tutorials/beginner/acc_calibration.jpg diff --git a/doc/sphinx/source/tutorials/beginner/add_drones.rst b/doc/sphinx/source/tutorials/beginner/add_drones.rst index 540948b2e2e..2e2c742a33e 100644 --- a/doc/sphinx/source/tutorials/beginner/add_drones.rst +++ b/doc/sphinx/source/tutorials/beginner/add_drones.rst @@ -1,4 +1,4 @@ -.. tutorials main_tutorials beginner add_drones +.. tutorials beginner add_drones ========================= Add Drones diff --git a/doc/sphinx/source/tutorials/beginner/airframe_setup.rst b/doc/sphinx/source/tutorials/beginner/airframe_setup.rst index cf35eac0fe7..ad93fb81db0 100644 --- a/doc/sphinx/source/tutorials/beginner/airframe_setup.rst +++ b/doc/sphinx/source/tutorials/beginner/airframe_setup.rst @@ -1,4 +1,4 @@ -.. tutorials main_tutorials beginner airframe_setup +.. tutorials beginner airframe_setup ====================== Airframe Setup diff --git a/doc/sphinx/source/tutorials/beginner/flight_plan_setup.rst b/doc/sphinx/source/tutorials/beginner/flight_plan_setup.rst index c8da5c30eec..1326d4bb06d 100644 --- a/doc/sphinx/source/tutorials/beginner/flight_plan_setup.rst +++ b/doc/sphinx/source/tutorials/beginner/flight_plan_setup.rst @@ -1,4 +1,4 @@ -.. tutorials main_tutorials beginner flight_plan +.. tutorials beginner flight_plan ====================== Flight Plan Setup diff --git a/doc/sphinx/source/tutorials/beginner/gcs_setup.rst b/doc/sphinx/source/tutorials/beginner/gcs_setup.rst index 60ed942fd12..29467f90887 100644 --- a/doc/sphinx/source/tutorials/beginner/gcs_setup.rst +++ b/doc/sphinx/source/tutorials/beginner/gcs_setup.rst @@ -1,4 +1,4 @@ -.. tutorials main_tutorials beginner gcs_setup +.. tutorials beginner gcs_setup ====================== GCS Setup diff --git a/doc/sphinx/source/tutorials/beginner/index_beginner.rst b/doc/sphinx/source/tutorials/beginner/index_beginner.rst index 5b16a9deeb3..c6ddf41ebd1 100644 --- a/doc/sphinx/source/tutorials/beginner/index_beginner.rst +++ b/doc/sphinx/source/tutorials/beginner/index_beginner.rst @@ -1,4 +1,4 @@ -.. tutorials main_tutorials beginner +.. tutorials beginner ====================== Beginner @@ -7,12 +7,13 @@ Beginner TBD .. toctree :: - gcs_setup - airframe_setup - add_drones - flight_plan_setup - testing_and_tuning - sensor_calibration + use_joystick + gcs_setup + airframe_setup + add_drones + flight_plan_setup + testing_and_tuning + sensor_calibration diff --git a/doc/sphinx/source/tutorials/beginner/mag_calibration.png b/doc/sphinx/source/tutorials/beginner/mag_calibration.png new file mode 100644 index 00000000000..fcc5f4eb2f9 Binary files /dev/null and b/doc/sphinx/source/tutorials/beginner/mag_calibration.png differ diff --git a/doc/sphinx/source/tutorials/intermediate/pictures_imu/plane_axis.png b/doc/sphinx/source/tutorials/beginner/plane_axis.png similarity index 100% rename from doc/sphinx/source/tutorials/intermediate/pictures_imu/plane_axis.png rename to doc/sphinx/source/tutorials/beginner/plane_axis.png diff --git a/doc/sphinx/source/tutorials/intermediate/pictures_imu/raw_sensors.jpg b/doc/sphinx/source/tutorials/beginner/raw_sensors.jpg similarity index 100% rename from doc/sphinx/source/tutorials/intermediate/pictures_imu/raw_sensors.jpg rename to doc/sphinx/source/tutorials/beginner/raw_sensors.jpg diff --git a/doc/sphinx/source/tutorials/beginner/sensor_calibration.rst b/doc/sphinx/source/tutorials/beginner/sensor_calibration.rst index 5abb797084e..f199edd05df 100644 --- a/doc/sphinx/source/tutorials/beginner/sensor_calibration.rst +++ b/doc/sphinx/source/tutorials/beginner/sensor_calibration.rst @@ -1,9 +1,189 @@ -.. tutorials main_tutorials beginner sensor_calibration +.. tutorials beginner sensor_calibration ====================== Sensor Calibration ====================== -TBD +The Accelerometers and magnetometers must be calibrated for the drone to fly correctly. +Accelerometer calibration +========================== + +1. Flash the board with your normal AP firmware (if it is not already on it.) +2. Switch to the "raw sensors" telemetry mode in the GCS via Settings->Telemetry and make sure that *Server* is running without the ``-n`` option. + +.. figure:: raw_sensors.jpg + :alt: How to set raw sensors telemetry + :align: center + + Set raw sensors telemetry mode + +3. Move your IMU/airframe into different positions to record relevant measurements for each IMU 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 as you will introduce too much vibrations, prefer holding it on a wall. + +.. note:: + + We talk about the **IMU axis** here, not the drone's axis. So be carrefull if IMU axis are not aligned with the drone's axis. + +.. figure:: 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`` + + .. note:: + + The calibration script needs scipy and matplotlib python libraries. If you don't have these, install them with ``sudo apt install python3-scipy python3-matplotlib``. + + + + If the log file contains logs from more than one aircraft, you will need to use the ``-i `` 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 + +
+ + + + + + + ... +
+ +.. note:: + For the accelerometer calibration, your autopilot board does not necessarily need to be in your drone's airframe as it depends only on the specific accelerometer chip you have. + +Magnetometer calibration +========================= + +The procedure is very much similar to accelerometer calibration with two differences: + ++ On step 3, Slowly spin your aircraft around all axes. Ideally you would spin it around all axes until you have densely covered the whole sphere with magnetometer measurements. (See figure below) ++ On step 5, use the ``MAG`` argument: + + ``sw/tools/calibration/calibrate.py -s MAG -p var/logs/YY_MM_DD__hh_mm_ss.data`` + +.. figure:: mag_calibration.png + :alt: A good calibration dataset + :align: center + + A good calibration set + +Copy the XML output in the *IMU* section of your airframe file. + +.. note:: + For the magnetometer calibration, your autopilot board **needs** to be in your drone's airframe as it depends on all interferences of the environment, like the wires around the magnetometer, the position of the battery, and maybe the position of saturn in the sky. + + +IMU orientation +================ + +The drone must know how your IMU is oriented. + +The drone axis are defined like so: + +- Z is vertical down, aligned with the gravity +- X is toward the front of the drone +- Y is to right of the drone + +.. figure:: plane_axis.png + :alt: Plane axis + :align: center + + Drone axis + +According to how you mounted the autopilot board/IMU in the drone, the IMU axes are not necessarily aligned with the drone's axes. + +Check if the axes are correct by watching the IMU_ACCEL message: + +- Put your drone on its natural attitude. **az** value should be approx **-10**, **ax** and **ay** being around **0**. +- Nose down **ax** is **-10**, **ay** and **az** are **0** +- Right wing down, **ay** is **-10**, **ax** and **az** are **0** + +If the signs are not correct (10 instead of -10), change them in the following lines : + +.. code-block:: xml + +
+ ... + + + + ... +
+ +.. note:: + + If the axis are not correct (e.g. X and Y should be swaped), you can switch them, however this is driver dependent. Here is an example for the Apogee autopilot, where X and Y are swaped: + + .. code-block:: xml + +
+ ... + + + + ... +
+ + +You have to do the same thing for the GYRO signs. It is very likely that you will use the same signs as the ACCEL signs. + +.. code-block:: xml + +
+ ... + + + + ... +
+ + +To check gyro signs, watch the IMU_GYRO message: + +- **gp** must be positive when banking to the right (gq and gr approx 0) +- **gq** must be positive when pitching up (gp and gr approx 0) +- **gr** must be positive when heading clockwise from top view (gq and gq approx 0) + +.. note:: + + The gyrometers measures rotation **speeds**, so if e.g. you bank the drone 45° right and stop, **gp** will increase, then come back to 0. + +The resulting axes must form direct (right-handed) coordinates. That means that you will most probaly have a even number of changes: either two negative signs, or one negative sign and two axes swaped. + +Finally, flash the drone with your modifications, then check the PFD. put the drone down and wait for 20-40s. If it turn, you have a bad setting. Then Check the directions of pitch up, pitch down, and rolls. For each check, rotate the drone by approx 20 degrees and wait. If the PFD move back, you probably miss a negative sign. + + +The IMU may not be perfectly aligned with the drone body. In this case, you can use the BODY_TO_IMU defines: + +.. code-block:: xml + +
+ ... + + + + ... +
+ +- PHI is the roll axis (around X) +- THETA is along the pitch axis (around Y) +- PSI is along the yaw axis (around Z) + +In the example above from a fixedwing, BODY_TO_IMU_THETA is set to 3 degrees for the drone to be slightly pitching up. diff --git a/doc/sphinx/source/tutorials/beginner/testing_and_tuning.rst b/doc/sphinx/source/tutorials/beginner/testing_and_tuning.rst index 75ceff04fe1..e213f181b3c 100644 --- a/doc/sphinx/source/tutorials/beginner/testing_and_tuning.rst +++ b/doc/sphinx/source/tutorials/beginner/testing_and_tuning.rst @@ -1,4 +1,4 @@ -.. tutorials main_tutorials beginner testing_and_tuning +.. tutorials beginner testing_and_tuning ====================== Testing and Tuning diff --git a/doc/sphinx/source/tutorials/beginner/use_joystick.rst b/doc/sphinx/source/tutorials/beginner/use_joystick.rst new file mode 100644 index 00000000000..1d0882d5cc5 --- /dev/null +++ b/doc/sphinx/source/tutorials/beginner/use_joystick.rst @@ -0,0 +1,28 @@ +.. tutorials beginner gcs_setup + +=============== +Use a Joystick +=============== + +You can use a joystick to command your drone via the datalink if you don't have an RC transmitter. + +Currently supported joysticks are listed in the ``paparazzi/conf/joystick`` directory. + +Learn how to configure a new joystick on this page: :doc:`../intermediate/create_joystick` + ++ Open the airframe file of you aircraft and change the *radio_control* type to *datalink* : ````. Build and upload to the drone. + +.. note:: For the first time you try it, remove the propeller blades from you drone : if your configuration is wrong, motors could start spinning and hurt you! + ++ Start a session as usual for your drone ++ Start the "Joystick" tool : Tools->Joystick, and stop the program (it might already be crashed because of a bad options) ++ Edit the Joystick command : ``$PAPARAZZI_SRC/sw/ground_segment/joystick/input2ivy -ac AC_NAME JOYSTICK_CONFIG_FILE.xml``. ++ Replace **AC_NAME** by the name of the aircraft (it is probably good as it takes the current A/C), and replace **JOYSTICK_CONFIG_FILE** by a filename from ``paparazzi/conf/joystick``. + +.. attention:: Initial sticks positions default to middle position until the axis has been moved. Move all axis to avoid bad surprises. + + You can also use the ``-c`` option (c meaning *check*) to prevent sending messages with bad values. Messages will start beeing sent only when all axis received events. + + ``$PAPARAZZI_SRC/sw/ground_segment/joystick/input2ivy -ac AC_NAME JOYSTICK_CONFIG_FILE.xml -c`` + +.. note:: Save the programs as a new session to avoid doing that all over again every time! diff --git a/doc/sphinx/source/tutorials/intermediate/create_joystick.rst b/doc/sphinx/source/tutorials/intermediate/create_joystick.rst new file mode 100644 index 00000000000..f521131cc2f --- /dev/null +++ b/doc/sphinx/source/tutorials/intermediate/create_joystick.rst @@ -0,0 +1,185 @@ +.. tutorials intermediate create_joystick + +==================================== +Create a new joystick configuration +==================================== + +New joystick configurations can be added in the ``paparazzi/conf/joystick`` directory. + +Profile a joystick +================== + +Test if your joystick is recognized: plug your joystick then run ``dmesg``. The message is different for every device, but the last lines should look like these:: + + [49174.642275] usb 1-1: new low-speed USB device number 8 using xhci_hcd + [49174.812307] usb 1-1: New USB device found, idVendor=046d, idProduct=c214, bcdDevice= 2.05 + [49174.812309] usb 1-1: New USB device strings: Mfr=1, Product=2, SerialNumber=0 + [49174.812310] usb 1-1: Product: Logitech Attack 3 + [49174.812311] usb 1-1: Manufacturer: Logitech + [49174.823264] input: Logitech Logitech Attack 3 as /devices/pci0000:00/0000:00:14.0/usb1/1-1/1-1:1.0/0003:046D:C214.000B/input/input37 + [49174.823608] hid-generic 0003:046D:C214.000B: input,hidraw4: USB HID v1.10 Joystick [Logitech Logitech Attack 3] on usb-0000:00:14.0-1/input0 + + +Launch ``./sw/ground_segment/joystick/test_stick``. It will display joystick informations, then print current status:: + + Available button: 5 (0x5) + Available hats: 0 (0x0) + Available axes: 4 (0x4) + Axis 0 : parameters = [-32768,32768] + Axis 1 : parameters = [-32768,32768] + Axis 2 : parameters = [-32768,32768] + Axis 3 : parameters = [-32768,32768] + Input device name: "Amazing Joystick" on SDL device "0" + buttons 0 0 0 0 0 | hat 0 | axes 0 0 0 0 + buttons 0 0 0 0 0 | hat 0 | axes 0 0 0 0 + buttons 0 0 0 0 0 | hat 0 | axes 0 0 0 0 + buttons 0 0 0 0 0 | hat 0 | axes 1 -40 0 0 + buttons 0 0 0 0 0 | hat 0 | axes -33 -83 0 0 + buttons 0 0 0 0 0 | hat 0 | axes -101 0 0 0 + +.. note:: Your joystick may need to be calibrated. Go to the :ref:`Calibration` section below. + +Create a new file for your joystick in the ``paparazzi/conf/joystick`` directory with the syntax of the following example: + +.. code-block:: xml + + + + + + + +