diff --git a/doc/sphinx/source/developer_guide/system_overview.rst b/doc/sphinx/source/developer_guide/system_overview.rst index a139872b80..e1313d90a5 100644 --- a/doc/sphinx/source/developer_guide/system_overview.rst +++ b/doc/sphinx/source/developer_guide/system_overview.rst @@ -1,8 +1,8 @@ .. developer_guide dev_first system_overview -====================== +========================= Detailed System Overview -====================== +========================= TBD diff --git a/doc/sphinx/source/index.rst b/doc/sphinx/source/index.rst index d18ded36dc..5190ce4495 100644 --- a/doc/sphinx/source/index.rst +++ b/doc/sphinx/source/index.rst @@ -28,10 +28,10 @@ Contents: :maxdepth: 2 quickstart/index_start - tutorials/index_tutorials installation/index_installation user_guide/index_user_guide 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 2fdfe41ef0..524d89e975 100644 --- a/doc/sphinx/source/installation/index_installation.rst +++ b/doc/sphinx/source/installation/index_installation.rst @@ -4,10 +4,23 @@ Installation ================= -TBD +Paparazzi is very easily installed on any laptop or workstation running the Ubuntu Linux OS or virtually any Debian based Linux. Apple Macintosh running Mac OS X system are also fairly well supported. Windows is supported through the WSL2 module (running a Linux kernel inside Windows10). + +The steps required to install the software needed to be able to let your UAS fly are: + +- Install tools and prerequisites needed by Paparazzi +- Download the source code from the source repository +- Compile the Paparazzi software from sourcecode +- Complete any final configuration .. toctree:: :maxdepth: 2 software/index_software + +You will also need to configure your aircraft according to your airframe and autopilot board: + +.. toctree:: + :maxdepth: 2 + hardware/index_hardware diff --git a/doc/sphinx/source/installation/software/index_software.rst b/doc/sphinx/source/installation/software/index_software.rst index dc09ca0d8f..9a8a0884d0 100644 --- a/doc/sphinx/source/installation/software/index_software.rst +++ b/doc/sphinx/source/installation/software/index_software.rst @@ -4,7 +4,30 @@ Software ====================== -Software installation ... +Downloading the software +________________________ + +The Paparazzi source code is hosted on Github. While you can download it as a tarball from https://github.com/paparazzi/paparazzi/releases, it is recommended to clone the repository with git. + +From the directory of your choice type: + +:: + + git clone --origin upstream https://github.com/paparazzi/paparazzi.git + +If you don't want to work with the latest master branch (it may contain some unstable features), check out the released stable version branch: + +:: + + cd paparazzi + git checkout v5.16 + + +OS-specific instructions +________________________ + +After this point, it is required to install the needed libraries. The procedure depends on the operating system you are using. +Please follow the instruction below: .. toctree :: :maxdepth: 2 @@ -12,3 +35,12 @@ Software installation ... linux mac_os windows + +Buiding and running the code +____________________________ + +Finally, build the ground station tools: + +:: + + make diff --git a/doc/sphinx/source/installation/software/linux.rst b/doc/sphinx/source/installation/software/linux.rst index 771938e6c2..1a625fb3bc 100644 --- a/doc/sphinx/source/installation/software/linux.rst +++ b/doc/sphinx/source/installation/software/linux.rst @@ -4,4 +4,129 @@ Linux ====================== -TBD +.. warning:: + + This guide may be outdated. See http://wiki.paparazziuav.org/wiki/Installation. + +Paparazzi is very easily installed on any laptop or workstation running Ubuntu, Debian (or any of their derivatives). + +The steps required to install the software needed to be able to let your UAS fly + +* Install the basic Paparazzi dependencies and the ARM cross compiling toolchain +* Download the source code from the source repository +* Allow access to your PC hardware connection by adding appropriate Udev rules +* Compile the binaries from the sources and launch the software + +Users of other Linux flavors than a recent Ubuntu or Debian and anyone needing manual control of each individual package can install them independently. + +For the impatient +================= + +For Ubuntu add the `paparazzi-uav ppa `_ (*sudo add-apt-repository ppa:paparazzi-uav/ppa*) +and install the paparazzi-dev package. + + +.. raw:: html + + + + + +Installation of dependencies +============================ +______ +Ubuntu +______ + +Binary packages for Ubuntu are available for the i386, amd64 and armhf architectures. + +Add the installation sources for the Paparazzi software packages. Run from a terminal: + +:: + + sudo add-apt-repository ppa:paparazzi-uav/ppa + +Then update the systems package inventory and install the main Paparazzi software dependencies. This will take some time. + +:: + + sudo apt-get update + sudo apt-get install paparazzi-dev + +______ +Debian +______ + +Binary packages for Debian are available for the i386 and amd64 architectures. armhf packages seem to be currently not supported by the OpenSUSE build service. + +For Debian Wheezy (7.0), Jessie (8.0) and Stretch (9.0) packages are built using the Open Build Service (OBS) on OpenSUSE Build Service project home:flixr:paparazzi-uav + +First add the key: + +:: + + wget -q "http://download.opensuse.org/repositories/home:/flixr:/paparazzi-uav/Debian_9.0/Release.key" -O- | sudo apt-key add - + +Add the appropriate repo, depending on your Debian version to sources.list + +:: + + echo "deb http://download.opensuse.org/repositories/home:/flixr:/paparazzi-uav/Debian_9.0/ ./" | tee -a /etc/apt/sources.list + echo "deb http://download.opensuse.org/repositories/home:/flixr:/paparazzi-uav/Debian_8.0/ ./" | tee -a /etc/apt/sources.list + echo "deb http://download.opensuse.org/repositories/home:/flixr:/paparazzi-uav/Debian_7.0/ ./" | tee -a /etc/apt/sources.list + +Update the systems package inventory and install the main Paparazzi software dependencies. + +:: + + sudo apt-get update + sudo apt-get install paparazzi-dev + + +______________________ +ARM embedded toolchain +______________________ + +For current Paparazzi versions (v5.0 and above) the gcc-arm-embedded toolchain is recommended, which also supports the STM32F4 with FPU (hardware floating point). +gcc-arm-none-eabi as Debian/Ubuntu package + +This is the recommended method + +Note that there are actually two different toolchains available! + +* ARM gcc-arm-embedded toolchain with Debian package name gcc-arm-embedded + + * includes libstdc++ and newlib-nano + +* Debian gcc-arm-none-eabi toolchain + + * does not include libstdc++ + * does not include newlib-nano + +Both toolchains should work for most use-cases (if you don't need C++ or nano specs), although the ARM gcc-arm-embedded toolchain is better tested. + +gcc-arm-embedded toolchain +__________________________ + +This is the recommended toolchain + +On most Ubuntu versions the gcc-arm-embedded toolchain can be installed as a debian package from the ppa: + +:: + + sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa + sudo apt-get update + sudo apt-get install gcc-arm-embedded + +Previously there was a PPA by terry.guo that contained this toolchain under the package name gcc-arm-none-eabi + +gcc-arm-none-eabi Debian toolchain +__________________________________ + +Current Debian (jessie) and Ubuntu (14.04 trusty and later) releases have the gcc-arm-none-eabi package in the official repositories (universe), and can be installed with: + +:: + + sudo apt-get update + sudo apt-get install gcc-arm-none-eabi gdb-arm-none-eabi + diff --git a/doc/sphinx/source/quickstart/first_simulation.rst b/doc/sphinx/source/quickstart/first_simulation.rst index c8381d0951..b7fb1310b7 100644 --- a/doc/sphinx/source/quickstart/first_simulation.rst +++ b/doc/sphinx/source/quickstart/first_simulation.rst @@ -4,6 +4,34 @@ Flight Simulation ====================== -TBD +Launch the simulation +===================== + +- In the paparazzi center, select the **Microjet** aircraft in the *A/C* combobox of the configuration panel. +- Select the **sim** target, and click *Build*. This should build without errors in the console panel, and finish with "DONE". +- Select the **Simulation** session in the execution panel, and click *Execute*. + +A new window opens, this is the GCS (Ground Control Station). + +.. image:: gcs.png + +The GCS layout can be changed, but in this layout there are 3 very important panels: + +- 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. + +Now, lets launch the drone: + +- On the purple panel, you should see that the "Holding Point" block is highlighted. This is the current block. Wait few seconds if the current block is "Wait GPS" or "Geo init". +- In the strip, click on the button in the blue circle. This is a shortcut button for the "Takeoff" block in the flight plan. You can also double click on the "Takeoff" block in the flight plan. +- In real life, we would now launch the drone. In simulation, there is a magic button to do so in the strip. Click on the button in the red circle. + +The drone should now move, and the current block will change to "Standby". + + +The Strip +========= + diff --git a/doc/sphinx/source/quickstart/gcs.png b/doc/sphinx/source/quickstart/gcs.png new file mode 100644 index 0000000000..830fb50b0b Binary files /dev/null and b/doc/sphinx/source/quickstart/gcs.png differ diff --git a/doc/sphinx/source/quickstart/index_start.rst b/doc/sphinx/source/quickstart/index_start.rst index f67efa56a1..b4d2be895d 100644 --- a/doc/sphinx/source/quickstart/index_start.rst +++ b/doc/sphinx/source/quickstart/index_start.rst @@ -4,11 +4,14 @@ QuickStart ================= -TBD +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 5f6781efad..839e824787 100644 --- a/doc/sphinx/source/quickstart/install.rst +++ b/doc/sphinx/source/quickstart/install.rst @@ -4,6 +4,50 @@ Quick Install ====================== -TBD +Paparazzi runs best on **Ubuntu 16.04 or higher**, so this quick installation guide is for Ubuntu users. I you have an other OS or if you want more detailled installation, see the :doc:`../installation/index_installation` page. +Open a terminal and execute each lines below. If one fails, ask for help on gitter. +Add paparazzi repositories 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 + +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 + +*Optionnal:* checkout on a stable version: + +.. code-block:: bash + + 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 + + +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 new file mode 100644 index 0000000000..80cd0a5df6 --- /dev/null +++ b/doc/sphinx/source/quickstart/paparazzi_center_tour.rst @@ -0,0 +1,57 @@ +.. quickstart main_quickstart paparazzi_center_tour + +================= +Paparazzi Center +================= + +The Paparazzi Center is composed of 5 panels, as shown in the image below. + +.. image:: pprz_center.png + + +Configuration panel +==================== + +This panel is dedicated to the configuration of the aircrafts. You can change the current aircraft with the *A/C* combobox. + +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`. + + +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. + +Some usual targets are: + +- **sim**: The basic fixedwing simulator written in OCaml without IMU simulation or any sensor models (noise, bias, etc) and mainly intended to validate your flight plan logic. +- **nps**: NPS is a more advanced rotorcraft and fixedwing simulator with sensor models and commonly uses JSBSim as FDM (Flight Dynamic Model). +- **ap**: This is for a *real* autopilot. + + +If the selected target is not a simulator, you can choose how you want to flash the board by choosing the **Flash mode**. Click on *Upload* to load the firmware on the board. + + +Execution and Running agents panels +==================================== + +In the Execution panel, a combo box provide a set of predefined and user 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). + + +Console panel +============== + +All messages from the programs run from the Paparazzi center will be displayed here. Error messages will be display in red, warnings in orange, and messages in green. + + +Now, lets launch a :doc:`first_simulation`! + + + + diff --git a/doc/sphinx/source/quickstart/pprz_center.png b/doc/sphinx/source/quickstart/pprz_center.png new file mode 100644 index 0000000000..0ff8b473ca Binary files /dev/null and b/doc/sphinx/source/quickstart/pprz_center.png differ diff --git a/doc/sphinx/source/tutorials/beginner/add_drones.rst b/doc/sphinx/source/tutorials/beginner/add_drones.rst index db85983fe4..540948b2e2 100644 --- a/doc/sphinx/source/tutorials/beginner/add_drones.rst +++ b/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. diff --git a/doc/sphinx/source/tutorials/beginner/configuration_capture.png b/doc/sphinx/source/tutorials/beginner/configuration_capture.png new file mode 100644 index 0000000000..caa2ea3bda Binary files /dev/null and b/doc/sphinx/source/tutorials/beginner/configuration_capture.png differ diff --git a/doc/sphinx/source/tutorials/beginner/new_ac.png b/doc/sphinx/source/tutorials/beginner/new_ac.png new file mode 100644 index 0000000000..52a7da7beb Binary files /dev/null and b/doc/sphinx/source/tutorials/beginner/new_ac.png differ diff --git a/doc/sphinx/source/tutorials/index_tutorials.rst b/doc/sphinx/source/tutorials/index_tutorials.rst index 917e7cbf21..d84224e2be 100644 --- a/doc/sphinx/source/tutorials/index_tutorials.rst +++ b/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 diff --git a/doc/sphinx/source/tutorials/interfacing_with_paparazzi.rst b/doc/sphinx/source/tutorials/interfacing_with_paparazzi.rst new file mode 100644 index 0000000000..d116411107 --- /dev/null +++ b/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. + + diff --git a/doc/sphinx/source/tutorials/intermediate/create_radio.rst b/doc/sphinx/source/tutorials/intermediate/create_radio.rst new file mode 100644 index 0000000000..e3672ec8fd --- /dev/null +++ b/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 + + + + + + + + + +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 + + + + + +Then, in the airframe file, add the following define to the ``radio_control`` module. Create it if necessary : + +.. code-block:: xml + + + + +The result should looks like that, with some differences according to your configuration : + +.. code-block:: xml + + + + + diff --git a/doc/sphinx/source/tutorials/intermediate/imu_configuration.rst b/doc/sphinx/source/tutorials/intermediate/imu_configuration.rst new file mode 100644 index 0000000000..2f3984ba74 --- /dev/null +++ b/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 + + + ... + + ... + + + +**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 `` 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 + +
+ + + + + + + ... +
+ + + + diff --git a/doc/sphinx/source/tutorials/intermediate/index_intermediate.rst b/doc/sphinx/source/tutorials/intermediate/index_intermediate.rst index 1c3f5e49f1..5120433ee0 100644 --- a/doc/sphinx/source/tutorials/intermediate/index_intermediate.rst +++ b/doc/sphinx/source/tutorials/intermediate/index_intermediate.rst @@ -8,5 +8,6 @@ TBD .. toctree :: write_module - + create_radio + imu_configuration diff --git a/doc/sphinx/source/tutorials/intermediate/pictures_imu/acc_calibration.jpg b/doc/sphinx/source/tutorials/intermediate/pictures_imu/acc_calibration.jpg new file mode 100644 index 0000000000..63a7209fea Binary files /dev/null and b/doc/sphinx/source/tutorials/intermediate/pictures_imu/acc_calibration.jpg differ diff --git a/doc/sphinx/source/tutorials/intermediate/pictures_imu/apogee_imu_axis.png b/doc/sphinx/source/tutorials/intermediate/pictures_imu/apogee_imu_axis.png new file mode 100644 index 0000000000..03bab6ee49 Binary files /dev/null and b/doc/sphinx/source/tutorials/intermediate/pictures_imu/apogee_imu_axis.png differ diff --git a/doc/sphinx/source/tutorials/intermediate/pictures_imu/plane_axis.png b/doc/sphinx/source/tutorials/intermediate/pictures_imu/plane_axis.png new file mode 100644 index 0000000000..5f0c1d09a1 Binary files /dev/null and b/doc/sphinx/source/tutorials/intermediate/pictures_imu/plane_axis.png differ diff --git a/doc/sphinx/source/tutorials/intermediate/pictures_imu/raw_sensors.jpg b/doc/sphinx/source/tutorials/intermediate/pictures_imu/raw_sensors.jpg new file mode 100644 index 0000000000..366bec064b Binary files /dev/null and b/doc/sphinx/source/tutorials/intermediate/pictures_imu/raw_sensors.jpg differ diff --git a/doc/sphinx/source/tutorials/intermediate/ppm_messages.png b/doc/sphinx/source/tutorials/intermediate/ppm_messages.png new file mode 100644 index 0000000000..dbbc8433db Binary files /dev/null and b/doc/sphinx/source/tutorials/intermediate/ppm_messages.png differ diff --git a/doc/sphinx/source/tutorials/intermediate/ppm_mode.png b/doc/sphinx/source/tutorials/intermediate/ppm_mode.png new file mode 100644 index 0000000000..637d961619 Binary files /dev/null and b/doc/sphinx/source/tutorials/intermediate/ppm_mode.png differ diff --git a/doc/sphinx/source/user_guide/software/gcs.rst b/doc/sphinx/source/user_guide/software/gcs.rst index 13677050a1..6b430e7fd1 100644 --- a/doc/sphinx/source/user_guide/software/gcs.rst +++ b/doc/sphinx/source/user_guide/software/gcs.rst @@ -1,8 +1,8 @@ .. user_guide main_user software gcs -====================== +============================= Ground Control Station (GCS) -====================== +============================= TBD diff --git a/doc/sphinx/source/user_guide/system_overview/system_overview.rst b/doc/sphinx/source/user_guide/system_overview/system_overview.rst index 9e5a8cf967..4ff98bfb5b 100644 --- a/doc/sphinx/source/user_guide/system_overview/system_overview.rst +++ b/doc/sphinx/source/user_guide/system_overview/system_overview.rst @@ -1,8 +1,8 @@ .. user_guide main_user system_overview -====================== +======================== Overall System Overview -====================== +======================== TBD