PaparazziUAV - User contributions [en]

JTAG

2014-12-26T21:21:28Z

Alonsoac: /* Upgrade BMP firmware */

==Introduction==
A JTAG interface is designed for on-chip debugging. It can also be used to flash your firmware if you do not have a means to upload software via USB already. For short, if you want to upload your own software or want to do serious paparazzi development work, the you need a JTAG adapter like this.

See also:
* [[FirmwareFlashing#JTAG|firmware flashing via JTAG]]
* [[DevGuide/JTAG-Debug|debugging with JTAG]]

==JTAG Adapters==
There are multiple Paparazzi-compatible devices available that support JTAG.

Below you find a list of JTAG devices that you can use in combination with e.g. a Paparazzi Lisa/M board.

=== FLOSS JTAG ===

The FLOSS JTAG is based on an FTDI chip that allows two simultaneous USB connections, which means that FLOSS JTAG allows JTAG and UART/COM connections.

Let's take a look at upper side of the board. It contains JTAG connector (which is connected on photo) and two sets of RX/TX LEDs for JTAG and UART/COM interface separately. The JTAG connector is 2x5 pins, 0.05-inch pitch, and is compatible with the Samtec FFSD-05-D-06.00-01-N-RW-R ribbon cable.

[[Image:Jtag-up.jpg]]

On the other side of the board there is 4 pin UART/COM connector, which contains (from top to bottom in the image below): Ground (black), RX (orange), TX (yellow), and +5V (red)

[[Image:Jtag-down.jpg]]

Usage of board is pretty simple: JTAG can be used to upload firmware into the board and/or repair board with broken bootloader, and UART/COM interfaced can be used to make "COM port style" connection to the board. COM connection can be used for example for telemetry debug.

More info available on the [http://randomprojects.org/wiki/Floss-JTAG randomprojects.org wiki].

=== Black Magic Probe ===

[[Image:BMPM_1_top.jpg|500x500px]][[Image:BMPM_1_bottom.jpg|500x500px]]

Some additional info about the Black Magic Probe is available at the [http://www.blacksphere.co.nz/main/blackmagic Black Sphere Technology website].

To use Black Magic Probe instead of FLOSS-JTAG or Luftboot for firmware flashing, append the following string to the upload command:

On Linux:
FLASH_MODE=JTAG_BMP BMP_PORT=/dev/ttyACM0
On Mac OS:
FLASH_MODE=JTAG_BMP BMP_PORT=/dev/cu.usbmodem<serial>

To make this the default flash method add this in the airframe file firmware section:
<configure name="FLASH_MODE" value="JTAG_BMP"/>
<configure name="BMP_PORT" value="/dev/ttyACM0"/>

See the [[FirmwareFlashing]] page for other methods.

==== Benefits ====

There are good reasons to use the Black Magic Probe Mini instead of FLOSS-JTAG:

*Lower cost
*No need for OpenOCD as BMPM has a built in GDB server
*Orders of magnitude faster as all the high speed protocol logic happens on the built-in STM32
*Supports Serial Wire Debug (SWD)
*Supports tracing using the SWD trace pin
*No need for loading and unloading of FTDI drivers on Mac OS X

====UART port====
The pinout for the UART port on the back side of the BMP as seen on the image above and starting from the top is ground,rx,tx,3.3v . You can use this for receiving telemetry.

====Upgrade BMP firmware====

Check firmware version:
$ sudo /usr/bin/arm-none-eabi-gdb
(gdb) target extended-remote /dev/ttyACM0
(gdb) monitor version

To upgrade the brain of your Black Magic Probe, a.k.a. its firmware:

- Download the compiled firmware from http://blacksphere.co.nz/builds/ (more info at https://github.com/blacksphere/blackmagic/wiki/Frequently-Asked-Questions)
- Download and run the stm32_mem.py script:
$ git clone git://blackmagicdebug.git.sourceforge.net/gitroot/blackmagicdebug/blackmagicdebug
$ cd blackmagicdebug/src/scripts
$ ./stm32_mem.py blackmagic-XXXX.bin (this is the .bin file you downloaded in previous step)

=== FT2232H Mini Module ===

Use ftdi prog to change the Description String into: FLOSS-JTAG. <br/>
More information for this board at [[Serial_Adapter]].
[[File:AlternativeFlossJtag.png]]

[[Category:Hardware]] [[Category:Software]] [[Category:Developer_Documentation]]

JTAG

2014-12-26T21:14:22Z

Alonsoac: /* Upgrade BMP firmware */

==Introduction==
A JTAG interface is designed for on-chip debugging. It can also be used to flash your firmware if you do not have a means to upload software via USB already. For short, if you want to upload your own software or want to do serious paparazzi development work, the you need a JTAG adapter like this.

See also:
* [[FirmwareFlashing#JTAG|firmware flashing via JTAG]]
* [[DevGuide/JTAG-Debug|debugging with JTAG]]

==JTAG Adapters==
There are multiple Paparazzi-compatible devices available that support JTAG.

Below you find a list of JTAG devices that you can use in combination with e.g. a Paparazzi Lisa/M board.

=== FLOSS JTAG ===

The FLOSS JTAG is based on an FTDI chip that allows two simultaneous USB connections, which means that FLOSS JTAG allows JTAG and UART/COM connections.

Let's take a look at upper side of the board. It contains JTAG connector (which is connected on photo) and two sets of RX/TX LEDs for JTAG and UART/COM interface separately. The JTAG connector is 2x5 pins, 0.05-inch pitch, and is compatible with the Samtec FFSD-05-D-06.00-01-N-RW-R ribbon cable.

[[Image:Jtag-up.jpg]]

On the other side of the board there is 4 pin UART/COM connector, which contains (from top to bottom in the image below): Ground (black), RX (orange), TX (yellow), and +5V (red)

[[Image:Jtag-down.jpg]]

Usage of board is pretty simple: JTAG can be used to upload firmware into the board and/or repair board with broken bootloader, and UART/COM interfaced can be used to make "COM port style" connection to the board. COM connection can be used for example for telemetry debug.

More info available on the [http://randomprojects.org/wiki/Floss-JTAG randomprojects.org wiki].

=== Black Magic Probe ===

[[Image:BMPM_1_top.jpg|500x500px]][[Image:BMPM_1_bottom.jpg|500x500px]]

Some additional info about the Black Magic Probe is available at the [http://www.blacksphere.co.nz/main/blackmagic Black Sphere Technology website].

To use Black Magic Probe instead of FLOSS-JTAG or Luftboot for firmware flashing, append the following string to the upload command:

On Linux:
FLASH_MODE=JTAG_BMP BMP_PORT=/dev/ttyACM0
On Mac OS:
FLASH_MODE=JTAG_BMP BMP_PORT=/dev/cu.usbmodem<serial>

To make this the default flash method add this in the airframe file firmware section:
<configure name="FLASH_MODE" value="JTAG_BMP"/>
<configure name="BMP_PORT" value="/dev/ttyACM0"/>

See the [[FirmwareFlashing]] page for other methods.

==== Benefits ====

There are good reasons to use the Black Magic Probe Mini instead of FLOSS-JTAG:

*Lower cost
*No need for OpenOCD as BMPM has a built in GDB server
*Orders of magnitude faster as all the high speed protocol logic happens on the built-in STM32
*Supports Serial Wire Debug (SWD)
*Supports tracing using the SWD trace pin
*No need for loading and unloading of FTDI drivers on Mac OS X

====UART port====
The pinout for the UART port on the back side of the BMP as seen on the image above and starting from the top is ground,rx,tx,3.3v . You can use this for receiving telemetry.

====Upgrade BMP firmware====

To upgrade the brain of your Black Magic Probe, a.k.a. its firmware:

- Download the compiled firmware from http://blacksphere.co.nz/builds/ (more info at https://github.com/blacksphere/blackmagic/wiki/Frequently-Asked-Questions)
- Download and run the stm32_mem.py script:
$ git clone git://blackmagicdebug.git.sourceforge.net/gitroot/blackmagicdebug/blackmagicdebug
$ cd blackmagicdebug/src/scripts
$ ./stm32_mem.py blackmagic-XXXX.bin (this is the .bin file you downloaded in previous step)

=== FT2232H Mini Module ===

Use ftdi prog to change the Description String into: FLOSS-JTAG. <br/>
More information for this board at [[Serial_Adapter]].
[[File:AlternativeFlossJtag.png]]

[[Category:Hardware]] [[Category:Software]] [[Category:Developer_Documentation]]

Module/Airspeed ETS

2014-12-21T02:25:46Z

Alonsoac: /* Introduction */

= Introduction =

[[Image:Ets_airspeed_v3.jpg|thumb|right|Eagletree Airspeed v3]]
<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Modules</categorytree>

The EagleTree Airspeed Sensor is a low cost module and comes with a good [http://en.wikipedia.org/wiki/Pitot_tube pitot tube] (Prandtl style, pitot-static tube) that includes static and dynamic ports. It has an I²C interface that connects directly to the Autopilot I²C port.

NOTE: the sensor has two operating modes which determine what value is sent to the autopilot. In the default mode the pressure diference between the 2 ends of the pitot is sent. Supposedly this could be used to calculate airspeed but in reality temperature must also be taken into account. The rest of this page assumes that a temperature reading is not needed and the usefullness is in question. Do not use it for any serious stuff.<BR>
In the other mode, called "third party mode", the actual speed value is sent as shown in the sensor. The sensor is said by the manufacturer to take temperature into account to arrive at this value so this should be used as the correct speed. Unfortunately the Paparazzi code does not work in this mode and additional hardware (an EagleTree elogger) is needed to put the sensor in this mode.

{|border="1"
|-valign="top"
||Module name||sensors/airspeed_ets
|-
|Sensor type
|air speed
|-
|Range
|4m/s .. 150m/s
|-
|Resolution
|0.3m/s
|-
|Refresh rate
|10Hz
|-
|I2C address
|0xEA
|}

[http://www.eagletreesystems.com/Support/manuals/airspeed-v3.pdf Product data sheet]

= Hardware =

The sensor can directly be connected to an I2C port of and autopilot. The + supply voltage can be between 3V and 16V.

When you buy the airspeed sensor it is set to operate in the default mode.

<span style="color:#FF0000">'''Caution!'''</span> Make sure you did not set it somehow to 3rd party mode.

== Wiring ==

The ETS Airspeed sensor has an I2C cable with the following layout:

{|border="1"
|-valign="top"
||'''Tiny/TWOG I2C pin'''||'''Autopilot I2C'''||'''ETS Airspeed wire colour'''
|-
|1
|GND
|white
|-
|2
| +5V
|red
|-
|3
| +3.3V
|
|-
|4
|SDA
|yellow
|-
|5
|SCL
|brown
|}

Please refer to your boards documentation to find out the correct pinout on your board (which cable to connect to which pin).
As an example the correct pinout for the TWOG v1.0 and Tiny has been given in the table above.

= Usage =

To use it load the ''airspeed_ets'' module:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
...
<load name="airspeed_ets.xml" />
...
</modules>
</source>
}}

Depending on your board and the I2C interface you are using, you may need to
enable I2CX, where X is 0,1,2,etc., if you are not using it already:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware>
...
<define name="USE_I2C0" /> 
<define name="USE_I2C1" /> 
<define name="USE_I2C2" /> 
<define name="USE_I2C3" /> 
</firmware>
</source>
}}

== Configuration ==

You can also set some '''optional parameters to change the default configuration'''.
For example to use I2C1 instead of I2C0, a scale of 1.44 (default is 1.8) and offset of 50 (default is 0) is needed:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
<load name="airspeed_ets.xml">

<define name="AIRSPEED_ETS_SCALE" value="1.44"/>
<define name="AIRSPEED_ETS_OFFSET" value="50"/>
<define name="AIRSPEED_ETS_I2C_DEV" value="i2c1"/>
</load>
</modules>
</source>
}}

== Usage as sensor for speed control ==

To use the sensor to control the speed of your aircraft add the aggressive climb flag, define which I2C device you are enabling and enable airspeed control:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<target name="ap" board="twog_1.0">
<define name="AGR_CLIMB"/>
<define name="USE_I2C0"/> 
<define name="USE_AIRSPEED"/> 
</target>
</source>
}}

=== Airframe configuration ===

Now to use real airspeed values for adjusting your aircrafts autopilot behavior there are several way to accomplish this. A simple classic way is to add the following to the end of the "VERTICAL CONTROL" section of your airframe file:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<section name="VERTICAL_CONTROL" prefix="V_CTL_">
....

<define name="AUTO_AIRSPEED_SETPOINT" value="13.0" unit="m/s" /> 
<define name="AUTO_AIRSPEED_PGAIN" value="0.060" />
<define name="AUTO_AIRSPEED_IGAIN" value="0.050" />

<define name="AUTO_GROUNDSPEED_SETPOINT" value="7.0" unit="m/s" /> 
<define name="AUTO_GROUNDSPEED_PGAIN" value="0.75" />
<define name="AUTO_GROUNDSPEED_IGAIN" value="0.25" />
</section>
</source>
}}

Note that the SETPOINT values may need to be adjusted to suit your aircraft.

Note that depending on whether you set the AIRSPEED setpoint or the GROUNDSPEED setpoint higher, either constant airspeed or constant groundspeed, respectively, will be the goal of the controller.

See paparazzi/conf/airframes/easystar_ets_example.xml for an example airframe configuration.

Better even is to start using ETECS, '''E'''nhanced '''T'''otal '''E'''nergy '''C'''ontrol '''S'''ystem

Take a look at See paparazzi/conf/airframes/MentorEnergy.xml for an example airframe configuration.

=== Debugging and logging the airspeed values ===

To debug or log the raw values from the ETS airspeed sensor define SENSOR_SYNC_SEND in your airframe file to send the message AIRSPEED_ETS on every sensor reading.
Note that defining this sends the AIRSPEED_ETS message at the sensor read rate as defined in conf/modules/airspeed_ets.xml.
This does not have any bearing on the AIRSPEED message (if both SENSOR_SYNC_SEND and USE_AIRSPEED are defined, then both messages are sent).

<span style="color:#FF0000">'''Caution!'''</span> ''Please note: if you are using the master branch and have merged commits on or later than July 16, 2013, please replace SENSOR_SYNC_SEND with AIRSPEED_ETS_SYNC_SEND''

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
<load name="airspeed_ets.xml">
<define name="SENSOR_SYNC_SEND"/>
</load>
</modules>
</source>
}}

The general airspeed can be displayed in the Messages tool by adding the AIRSPEED message to the telemetry file as follows:
{{Box Code|conf/telemetry/default.xml|
<source lang="xml">
<process name="Ap">
<mode name="default">
<message name="AIRSPEED" period="1.0"/>
...
</source>
}}

The AIRSPEED_ETS message does NOT need to be added to the telemetry configuration since it is sent directly by the module if SENSOR_SYNC_SEND is defined.

=== NOTES ===
# In the GCS, the strip displays ground speed and '''not''' airspeed by default. In order to display airspeed, drag-and-drop the airspeed message field from the Messages tool onto the 2D map of the GCS.
# The telemetry name AIRSPEED" should actually be called SPEED and contains Groundspeed and airspeed return values.

== Measurement only ==

To use the sensor for airspeed measurement is also possible. This Measurement only mode does thus not imput to the control loops to have effect to the aircraft behaviour.

To see the sensors data in the log file set the SENSOR_SYNC_SEND in your airframe file. Every time new data is available it will be sent directly.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
<load name="airspeed_ets.xml">
<define name="SENSOR_SYNC_SEND"/>
</load>
</modules>
</source>
}}

<span style="color:#FF0000">'''Caution!'''</span> ''Please note: if you are using the master branch and have merged commits on or later than July 16, 2013, please replace SENSOR_SYNC_SEND with AIRSPEED_ETS_SYNC_SEND''

===Result message===

The raw data (adc), estimated offset at init time (offset) and the converted result (scaled) is written to the log file.
{{Box Code|conf/messages.xml|
<source lang="xml">
<message name="AIRSPEED_ETS" id="57">
<field name="adc" type="uint16" />
<field name="offset" type="uint16" />
<field name="scaled" type="float" />
</message>
</source>
}}

Sample log file lines
149.529 123 AIRSPEED_ETS 1626 1606 8.024844
149.633 123 AIRSPEED_ETS 1626 1606 8.024844
149.730 123 AIRSPEED_ETS 1627 1606 7.942226
149.841 123 AIRSPEED_ETS 1628 1606 7.942226

=Issues=

Some people report that the sensor only works after a fresh upload, not after a regular power on. Adding a AIRSPEED_ETS_START_DELAY setting could help getting it to work. For this to work need at least version 5.2 of Paparazzi.

Add the following to your module part in your airframe XML document. Where ''value'' can be anything from 0.01 to 4seconds. Some users report that a value of 1 fixes the issue for them.

<load name="airspeed_ets.xml">

...
<define name="AIRSPEED_ETS_START_DELAY" value="1"/>
...

</load>

[[Category:User_Documentation]] [[Category:Modules]]

TCP Aircraft Server

2014-08-20T02:35:39Z

Alonsoac: document additional tcp methods

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Tools</categorytree>
__TOC__

The <tt>tcp aircraft server</tt> (in <tt>sw/tools/tcp_aircraft_server/</tt>) is an agent that re-broadcasts the ivy telemetry stream from a specified vehicle over tcp to a specified remote ip which hosts its own local ground segment ivy network. This allows the broadcast of a vehicle telemetry stream over the internet to a remote party without the need for VPNs.

== Usage ==

=== Broadcast Ground Station ===

If you have not done so already, set your Paparazzi src and home directories:

export PAPARAZZI_SRC=~/path/to/paparazzi
export PAPARAZZI_HOME=~/path/to/paparazzi

Then, from your Paparazzi directory, run:
./sw/ground_segment/tmtc/ivy_tcp_aircraft -id <ac_id_number> -h <remote IP>

=== Recipient Computer, option #1 ===

Run:
./sw/tools/tcp_aircraft_server/tcp_aircraft_server.py

Then open [[Paparazzi_Center|Paparazzi Center]] using the -n option for the [[Server]] unless you wish to log messages locally, and use the tools within Paparazzi Center as you would do normally.

The recipient side of the setup broadcasts locally over the default Paparazzi ivy bus 127.255.255.255:2010

=== Recipient Computer, option #2 ===

This allows for a multiple tier control architecture.

Designate one computer as the server and run these 2 programs. First one communicates with remote controllers and second one with ground stations.

./sw/ground_segment/tmtc/broadcaster -f TM -t DL -p 4243
./sw/ground_segment/tmtc/broadcaster

Designate the same or another or several other computers as remote controller and run:
./sw/ground_segment/tmtc/ivy_tcp_controller -h <ip address of server computer>

On the controller open [[Paparazzi_Center|Paparazzi Center]] using the -n option for the [[Server]] unless you wish to log messages locally, and use the tools within Paparazzi Center as you would do normally.

You can connect multiple ground stations to the same server.

All of these programs accept a --help argument and will show more options.

NOTE: For this to work it is necessary to synchronize the compiled code in the aircraft, the controller and the ground station.

[[Category:Tools]] [[Category:User_Documentation]]

Subsystem/actuators

2014-06-28T04:14:28Z

Alonsoac: fix MKK and add MKK v2

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Subsystems</categorytree>
This subsystem only needs be explicitly specified for rotorcrafts where there are several different actuators implementations and you have to add the correct one depending on the ESCs you use.

Currently possible actuators subsystems are
* ''mkk''
* ''asctec''
* ''asctec_v2''
* ''pwm''
* ''skiron''
* ''heli''
* ''ardrone2''

== MKK ==
Mikrokopter ESCs
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="mkk">
<configure name="MKK_I2C_SCL_TIME" value="50"/> 
<configure name="ACTUATORS_MKK_I2C_DEV" value="i2c1"/>
</subsystem>
<define name="I2C_TRANSACTION_QUEUE_LEN" value="10"/> 
</firmware>
</source>
}}

* ''MKK_I2C_SCL_TIME'' is specific to LPC21x based boards (e.g. booz) and has no effect for STM32 based boards (e.g. Lisa/M/L)

=== XML configuration ===

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<section name="ACTUATORS_MKK" prefix="ACTUATORS_MKK_">
<define name="NB" value="4"/>
<define name="ADDR" value="{ 0x52, 0x54, 0x56, 0x58 }"/>
<define name="DEVICE" value="i2c1"/>
</section>
<servos driver="mkk">
<servo name="FRONT" no="0" min="0" neutral="2" max="255"/>
<servo name="RIGHT" no="1" min="0" neutral="2" max="255"/>
<servo name="BACK" no="2" min="0" neutral="2" max="255"/>
<servo name="LEFT" no="3" min="0" neutral="2" max="255"/>
</servos>
<command_laws>
<call fun="motor_mixing_run(autopilot_motors_on,FALSE,values)"/>
<set servo="FRONT" value="motor_mixing.commands[SERVO_FRONT]"/>
<set servo="BACK" value="motor_mixing.commands[SERVO_BACK]"/>
<set servo="RIGHT" value="motor_mixing.commands[SERVO_RIGHT]"/>
<set servo="LEFT" value="motor_mixing.commands[SERVO_LEFT]"/>
</command_laws>
</source>
}}

The order of addresses in the list defines the numbering of motors! Warn on this during motor mixing!

You also need the matching [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]].
For Paparazzi versions older than 5.0 MKK specific values for SUPERVISION defines:
* ''STOP_MOTOR'' : 0, optional, as the default is already 0
* ''MIN_MOTOR'' : 3
* ''MAX_MOTOR'' : 200
This does not apply to version 5.0 and above.

== MKK v2 ==

Similar to the above, this is version 2 of the MKK ESCs. The configuration is the same as above, just change mkk to mkk_v2 and MKK to MKK_V2.

This also works with ESCs that have the SimonK firmware and that have I2C support. Very limited documentation is available at [https://github.com/sim-/tgy/ the github page]. It should be noted that you will need to compile and load the firmware for each motor as you will need to change the I2C address for each one to match the ADDR define. If you have success with this please post some more info here.

== Asctec v1 ==
These controllers already to the mixing themselves, so the [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]] section is not needed.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="asctec"/>
</firmware>
</source>
}}

== Asctec v2 ==
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="asctec_v2"/>
</firmware>
</source>
}}
=== XML configuration ===
You need the matching [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]].

== PWM ==
Only for stm32 based autopilot boards (eg. Lisa/M, Lisa/L)
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="pwm">
<define name="SERVO_HZ" value="400"/>
</subsystem>
</firmware>
</source>
}}

The define ''SERVO_HZ'' sets a higher update frequency for the pwm controllers which is needed for good response times on some ESCs. Some newer ESCs are said to work better with lower frequencies. More information should be added here.
=== XML configuration ===
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<servos min="0" neutral="0" max="0xff">
<servo name="FRONT" no="0" min="1000" neutral="1000" max="2000"/>
<servo name="BACK" no="1" min="1000" neutral="1000" max="2000"/>
<servo name="LEFT" no="2" min="1000" neutral="1000" max="2000"/>
<servo name="RIGHT" no="3" min="1000" neutral="1000" max="2000"/>
</servos>
</source>
}}
You also need the matching [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]].

== Dual PWM ==
This driver allows you to generate dual pulses to control for example double servos like those :

[[File:Dual linear servos.jpg]]

The signal we want to generate look like that :

[[File:Dual_pulse.png]]

During the time of a regular pwm pulse (20ms) we got two parts :
* the first 1 with a total period of 4ms. During that part we generate the first pulse that is going to control for exemple the first servo.
* the first 2 with a total period of 16ms. During that part we generate the second pulse that is going to control for exemple the second servo.

=== How to use the driver ===

<span style="color:#FF0000">'''CAUTION!'''</span> <b>This module is only implemented on the lisa M and lisa S boards at the time of writing this documentation (28 mars 2014)</b>

First of all you are going to need to add the subsystem that is going to generate those pulses :

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing">
<target name="ap" board="lisa_s_0.1">
...
</target>

...

<subsystem name="actuators" type="dualpwm">
<define name="DUAL_PWM_ON"/>
</subsystem>

</firmware>
</source>
}}

=== XML configuration ===
Then we will be able to add a servo block into the airframe file (in the same way we would for regular servos). But we have to specify the driver that we are using for thoses servos :

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
...
<servos driver="DualPwm">
<servo name="SWITCH" no="3" min="1100" neutral="1500" max="1900"/>
<servo name="pitchator" no="2" min="1100" neutral="1500" max="1900"/>
</servos>
...
</source>
}}

<span style="color:#FF0000">'''CAUTION!'''</span> <b>The tricky part about this module is that it requires the use of the full timer (that was previously shared between multiple regular pwm). In order to reduce the wast of pins we can only put that type of servos on specifics pins :
* lisa S (version 0.1) : on the servos 2 and 3 (as shown above). The dual PWM will then but outputted on the 5th pin (yes that is not logical).
* lisa M (version 2.0) : on the servos 4 and 5. The dual PWM will be outputted on the 4th pin.
</b>

[[Category:User_Documentation]] [[Category:Subsystems]]

Subsystem/actuators

2014-06-28T02:36:29Z

Alonsoac: /* XML configuration */

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Subsystems</categorytree>
This subsystem only needs be explicitly specified for rotorcrafts where there are several different actuators implementations and you have to add the correct one depending on the ESCs you use.

Currently possible actuators subsystems are
* ''mkk''
* ''asctec''
* ''asctec_v2''
* ''pwm''
* ''skiron''
* ''heli''
* ''ardrone2''

== MKK ==
Mikrokopter ESCs
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="mkk">
<configure name="MKK_I2C_SCL_TIME" value="50"/> 
</subsystem>
<define name="I2C_TRANSACTION_QUEUE_LEN" value="10"/> 
</firmware>
</source>
}}

* ''MKK_I2C_SCL_TIME'' is specific to LPC21x based boards (e.g. booz) and has no effect for STM32 based boards (e.g. Lisa/M/L)

=== XML configuration ===
required defines in section ''ACTUATORS_MKK'':
* ''NB'': number of motors
* ''ADDR'': the I2C addresses of your motors
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<section name="ACTUATORS_MKK" prefix="ACTUATORS_MKK_">
<define name="NB" value="4"/>
<define name="ADDR" value="{ 0x52, 0x54, 0x56, 0x58 }"/>
</section>
</source>
}}
The order of addresses in the list defines the numbering of motors! Warn on this during motor mixing!

You also need the matching [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]].
For Paparazzi versions older than 5.0 MKK specific values for SUPERVISION defines:
* ''STOP_MOTOR'' : 0, optional, as the default is already 0
* ''MIN_MOTOR'' : 3
* ''MAX_MOTOR'' : 200
This does not apply to version 5.0 and above.

== Asctec v1 ==
These controllers already to the mixing themselves, so the [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]] section is not needed.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="asctec"/>
</firmware>
</source>
}}

== Asctec v2 ==
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="asctec_v2"/>
</firmware>
</source>
}}
=== XML configuration ===
You need the matching [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]].

== PWM ==
Only for stm32 based autopilot boards (eg. Lisa/M, Lisa/L)
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="pwm">
<define name="SERVO_HZ" value="400"/>
</subsystem>
</firmware>
</source>
}}

The define ''SERVO_HZ'' sets a higher update frequency for the pwm controllers which is needed for good response times on some ESCs. Some newer ESCs are said to work better with lower frequencies. More information should be added here.
=== XML configuration ===
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<servos min="0" neutral="0" max="0xff">
<servo name="FRONT" no="0" min="1000" neutral="1000" max="2000"/>
<servo name="BACK" no="1" min="1000" neutral="1000" max="2000"/>
<servo name="LEFT" no="2" min="1000" neutral="1000" max="2000"/>
<servo name="RIGHT" no="3" min="1000" neutral="1000" max="2000"/>
</servos>
</source>
}}
You also need the matching [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]].

== Dual PWM ==
This driver allows you to generate dual pulses to control for example double servos like those :

[[File:Dual linear servos.jpg]]

The signal we want to generate look like that :

[[File:Dual_pulse.png]]

During the time of a regular pwm pulse (20ms) we got two parts :
* the first 1 with a total period of 4ms. During that part we generate the first pulse that is going to control for exemple the first servo.
* the first 2 with a total period of 16ms. During that part we generate the second pulse that is going to control for exemple the second servo.

=== How to use the driver ===

<span style="color:#FF0000">'''CAUTION!'''</span> <b>This module is only implemented on the lisa M and lisa S boards at the time of writing this documentation (28 mars 2014)</b>

First of all you are going to need to add the subsystem that is going to generate those pulses :

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing">
<target name="ap" board="lisa_s_0.1">
...
</target>

...

<subsystem name="actuators" type="dualpwm">
<define name="DUAL_PWM_ON"/>
</subsystem>

</firmware>
</source>
}}

=== XML configuration ===
Then we will be able to add a servo block into the airframe file (in the same way we would for regular servos). But we have to specify the driver that we are using for thoses servos :

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
...
<servos driver="DualPwm">
<servo name="SWITCH" no="3" min="1100" neutral="1500" max="1900"/>
<servo name="pitchator" no="2" min="1100" neutral="1500" max="1900"/>
</servos>
...
</source>
}}

<span style="color:#FF0000">'''CAUTION!'''</span> <b>The tricky part about this module is that it requires the use of the full timer (that was previously shared between multiple regular pwm). In order to reduce the wast of pins we can only put that type of servos on specifics pins :
* lisa S (version 0.1) : on the servos 2 and 3 (as shown above). The dual PWM will then but outputted on the 5th pin (yes that is not logical).
* lisa M (version 2.0) : on the servos 4 and 5. The dual PWM will be outputted on the 4th pin.
</b>

[[Category:User_Documentation]] [[Category:Subsystems]]

Lisa/M v2.0

2014-06-26T16:33:47Z

Alonsoac: /* Using JTAG */ add note about BMP

<div style="float: right; width: 15%"><categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Autopilots</categorytree></div>
<div style="float: right; width: 45%; overflow: hidden">[[Image:LisaM_V2_0_TopView.JPG|right|500px|Lisa/M V2.0 top view]]</div>
<div style="float: right; width: 40%">__TOC__</div>

Lisa/M is a small, general purpose autopilot designed with flexibility across multiple applications in mind. Small weight and size, with (optional) integrated [[AspirinIMU | Aspirin IMU]] and full size 0.1" servo headers make the Lisa/M suitable for both fixed-wing and rotorcraft vehicles. This autopilot is based on a STM32 processor for extensive peripheral connection and faster processing.

A number of tutorials are being prepared for getting started with Lisa/M:
* [[Lisa/M/Tutorial/FixedWing|Fixedwing tutorial]]
* [[Lisa/M/Tutorial/RotorCraft|Rotorcraft tutorial]]

Please join us in our quest to make the getting started information even more, eh... informative, by adjusting those pages with your own improvements.

== Features ==

Lisa/M is based on the 64 pins STM32F105RCT6 [http://www.st.com/internet/mcu/product/221023.jsp connectivity line family] processor featuring 64k of RAM and 256k of FLASH. All the pins are exposed, providing access to the complete set of the STM32 peripherals.
NOTE: This MCU is different from LISA/L. Lisa/L is based on the 64 pins STM32F103RE processor featuring 64k of RAM and 512k of FLASH, which is part of the [http://www.st.com/internet/mcu/product/164485.jsp high-density performance line family].

* STM32 microcontroller [http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATASHEET/CD00220364.pdf STM32F105RCT6 datasheet] with 256kB flash and 64kB RAM
* Pressure sensor [http://www.bosch-sensortec.com/content/language1/html/3477.htm BMP085] (optional as of 08/2012)
* 7 x Analog input channels
* 3 x Generic digital in-/out-puts
* 2 x 3.3V TTL UART (5V tolerant)
* 8 x Servo PPM outputs (only 6 if second I2C (I2C1) bus in use)
* 1 x CAN bus
* 1 x [http://en.wikipedia.org/wiki/Serial_Peripheral_Interface SPI] bus
* 1 x [http://en.wikipedia.org/wiki/I2c I<sup>2</sup>C] bus (2 x when using only the first 6 Servo PPM outputs)
* 1 x Micro USB
* 4 x status LEDs with attached test point
* 10.8 grams (0.4 oz) (with Aspirin IMU mounted)
* 9.9 grams (0.35 oz) (without Aspirin IMU mounted)
* ~34mm x ~60mm x ~10mm
* 4 layers PCB design

With mounted Aspirin IMU has the following additional sensors on board:

* 3 Axis Gyroscope
* 3 Axis Accelerometer
* 3 Axis Magnetometer
* Barometer MS5611 (as of Aspirin v2.1)

NOTE:
'''Lisa/M has pads for the BMP085 pressure sensor. Lias/M 2 boards made before August 2012 had the BMP085 sensor mounted. Boards made after August 2012 do not have the sensor mounted as they are designed to be used with Aspirin 2.1 which has the new MS5611-01BA03 barometric pressure sensor.'''

The drivers for the MS5611-01BA03 are '''work in progress''' and are available in the master branch of the Paparazzi codebase. All '''help''' with testing and improving the driver are '''very welcome'''!

So, except for a GPS unit you have all necessary sensors for full attitude and altitude stabilization in an extremely small package.

<gallery widths=200px heights=200px>
Image:LisaM_V2_0_TopView.JPG|Lisa/M V2.0 top view
Image:LisaM_V2_0_BottomView.JPG|Lisa/M V2.0 bottom view
</gallery>

== Pinout ==
Pins Name and Type are specified with respect to the Autopilot Board.

<div style="float: right; width: 100%">
[[Image:LisaM_V2_0_top_labeled.png|900px]]
[[Image:LisaM_warning_label.png|200px]]
</div>

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''SERVO1/2/3/4/5/6/7/8'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||SERVOx||OUT||Servo signal (PWM)(See Note 1 below)||style="background:Yellow; color:black"|Yellow
|-
|2||SV||PWR||Servo Bus Voltage Rail (conf w/ JP1)||style="background:red; color:white"|Red
|-
|3||GND||PWR||common ground||style="background:black; color:white"|Black
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''JTAG'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||N/A||N/A||JTAG Debug Header (Pin 1 is +3V3)||style="background:white; color:black"|None
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''UART3'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2||V_IN||PWR||UART Voltage (conf w/ JP6 and JP7)||style="background:Red; color:white"|Red
|-
|3||TX||OUT||USART3 Serial Output (3.3V level)||style="background:Yellow; color:black"|Yellow
|-
|4||RX||IN||USART3 Serial Input (3.3V level)(Pullup to Pin 2 voltage)(5V tolerant)||style="background:Orange; color:white"|Orange
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''UART1/5'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||3.3V Rail from autopilot (conf w/ JP8 and JP9)||style="background:Red; color:white"|Red
|-
|3||RX1||IN||USART1 Serial Input (3.3V level)(Pullup to Pin 2 voltage)(5V tolerant)||style="background:Orange; color:white"|Orange
|-
|4||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|5|| +3V3||PWR||3.3V Rail from autopilot (conf w/ JP8 and JP9)||style="background:Red; color:white"|Red
|-
|6||RX5||IN||UART5 Serial Input (3.3V level)(Pullup to Pin 5 voltage)(5V tolerant)||style="background:Orange; color:white"|Orange
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''GPIO'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||3.3V Rail from autopilot||style="background:Red; color:white"|Red
|-
|4||PC12||I/O||GPIO, connected to PC12 (5V tolerant)||style="background:#FDC579; color:black"|Dark Tan
|-
|5||TRST||I/O||JTAG_TRST (also connected to LED1 cathode)||style="background:#FED6B1; color:black"|Light Tan
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''ANALOG2'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||3.3V Rail from autopilot||style="background:Red; color:white"|Red
|-
|3|| +5V||PWR||5V Rail from autopilot||style="background:Red; color:white"|Red
|-
|4||ADC4||I/O||by default connected to LED_4 cathode (Remove LED/resistor to use as ADC4)||style="background:magenta; color:white"|Magenta
|-
|5||ADC6||I/O||by default connected to LED_3 cathode (Remove LED/resistor to use as ADC6)||style="background:#FFA1B2; color:black"|Pink
|-
|6||BOOT0||I/O||BOOT0||style="background:grey; color:black"|Grey
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''USB'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||N/A||N/A||USB (The USB connections are also available as 0.05" (1.27mm) through hole pads underneath the GPIO header)||style="background:white; color:black"|None
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''I2C1 CAN'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| V_BATT||PWR||V_BATT Bus on autopilot, voltage divider for V_BAT_MEAS, (conf w/ JP2 to connect to V_IN)||style="background:Red; color:white"|Red
|-
|3|| V_IN||PWR||Connected to autopilot voltage regulator inputs (conf w/ JP1, JP2 and JP3)||style="background:Red; color:white"|Red
|-
|4||CANL||I/O||CANL (5V level)||style="background:orange; color:white"|Orange
|-
|5||CANH||I/O||CANH (5V level)||style="background:yellow; color:black"|Yellow
|-
|6||SCL||I/O||SCL (5V level)(See Note 1 below)||style="background:green; color:white"|Green
|-
|7||SDA||I/O||SDA (5V level)(See Note 1 below)||style="background:blue; color:white"|Blue
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''SPI1'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||3.3V Rail from autopilot||style="background:Red; color:white"|Red
|-
|3||MOSI||Out||MOSI||style="background:orange; color:white"|Orange
|-
|4||MISO||In||MISO||style="background:yellow; color:black"|Yellow
|-
|5||SCK||Out||SCK||style="background:green; color:white"|Green
|-
|6||SS||Out||SS||style="background:blue; color:white"|Blue
|-
|7||DRDY||I/O||DRDY||style="background:#FDC579; color:black"|Dark Tan
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''ANALOG1'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||3.3V Rail from autopilot||style="background:Red; color:white"|Red
|-
|3|| +5V||PWR||5V Rail from autopilot||style="background:Red; color:white"|Red
|-
|4||ADC1||In||ADC1 (or LED_6 if populated)||style="background:green; color:white"|Green
|-
|5||ADC2||In||ADC2 (or LED_7 if populated)||style="background:blue; color:white"|Blue
|-
|6||ADC3||In||ADC3 (or LED_8 if populated)||style="background:#FED6B1; color:black"|Light Tan
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''UART2'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||UART Voltage (conf w/ JP4 and JP5)||style="background:Red; color:white"|Red
|-
|3||TX||OUT||USART2 Serial Output (3.3V level)||style="background:Yellow; color:black"|Yellow
|-
|4||RX||IN||USART2 Serial Input (3.3V level)('''NOT 5V TOLERANT''')(Pullup to Pin 2 voltage)||style="background:Orange; color:white"|Orange
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''I2C2'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||3.3V Rail from autopilot||style="background:Red; color:white"|Red
|-
|3||SCL||I/O||SCL (3.3V level)||style="background:green; color:white"|Green
|-
|4||SDA||I/O||SDA (3.3V level)||style="background:blue; color:white"|Blue
|}

'''NOTE 1''': SERVO7 and SERVO8 are directly connected to I2C1_SCL and I2C1_SDA lines. Therefore one has to choose, either use SERVO7 and SERVO8 '''OR''' have the I2C1 bus available, if that one needs to be used for whatever reason alongside the I2C2 bus. To use the servos 7 and 8 just set the <define name="USE_SERVOS_7AND8"/> in your airframe file and you are good to go. For this to work one must make sure to have the latest Paparazzi sourcecode.

=== LEDs ===
Lisa/M 2.0 has 5 LEDS (+1 power LED). There are 3 additional LEDs (LED_6, LED_7, LED_8) that are not populated by default (in favor of using ADC1-3 on the ANALOG1 connector).
By default the LEDs are use for:
; LED_1, red: ''SYS_TIME_LED'': blinks with 1Hz
; LED_2, green : ''AHRS_ALIGNER_LED'': blinks until the AHRS is aligned (gyro bias initilalized) and then stays on
; LED_3, green : ''GPS_LED'': blinking if trying to get a fix, on if 3D fix
; LED_4, red : ''RADIO_CONTROL_LED'': on if RC signal is ok
; LED_5, green : not set to anything by default

=== Jumper Configuration ===
There are a number of jumpers on Lisa/M used to configure voltage levels and power input.

The default configuration is UART3 VCC at V_IN, UART1/2/5 VCC at +3V3, with the V_SERVO servo voltage rail NOT connected to the autopilot V_IN rail, allowing one to power the autopilot and servos separately. The +5V regulator is NOT bypassed, allowing a regulated +5V on listed headers and for the CAN transceiver and I2C level shifter. The V_BATT connector is NOT connected to V_IN, so one can attach a battery voltage to the V_BATT pin to measure the battery voltage, if so desired.

<gallery widths=380px heights=205px>
Image:LisaM_V2_0_top_jumpers_and_leds.png | Lisa/M v2.0 Top Jumpers and LEDs
Image:LisaM_V2_0_bottom_jumpers.png | Lisa/M v2.0 Bottom Jumpers
</gallery>
<br style="clear:both">

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''Power Jumper Configuration'''
!width="7%"|''Jumper''!!width="20%"|''Bus Connection''!!width="7%"|''Default''!!''Description''
|-
|JP1||SERVO_BUS to V_IN||OPEN||Connects servo header voltage rail SERVO_BUS to autopilot input voltage V_IN rail
|-
|JP2||V_BATT to V_IN||OPEN||Connects I2C1/CAN rail V_BATT to autopilot input voltage V_IN rail
|-
|JP3||V_IN to +5V||OPEN||Connects autopilot input voltage V_IN rail to autopilot +5V rail, bypassing onboard 5V supply
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''UART3 VCC Configuration'''
!width="7%"|''Jumper''!!width="20%"|''Bus Connection''!!width="7%"|''Default''!!''Description''
|-
|JP6||UART3_VCC to V_IN||style="background:black; color:white"|CLOSED||Connects UART3 connector VCC to autopilot input voltage V_IN rail
|-
|JP7||UART3_VCC to +3V3||OPEN||Connects UART3 connector VCC to autopilot +3V3 rail
|}
'''WARNING: UART3 GPS Connector is connected to V_IN, check your GPS input voltage before connecting!!!'''

'''WARNING: DO NOT CLOSE BOTH JP6 AND JP7 SIMULTANEOUSLY!!!'''

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''UART2 VCC Configuration'''
!width="7%"|''Jumper''!!width="20%"|''Bus Connection''!!width="7%"|''Default''!!''Description''
|-
|JP4||UART2_VCC to V_IN||OPEN||Connects UART2 connector VCC to autopilot input voltage V_IN rail '''SEE WARNING BELOW'''
|-
|JP5||UART2_VCC to +3V3||style="background:black; color:white"|CLOSED||Connects UART2 connector VCC to autopilot +3V3 rail
|}
'''WARNING: UART2 RX is NOT 5V TOLERANT. Thus, while possible to connect UART2_VCC to V_IN, DO NOT ATTEMPT THIS. Only use JP5 (the default).

'''WARNING: DO NOT CLOSE BOTH JP4 AND JP5 SIMULTANEOUSLY!!!'''

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''UART1 and UART5 VCC Configuration'''
!width="7%"|''Jumper''!!width="20%"|''Bus Connection''!!width="7%"|''Default''!!''Description''
|-
|JP8||UART1&5_VCC to V_IN||OPEN||Connects UART1 and UART5 connector VCC to autopilot input voltage V_IN rail
|-
|JP9||UART1&5_VCC to +3V3||style="background:black; color:white"|CLOSED||Connects UART1 and UART5 connector VCC to autopilot +3V3 rail
|}
'''WARNING: DO NOT CLOSE BOTH JP8 AND JP9 SIMULTANEOUSLY!!!'''

There are additional jumpers on the board for expert or developer configurations, please see [[Lisa/M_v20#Schematic|schematic]] and [[Lisa/M_v20#Downloads|layout]] for more information.

=== Powering the Board ===

[[Image:LisaM_warning_label.png|right|200px]]

The 3.3V regulator on Lisa/M is a [http://www.micrel.com/page.do?page=/product-info/products/mic5209.shtml MIC5209-3.3YM] capable of delivering up to 500mA. While it is possible to power this regulator with up to 16V, '''DO NOT''' do this. By default, the UART3 RX pin is pulled up to the input voltage V_IN. For this reason, 5V is the maximum input voltage. Note that the UART3 GPS Connector is connected to V_IN, check your GPS input voltage before connecting. If one desires to have V_IN at a higher voltage, the jumpers should be adjusted accordingly. As noted, this regulator can handle up to 16V, though experience has shown that this regulator can become very hot in operation with high input voltages, resulting in potential thermal shutdown while in flight. Depending on the expected current draw, it is best to power this regulator with a lower voltage. 5V is the perfect choice.

The onboard 5V regulator on Lisa/M is a [http://www.national.com/pf/LP/LP2992.html LP2992], a low-noise, low-dropout linear regulator capable of delivering up to 250mA. This regulator can be bypassed with JP3, connecting the autopilot V_IN bus directly to the autopilot 5V bus if, for example, one is using an external 5V regulated supply, and a higher current is needed. Unless external use of 5V is required on the ANALOG1 and ANALOG2 headers, the only 5V usage onboard is for the CAN transceiver and the I2C1 level shifter.

When measuring the supply voltage of a battery with the V_BATT pin (could be connected to V_IN through JP2), it is important to note the maximum voltage limit. The voltage divider on the board for measuring with a 3.3V ADC is --'''V_BAT'''--/\/\'''10k'''/\/\--'''V_BAT_MEAS'''--/\/\'''2k2'''/\/\--'''GND'''--. This means that the maximum allowable voltage on V_BATT is

<math>V\_BAT_{max} = 3.3V*\frac{10k}{2.2k} = 15V</math>

If a higher voltage measurement is desired, another voltage divider is required off-board. Alternatively, one could modify the existing voltage divider (e.g. change 10k resistor to 22k to get 33V maximum). When checking if voltage exceeds the maximum, make sure to consider maximum battery voltage, not nominal voltage (e.g. 4.22V or so for a single lithium cell, not 3.7V nominal, so the maximum number of cells in series is 3, like a 3S LiPo pack).

== Schematic ==
<gallery widths=250px heights=168px>
Image:Lisa_m_v2_0_sheet_1.png | LisaM V2.0 Schematic Sheet 1/3
Image:Lisa_m_v2_0_sheet_2.png | LisaM V2.0 Schematic Sheet 2/3
Image:Lisa_m_v2_0_sheet_3.png | LisaM V2.0 Schematic Sheet 3/3
</gallery>
<br style="clear:both">

== Examples of Airborne Equipment Electrical Connections ==

=== Quadrocopter, Spektrum Satellite Receivers, PWM Motor Controllers (ESC) and dedicated avionics Battery Elimination Circuit (BEC) ===

[[File:LisaM_V2_0_wiring_quadrocopter_spektrum_bec_pwmesc.png|700px]]

This is a recommended powering configuration. It eliminates the balancing issues of the built in BECs into the ESCs.

The dotted lines from the BEC show the alternative wiring that does not require closing the VS jumper on the Lisa/M. The disadvantage is that you have to wire/crimp the BEC output wires into the picoblade molex connector providing the battery voltage reference. Usually it is easier to just use the existing "servo" connector on the BEC and closing the jumper instead.

=== Quadrocopter, Spektrum Satellite Receivers and PWM Motor Controllers (ESC) ===

[[File:LisaM_v2_0_wiring_quadrocopter_spektrum_pwmesc.png|700px]]

This configuration assumes the ESCs have a battery eliminator circuit (BEC) function and provide 5 volts on their 5V pins. Closing JP1 powers Lisa/M and the attached accessories.

<span style="color:red">Warning:</span> The built in BECs on the ESCs are usually linear voltage regulators, they are fairly inefficient compared to dedicated BECs that are usually implemented as switching DC/DC converters.

<span style="color:red">Warning:</span> Due to manufacturing differences of BECs, connecting more then one BEC in parallel will likely cause one of the BECs to take majority of the load and dissipate most of the drop down voltage. ([https://en.wikipedia.org/wiki/Linear_regulator Read on how linear voltage regulators work.]) As in this example the BECs are part of the ESCs, one of the ESCs will get warmer than the others, which in turn may lead to reliability issues.

[[File:LisaM_V2_0_wiring_quadrocopter_spektrum_pwmesc_shunts.png|700px]]

<span style="color:green">Tip:</span> To improve balancing between the ESC built in BECs you can add a 1Ohm resistor in the +5V line coming from the motor controller. This will cause some pre-loading of the voltage regulator and improve the load sharing between the BECs while decreasing the efficiency of the supply.

When using cheap ATMega or SiLabs-based PWM motor controllers consider replacing their firmware with either [https://github.com/sim-/tgy Simon Kirby] or [https://github.com/bitdump/BLHeli BLHeli] firmware respectively to get useful performance of your multicopter! You can find a firmware compatibility list [https://docs.google.com/spreadsheet/ccc?key=0AhR02IDNb7_MdEhfVjk3MkRHVzhKdjU1YzdBQkZZRlE here].

=== Quadrocopter, Spektrum Satellite Receivers and I2C Motor Controllers (ESC) ===

[[File:LisaM_V2_0_quadrocopter_spektrum_i2c_esc_wiring.png|700px]]

This diagram "should" be the same for AscTec as well as Mikrokopter motor controller based airframes.

=== Fixedwing, Spektrum Satellite Receivers and Elevons Only ===

[[File:LisaM_V2_0_wiring_fixedwing_spektrum_elevons.png|700px]]

This configuration assumes the ESC has a BEC and provides 5 volts on its 5V pin. Closing JP1 powers Lisa/M and the attached accessories.

=== Fixedwing, Spektrum Satellite Receivers ===

[[File:LisaM_V2_0_wiring_fixedwing_spektrum.png|700px]]

This configuration assumes the ESC has a BEC and provides 5 volts on its 5V pin. Closing JP1 powers Lisa/M and the attached accessories.

=== Transitioning [http://wiki.thequadshot.com Quadshot] Using Spektrum Receivers ===

[[File:LisaM_V2_0_wiring_quadshot_spektrum.png|700px]]

The ESCs have BECs and provide 5 volts on their 5V pins. Closing JP1 powers Lisa/M and the attached accessories.

Still need: Large Fixed-wing with advanced power system and/or IC engine, PPM example

== R/C Receivers ==

One can use [[Subsystem/radio_control#Spektrum|Spektrum]] DSM2 or compatible receivers as well as traditional PPM receivers. It is even possible to [[Subsystem/radio_control#Spektrum|connect two Spectrum or compatible satellite receivers]] for better redundancy or to improve RC signal reception. Connecting a RC receiver for flying your aircraft in manual mode during setup and test phase is 99% of the cases a must. Therefore the Paparazzi team made it easy to connect one.

=== Using a Spektrum DSM receiver ===

==== Physically connecting ====

Wiring up a Spektrum or compatible satellite receiver is not to difficult to do.
It is very important to make absolutley sure the connectors are properly made.
Not being precise in this step can mean full RC loss and loss of airframe in the first tuning testflights.

The spektrum satellite receiver should be connected to the UART1 connector on the autopilot board. Make sure the voltage on the AP board UART1 + pin is not to high, or to low for your receiver.

Steps:
# Connect the minus(-) of the receiver to GND of UART1
# The receiver plus(+) to the UART1 Plus(+)
# Data out signal of the receiver to the RX pin on the UART1

==== Binding ====

To get a receiver and transmitter to work together you must perform a binding process.

It is important to '''bind''' your Spectrum DSM receiver to your transmitter '''via''' your '''Lisa board''', not in any other way!

The way to bind is by temporary connecting via fiddly small molex pins.
It is advised to make a small bind plug out of a molex connector for this purpose.
Before you start make sure you have your airframe configuration already uploaded either via USB or a JTAG cable.

The bind procedure:

# On the connector '''ANALOG1''' have a wire between the GND and ADC1 pin, located in the middle of the board
# Power up your autopilot board
# Hold the bind button on your '''transmitter''', while '''keeping it pressed''' switch on your transmitter
#:Wait...! All lights of the receiver blink and then go steady
# Let go of your transmitter bind button
# Power off your Lisa Board
# Remove the wire connecting the GND and ADC1 pins on the ANALOG1 connector
# Repower your board, if you have servos connected and wiggle the RC transmitter sticks some servos should move

That is all, you are done.
The bind procedure only needs to be done '''once''' for your receiver.

=== Using a PPM receiver ===

Using a PPM receiver, a so called '''PPM sum stream''' input is possible. [[RC_Receivers_and_Radios#PPM_Based_Systems | To make it work, you need a PPM sum stream out capable receiver. Find out more following this link]]

==== Connecting ====

Connect the PPM out signal to the RX pin of UART1.

Make sure put this in your airframe file in your AP target section.
<source lang="xml">
...
<subsystem name="radio_control" type="ppm">
<configure name="RADIO_CONTROL_PPM_PIN" value="UART1_RX"/>
</subsystem>
...
</source>

===== Alternative =====

However if in the case you want to use the UART1 port for something else, there is an option to connect the receiver to a servo pin. Yes, that's right, a servo connector is used for receiving a PPM stream '''input'''. If you want to walk that path, the default pin number to capture the PPM sum stream is via servo connector SERVO6

If you connect the PPM ou capable receiver that way make sure to put this in your airframe file in your AP target section:

<source lang="xml">
...
<subsystem name="radio_control" type="ppm">
<configure name="RADIO_CONTROL_PPM_PIN" value="SERVO6"/>
</subsystem>
...
</source>

If you do not have or cannot modify a receiver to a ''PPM out'' able receiver, a [[PPM_Encoder | PPM encoder board]] can be used to avoid opening your receiver for PPM out modification.

== Extras ==

=== UART I/O ===

UART pins can also be used as general purpose I/O, this might come in handy in case all other inputs or your AP board are in use.

=== USB as UART1TX + hardware flow control===

[[File:Lisam-usb-uart1.jpg]]

The USB_VBUS on the Lisa/M 2.0 can be used as UART1 TX. To do this, a diode has to be removed. Make sure to include a series resistor of 100-3000 Ohm to protect the microcontroller from overcurrents. The 2nd and 3th pin of the USB pads are CTS and RTS respactively. It is recommended to include a series resistor in the RTS line, as this is an outgoing line.

If you want to enable flow control in the software, but don't want to use flow control when no cable is connected to the CTS/RTS, a pulldown resistor of 10 kOhm has to be added between the CTS and the GND. If you do this, take care when connecting UART devices that have a large series resistor in their RTS line. The combination of the pulldown resistor and the series resistor might cause the high-level voltage to drop under the high-level treshold of the microcontroller, causing strange behaviour.

For Example the RTS , mostly a purple wire, is the '''pin 10''' on the Xtend module when set in the module with Hardware flow control (use X-CTU)
CTS, most blue, on pin 9 of the Xtend

<gallery widths=380px heights=205px>
Image:Lisam-diode.JPG | Remove this diode. After removing this diode you can not power the board via USB anymore.
Image:Lisam-gpio-usb.JPG | Take care of the small distance between the GPIO pins and the USB pads.
</gallery>

== PCB ==

=== Gerber & Drill Files ===

'''''Download Lisa/M v2.0 gerber & drill files (zip)''''' ''[[Lisa/M_v2.0#Get the design|Get the design]]''

== Assembly ==

To create and assemble a board oneself is possible. It takes some skills however.

For the Lisa/m v2.0 without the Aspirin sensor board a good soldering iron is enough.(smallest components are 0402) For the Aspirin Sensor board you need a hot air soldering station.

In case you wan to follow that path you need the desing. You came to the right place here is the info to get the needed files;

===Components Layout===

''[[Lisa/M_v2.0#Get the design|Get the design]]''

Need some top and bottom of board images and line drawings here.

=== Bill Of Material ===

'''''Download Lisa/M v2.0 Bill Of Material (zipped .xls file)''''' ''[[Lisa/M_v2.0#Get the design|Get the design]]''

Open .sch File in Eagle, execute UPL --> bom.ulp , save as .txt

== PCB and assembled boards suppliers ==

To difficult to creat your own AP board, understandable, thus pre made board available via [[Get_Hardware|Get Hardware]] page... hopefully :)

== Mechanical Dimensions ==

[[Image:LisaM_V2_0_top_mechanical.png|500px|Lisa/M v2.0 Mechanical Dimensions]]

The overall height of the board including the servo connectors is 10mm. Note that the overall length includes the USB connector. The mounting holes are nominal 2mm diameter (with a bit of clearance).

== Get the design ==

'''Source files'''
:*download available on GitHub: ''[https://github.com/paparazzi/paparazzi-hardware/tree/master/controller/lisa_m/v2.0 Lisa/M v2.0 Cadsoft Eagle 6 Design]''
'''Gerber & Drill files'''
:*download ''NOT YET AVAILABLE'' Need generated gerbers and drill files
'''Assembly files'''
:*download ''NOT YET AVAILABLE'' Need Lisa/M v2.0 Components layouts (pdf)
:*download ''NOT YET AVAILABLE'' Need Lisa/M v2.0 Bill Of Material

== Uploading new software ==
New onboard software for the Lisa/M v2.0 can uploaded by connecting your PC via a micro-USB port to the autopilot board. For this the board need to contain the [[Luftboot]] bootloader. All Lisa/M 2.0 from Transition Robotics Inc. come with luftboot already in the board.

An alternative to get your firmware in the board is by using a JTAG connector connected via the 10-pin Samtec connector that is available on the board.

See the [[FirmwareFlashing]] page for an overview of different methods to upload new software to your autopilot.

=== Using luftboot ===
'''This is the default FLASH_MODE for Lisa/M v2.0''', it could be explicitly selected by adding
:<source lang="xml"><configure name="FLASH_MODE" value="DFU"/></source>
to the firmware section of your airframe file. Make sure to set Lisa/M 2.0 as it's target board.

Once USB is plugged in, the board automatically goes to bootloader mode and the status LEDs cycle up and down:

[[File:Luftboot.gif|320px]]

If you have trouble entering the bootloader mode or want to upload/update the bootloader itself, see the [[Luftboot]] page.

=== Using JTAG ===
You still can use a [[JTAG|JTAG adapter]] for [[FirmwareFlashing#JTAG|flashing]] and [[DevGuide/JTAG-Debug|debugging]] your paparazzi firmware. To use [[FirmwareFlashing#JTAG|JTAG flashing]] configure the ''FLASH_MODE'' in your firmware section:
:<source lang="xml"><configure name="FLASH_MODE" value="JTAG"/></source>

It is possible to use an advanced adapter called Black Magic Probe. See more details [[here|JTAG#Black_Magic_Probe]]

Using JTAG will not overwrite the bootloader by default. To overwrite the luftboot bootloader configure
:<source lang="xml"><configure name="NO_LUFTBOOT" value="1"/></source>

Then press upload as normal...

=== Serial Firmware Upload ===
Firmware upload using the factory integrated bootloader can be useful e.g. if you have overwritten [[Luftboot]] accidentally and don´t have access to [[JTAG]].<br/>
Either set the flash mode in the target section of the airframe configuration:
:<source lang="xml"><configure name="FLASH_MODE" value="SERIAL"/></source>
or add it to the commandline invocation:
make AIRCRAFT=<aircraftname> ap.upload FLASH_MODE=SERIAL

Due to hardware constraints, the board has to be modified to make use of the bootloader, which is only accessible on UART1:
# Diode D3 has to be removed (the bigger black brick next to the USB connector). Attention, no more powering via USB after that.
# BOOT1 has to be set to GND by connecting ACC_DRDY(unused) to GND at the Aspirin pads

Now a boot sequence works as follows:
#BOOT1 has to be set to 3.3V by use of a jumper cable
#Connect a 3,3V serial cable (FTDI, MAX232...) to UART1, the TX pin is USB_VBUS
#Power the board and activate the bootloader program

=== Prevent board from going into bootloader mode ===

Normally, if you power up the board with the USB cable connected to a PC it will automatically go into bootloader mode. If you want the board to power up normally with the cable connected you can ground the ADC2 in the ANALOG1 connector.

== Detailed Hardware Revision History ==

=== Changes Between LISA v1.1 and v2.0 ===

* Lots of silkscreen improvements
* Added attributes to all parts to make the usage of bom-ex ulp possible.
* Improved routing to allow teardropping
* Fixed stm32f1, f2 and f4 compatibility circuit. (has to jump to ground not to 3v3)
* Connected existing UART RX pullups to the respective connector power pins instead of 3v3. To prevent connecting 5V over IO pin to the 3v3 power rail.
* Added pullups on all UART RX lines to prevent undesired floatation.
* LED's are connected to 3v3 now. To make sure we don't have an issue with voltage tolerance on the gpio pins.
* ...

== Hardware Change Requests ==

If you have a Lisa/M 2.0 and in the process of using it you come up with something you find annoying, dangerous, or restricting, add your hardware update requests here. Better still, modify the Lisa schematics yourself and show your new improvements if you are skilled enough to do this.

* REQ: Replace BMP085 with MS5611 (the MS5611 seems to be better in performance then the BMP but it is more expensive and seems to be more difficult to obtain.
** A: Using a MS5611 is possible through using a Aspirin v2.1 board

* REQ: Replace 7 Pin CAN with molex with something less risky to be inserted in 7 Pin SPI in relation to powering the board via CAN molex.

* REQ: Separate spot for external power if powered via separate battery. Realizing we can via Servo ports by Bridge J1 but still like to measure board voltage then and have a way to add power without mistakenly insert I2CCAN Molex conector into SPI Molex on board connector. Thus a separate CAN and Power plug. Power on regular four pin molex with GND, V+5, , V_BATT, V_I (Current sense). Option to have thicker wire to be soldered to the board, for power hungry setups and other issues connectors for power are not a good idea.

* REQ: Replace Aspirin IMU board with InvenSense MPU-9150 and bring the MS5611 back onto the Lisa/M board to reduce footprint, mass, and manufacturing cost once the 9150 becomes readily available(if at al with SPI) and is tested to perform well.

== Lisa/Lia F4 ==
Lisa/Lia autopilot can be easily converted to a much more powerful controller, based on STM32F405RGT6 chip [http://www.st.com/web/catalog/mmc/FM141/SC1169/SS1577/LN1035/PF252144]. The chip has the same dimensions (LQFP64 10x10mm package) with the exact same pinout as the original STM32F105RCT6 chip. The main advantage of the f4 chip is:

* 168MHz CPU speed, 1MB flash and 192kb RAM
* FPU (fast floating point computations)
* configurable DMA streams (more peripherals can use DMA)
* multiplexed IO pins (peripherals can be mapped to various IO pins)
* CPU usage only about 5% with standard rotorcraft flight configuration

STM32F405RGT6 chip can be ordered for example [http://cz.mouser.com/ProductDetail/STMicroelectronics/STM32F405RGT6/?qs=Z8%252beY1k3TIKgj7QWsYGpQw== here]. To replace the chip a good soldering station with microscope and enough light is recommended. After replacing the chip, jumpers CMP1 and CMP2 have to be opened.
<gallery widths=300px heights=200px>
[[File:F4_digikey.jpg]]
Image:F4_digikey.jpg|DigiKey part number for F4 chip
Image:F4_on_board.jpg|Lia F4 with the new chip
</gallery>

=== Programming ===
The STM32F4 can be flashed via SWD/JTAG (e.g. with the BlackMagicProbe) or via [[DFU#Native_DFU_bootloader_.28embedded_in_ROM.29|DFU-UTIL]].
[[Luftboot|Luftboot]] currently supports only F1xx chips.

A guide how to flash the F4 chip from Eclipse can be found in [[RT_Paparazzi|RT_Paparazzi]].

[[Category:Lisa]] [[Category:User_Documentation]] [[Category:Autopilots]]

JTAG

2014-06-26T08:30:12Z

Alonsoac: /* Black Magic Probe */

==Introduction==
A JTAG interface is designed for on-chip debugging. It can also be used to flash your firmware if you do not have a means to upload software via USB already. For short, if you want to upload your own software or want to do serious paparazzi development work, the you need a JTAG adapter like this.

See also:
* [[FirmwareFlashing#JTAG|firmware flashing via JTAG]]
* [[DevGuide/JTAG-Debug|debugging with JTAG]]

==JTAG Adapters==
There are multiple Paparazzi-compatible devices available that support JTAG.

Below you find a list of JTAG devices that you can use in combination with e.g. a Paparazzi Lisa/M board.

=== FLOSS JTAG ===

The FLOSS JTAG is based on an FTDI chip that allows two simultaneous USB connections, which means that FLOSS JTAG allows JTAG and UART/COM connections.

Let's take a look at upper side of the board. It contains JTAG connector (which is connected on photo) and two sets of RX/TX LEDs for JTAG and UART/COM interface separately. The JTAG connector is 2x5 pins, 0.05-inch pitch, and is compatible with the Samtec FFSD-05-D-06.00-01-N-RW-R ribbon cable.

[[Image:Jtag-up.jpg]]

On the other side of the board there is 4 pin UART/COM connector, which contains (from top to bottom in the image below): Ground (black), RX (orange), TX (yellow), and +5V (red)

[[Image:Jtag-down.jpg]]

Usage of board is pretty simple: JTAG can be used to upload firmware into the board and/or repair board with broken bootloader, and UART/COM interfaced can be used to make "COM port style" connection to the board. COM connection can be used for example for telemetry debug.

More info available on the [http://randomprojects.org/wiki/Floss-JTAG randomprojects.org wiki].

=== Black Magic Probe ===

[[Image:BMPM_1_top.jpg|500x500px]][[Image:BMPM_1_bottom.jpg|500x500px]]

Some additional info about the Black Magic Probe is available at the [http://www.blacksphere.co.nz/main/blackmagic Black Sphere Technology website].

To use Black Magic Probe instead of FLOSS-JTAG or Luftboot for firmware flashing, append the following string to the upload command:

On Linux:
FLASH_MODE=JTAG_BMP BMP_PORT=/dev/ttyACM0
On Mac OS:
FLASH_MODE=JTAG_BMP BMP_PORT=/dev/cu.usbmodem<serial>

To make this the default flash method add this in the airframe file firmware section:
<configure name="FLASH_MODE" value="JTAG_BMP"/>
<configure name="BMP_PORT" value="/dev/ttyACM0"/>

See the [[FirmwareFlashing]] page for other methods.

==== Benefits ====

There are good reasons to use the Black Magic Probe Mini instead of FLOSS-JTAG:

*Lower cost
*No need for OpenOCD as BMPM has a built in GDB server
*Orders of magnitude faster as all the high speed protocol logic happens on the built-in STM32
*Supports Serial Wire Debug (SWD)
*Supports tracing using the SWD trace pin
*No need for loading and unloading of FTDI drivers on Mac OS X

====UART port====
The pinout for the UART port on the back side of the BMP as seen on the image above and starting from the top is ground,rx,tx,3.3v . You can use this for receiving telemetry.

====Upgrade BMP firmware====

To upgrade the brain of your Black Magic Probe, a.k.a. its firmware, use these commands on your command line:

$ git clone git://blackmagicdebug.git.sourceforge.net/gitroot/blackmagicdebug/blackmagicdebug
$ cd blackmagicdebug/src
$ make CROSS_COMPILE=~/sat/bin/arm-none-eabi-
$ ../scripts/stm32_mem.py blackmagic.bin

Note the minus sign after ''eabi'', ye that is correct, best to cut 'n paste the lines without the $ sign in front ofcourse.

=== FT2232H Mini Module ===

Use ftdi prog to change the Description String into: FLOSS-JTAG. <br/>
More information for this board at [[Serial_Adapter]].
[[File:AlternativeFlossJtag.png]]

[[Category:Hardware]] [[Category:Software]] [[Category:Developer_Documentation]]

JTAG

2014-06-26T08:24:07Z

Alonsoac: /* Black Magic Probe */

==Introduction==
A JTAG interface is designed for on-chip debugging. It can also be used to flash your firmware if you do not have a means to upload software via USB already. For short, if you want to upload your own software or want to do serious paparazzi development work, the you need a JTAG adapter like this.

See also:
* [[FirmwareFlashing#JTAG|firmware flashing via JTAG]]
* [[DevGuide/JTAG-Debug|debugging with JTAG]]

==JTAG Adapters==
There are multiple Paparazzi-compatible devices available that support JTAG.

Below you find a list of JTAG devices that you can use in combination with e.g. a Paparazzi Lisa/M board.

=== FLOSS JTAG ===

The FLOSS JTAG is based on an FTDI chip that allows two simultaneous USB connections, which means that FLOSS JTAG allows JTAG and UART/COM connections.

Let's take a look at upper side of the board. It contains JTAG connector (which is connected on photo) and two sets of RX/TX LEDs for JTAG and UART/COM interface separately. The JTAG connector is 2x5 pins, 0.05-inch pitch, and is compatible with the Samtec FFSD-05-D-06.00-01-N-RW-R ribbon cable.

[[Image:Jtag-up.jpg]]

On the other side of the board there is 4 pin UART/COM connector, which contains (from top to bottom in the image below): Ground (black), RX (orange), TX (yellow), and +5V (red)

[[Image:Jtag-down.jpg]]

Usage of board is pretty simple: JTAG can be used to upload firmware into the board and/or repair board with broken bootloader, and UART/COM interfaced can be used to make "COM port style" connection to the board. COM connection can be used for example for telemetry debug.

More info available on the [http://randomprojects.org/wiki/Floss-JTAG randomprojects.org wiki].

=== Black Magic Probe ===

[[Image:BMPM_1_top.jpg|500x500px]][[Image:BMPM_1_bottom.jpg|500x500px]]

Some additional info about the Black Magic Probe is available at the [http://www.blacksphere.co.nz/main/blackmagic Black Sphere Technology website].

To use Black Magic Probe instead of FLOSS-JTAG or Luftboot for firmware flashing, append the following string to the upload command:

On Linux:
FLASH_MODE=JTAG BMP_PORT=/dev/ttyACM0
On Mac OS:
FLASH_MODE=JTAG BMP_PORT=/dev/cu.usbmodem<serial>

To make this the default flash method add this in the airframe file firmware section:
<configure name="FLASH_MODE" value="JTAG_BMP"/>
<configure name="BMP_PORT" value="/dev/ttyACM0"/>

See the [[FirmwareFlashing]] page for other methods.

==== Benefits ====

There are good reasons to use the Black Magic Probe Mini instead of FLOSS-JTAG:

*Lower cost
*No need for OpenOCD as BMPM has a built in GDB server
*Orders of magnitude faster as all the high speed protocol logic happens on the built-in STM32
*Supports Serial Wire Debug (SWD)
*Supports tracing using the SWD trace pin
*No need for loading and unloading of FTDI drivers on Mac OS X

====UART port====
The pinout for the UART port on the back side of the BMP as seen on the image above and starting from the top is ground,rx,tx,3.3v . You can use this for receiving telemetry.

====Upgrade BMP firmware====

To upgrade the brain of your Black Magic Probe, a.k.a. its firmware, use these commands on your command line:

$ git clone git://blackmagicdebug.git.sourceforge.net/gitroot/blackmagicdebug/blackmagicdebug
$ cd blackmagicdebug/src
$ make CROSS_COMPILE=~/sat/bin/arm-none-eabi-
$ ../scripts/stm32_mem.py blackmagic.bin

Note the minus sign after ''eabi'', ye that is correct, best to cut 'n paste the lines without the $ sign in front ofcourse.

=== FT2232H Mini Module ===

Use ftdi prog to change the Description String into: FLOSS-JTAG. <br/>
More information for this board at [[Serial_Adapter]].
[[File:AlternativeFlossJtag.png]]

[[Category:Hardware]] [[Category:Software]] [[Category:Developer_Documentation]]

Flight Plans

2014-06-05T03:17:45Z

Alonsoac: /* Call */

A '''flight plan''' is a XML document which one can create and store aboard an autopilot. The flight plan will describe how you want your aircraft to travel if released into into the wild blue yonder.

== DTD and Structure ==

The formal description of the flight plan file is given in the [http://en.wikipedia.org/wiki/Document_Type_Definition '''DTD'''] (located in <tt>conf/flight_plans/flight_plan.dtd</tt>). This
DTD must be referenced in the header of your flight plan XML document using the following line:<br>

<source lang="xml"><!DOCTYPE flight_plan SYSTEM "flight_plan.dtd"></source>

The flight plans are stored in the <tt>conf/flight_plans</tt> directory. The [[Flight_Plan_Editor|flight plan editor]] can be used to create basic flight plans via the GUI.

Extract from the [http://en.wikipedia.org/wiki/Document_Type_Definition DTD]:
<tt><!ELEMENT flight_plan (header?,waypoints,sectors?,include*,exceptions?,blocks)></tt>

'''A flight plan is composed of two mandatory elements: [[#waypoints|waypoints]] and [[#blocks|blocks]]'''

The root <tt>flight_plan</tt> element is specified with several attributes:
<tt>'''<flight_plan name lat0 lon0 ground_alt security_height home_mode_height qfu alt max_dist_from_home>'''</tt>
; <tt>'''name'''</tt>: The name of the mission (a text string)
; <tt>'''lat0, lon0'''</tt>: Defines the latitude and longitude coordinates of the reference point {0,0} in WGS84 degree coordinates
; <tt>'''ground_alt'''</tt>: The ground altitude (in meters), Above Sea Level where you are flying. It defines the <tt>GROUND_ALT</tt> constant value which can be used in combination with a waypoint <height> parameter to define a waypoint height
; <tt>'''security_height'''</tt>: The height (over <tt>'''ground_alt'''</tt>) used by the circle-home failsafe procedure and in other flight procedures such as formation flight and anti-collision avoidance. Warnings are produced if you place a waypoint lower than <tt>'''security_height'''</tt> (usually the case for the landing point)
; <tt>'''home_mode_height'''</tt> (optional): This optional attribute available since v4.2 allows to override <tt>'''security_height'''</tt> as failsafe height in home mode. If <tt>'''home_mode_height'''</tt> Is set lower than <tt>'''security_height'''</tt>, the later is used. This attribute is useful if you need to return home at a high altitude rather than a low altitude.
; <tt>'''qfu'''</tt> (optional): defines the global constant <tt>QFU</tt>. It usually is the magnetic heading in degrees (north=0, east=90) of the runway, the opposite of wind direction. This constant may be used in the mission description. It is also used by the simulator as the original course of the aircraft. So if you want to take off and climb to the West you would use qfu=270.
; <tt>'''alt'''</tt>: The default altitude of waypoints ([[Altitude_definitions|Above Sea Level]]). So if your ground altitude is 400 then alt needs to be a value greater than ground altitude and above any obstructions in the flight plan.
; <tt>'''max_dist_from_home'''</tt>: A radius representing the maximum allowed distance (in meters) from the HOME waypoint. Exceeding this value (ie flying outside the circle with this radius) will trigger an exception. It is up to you to define the block to be executed (ie what to do) for the exception.

''Here is an '''example''' of such a line in the top of a flight plan:''

<source lang="xml">
<flight_plan alt="250" ground_alt="185" lat0="43.46223" lon0="1.27289" name="Example Muret" max_dist_from_home="300" qfu="270" security_height="25" >
</source>

Note that a flight plan could also contain optional <tt>include</tt>'s and <tt>exceptions</tt> cases.

In English the above flight plan says the name is Example Muret. The reference coordinates for the 0,0 point is: 43.46223 (lat) and 1.27289 (long). The flying site 0,0 location is 185m above sea level. The security height is 25m above 0,0 point or 210m above sea level. The default (ie if not defined in a waypoint this alt is used) altitude is 250m (above sea level). The home mode block altitude is defined to be 150m above sea level. Also, for security, a circle is defined with a radius that's 300m from 0,0 position. This is the max_dist_from_home value. Fly 301m from 0,0 and an exception is triggered. A useful block is to trigger/go to the home mode block and return to home when the aircraft flies outside the safety circle. Example flight plans are helpful for study before you build your own from scratch.

== Waypoints ==

The waypoints are the geographic locations used to specify the trajectories. A waypoint is specified by it's name and coordinates:
<tt>''' <waypoint name wpx wpy [alt] [height]/> '''</tt>
where wpx and wpy are real positional coordinates ( <tt>'''lat/lon'''</tt> ) '''or''' UTM coordinates ( <tt>'''utm_x0/utm_y0'''</tt> ) '''or''' relative coordinates ( <tt>'''x/y'''</tt> ) in meters from your reference point {0,0} . <tt>alt</tt> is an optional parameter and can be used to assign an altitude to a particular waypoint that is different from the globally defined <tt>alt</tt> parameter of the flightplan. The <tt>height</tt> attribute can be used to set the waypoint height relative to the [[Altitude_definitions|ground altitude]] (<tt>ground_alt</tt>) of the flight plan for this waypoint.

An example:
<source lang="xml">
<waypoints>
<waypoint name="HOME" x="0.0" y="30.0"/>
<waypoint name="BRIDGEOVERRIVER" x="-100.0" y="60.0" alt="270."/>
<waypoint name="MyBarn" x="-130.0" y="217.5" alt="3000."/>
<waypoint name="3" x="-30.0" y="50" height="50."/>
<waypoint name="4" x="-30.0" y="50." alt="ground_alt + 50"/>
<waypoint name="_MYHELPERSPOT" x="-30.0" y="60" height="50."/>
<waypoint name="_MYOTHERHELPERSPOT" x="-70.0" y="90" height="70."/>
<waypoint name="TOWER" lat="48.858249" lon="2.294494" height="324."/>
<waypoint name="MountainCAFE" utm_x0="360284.8" utm_y0="4813595.5" alt="1965."/>
</waypoints>
</source>

'''Tips'''
* Waypoints are easily adjusted with the [[Flight_Plan_Editor|flight plan editor]].
* If a waypoint name starts with an underscore ( _ ), the waypoint is '''not displayed''' in the GCS, except in editor mode.
* The maximum number of waypoints is 254.
* A waypoint named <tt>HOME</tt> is required if the failsafe HOME mode procedure is used.

== Sectors ==

Flat ''Sectors'' can be described as an area defined by list of waypoint corners. Such an area will be displayed in the Ground Control Station (GCS) by colored lines connecting the cornerpoints.
A function is generated to check if a point, usually the aircraft itself, is ''inside'' this sector. Currently, this feature requires that the polygon is <b>convex</b> and described in a <b>clockwise</b> order. For a sector named <tt>MyBigGarden</tt> the generated function for the example here would be <tt>bool_t InsideMyBigGarden(float x, float y);</tt> where <tt>x</tt> and <tt>y</tt> are east and north coordinated, in meters, relative to the geographic reference of the flight plan. If the flight plan is dynamically relocated, such a sector will be relocated but the display is currently not updated on the GCS. It would be great if one would help improving that part of the source code. Note that sector names are not allowed to contain spaces.

For example, with the following element in a flight plan.
<source lang="xml">
<sectors>
<sector name="MyBigGarden" color="red">
<corner name="_1"/>
<corner name="_2"/>
<corner name="_3"/>
<corner name="_4"/>
</sector>
</sectors>
</source>

It is then possible to add an exception clause to your flightplan. For example if the aircraft for some reason flies outside this, defined by us, sector the airframe will fly to a standby waypoint. The exclamation mark (!) means the boolean operator <tt>NOT</tt> in this example. In regular language one would describe "If my airframe is NOT inside the MyBigGarden sector anymore then deroute it to the standby waypoint. In Flightplan "Speak" this is written like:
<source lang="xml">
<exception cond="! InsideMyBigGarden(GetPosX(), GetPosY())" deroute="standby"/>
</source>

NOTE: editing of the waypoints of the sector during the flight will not dynamically update the inside function. It will always check if the position is inside the original sector.

'''Tips'''
* A nice option in the corner notation is that one can add an underscore ( _ ) in front of the name; a corner or waypoint name that starts with an underscore is not displayed in the GCS. Only in editor mode it is visible. It is visible in editor mode, because if you the could not see it, it also would be not possible to edit or drag the corner or waypoint to another position.
* The color indicating the sector borders is not fixed but can be defined by oneself if wished for via the color attribute.

== Includes ==

<tt>include</tt> is used to add some flight plan elements defined in an external procedure. It’s useful to include pre-written procedures with only few arguments and then clarify the flight plan.
Here is the structure:
<tt><include name procedure> [<arg name value />]*[<with from to />]*</include></tt>
where <tt>name</tt> attribute of the include element will be used in this flight plan to prefix the blocks of the <tt>procedure</tt>, the XML referenced file.
Named arguments may be given with their value in the <tt>arg</tt> elements. The <tt>with</tt> tag allows to link labels (e.g. attribute of a deroute instruction or of an exception) from the procedure to blocks of the main flight plan.
Then, each block of the procedure is like any block of the flight plan and is designated with a dotted identifier: block <tt>b</tt> of a procedure named <tt>p</tt> is named <tt>b.p</tt> .

Here is an example:
<source lang="xml">
<includes>
<include name="landing" procedure="landing.xml"/>
</includes>
</source>

== Blocks ==

Block elements are the main part of a flight plan: they describe each unit of the mission.
They are made of various primitives, called stages and exceptions, you can put one after the other. When a
stage (or a block) is finished, the autopilot goes to the next one. The behaviour after the last stage of the last block is undefined.

As described in the DTD, the <tt>blocks</tt> element is composed of <tt>block</tt> elements which are sequence of ''stages'':
<source lang="xml">
<!ELEMENT blocks (block+)>
<!ELEMENT block (exception|while|heading|attitude|go|xyz|set|call|circle|deroute|stay|follow|survey_rectangle|for|return|eight|oval|home|path)*>
</source>

Example:
<source lang="xml">
<block name="circlehome">
<circle radius="75" wp="HOME"/>
</block>
</source>

You can add a button in the [[GCS#Strips|strip of the aircraft]] with the attribute <tt>strip_button</tt>:
<source lang="xml">
<block name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
This button will activate the block. If the attribute <tt>group</tt> is specified, all strip buttons of the same group will be placed vertically on top of each other.

In the same way, a key shortcut can be specified:
<source lang="xml">
<block key="D" name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
Modifiers are allowed, using the syntax of [http://library.gnome.org/devel/gtk/2.15/gtk-Keyboard-Accelerators.html#gtk-accelerator-parse GTK accelerators].

An icon can be specified to display the button. The <tt>strip_button</tt> label then is a tooltip for the icon. The icon must be an image file available in the directory <tt>data/pictures/gcs_icons</tt>:
<source lang="xml"><block name="Takeoff" strip_icon="takeoff.png" strip_button="Takeoff"></source>

You can call functions before or after each execution of the block:
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

==== Expressions ====

Most of the numeric attributes in stages are analyzed as C expressions. The syntax of this C expression is restricted to
* numeric constants
* some internal autopilot variables (not fully documented, see examples)
* Some binary operators: <, >, <=, >=, <>, ==, +, -, /, *
* Some utility functions

Some examples of usable expressions are given in the next sections.
=== Initialization Blocks ===
Most flight plans will have three blocks of flight plan initialization blocks. It is good practice to follow this example below if you first start learing to create flightplans

The first block waits until the GPS fix has been established, as shown below.
<source lang="xml">
<blocks>
<block name="Wait GPS">
<set value="1" var="kill_throttle"/>
<while cond="!GpsFixValid()"/>
</block>
</source>
The second block updates the local waypoints with respect to the UAV.
<source lang="xml">
<block name="Geo init">
<while cond="LessThan(NavBlockTime(), 10)"/>
<call fun="NavSetGroundReferenceHere()"/>
</block>
</source>
This next block prevents the UAV from starting the engine and taking off.
<source lang="xml">
<block name="Holding point">

<set value="1" var="kill_throttle"/>
<attitude roll="0" throttle="0" vmode="throttle"/>
</block>
</source>

=== Exceptions ===

The flight manager can handle exceptions. They consist in conditions checked periodically (at the same pace as the navigation control), allowing the control to jump to a given block. Here is the syntax of exceptions:
<source lang="xml"><exception cond="..." deroute="..."></source>
where <tt>cond</tt> is an expression and <tt>deroute</tt> is the name of the block we want to switch to as soon as the condition is true.

Here are some example of exceptions:
<source lang="xml">
<exception cond="10 > PowerVoltage()" deroute="go_down"/>
<exception cond="(ground_alt+10 > GetPosAlt())" deroute="go_up"/>
<exception cond="(autopilot_flight_time > 840)" deroute="quick_land"/>
</source>

Exceptions can be local to a block or global to the flight plan, in the <tt><exceptions></tt> element. In the following example, time since last reception of a message from the ground station is monitored and the navigation is switched to the <tt>Standby</tt> block if no message have been received for 22s. This exception is valid for '''all''' the blocks.
<source lang="xml">
<flight_plan ...>
<waypoints> ... </waypoints>
<exceptions>
<exception cond="datalink_time > 22" deroute="Standby"/>
</exceptions>
<blocks> ...
</source>

=== Deroute ===

The <tt>deroute</tt> is the ''goto'' directive of the flight plan; it switches the navigation to the given block:
<source lang="xml"><deroute block="landing"/></source>

Note that this primitive should not be used to execute loops which are provided by the following elements.

=== Loops ===

Unbounded loops are written with <tt>while</tt> elements whose <tt>cond</tt> attribute is a boolean expression.
Children of <tt>while</tt> are stages:
<source lang="xml">
<while cond="TRUE">
<go wp="A"/>
<go wp="B"/>
<go wp="C"/>
<while cond="5 > stage_time"/>
</while>
</source>
In this example, we run an infinite loop, lettin the aircraft try to go via waypoints <tt>A</tt>, <tt>B</tt> and <tt>C</tt> and waiting for 5 seconds before repeating.

Bounded loops are written with the <tt>for</tt> tag:
<source lang="xml">
<for var="i" from="0" to="3">
...
</for>
</source>
where the body of the loop will be run four times.

The variable of a <tt>for</tt> loop can be used inside expressions appearing as attributes of the stages:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75" alt="ground_alt+50*$i" until="stage_time>10" />
</for>
</source>

In this example, the aircraft will circle around waypoint '''HOME''' for 10 seconds at and altitude above ground of 50m, 10 seconds at altitude 100 meter (50+50), ... until 250m (5x +50).

Note: Two bounded loops using the same control variable are not allowed in the same block.

=== Navigation modes ===

Navigation modes give the description of the desired trajectory in 3D. While the horizontal mode is specified through
''stages'', the vertical control is specified with various attributes of these stages. The current available navigation stages are
* attitude : just keep a fixed attitude;
* heading : keep a given course;
* go : go to a given waypoint;
* path : list of waypoints linked by ''go''
* circle : circle around a waypoint;
* oval : two half circles with a straight between two nav points
* eight : fly a figure of eight through a waypoint and around another
* stay : hold the position (hard to realize for a fixed-wing aircraft);
* follow : follow another aircraft;
* xyz : circle around a point moveable with the RC transmitter stick (obsolete with the datalink).

The vertical control is achieved using the <tt>vmode</tt> attribute of these stages. The possible values are
* '''alt''' (the default) : the autopilot keeps the desired altitude which is the altitude of the waypoint (if any) or the altitude specified with the <tt>alt</tt> attribute;
* '''climb''' : the autopilot keeps the desired vertical speed specified with the <tt>climb</tt> attribute (in m/s);
* '''throttle''' : the autopilots sets the desired throttle specified with the <tt>throttle</tt> attribute (between 0 and 1);
* '''glide''' : the autopilot keeps the desired slope between two waypoints

The default control is done with the throttle. However, setting the <tt>pitch</tt> attribute to '''auto''' and the <tt>throttle</tt> attribute to a constant allows a vertical control only by controlling the attitude of the A/C.
The <tt>pitch</tt> attribute also can be set to any value (in degrees) while the throttle control is in use: it usually affects the airspeed of the aircraft.

The different navigation modes are detailed in the next sections.

=== Attitude ===

Element <tt>attitude</tt> is the navigation mode which corresponds to the current lowest control loop for horizontal mode.
The autopilot then keeps a constant attitude. The <tt>roll</tt> attribute is required (in degrees, positive to put right wing low).

To fly away, at constant airspeed:
<source lang="xml"><attitude roll="0" vmode="throttle", throttle="0.5"/></source>

To fly around, holding a given altitude:
<source lang="xml"><attitude roll="30" alt="ground_alt+50"/></source>

Note that it is not a ''safe'' navigation mode since the geographic position of the plane is not controlled. However, this mode is useful to tune the roll attitude control loop.

=== Heading ===

<tt>heading</tt> primitive is relative to the second level loop for horizontal mode in the autopilot which will keep the given <tt>course</tt>, a required attribute (in degrees, clockwise, north=0, east=90).

One example to takeoff, following the QFU, 80% throttle, nose up (15 degrees) until height of 30m is reached:
<source lang="xml"><heading course="QFU" vmode="throttle" throttle="0.8" pitch="15" until="(GetPosAlt() > ground_alt+30)"/></source>

=== Go ===

The <tt>go</tt> primitive is probably the most useful one. Basically, the autopilot will try to join a given waypoint (<tt>wp</tt>, the only required attribute). So the simplest thing you can ask for is
<source lang="xml"><go wp="HOME"/></source>
which will set the '''HOME''' waypoint as the desired target position. Note than since <tt>vmode="alt"</tt> is the default, the altitude of the target waypoint is also taken into account. The navigation will switch to the next stage as soon as the target is reached.

It is usually not a good idea to try to join a waypoint without asking for a precise trajectory, i.e. a given line.
Setting the <tt>hmode</tt> attribute to '''route''', the navigation will go over a segment joining two waypoints:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route"/></source>

The target altitude is the altitude of the target waypoint; it can also be set with the <tt>alt</tt> attribute. The following example keeps an altitude with fixed throttle:
<source lang="xml"><go from="wp2" wp="wp3" hmode="route" pitch="auto" throttle="0.75" alt="ground_alt+100"/></source>

The attributes related to the vertical control can also be set to replace the default altitude mode:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" vmode="climb" climb="1.5"/></source>

Finally, the <tt>approaching_time</tt> (in seconds) attribute helps to decide when the target is ''reached''. It can be set
to '''0''' to go over the target waypoint (default value is the '''CARROT''' time, set in the airframe configuration file).
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" approaching_time="1"/></source>

=== Path ===

The <tt>path</tt> primitive is just a shorthand expression for a set of <tt>go</tt> primitives. A list of waypoints defined with the <tt>wpts</tt> attribute is pre-processed into a set of <tt>go</tt> primitives with the <tt>hmode</tt> attribute. For example:
<source lang="xml"><path wpts="wp1, wp2, wp3"/></source>

Other attributes are optional:
<source lang="xml"><path wpts="wp3, wp1, wp2" approaching_time="1" pitch="auto" throttle="0.5"/></source>

=== Circle ===

The <tt>circle</tt> primitive is the second main navigation mode: the trajectory is defined as a circle around a given waypoint with a given radius:
<source lang="xml"><circle wp="HOME" radius="75"/></source>
A positive radius makes the UAS move clockwise, a negative counter-clockwise.

The <tt>until</tt> attribute may be used to control the end of the stage. The following example defines an ascending trajectory at constant throttle, nose up (15 degrees), over growing circles, until the battery level is low:
<source lang="xml"><circle wp="wp1" radius="50+(GetPosAlt()-ground_alt)/2" vmode="throttle" throttle="0.75" pitch="15" until="10>PowerVoltage()"/></source>

=== Oval ===
The oval consists of two half circles that are connected with two straight lines. This flight path is usefull when a IMU is used because the straights allow for level flight.
<source lang="xml"> <oval p1="1" p2="2" radius="nav_radius"/> </source>

=== Eight ===
Fly a figure of eight that consists of two straight legs that pass though the center and the center of the half circle at the end of the two legs is in the turn around waypoint. The altitude of the center waypoint is used for the entire figure. The turn around waypoint is moved to match radius given.
<source lang="xml"> <eight center="1" radius="nav_radius" turn_around="2"/> </source>

=== Follow ===

The <tt>follow</tt> is a special primitive which makes the UAS follow another UAS (real or simulated, named with its <tt>ac_id</tt>) at a given <tt>distance</tt> (in meters) behind and at a given <tt>height</tt> (in meters) above.

In this example, the autopilot will try to follow A/C number '''4''', staying '''50'''m behind and '''20'''m above.
<source lang="xml"><follow ac_id="4" distance="50" height="20"/></source>
Note that the <tt>traffic_info.c</tt> file is required by this feature and the <tt>TRAFFIC_INFO</tt> flag has to be set to enable it. Then, the following lines must be added in the airframe file:
<tt>ap.srcs += traffic_info.c</tt>
<tt>ap.CFLAGS += -DTRAFFIC_INFO</tt>
<tt>sim.srcs += traffic_info.c</tt>
<tt>sim.CFLAGS += -DTRAFFIC_INFO</tt>

=== Stay ===

The <tt>stay</tt> is a mode for UAS's able to hover:
<source lang="xml"><stay wp="HOME" alt="10"/></source>

=== XYZ ===

<tt>xyz</tt> is a special mode where the UAS circles around a user moveable waypoint. This waypoint is moved with the RC sticks:
* YAW channel controls the point over the west-east axis;
* PITCH channel controls the point over the south-north axis;
* ROLL channel controls the altitude.

Example (default radius is '''100'''):
<source lang="xml"><xyz radius="40"/></source>

=== Set ===

The <tt>set</tt> element is a dangerous one which should be used only by expert users: it is used to directly set an internal variable of the autopilot. For example, you can change the value of the default ground altitude, a variable used by the home mode failsafe procedure (and maybe by your own flight plan):
<source lang="xml"><set var="ground_alt" value="ground_alt+50"/></source>
This directive is extremely powerful and has great potential for error - use with caution.

=== Call ===

The <tt>call</tt> allows the user to define its own navigation procedures in C. The <tt>value</tt> must be a call to a boolean function which must return TRUE as long as the stage is not completed (a function which should be called only once would then return immediately FALSE).
This feature is illustrated with the '''line''' pattern:
<source lang="xml">
<call fun="nav_line_init()"/>
<call fun="nav_line(WP_1, WP_2, nav_radius)"/>
</source>
where <tt>nav_line_init()</tt> returns FALSE and <tt>nav_line()</tt> always returns TRUE (this stage never ends).
Such functions usually are defined in a supplementary C file which must be specified in the airframe file (in the <tt>makefile</tt> section)
<tt>ap.srcs += nav_line.c
sim.srcs += nav_line.c</tt>
These functions also must be declared in a header file which must be mentioned in the header element of the flight plan:
<source lang="xml">
<header>
#include "nav_line.h"
</header>
</source>
These C source file and H header file must be located in the <tt>sw/airborne</tt> directory.

You can also call functions before or after each execution of the block (this means continuously on each iteration of each stage of the block, not just when entering o exiting the block).
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

== Advanced Examples ==
Parameters used in a flight plan can be computed expressions. In this example, the plane is asked to perform 5 circles at progressively increasing altitudes for exactly one minute at each altitude:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75"
alt="ground_alt + 50*$i"
until="stage_time > 60" />
</for>
</source>

=== Immobilize Actuators ===

h_ctl setpoints variable are set by the h_ctl_attitude_loop() (from fw_h_ctl.c) loop) which can be disabled with the
h_ctl_disabled flag:
<source lang="xml">
<set var="h_ctl_disabled" value="TRUE"/>
<set var="h_ctl_aileron_setpoint" value="0"/>
<set var="h_ctl_elevator_setpoint" value="MAX_PPRZ/2"/>
.... waiting for a condition ...
<set var="h_ctl_disabled" value="FALSE"/>
</source>

== Procedures ==

Procedures are libraries which can be included in flight plans. They are composed of waypoints, sectors and blocks. The header of a procedure may contain some parameters which are replaced by arguments when the procedure is included.

Extract of the DTD: a procedure is a sequence of parameters, waypoints, ...:
<source lang="xml"><!ELEMENT procedure (param*,header?,waypoints?,sectors?,exceptions?,blocks?)></source>

A <tt>param</tt>eter is just a name. A parameter is optional if it is declared with a default value.
An example with a required and an optional parameter:
<source lang="xml">
<param name="alt"/>
<param name="radius" default_value="75"/>
</source>

Procedures are called with the <tt>include</tt> element in a flight plan. A procedure cannot be included twice or by another procedure. A procedure call requires:

* the name of the procedure file, the name given to this inclusion;
* values for the parameters;
* backlinks for block name exits of the procedure.

For example:
<source lang="xml"><include name="landing" procedure="landing.xml"/></source>

Here is the corresponding procedure '''landing.xml''':
<source lang="xml">
<!DOCTYPE procedure SYSTEM "flight_plan.dtd">
<procedure>
<waypoints>
<waypoint name="AF" x="177.4" y="45.1" alt="30"/>
<waypoint name="TD" x="28.8" y="57.0" alt="0"/>
<waypoint name="_BASELEG" x="168.8" y="-13.8"/>
</waypoints>
<blocks>
...
<block name="land">
<call fun="nav_compute_baseleg(WP_AF, WP_TD, WP__BASELEG, nav_radius)"/>
<circle radius="nav_radius" until="NavCircleCount() > 0.5" wp="_BASELEG"/>
<circle radius="nav_radius" until="And(NavQdrCloseTo(DegOfRad(baseleg_out_qdr)-10), 10 > fabs(GetPosAlt()- WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
</block>
...
</blocks>
</procedure>
</source>

Note that the name of procedure '''land''' block will be renamed into '''landing.land''':
<source lang="xml"><deroute block="landing.land"/></source>
will jump to this procedure block.

Suppose you have a go-around condition in your landing procedure. You would write it
<source lang="xml"><exception cond="..." deroute="go-around"/></source>
then you must link this block exit with one of your block (e.g. <tt>Standby</tt>). So you would include the procedure as follows:
<source lang="xml">
<include name="landing" procedure="landing.xml">
<with from="go-around" to="Standby"/>
</include>
</source>

== Tips and Tricks ==

There are many ways to skin a cat just as there are many ways to craft your flight plan. Following the best practices tips can save you from a lot of frustration and mishap.

* Simulate your flight plan before taking it to the sky. Flight plans should always be carefully tested prior to flight, take a look at the [[Simulation|simulation]] page for details on how to simulate your plan.
* Make an subdirectory in the Flight_plan directory with your own name and add your flight plans there. Make sure that the location of the DTD is correct, e.g by using relative directory double dots as in <tt><!DOCTYPE flight_plan SYSTEM "../flight_plan.dtd"></tt>

* Take a good look at other flight plans included with Paparazzi. To learn from example flight plans please visit the [[Flight_Plan_Examples|flight plan examples]] page
* There are several option to build failsafe features into you flightplan, [[Failsafe|for some examples visit the Failsafe page]].
* Some flight plan examples define waypoint locations using relative coordinates. These are relative positions from the fixed lat and lon in the header of the flight plan. When simulating your flight plan the aircraft always use the lat/lon as defined in the flight plan since a regular simulation has no notion of you current position of you local PC where you simulate on. This is something to keep in mind if you test your flight plan in real flights.

[[Category:Software]] [[Category:User_Documentation]]

Flight Plans

2014-06-05T03:17:07Z

Alonsoac: /* Call */

A '''flight plan''' is a XML document which one can create and store aboard an autopilot. The flight plan will describe how you want your aircraft to travel if released into into the wild blue yonder.

== DTD and Structure ==

The formal description of the flight plan file is given in the [http://en.wikipedia.org/wiki/Document_Type_Definition '''DTD'''] (located in <tt>conf/flight_plans/flight_plan.dtd</tt>). This
DTD must be referenced in the header of your flight plan XML document using the following line:<br>

<source lang="xml"><!DOCTYPE flight_plan SYSTEM "flight_plan.dtd"></source>

The flight plans are stored in the <tt>conf/flight_plans</tt> directory. The [[Flight_Plan_Editor|flight plan editor]] can be used to create basic flight plans via the GUI.

Extract from the [http://en.wikipedia.org/wiki/Document_Type_Definition DTD]:
<tt><!ELEMENT flight_plan (header?,waypoints,sectors?,include*,exceptions?,blocks)></tt>

'''A flight plan is composed of two mandatory elements: [[#waypoints|waypoints]] and [[#blocks|blocks]]'''

The root <tt>flight_plan</tt> element is specified with several attributes:
<tt>'''<flight_plan name lat0 lon0 ground_alt security_height home_mode_height qfu alt max_dist_from_home>'''</tt>
; <tt>'''name'''</tt>: The name of the mission (a text string)
; <tt>'''lat0, lon0'''</tt>: Defines the latitude and longitude coordinates of the reference point {0,0} in WGS84 degree coordinates
; <tt>'''ground_alt'''</tt>: The ground altitude (in meters), Above Sea Level where you are flying. It defines the <tt>GROUND_ALT</tt> constant value which can be used in combination with a waypoint <height> parameter to define a waypoint height
; <tt>'''security_height'''</tt>: The height (over <tt>'''ground_alt'''</tt>) used by the circle-home failsafe procedure and in other flight procedures such as formation flight and anti-collision avoidance. Warnings are produced if you place a waypoint lower than <tt>'''security_height'''</tt> (usually the case for the landing point)
; <tt>'''home_mode_height'''</tt> (optional): This optional attribute available since v4.2 allows to override <tt>'''security_height'''</tt> as failsafe height in home mode. If <tt>'''home_mode_height'''</tt> Is set lower than <tt>'''security_height'''</tt>, the later is used. This attribute is useful if you need to return home at a high altitude rather than a low altitude.
; <tt>'''qfu'''</tt> (optional): defines the global constant <tt>QFU</tt>. It usually is the magnetic heading in degrees (north=0, east=90) of the runway, the opposite of wind direction. This constant may be used in the mission description. It is also used by the simulator as the original course of the aircraft. So if you want to take off and climb to the West you would use qfu=270.
; <tt>'''alt'''</tt>: The default altitude of waypoints ([[Altitude_definitions|Above Sea Level]]). So if your ground altitude is 400 then alt needs to be a value greater than ground altitude and above any obstructions in the flight plan.
; <tt>'''max_dist_from_home'''</tt>: A radius representing the maximum allowed distance (in meters) from the HOME waypoint. Exceeding this value (ie flying outside the circle with this radius) will trigger an exception. It is up to you to define the block to be executed (ie what to do) for the exception.

''Here is an '''example''' of such a line in the top of a flight plan:''

<source lang="xml">
<flight_plan alt="250" ground_alt="185" lat0="43.46223" lon0="1.27289" name="Example Muret" max_dist_from_home="300" qfu="270" security_height="25" >
</source>

Note that a flight plan could also contain optional <tt>include</tt>'s and <tt>exceptions</tt> cases.

In English the above flight plan says the name is Example Muret. The reference coordinates for the 0,0 point is: 43.46223 (lat) and 1.27289 (long). The flying site 0,0 location is 185m above sea level. The security height is 25m above 0,0 point or 210m above sea level. The default (ie if not defined in a waypoint this alt is used) altitude is 250m (above sea level). The home mode block altitude is defined to be 150m above sea level. Also, for security, a circle is defined with a radius that's 300m from 0,0 position. This is the max_dist_from_home value. Fly 301m from 0,0 and an exception is triggered. A useful block is to trigger/go to the home mode block and return to home when the aircraft flies outside the safety circle. Example flight plans are helpful for study before you build your own from scratch.

== Waypoints ==

The waypoints are the geographic locations used to specify the trajectories. A waypoint is specified by it's name and coordinates:
<tt>''' <waypoint name wpx wpy [alt] [height]/> '''</tt>
where wpx and wpy are real positional coordinates ( <tt>'''lat/lon'''</tt> ) '''or''' UTM coordinates ( <tt>'''utm_x0/utm_y0'''</tt> ) '''or''' relative coordinates ( <tt>'''x/y'''</tt> ) in meters from your reference point {0,0} . <tt>alt</tt> is an optional parameter and can be used to assign an altitude to a particular waypoint that is different from the globally defined <tt>alt</tt> parameter of the flightplan. The <tt>height</tt> attribute can be used to set the waypoint height relative to the [[Altitude_definitions|ground altitude]] (<tt>ground_alt</tt>) of the flight plan for this waypoint.

An example:
<source lang="xml">
<waypoints>
<waypoint name="HOME" x="0.0" y="30.0"/>
<waypoint name="BRIDGEOVERRIVER" x="-100.0" y="60.0" alt="270."/>
<waypoint name="MyBarn" x="-130.0" y="217.5" alt="3000."/>
<waypoint name="3" x="-30.0" y="50" height="50."/>
<waypoint name="4" x="-30.0" y="50." alt="ground_alt + 50"/>
<waypoint name="_MYHELPERSPOT" x="-30.0" y="60" height="50."/>
<waypoint name="_MYOTHERHELPERSPOT" x="-70.0" y="90" height="70."/>
<waypoint name="TOWER" lat="48.858249" lon="2.294494" height="324."/>
<waypoint name="MountainCAFE" utm_x0="360284.8" utm_y0="4813595.5" alt="1965."/>
</waypoints>
</source>

'''Tips'''
* Waypoints are easily adjusted with the [[Flight_Plan_Editor|flight plan editor]].
* If a waypoint name starts with an underscore ( _ ), the waypoint is '''not displayed''' in the GCS, except in editor mode.
* The maximum number of waypoints is 254.
* A waypoint named <tt>HOME</tt> is required if the failsafe HOME mode procedure is used.

== Sectors ==

Flat ''Sectors'' can be described as an area defined by list of waypoint corners. Such an area will be displayed in the Ground Control Station (GCS) by colored lines connecting the cornerpoints.
A function is generated to check if a point, usually the aircraft itself, is ''inside'' this sector. Currently, this feature requires that the polygon is <b>convex</b> and described in a <b>clockwise</b> order. For a sector named <tt>MyBigGarden</tt> the generated function for the example here would be <tt>bool_t InsideMyBigGarden(float x, float y);</tt> where <tt>x</tt> and <tt>y</tt> are east and north coordinated, in meters, relative to the geographic reference of the flight plan. If the flight plan is dynamically relocated, such a sector will be relocated but the display is currently not updated on the GCS. It would be great if one would help improving that part of the source code. Note that sector names are not allowed to contain spaces.

For example, with the following element in a flight plan.
<source lang="xml">
<sectors>
<sector name="MyBigGarden" color="red">
<corner name="_1"/>
<corner name="_2"/>
<corner name="_3"/>
<corner name="_4"/>
</sector>
</sectors>
</source>

It is then possible to add an exception clause to your flightplan. For example if the aircraft for some reason flies outside this, defined by us, sector the airframe will fly to a standby waypoint. The exclamation mark (!) means the boolean operator <tt>NOT</tt> in this example. In regular language one would describe "If my airframe is NOT inside the MyBigGarden sector anymore then deroute it to the standby waypoint. In Flightplan "Speak" this is written like:
<source lang="xml">
<exception cond="! InsideMyBigGarden(GetPosX(), GetPosY())" deroute="standby"/>
</source>

NOTE: editing of the waypoints of the sector during the flight will not dynamically update the inside function. It will always check if the position is inside the original sector.

'''Tips'''
* A nice option in the corner notation is that one can add an underscore ( _ ) in front of the name; a corner or waypoint name that starts with an underscore is not displayed in the GCS. Only in editor mode it is visible. It is visible in editor mode, because if you the could not see it, it also would be not possible to edit or drag the corner or waypoint to another position.
* The color indicating the sector borders is not fixed but can be defined by oneself if wished for via the color attribute.

== Includes ==

<tt>include</tt> is used to add some flight plan elements defined in an external procedure. It’s useful to include pre-written procedures with only few arguments and then clarify the flight plan.
Here is the structure:
<tt><include name procedure> [<arg name value />]*[<with from to />]*</include></tt>
where <tt>name</tt> attribute of the include element will be used in this flight plan to prefix the blocks of the <tt>procedure</tt>, the XML referenced file.
Named arguments may be given with their value in the <tt>arg</tt> elements. The <tt>with</tt> tag allows to link labels (e.g. attribute of a deroute instruction or of an exception) from the procedure to blocks of the main flight plan.
Then, each block of the procedure is like any block of the flight plan and is designated with a dotted identifier: block <tt>b</tt> of a procedure named <tt>p</tt> is named <tt>b.p</tt> .

Here is an example:
<source lang="xml">
<includes>
<include name="landing" procedure="landing.xml"/>
</includes>
</source>

== Blocks ==

Block elements are the main part of a flight plan: they describe each unit of the mission.
They are made of various primitives, called stages and exceptions, you can put one after the other. When a
stage (or a block) is finished, the autopilot goes to the next one. The behaviour after the last stage of the last block is undefined.

As described in the DTD, the <tt>blocks</tt> element is composed of <tt>block</tt> elements which are sequence of ''stages'':
<source lang="xml">
<!ELEMENT blocks (block+)>
<!ELEMENT block (exception|while|heading|attitude|go|xyz|set|call|circle|deroute|stay|follow|survey_rectangle|for|return|eight|oval|home|path)*>
</source>

Example:
<source lang="xml">
<block name="circlehome">
<circle radius="75" wp="HOME"/>
</block>
</source>

You can add a button in the [[GCS#Strips|strip of the aircraft]] with the attribute <tt>strip_button</tt>:
<source lang="xml">
<block name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
This button will activate the block. If the attribute <tt>group</tt> is specified, all strip buttons of the same group will be placed vertically on top of each other.

In the same way, a key shortcut can be specified:
<source lang="xml">
<block key="D" name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
Modifiers are allowed, using the syntax of [http://library.gnome.org/devel/gtk/2.15/gtk-Keyboard-Accelerators.html#gtk-accelerator-parse GTK accelerators].

An icon can be specified to display the button. The <tt>strip_button</tt> label then is a tooltip for the icon. The icon must be an image file available in the directory <tt>data/pictures/gcs_icons</tt>:
<source lang="xml"><block name="Takeoff" strip_icon="takeoff.png" strip_button="Takeoff"></source>

You can call functions before or after each execution of the block:
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

==== Expressions ====

Most of the numeric attributes in stages are analyzed as C expressions. The syntax of this C expression is restricted to
* numeric constants
* some internal autopilot variables (not fully documented, see examples)
* Some binary operators: <, >, <=, >=, <>, ==, +, -, /, *
* Some utility functions

Some examples of usable expressions are given in the next sections.
=== Initialization Blocks ===
Most flight plans will have three blocks of flight plan initialization blocks. It is good practice to follow this example below if you first start learing to create flightplans

The first block waits until the GPS fix has been established, as shown below.
<source lang="xml">
<blocks>
<block name="Wait GPS">
<set value="1" var="kill_throttle"/>
<while cond="!GpsFixValid()"/>
</block>
</source>
The second block updates the local waypoints with respect to the UAV.
<source lang="xml">
<block name="Geo init">
<while cond="LessThan(NavBlockTime(), 10)"/>
<call fun="NavSetGroundReferenceHere()"/>
</block>
</source>
This next block prevents the UAV from starting the engine and taking off.
<source lang="xml">
<block name="Holding point">

<set value="1" var="kill_throttle"/>
<attitude roll="0" throttle="0" vmode="throttle"/>
</block>
</source>

=== Exceptions ===

The flight manager can handle exceptions. They consist in conditions checked periodically (at the same pace as the navigation control), allowing the control to jump to a given block. Here is the syntax of exceptions:
<source lang="xml"><exception cond="..." deroute="..."></source>
where <tt>cond</tt> is an expression and <tt>deroute</tt> is the name of the block we want to switch to as soon as the condition is true.

Here are some example of exceptions:
<source lang="xml">
<exception cond="10 > PowerVoltage()" deroute="go_down"/>
<exception cond="(ground_alt+10 > GetPosAlt())" deroute="go_up"/>
<exception cond="(autopilot_flight_time > 840)" deroute="quick_land"/>
</source>

Exceptions can be local to a block or global to the flight plan, in the <tt><exceptions></tt> element. In the following example, time since last reception of a message from the ground station is monitored and the navigation is switched to the <tt>Standby</tt> block if no message have been received for 22s. This exception is valid for '''all''' the blocks.
<source lang="xml">
<flight_plan ...>
<waypoints> ... </waypoints>
<exceptions>
<exception cond="datalink_time > 22" deroute="Standby"/>
</exceptions>
<blocks> ...
</source>

=== Deroute ===

The <tt>deroute</tt> is the ''goto'' directive of the flight plan; it switches the navigation to the given block:
<source lang="xml"><deroute block="landing"/></source>

Note that this primitive should not be used to execute loops which are provided by the following elements.

=== Loops ===

Unbounded loops are written with <tt>while</tt> elements whose <tt>cond</tt> attribute is a boolean expression.
Children of <tt>while</tt> are stages:
<source lang="xml">
<while cond="TRUE">
<go wp="A"/>
<go wp="B"/>
<go wp="C"/>
<while cond="5 > stage_time"/>
</while>
</source>
In this example, we run an infinite loop, lettin the aircraft try to go via waypoints <tt>A</tt>, <tt>B</tt> and <tt>C</tt> and waiting for 5 seconds before repeating.

Bounded loops are written with the <tt>for</tt> tag:
<source lang="xml">
<for var="i" from="0" to="3">
...
</for>
</source>
where the body of the loop will be run four times.

The variable of a <tt>for</tt> loop can be used inside expressions appearing as attributes of the stages:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75" alt="ground_alt+50*$i" until="stage_time>10" />
</for>
</source>

In this example, the aircraft will circle around waypoint '''HOME''' for 10 seconds at and altitude above ground of 50m, 10 seconds at altitude 100 meter (50+50), ... until 250m (5x +50).

Note: Two bounded loops using the same control variable are not allowed in the same block.

=== Navigation modes ===

Navigation modes give the description of the desired trajectory in 3D. While the horizontal mode is specified through
''stages'', the vertical control is specified with various attributes of these stages. The current available navigation stages are
* attitude : just keep a fixed attitude;
* heading : keep a given course;
* go : go to a given waypoint;
* path : list of waypoints linked by ''go''
* circle : circle around a waypoint;
* oval : two half circles with a straight between two nav points
* eight : fly a figure of eight through a waypoint and around another
* stay : hold the position (hard to realize for a fixed-wing aircraft);
* follow : follow another aircraft;
* xyz : circle around a point moveable with the RC transmitter stick (obsolete with the datalink).

The vertical control is achieved using the <tt>vmode</tt> attribute of these stages. The possible values are
* '''alt''' (the default) : the autopilot keeps the desired altitude which is the altitude of the waypoint (if any) or the altitude specified with the <tt>alt</tt> attribute;
* '''climb''' : the autopilot keeps the desired vertical speed specified with the <tt>climb</tt> attribute (in m/s);
* '''throttle''' : the autopilots sets the desired throttle specified with the <tt>throttle</tt> attribute (between 0 and 1);
* '''glide''' : the autopilot keeps the desired slope between two waypoints

The default control is done with the throttle. However, setting the <tt>pitch</tt> attribute to '''auto''' and the <tt>throttle</tt> attribute to a constant allows a vertical control only by controlling the attitude of the A/C.
The <tt>pitch</tt> attribute also can be set to any value (in degrees) while the throttle control is in use: it usually affects the airspeed of the aircraft.

The different navigation modes are detailed in the next sections.

=== Attitude ===

Element <tt>attitude</tt> is the navigation mode which corresponds to the current lowest control loop for horizontal mode.
The autopilot then keeps a constant attitude. The <tt>roll</tt> attribute is required (in degrees, positive to put right wing low).

To fly away, at constant airspeed:
<source lang="xml"><attitude roll="0" vmode="throttle", throttle="0.5"/></source>

To fly around, holding a given altitude:
<source lang="xml"><attitude roll="30" alt="ground_alt+50"/></source>

Note that it is not a ''safe'' navigation mode since the geographic position of the plane is not controlled. However, this mode is useful to tune the roll attitude control loop.

=== Heading ===

<tt>heading</tt> primitive is relative to the second level loop for horizontal mode in the autopilot which will keep the given <tt>course</tt>, a required attribute (in degrees, clockwise, north=0, east=90).

One example to takeoff, following the QFU, 80% throttle, nose up (15 degrees) until height of 30m is reached:
<source lang="xml"><heading course="QFU" vmode="throttle" throttle="0.8" pitch="15" until="(GetPosAlt() > ground_alt+30)"/></source>

=== Go ===

The <tt>go</tt> primitive is probably the most useful one. Basically, the autopilot will try to join a given waypoint (<tt>wp</tt>, the only required attribute). So the simplest thing you can ask for is
<source lang="xml"><go wp="HOME"/></source>
which will set the '''HOME''' waypoint as the desired target position. Note than since <tt>vmode="alt"</tt> is the default, the altitude of the target waypoint is also taken into account. The navigation will switch to the next stage as soon as the target is reached.

It is usually not a good idea to try to join a waypoint without asking for a precise trajectory, i.e. a given line.
Setting the <tt>hmode</tt> attribute to '''route''', the navigation will go over a segment joining two waypoints:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route"/></source>

The target altitude is the altitude of the target waypoint; it can also be set with the <tt>alt</tt> attribute. The following example keeps an altitude with fixed throttle:
<source lang="xml"><go from="wp2" wp="wp3" hmode="route" pitch="auto" throttle="0.75" alt="ground_alt+100"/></source>

The attributes related to the vertical control can also be set to replace the default altitude mode:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" vmode="climb" climb="1.5"/></source>

Finally, the <tt>approaching_time</tt> (in seconds) attribute helps to decide when the target is ''reached''. It can be set
to '''0''' to go over the target waypoint (default value is the '''CARROT''' time, set in the airframe configuration file).
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" approaching_time="1"/></source>

=== Path ===

The <tt>path</tt> primitive is just a shorthand expression for a set of <tt>go</tt> primitives. A list of waypoints defined with the <tt>wpts</tt> attribute is pre-processed into a set of <tt>go</tt> primitives with the <tt>hmode</tt> attribute. For example:
<source lang="xml"><path wpts="wp1, wp2, wp3"/></source>

Other attributes are optional:
<source lang="xml"><path wpts="wp3, wp1, wp2" approaching_time="1" pitch="auto" throttle="0.5"/></source>

=== Circle ===

The <tt>circle</tt> primitive is the second main navigation mode: the trajectory is defined as a circle around a given waypoint with a given radius:
<source lang="xml"><circle wp="HOME" radius="75"/></source>
A positive radius makes the UAS move clockwise, a negative counter-clockwise.

The <tt>until</tt> attribute may be used to control the end of the stage. The following example defines an ascending trajectory at constant throttle, nose up (15 degrees), over growing circles, until the battery level is low:
<source lang="xml"><circle wp="wp1" radius="50+(GetPosAlt()-ground_alt)/2" vmode="throttle" throttle="0.75" pitch="15" until="10>PowerVoltage()"/></source>

=== Oval ===
The oval consists of two half circles that are connected with two straight lines. This flight path is usefull when a IMU is used because the straights allow for level flight.
<source lang="xml"> <oval p1="1" p2="2" radius="nav_radius"/> </source>

=== Eight ===
Fly a figure of eight that consists of two straight legs that pass though the center and the center of the half circle at the end of the two legs is in the turn around waypoint. The altitude of the center waypoint is used for the entire figure. The turn around waypoint is moved to match radius given.
<source lang="xml"> <eight center="1" radius="nav_radius" turn_around="2"/> </source>

=== Follow ===

The <tt>follow</tt> is a special primitive which makes the UAS follow another UAS (real or simulated, named with its <tt>ac_id</tt>) at a given <tt>distance</tt> (in meters) behind and at a given <tt>height</tt> (in meters) above.

In this example, the autopilot will try to follow A/C number '''4''', staying '''50'''m behind and '''20'''m above.
<source lang="xml"><follow ac_id="4" distance="50" height="20"/></source>
Note that the <tt>traffic_info.c</tt> file is required by this feature and the <tt>TRAFFIC_INFO</tt> flag has to be set to enable it. Then, the following lines must be added in the airframe file:
<tt>ap.srcs += traffic_info.c</tt>
<tt>ap.CFLAGS += -DTRAFFIC_INFO</tt>
<tt>sim.srcs += traffic_info.c</tt>
<tt>sim.CFLAGS += -DTRAFFIC_INFO</tt>

=== Stay ===

The <tt>stay</tt> is a mode for UAS's able to hover:
<source lang="xml"><stay wp="HOME" alt="10"/></source>

=== XYZ ===

<tt>xyz</tt> is a special mode where the UAS circles around a user moveable waypoint. This waypoint is moved with the RC sticks:
* YAW channel controls the point over the west-east axis;
* PITCH channel controls the point over the south-north axis;
* ROLL channel controls the altitude.

Example (default radius is '''100'''):
<source lang="xml"><xyz radius="40"/></source>

=== Set ===

The <tt>set</tt> element is a dangerous one which should be used only by expert users: it is used to directly set an internal variable of the autopilot. For example, you can change the value of the default ground altitude, a variable used by the home mode failsafe procedure (and maybe by your own flight plan):
<source lang="xml"><set var="ground_alt" value="ground_alt+50"/></source>
This directive is extremely powerful and has great potential for error - use with caution.

=== Call ===

The <tt>call</tt> allows the user to define its own navigation procedures in C. The <tt>value</tt> must be a call to a boolean function which must return TRUE as long as the stage is not completed (a function which should be called only once would then return immediately FALSE).
This feature is illustrated with the '''line''' pattern:
<source lang="xml">
<call fun="nav_line_init()"/>
<call fun="nav_line(WP_1, WP_2, nav_radius)"/>
</source>
where <tt>nav_line_init()</tt> returns FALSE and <tt>nav_line()</tt> always returns TRUE (this stage never ends).
Such functions usually are defined in a supplementary C file which must be specified in the airframe file (in the <tt>makefile</tt> section)
<tt>ap.srcs += nav_line.c
sim.srcs += nav_line.c</tt>
These functions also must be declared in a header file which must be mentioned in the header element of the flight plan:
<source lang="xml">
<header>
#include "nav_line.h"
</header>
</source>
These C source file and H header file must be located in the <tt>sw/airborne</tt> directory.

You can also call functions before or after each execution of the block (this means continuosly on each iteration of each stage of the block, not just when entering o exiting the block).
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

== Advanced Examples ==
Parameters used in a flight plan can be computed expressions. In this example, the plane is asked to perform 5 circles at progressively increasing altitudes for exactly one minute at each altitude:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75"
alt="ground_alt + 50*$i"
until="stage_time > 60" />
</for>
</source>

=== Immobilize Actuators ===

h_ctl setpoints variable are set by the h_ctl_attitude_loop() (from fw_h_ctl.c) loop) which can be disabled with the
h_ctl_disabled flag:
<source lang="xml">
<set var="h_ctl_disabled" value="TRUE"/>
<set var="h_ctl_aileron_setpoint" value="0"/>
<set var="h_ctl_elevator_setpoint" value="MAX_PPRZ/2"/>
.... waiting for a condition ...
<set var="h_ctl_disabled" value="FALSE"/>
</source>

== Procedures ==

Procedures are libraries which can be included in flight plans. They are composed of waypoints, sectors and blocks. The header of a procedure may contain some parameters which are replaced by arguments when the procedure is included.

Extract of the DTD: a procedure is a sequence of parameters, waypoints, ...:
<source lang="xml"><!ELEMENT procedure (param*,header?,waypoints?,sectors?,exceptions?,blocks?)></source>

A <tt>param</tt>eter is just a name. A parameter is optional if it is declared with a default value.
An example with a required and an optional parameter:
<source lang="xml">
<param name="alt"/>
<param name="radius" default_value="75"/>
</source>

Procedures are called with the <tt>include</tt> element in a flight plan. A procedure cannot be included twice or by another procedure. A procedure call requires:

* the name of the procedure file, the name given to this inclusion;
* values for the parameters;
* backlinks for block name exits of the procedure.

For example:
<source lang="xml"><include name="landing" procedure="landing.xml"/></source>

Here is the corresponding procedure '''landing.xml''':
<source lang="xml">
<!DOCTYPE procedure SYSTEM "flight_plan.dtd">
<procedure>
<waypoints>
<waypoint name="AF" x="177.4" y="45.1" alt="30"/>
<waypoint name="TD" x="28.8" y="57.0" alt="0"/>
<waypoint name="_BASELEG" x="168.8" y="-13.8"/>
</waypoints>
<blocks>
...
<block name="land">
<call fun="nav_compute_baseleg(WP_AF, WP_TD, WP__BASELEG, nav_radius)"/>
<circle radius="nav_radius" until="NavCircleCount() > 0.5" wp="_BASELEG"/>
<circle radius="nav_radius" until="And(NavQdrCloseTo(DegOfRad(baseleg_out_qdr)-10), 10 > fabs(GetPosAlt()- WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
</block>
...
</blocks>
</procedure>
</source>

Note that the name of procedure '''land''' block will be renamed into '''landing.land''':
<source lang="xml"><deroute block="landing.land"/></source>
will jump to this procedure block.

Suppose you have a go-around condition in your landing procedure. You would write it
<source lang="xml"><exception cond="..." deroute="go-around"/></source>
then you must link this block exit with one of your block (e.g. <tt>Standby</tt>). So you would include the procedure as follows:
<source lang="xml">
<include name="landing" procedure="landing.xml">
<with from="go-around" to="Standby"/>
</include>
</source>

== Tips and Tricks ==

There are many ways to skin a cat just as there are many ways to craft your flight plan. Following the best practices tips can save you from a lot of frustration and mishap.

* Simulate your flight plan before taking it to the sky. Flight plans should always be carefully tested prior to flight, take a look at the [[Simulation|simulation]] page for details on how to simulate your plan.
* Make an subdirectory in the Flight_plan directory with your own name and add your flight plans there. Make sure that the location of the DTD is correct, e.g by using relative directory double dots as in <tt><!DOCTYPE flight_plan SYSTEM "../flight_plan.dtd"></tt>

* Take a good look at other flight plans included with Paparazzi. To learn from example flight plans please visit the [[Flight_Plan_Examples|flight plan examples]] page
* There are several option to build failsafe features into you flightplan, [[Failsafe|for some examples visit the Failsafe page]].
* Some flight plan examples define waypoint locations using relative coordinates. These are relative positions from the fixed lat and lon in the header of the flight plan. When simulating your flight plan the aircraft always use the lat/lon as defined in the flight plan since a regular simulation has no notion of you current position of you local PC where you simulate on. This is something to keep in mind if you test your flight plan in real flights.

[[Category:Software]] [[Category:User_Documentation]]

Flight Plans

2014-06-05T03:16:39Z

Alonsoac: /* Call */

A '''flight plan''' is a XML document which one can create and store aboard an autopilot. The flight plan will describe how you want your aircraft to travel if released into into the wild blue yonder.

== DTD and Structure ==

The formal description of the flight plan file is given in the [http://en.wikipedia.org/wiki/Document_Type_Definition '''DTD'''] (located in <tt>conf/flight_plans/flight_plan.dtd</tt>). This
DTD must be referenced in the header of your flight plan XML document using the following line:<br>

<source lang="xml"><!DOCTYPE flight_plan SYSTEM "flight_plan.dtd"></source>

The flight plans are stored in the <tt>conf/flight_plans</tt> directory. The [[Flight_Plan_Editor|flight plan editor]] can be used to create basic flight plans via the GUI.

Extract from the [http://en.wikipedia.org/wiki/Document_Type_Definition DTD]:
<tt><!ELEMENT flight_plan (header?,waypoints,sectors?,include*,exceptions?,blocks)></tt>

'''A flight plan is composed of two mandatory elements: [[#waypoints|waypoints]] and [[#blocks|blocks]]'''

The root <tt>flight_plan</tt> element is specified with several attributes:
<tt>'''<flight_plan name lat0 lon0 ground_alt security_height home_mode_height qfu alt max_dist_from_home>'''</tt>
; <tt>'''name'''</tt>: The name of the mission (a text string)
; <tt>'''lat0, lon0'''</tt>: Defines the latitude and longitude coordinates of the reference point {0,0} in WGS84 degree coordinates
; <tt>'''ground_alt'''</tt>: The ground altitude (in meters), Above Sea Level where you are flying. It defines the <tt>GROUND_ALT</tt> constant value which can be used in combination with a waypoint <height> parameter to define a waypoint height
; <tt>'''security_height'''</tt>: The height (over <tt>'''ground_alt'''</tt>) used by the circle-home failsafe procedure and in other flight procedures such as formation flight and anti-collision avoidance. Warnings are produced if you place a waypoint lower than <tt>'''security_height'''</tt> (usually the case for the landing point)
; <tt>'''home_mode_height'''</tt> (optional): This optional attribute available since v4.2 allows to override <tt>'''security_height'''</tt> as failsafe height in home mode. If <tt>'''home_mode_height'''</tt> Is set lower than <tt>'''security_height'''</tt>, the later is used. This attribute is useful if you need to return home at a high altitude rather than a low altitude.
; <tt>'''qfu'''</tt> (optional): defines the global constant <tt>QFU</tt>. It usually is the magnetic heading in degrees (north=0, east=90) of the runway, the opposite of wind direction. This constant may be used in the mission description. It is also used by the simulator as the original course of the aircraft. So if you want to take off and climb to the West you would use qfu=270.
; <tt>'''alt'''</tt>: The default altitude of waypoints ([[Altitude_definitions|Above Sea Level]]). So if your ground altitude is 400 then alt needs to be a value greater than ground altitude and above any obstructions in the flight plan.
; <tt>'''max_dist_from_home'''</tt>: A radius representing the maximum allowed distance (in meters) from the HOME waypoint. Exceeding this value (ie flying outside the circle with this radius) will trigger an exception. It is up to you to define the block to be executed (ie what to do) for the exception.

''Here is an '''example''' of such a line in the top of a flight plan:''

<source lang="xml">
<flight_plan alt="250" ground_alt="185" lat0="43.46223" lon0="1.27289" name="Example Muret" max_dist_from_home="300" qfu="270" security_height="25" >
</source>

Note that a flight plan could also contain optional <tt>include</tt>'s and <tt>exceptions</tt> cases.

In English the above flight plan says the name is Example Muret. The reference coordinates for the 0,0 point is: 43.46223 (lat) and 1.27289 (long). The flying site 0,0 location is 185m above sea level. The security height is 25m above 0,0 point or 210m above sea level. The default (ie if not defined in a waypoint this alt is used) altitude is 250m (above sea level). The home mode block altitude is defined to be 150m above sea level. Also, for security, a circle is defined with a radius that's 300m from 0,0 position. This is the max_dist_from_home value. Fly 301m from 0,0 and an exception is triggered. A useful block is to trigger/go to the home mode block and return to home when the aircraft flies outside the safety circle. Example flight plans are helpful for study before you build your own from scratch.

== Waypoints ==

The waypoints are the geographic locations used to specify the trajectories. A waypoint is specified by it's name and coordinates:
<tt>''' <waypoint name wpx wpy [alt] [height]/> '''</tt>
where wpx and wpy are real positional coordinates ( <tt>'''lat/lon'''</tt> ) '''or''' UTM coordinates ( <tt>'''utm_x0/utm_y0'''</tt> ) '''or''' relative coordinates ( <tt>'''x/y'''</tt> ) in meters from your reference point {0,0} . <tt>alt</tt> is an optional parameter and can be used to assign an altitude to a particular waypoint that is different from the globally defined <tt>alt</tt> parameter of the flightplan. The <tt>height</tt> attribute can be used to set the waypoint height relative to the [[Altitude_definitions|ground altitude]] (<tt>ground_alt</tt>) of the flight plan for this waypoint.

An example:
<source lang="xml">
<waypoints>
<waypoint name="HOME" x="0.0" y="30.0"/>
<waypoint name="BRIDGEOVERRIVER" x="-100.0" y="60.0" alt="270."/>
<waypoint name="MyBarn" x="-130.0" y="217.5" alt="3000."/>
<waypoint name="3" x="-30.0" y="50" height="50."/>
<waypoint name="4" x="-30.0" y="50." alt="ground_alt + 50"/>
<waypoint name="_MYHELPERSPOT" x="-30.0" y="60" height="50."/>
<waypoint name="_MYOTHERHELPERSPOT" x="-70.0" y="90" height="70."/>
<waypoint name="TOWER" lat="48.858249" lon="2.294494" height="324."/>
<waypoint name="MountainCAFE" utm_x0="360284.8" utm_y0="4813595.5" alt="1965."/>
</waypoints>
</source>

'''Tips'''
* Waypoints are easily adjusted with the [[Flight_Plan_Editor|flight plan editor]].
* If a waypoint name starts with an underscore ( _ ), the waypoint is '''not displayed''' in the GCS, except in editor mode.
* The maximum number of waypoints is 254.
* A waypoint named <tt>HOME</tt> is required if the failsafe HOME mode procedure is used.

== Sectors ==

Flat ''Sectors'' can be described as an area defined by list of waypoint corners. Such an area will be displayed in the Ground Control Station (GCS) by colored lines connecting the cornerpoints.
A function is generated to check if a point, usually the aircraft itself, is ''inside'' this sector. Currently, this feature requires that the polygon is <b>convex</b> and described in a <b>clockwise</b> order. For a sector named <tt>MyBigGarden</tt> the generated function for the example here would be <tt>bool_t InsideMyBigGarden(float x, float y);</tt> where <tt>x</tt> and <tt>y</tt> are east and north coordinated, in meters, relative to the geographic reference of the flight plan. If the flight plan is dynamically relocated, such a sector will be relocated but the display is currently not updated on the GCS. It would be great if one would help improving that part of the source code. Note that sector names are not allowed to contain spaces.

For example, with the following element in a flight plan.
<source lang="xml">
<sectors>
<sector name="MyBigGarden" color="red">
<corner name="_1"/>
<corner name="_2"/>
<corner name="_3"/>
<corner name="_4"/>
</sector>
</sectors>
</source>

It is then possible to add an exception clause to your flightplan. For example if the aircraft for some reason flies outside this, defined by us, sector the airframe will fly to a standby waypoint. The exclamation mark (!) means the boolean operator <tt>NOT</tt> in this example. In regular language one would describe "If my airframe is NOT inside the MyBigGarden sector anymore then deroute it to the standby waypoint. In Flightplan "Speak" this is written like:
<source lang="xml">
<exception cond="! InsideMyBigGarden(GetPosX(), GetPosY())" deroute="standby"/>
</source>

NOTE: editing of the waypoints of the sector during the flight will not dynamically update the inside function. It will always check if the position is inside the original sector.

'''Tips'''
* A nice option in the corner notation is that one can add an underscore ( _ ) in front of the name; a corner or waypoint name that starts with an underscore is not displayed in the GCS. Only in editor mode it is visible. It is visible in editor mode, because if you the could not see it, it also would be not possible to edit or drag the corner or waypoint to another position.
* The color indicating the sector borders is not fixed but can be defined by oneself if wished for via the color attribute.

== Includes ==

<tt>include</tt> is used to add some flight plan elements defined in an external procedure. It’s useful to include pre-written procedures with only few arguments and then clarify the flight plan.
Here is the structure:
<tt><include name procedure> [<arg name value />]*[<with from to />]*</include></tt>
where <tt>name</tt> attribute of the include element will be used in this flight plan to prefix the blocks of the <tt>procedure</tt>, the XML referenced file.
Named arguments may be given with their value in the <tt>arg</tt> elements. The <tt>with</tt> tag allows to link labels (e.g. attribute of a deroute instruction or of an exception) from the procedure to blocks of the main flight plan.
Then, each block of the procedure is like any block of the flight plan and is designated with a dotted identifier: block <tt>b</tt> of a procedure named <tt>p</tt> is named <tt>b.p</tt> .

Here is an example:
<source lang="xml">
<includes>
<include name="landing" procedure="landing.xml"/>
</includes>
</source>

== Blocks ==

Block elements are the main part of a flight plan: they describe each unit of the mission.
They are made of various primitives, called stages and exceptions, you can put one after the other. When a
stage (or a block) is finished, the autopilot goes to the next one. The behaviour after the last stage of the last block is undefined.

As described in the DTD, the <tt>blocks</tt> element is composed of <tt>block</tt> elements which are sequence of ''stages'':
<source lang="xml">
<!ELEMENT blocks (block+)>
<!ELEMENT block (exception|while|heading|attitude|go|xyz|set|call|circle|deroute|stay|follow|survey_rectangle|for|return|eight|oval|home|path)*>
</source>

Example:
<source lang="xml">
<block name="circlehome">
<circle radius="75" wp="HOME"/>
</block>
</source>

You can add a button in the [[GCS#Strips|strip of the aircraft]] with the attribute <tt>strip_button</tt>:
<source lang="xml">
<block name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
This button will activate the block. If the attribute <tt>group</tt> is specified, all strip buttons of the same group will be placed vertically on top of each other.

In the same way, a key shortcut can be specified:
<source lang="xml">
<block key="D" name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
Modifiers are allowed, using the syntax of [http://library.gnome.org/devel/gtk/2.15/gtk-Keyboard-Accelerators.html#gtk-accelerator-parse GTK accelerators].

An icon can be specified to display the button. The <tt>strip_button</tt> label then is a tooltip for the icon. The icon must be an image file available in the directory <tt>data/pictures/gcs_icons</tt>:
<source lang="xml"><block name="Takeoff" strip_icon="takeoff.png" strip_button="Takeoff"></source>

You can call functions before or after each execution of the block:
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

==== Expressions ====

Most of the numeric attributes in stages are analyzed as C expressions. The syntax of this C expression is restricted to
* numeric constants
* some internal autopilot variables (not fully documented, see examples)
* Some binary operators: <, >, <=, >=, <>, ==, +, -, /, *
* Some utility functions

Some examples of usable expressions are given in the next sections.
=== Initialization Blocks ===
Most flight plans will have three blocks of flight plan initialization blocks. It is good practice to follow this example below if you first start learing to create flightplans

The first block waits until the GPS fix has been established, as shown below.
<source lang="xml">
<blocks>
<block name="Wait GPS">
<set value="1" var="kill_throttle"/>
<while cond="!GpsFixValid()"/>
</block>
</source>
The second block updates the local waypoints with respect to the UAV.
<source lang="xml">
<block name="Geo init">
<while cond="LessThan(NavBlockTime(), 10)"/>
<call fun="NavSetGroundReferenceHere()"/>
</block>
</source>
This next block prevents the UAV from starting the engine and taking off.
<source lang="xml">
<block name="Holding point">

<set value="1" var="kill_throttle"/>
<attitude roll="0" throttle="0" vmode="throttle"/>
</block>
</source>

=== Exceptions ===

The flight manager can handle exceptions. They consist in conditions checked periodically (at the same pace as the navigation control), allowing the control to jump to a given block. Here is the syntax of exceptions:
<source lang="xml"><exception cond="..." deroute="..."></source>
where <tt>cond</tt> is an expression and <tt>deroute</tt> is the name of the block we want to switch to as soon as the condition is true.

Here are some example of exceptions:
<source lang="xml">
<exception cond="10 > PowerVoltage()" deroute="go_down"/>
<exception cond="(ground_alt+10 > GetPosAlt())" deroute="go_up"/>
<exception cond="(autopilot_flight_time > 840)" deroute="quick_land"/>
</source>

Exceptions can be local to a block or global to the flight plan, in the <tt><exceptions></tt> element. In the following example, time since last reception of a message from the ground station is monitored and the navigation is switched to the <tt>Standby</tt> block if no message have been received for 22s. This exception is valid for '''all''' the blocks.
<source lang="xml">
<flight_plan ...>
<waypoints> ... </waypoints>
<exceptions>
<exception cond="datalink_time > 22" deroute="Standby"/>
</exceptions>
<blocks> ...
</source>

=== Deroute ===

The <tt>deroute</tt> is the ''goto'' directive of the flight plan; it switches the navigation to the given block:
<source lang="xml"><deroute block="landing"/></source>

Note that this primitive should not be used to execute loops which are provided by the following elements.

=== Loops ===

Unbounded loops are written with <tt>while</tt> elements whose <tt>cond</tt> attribute is a boolean expression.
Children of <tt>while</tt> are stages:
<source lang="xml">
<while cond="TRUE">
<go wp="A"/>
<go wp="B"/>
<go wp="C"/>
<while cond="5 > stage_time"/>
</while>
</source>
In this example, we run an infinite loop, lettin the aircraft try to go via waypoints <tt>A</tt>, <tt>B</tt> and <tt>C</tt> and waiting for 5 seconds before repeating.

Bounded loops are written with the <tt>for</tt> tag:
<source lang="xml">
<for var="i" from="0" to="3">
...
</for>
</source>
where the body of the loop will be run four times.

The variable of a <tt>for</tt> loop can be used inside expressions appearing as attributes of the stages:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75" alt="ground_alt+50*$i" until="stage_time>10" />
</for>
</source>

In this example, the aircraft will circle around waypoint '''HOME''' for 10 seconds at and altitude above ground of 50m, 10 seconds at altitude 100 meter (50+50), ... until 250m (5x +50).

Note: Two bounded loops using the same control variable are not allowed in the same block.

=== Navigation modes ===

Navigation modes give the description of the desired trajectory in 3D. While the horizontal mode is specified through
''stages'', the vertical control is specified with various attributes of these stages. The current available navigation stages are
* attitude : just keep a fixed attitude;
* heading : keep a given course;
* go : go to a given waypoint;
* path : list of waypoints linked by ''go''
* circle : circle around a waypoint;
* oval : two half circles with a straight between two nav points
* eight : fly a figure of eight through a waypoint and around another
* stay : hold the position (hard to realize for a fixed-wing aircraft);
* follow : follow another aircraft;
* xyz : circle around a point moveable with the RC transmitter stick (obsolete with the datalink).

The vertical control is achieved using the <tt>vmode</tt> attribute of these stages. The possible values are
* '''alt''' (the default) : the autopilot keeps the desired altitude which is the altitude of the waypoint (if any) or the altitude specified with the <tt>alt</tt> attribute;
* '''climb''' : the autopilot keeps the desired vertical speed specified with the <tt>climb</tt> attribute (in m/s);
* '''throttle''' : the autopilots sets the desired throttle specified with the <tt>throttle</tt> attribute (between 0 and 1);
* '''glide''' : the autopilot keeps the desired slope between two waypoints

The default control is done with the throttle. However, setting the <tt>pitch</tt> attribute to '''auto''' and the <tt>throttle</tt> attribute to a constant allows a vertical control only by controlling the attitude of the A/C.
The <tt>pitch</tt> attribute also can be set to any value (in degrees) while the throttle control is in use: it usually affects the airspeed of the aircraft.

The different navigation modes are detailed in the next sections.

=== Attitude ===

Element <tt>attitude</tt> is the navigation mode which corresponds to the current lowest control loop for horizontal mode.
The autopilot then keeps a constant attitude. The <tt>roll</tt> attribute is required (in degrees, positive to put right wing low).

To fly away, at constant airspeed:
<source lang="xml"><attitude roll="0" vmode="throttle", throttle="0.5"/></source>

To fly around, holding a given altitude:
<source lang="xml"><attitude roll="30" alt="ground_alt+50"/></source>

Note that it is not a ''safe'' navigation mode since the geographic position of the plane is not controlled. However, this mode is useful to tune the roll attitude control loop.

=== Heading ===

<tt>heading</tt> primitive is relative to the second level loop for horizontal mode in the autopilot which will keep the given <tt>course</tt>, a required attribute (in degrees, clockwise, north=0, east=90).

One example to takeoff, following the QFU, 80% throttle, nose up (15 degrees) until height of 30m is reached:
<source lang="xml"><heading course="QFU" vmode="throttle" throttle="0.8" pitch="15" until="(GetPosAlt() > ground_alt+30)"/></source>

=== Go ===

The <tt>go</tt> primitive is probably the most useful one. Basically, the autopilot will try to join a given waypoint (<tt>wp</tt>, the only required attribute). So the simplest thing you can ask for is
<source lang="xml"><go wp="HOME"/></source>
which will set the '''HOME''' waypoint as the desired target position. Note than since <tt>vmode="alt"</tt> is the default, the altitude of the target waypoint is also taken into account. The navigation will switch to the next stage as soon as the target is reached.

It is usually not a good idea to try to join a waypoint without asking for a precise trajectory, i.e. a given line.
Setting the <tt>hmode</tt> attribute to '''route''', the navigation will go over a segment joining two waypoints:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route"/></source>

The target altitude is the altitude of the target waypoint; it can also be set with the <tt>alt</tt> attribute. The following example keeps an altitude with fixed throttle:
<source lang="xml"><go from="wp2" wp="wp3" hmode="route" pitch="auto" throttle="0.75" alt="ground_alt+100"/></source>

The attributes related to the vertical control can also be set to replace the default altitude mode:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" vmode="climb" climb="1.5"/></source>

Finally, the <tt>approaching_time</tt> (in seconds) attribute helps to decide when the target is ''reached''. It can be set
to '''0''' to go over the target waypoint (default value is the '''CARROT''' time, set in the airframe configuration file).
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" approaching_time="1"/></source>

=== Path ===

The <tt>path</tt> primitive is just a shorthand expression for a set of <tt>go</tt> primitives. A list of waypoints defined with the <tt>wpts</tt> attribute is pre-processed into a set of <tt>go</tt> primitives with the <tt>hmode</tt> attribute. For example:
<source lang="xml"><path wpts="wp1, wp2, wp3"/></source>

Other attributes are optional:
<source lang="xml"><path wpts="wp3, wp1, wp2" approaching_time="1" pitch="auto" throttle="0.5"/></source>

=== Circle ===

The <tt>circle</tt> primitive is the second main navigation mode: the trajectory is defined as a circle around a given waypoint with a given radius:
<source lang="xml"><circle wp="HOME" radius="75"/></source>
A positive radius makes the UAS move clockwise, a negative counter-clockwise.

The <tt>until</tt> attribute may be used to control the end of the stage. The following example defines an ascending trajectory at constant throttle, nose up (15 degrees), over growing circles, until the battery level is low:
<source lang="xml"><circle wp="wp1" radius="50+(GetPosAlt()-ground_alt)/2" vmode="throttle" throttle="0.75" pitch="15" until="10>PowerVoltage()"/></source>

=== Oval ===
The oval consists of two half circles that are connected with two straight lines. This flight path is usefull when a IMU is used because the straights allow for level flight.
<source lang="xml"> <oval p1="1" p2="2" radius="nav_radius"/> </source>

=== Eight ===
Fly a figure of eight that consists of two straight legs that pass though the center and the center of the half circle at the end of the two legs is in the turn around waypoint. The altitude of the center waypoint is used for the entire figure. The turn around waypoint is moved to match radius given.
<source lang="xml"> <eight center="1" radius="nav_radius" turn_around="2"/> </source>

=== Follow ===

The <tt>follow</tt> is a special primitive which makes the UAS follow another UAS (real or simulated, named with its <tt>ac_id</tt>) at a given <tt>distance</tt> (in meters) behind and at a given <tt>height</tt> (in meters) above.

In this example, the autopilot will try to follow A/C number '''4''', staying '''50'''m behind and '''20'''m above.
<source lang="xml"><follow ac_id="4" distance="50" height="20"/></source>
Note that the <tt>traffic_info.c</tt> file is required by this feature and the <tt>TRAFFIC_INFO</tt> flag has to be set to enable it. Then, the following lines must be added in the airframe file:
<tt>ap.srcs += traffic_info.c</tt>
<tt>ap.CFLAGS += -DTRAFFIC_INFO</tt>
<tt>sim.srcs += traffic_info.c</tt>
<tt>sim.CFLAGS += -DTRAFFIC_INFO</tt>

=== Stay ===

The <tt>stay</tt> is a mode for UAS's able to hover:
<source lang="xml"><stay wp="HOME" alt="10"/></source>

=== XYZ ===

<tt>xyz</tt> is a special mode where the UAS circles around a user moveable waypoint. This waypoint is moved with the RC sticks:
* YAW channel controls the point over the west-east axis;
* PITCH channel controls the point over the south-north axis;
* ROLL channel controls the altitude.

Example (default radius is '''100'''):
<source lang="xml"><xyz radius="40"/></source>

=== Set ===

The <tt>set</tt> element is a dangerous one which should be used only by expert users: it is used to directly set an internal variable of the autopilot. For example, you can change the value of the default ground altitude, a variable used by the home mode failsafe procedure (and maybe by your own flight plan):
<source lang="xml"><set var="ground_alt" value="ground_alt+50"/></source>
This directive is extremely powerful and has great potential for error - use with caution.

=== Call ===

The <tt>call</tt> allows the user to define its own navigation procedures in C. The <tt>value</tt> must be a call to a boolean function which must return TRUE as long as the stage is not completed (a function which should be called only once would then return immediately FALSE).
This feature is illustrated with the '''line''' pattern:
<source lang="xml">
<call fun="nav_line_init()"/>
<call fun="nav_line(WP_1, WP_2, nav_radius)"/>
</source>
where <tt>nav_line_init()</tt> returns FALSE and <tt>nav_line()</tt> always returns TRUE (this stage never ends).
Such functions usually are defined in a supplementary C file which must be specified in the airframe file (in the <tt>makefile</tt> section)
<tt>ap.srcs += nav_line.c
sim.srcs += nav_line.c</tt>
These functions also must be declared in a header file which must be mentioned in the header element of the flight plan:
<source lang="xml">
<header>
#include "nav_line.h"
</header>
</source>
These C source file and H header file must be located in the <tt>sw/airborne</tt> directory.

You can also call functions before or after each execution of the block (this means continually on each iteration of each stage of the block, not just when entering o exiting the block).
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

== Advanced Examples ==
Parameters used in a flight plan can be computed expressions. In this example, the plane is asked to perform 5 circles at progressively increasing altitudes for exactly one minute at each altitude:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75"
alt="ground_alt + 50*$i"
until="stage_time > 60" />
</for>
</source>

=== Immobilize Actuators ===

h_ctl setpoints variable are set by the h_ctl_attitude_loop() (from fw_h_ctl.c) loop) which can be disabled with the
h_ctl_disabled flag:
<source lang="xml">
<set var="h_ctl_disabled" value="TRUE"/>
<set var="h_ctl_aileron_setpoint" value="0"/>
<set var="h_ctl_elevator_setpoint" value="MAX_PPRZ/2"/>
.... waiting for a condition ...
<set var="h_ctl_disabled" value="FALSE"/>
</source>

== Procedures ==

Procedures are libraries which can be included in flight plans. They are composed of waypoints, sectors and blocks. The header of a procedure may contain some parameters which are replaced by arguments when the procedure is included.

Extract of the DTD: a procedure is a sequence of parameters, waypoints, ...:
<source lang="xml"><!ELEMENT procedure (param*,header?,waypoints?,sectors?,exceptions?,blocks?)></source>

A <tt>param</tt>eter is just a name. A parameter is optional if it is declared with a default value.
An example with a required and an optional parameter:
<source lang="xml">
<param name="alt"/>
<param name="radius" default_value="75"/>
</source>

Procedures are called with the <tt>include</tt> element in a flight plan. A procedure cannot be included twice or by another procedure. A procedure call requires:

* the name of the procedure file, the name given to this inclusion;
* values for the parameters;
* backlinks for block name exits of the procedure.

For example:
<source lang="xml"><include name="landing" procedure="landing.xml"/></source>

Here is the corresponding procedure '''landing.xml''':
<source lang="xml">
<!DOCTYPE procedure SYSTEM "flight_plan.dtd">
<procedure>
<waypoints>
<waypoint name="AF" x="177.4" y="45.1" alt="30"/>
<waypoint name="TD" x="28.8" y="57.0" alt="0"/>
<waypoint name="_BASELEG" x="168.8" y="-13.8"/>
</waypoints>
<blocks>
...
<block name="land">
<call fun="nav_compute_baseleg(WP_AF, WP_TD, WP__BASELEG, nav_radius)"/>
<circle radius="nav_radius" until="NavCircleCount() > 0.5" wp="_BASELEG"/>
<circle radius="nav_radius" until="And(NavQdrCloseTo(DegOfRad(baseleg_out_qdr)-10), 10 > fabs(GetPosAlt()- WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
</block>
...
</blocks>
</procedure>
</source>

Note that the name of procedure '''land''' block will be renamed into '''landing.land''':
<source lang="xml"><deroute block="landing.land"/></source>
will jump to this procedure block.

Suppose you have a go-around condition in your landing procedure. You would write it
<source lang="xml"><exception cond="..." deroute="go-around"/></source>
then you must link this block exit with one of your block (e.g. <tt>Standby</tt>). So you would include the procedure as follows:
<source lang="xml">
<include name="landing" procedure="landing.xml">
<with from="go-around" to="Standby"/>
</include>
</source>

== Tips and Tricks ==

There are many ways to skin a cat just as there are many ways to craft your flight plan. Following the best practices tips can save you from a lot of frustration and mishap.

* Simulate your flight plan before taking it to the sky. Flight plans should always be carefully tested prior to flight, take a look at the [[Simulation|simulation]] page for details on how to simulate your plan.
* Make an subdirectory in the Flight_plan directory with your own name and add your flight plans there. Make sure that the location of the DTD is correct, e.g by using relative directory double dots as in <tt><!DOCTYPE flight_plan SYSTEM "../flight_plan.dtd"></tt>

* Take a good look at other flight plans included with Paparazzi. To learn from example flight plans please visit the [[Flight_Plan_Examples|flight plan examples]] page
* There are several option to build failsafe features into you flightplan, [[Failsafe|for some examples visit the Failsafe page]].
* Some flight plan examples define waypoint locations using relative coordinates. These are relative positions from the fixed lat and lon in the header of the flight plan. When simulating your flight plan the aircraft always use the lat/lon as defined in the flight plan since a regular simulation has no notion of you current position of you local PC where you simulate on. This is something to keep in mind if you test your flight plan in real flights.

[[Category:Software]] [[Category:User_Documentation]]

Rotorcraft Configuration

2014-06-05T02:30:38Z

Alonsoac: /* Autopilot modes */ details on horiz guidance for hover modes

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Airframe_Configuration</categorytree>
This page describes configuration options <span style="color:red"><b>specific to the rotorcraft firmware</b></span> in the [[Airframe_Configuration|airframe file]].

== Firmware and Hardware definitions ==

This is one example of a pretty standard quadcopter firmware definition:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
<target name="nps" board="pc">
<subsystem name="fdm" type="jsbsim"/>
</target>
<target name="ap" board="lisa_m_1.0"/>

<subsystem name="radio_control" type="ppm"/>
<subsystem name="telemetry" type="transparent"/>
<subsystem name="actuators" type="mkk"/>
<subsystem name="imu" type="aspirin_v1.5"/>
<subsystem name="gps" type="ublox"/>
<subsystem name="ahrs" type="int_cmpl_quat"/>
<subsystem name="stabilization" type="int_quat"/>
</firmware>
</source>
}}

=== Select your Board ===
Make sure you use the <b>rotorcraft [[Airframe_Configuration#Firmware|firmware]]</b> and choose the correct board, e.g.

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
<target name="sim" board="pc"/> 
<target name="ap" board="lisa_m_2.0"/> 
...
</firmware>
</source>
}}

The ap board name can be found in /conf/boards.

=== Actuators ===
You have to specify which ESCs you have by adding the appropriate [[Subsystem/actuators|actuators subsystem.]]
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
<target name="ap" board="booz_1.0"/>
...
<subsystem name="actuators" type="mkk"/>
</firmware>
</source>
}}

=== Control Loops ===
See the [[Subsystem/stabilization|stabilization subsystem]] page to choose which attitude control algorithm to use and how to configure them.

The [[Control Loops]] page has some diagrams.

=== INS ===
The INS (Integrated Navigation System) subsystem contains estimations filter to e.g. fuse GPS and IMU data for better position and speed estimates.
The INS subsystem is optional in <= v4.2.

Since v4.9x the INS subsystem is mandatory, to use the same as in v4.2 omit the type.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
<target name="ap" board="booz_1.0"/>
...
<subsystem name="ins"/>
</firmware>
</source>
}}
You can also compensate for GPS lag in hff (horizontal filter float) if it is known (in seconds):
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
<target name="ap" board="booz_1.0"/>
...
<subsystem name="ins" type="hff">
<define name="GPS_LAG=0.2"/>
</subsystem>
</firmware>
</source>
}}

== Motor Arming ==
By default the motors are armed with zero-throttle and full yaw. The motors are never started if AHRS is not aligned (disable it with AUTOPILOT_DISABLE_AHRS_KILL).

Other arming sequences can be configured:
* USE_KILL_SWITCH_FOR_MOTOR_ARMING defined (to 1):
** switch kill switch off to arm the motors
** if kill switch is off during startup, you need to kill again first, then unkill to start
** throttle needs to be down, other sticks centered to start motors
** need to be in manual mode to start the motors

* USE_THROTTLE_FOR_MOTOR_ARMING defined (to 1):
** automatically start motors when applying throttle
** if throttle was not down at startup, you need to put throttle down again first
** other sticks need to be centered to start motors
** need to be in manual mode to start the motors

== Autopilot modes ==
For rotorcrafts we have a lot of different modes that can be mapped to your 3-position switch (Manual, Auto1, Auto2).
The horizontal and vertical mode can be set differently as the following possible modes indicate (in parenthesis are the abbreviations displayed in the [[GCS#Strips|GCS]] strip).

'''Limiting max thrust via RC'''<br>
Modes with 'automatic' thrust control (e.g. x_Z_HOLD and NAV) let you limit the maximum thrust via RC by default. So you should push your throttle stick up after entering such a mode so the vertical controller has some "room" to stabilize the altitude. Should something weird happen you can limit the max thrust by taking throttle back.<br> You can turn this behavior off by defining '''NO_RC_THRUST_LIMIT'''

; AP_MODE_FAILSAFE (SAFE) :
This is a failsafe mode that gets triggered if:
* RC signal is lost (and you are not in KILL or NAV mode)
* GPS and RC is lost in NAV mode
The standard behaviour is that autopilot will level the rotorcraft out (setpoints to zero pitch and roll angles) and descend at 0.5m/s downwards. But this behavior can also be changed to something else ofcourse.

; AP_MODE_KILL (KILL) :
Motors are simply switched off.

; AP_MODE_RATE_DIRECT (RATE) :
This is basically the "most" manual mode you can get. You control not the attitude (roll and pitch angles) but the rotation rate. You also set the throttle directly with your RC.

; AP_MODE_ATTITUDE_DIRECT (ATT) :
You control the attitude (roll, pitch and yaw angles), but the throttle directly proportional to your stick position.

; AP_MODE_RATE_RC_CLIMB (R_RCC) :
You control the rotation rate and the vertical speed according to your throttle stick position.<br>If you have your throttle stick in the middle position, the altitude is kept, down goes down at a speed proportional to your stick position (same for up). In this mode it makes sense to mount the spring for your throttle stick so it can recenter itself.

; AP_MODE_ATTITUDE_RC_CLIMB (A_RCC) :
You control the attitude (roll, pitch and yaw angles) and the vertical speed according to your throttle stick position.<br>If you have your throttle stick in the middle position the altitude is kept, if you move the stick down it goes down at a speed proportional to your stick position (same for up). In this mode it makes sense to mount the spring for your throttle stick so it recenter itself.

; AP_MODE_ATTITUDE_CLIMB (ATT_C) :
You control the attitude (roll, pitch and yaw angles) and the vertical speed. The vertical speed is set via fms (e.g. joystick).

; AP_MODE_RATE_Z_HOLD (R_ZH) :
You control the rotation rate and it holds the altitude you were at when entering this mode.<br>Your throttle stick position still limits the max throttle authority unless disabled with NO_RC_THRUST_LIMIT.

; AP_MODE_ATTITUDE_Z_HOLD (A_ZH) :
You control the attitude (roll, pitch and yaw angles) and it holds the altitude you were at when entering this mode.<br>Your throttle stick position still limits the max throttle authority unless disabled with NO_RC_THRUST_LIMIT.

; AP_MODE_HOVER_DIRECT (HOVER) :
The rotorcraft hovers at the horizontal position you were at when entering this mode (position control). You still set the throttle directly with your RC. Yaw command on the RC allows for heading change. If USE_SPEED_REF=1 then pitch and roll commands in the RC control speed according to max speed set with REF_MAX_SPEED in the GUIDANCE_H section of airframe file.

; AP_MODE_HOVER_CLIMB (HOV_C) :
The rotorcraft hovers at the position you were at when entering this mode (position control). RC commands work the same as in HOVER mode. The vertical speed is set via fms (e.g. joystick).

; AP_MODE_HOVER_Z_HOLD (H_ZH):
The rotorcraft hovers at the 3D position you were at when entering this mode (position and altitude control). RC commands work the same as in HOVER mode. <br>Your throttle stick position still limits the max throttle authority unless disabled with NO_RC_THRUST_LIMIT.

; AP_MODE_NAV (NAV) :
Full navigation mode. The rotorcraft follows your flightplan.<br>If you have a valid RC signal, your throttle stick position still limits the max throttle authority unless disabled with NO_RC_THRUST_LIMIT.

; AP_MODE_RC_DIRECT (RC_D) :
Safety pilot direct commands for helicopter.

; AP_MODE_CARE_FREE_DIRECT (CF):
Safety pilot direct commands for helicopter, but the roll and pitch commands are based on the yaw angle when entering this mode.

== XML Parameters ==

=== Mode ===
In the mode section you can set the autopilot modes associated with your 3-way mode switch on your RC.
<source lang="xml">
<section name="MODE" prefix="MODE_">
<define name="MANUAL" value="AP_MODE_ATTITUDE_DIRECT" />
<define name="AUTO1" value="AP_MODE_ATTITUDE_Z_HOLD" />
<define name="AUTO2" value="AP_MODE_NAV" />
</section>
</source>

=== Commands ===

The <b><tt>commands</tt></b> lists the abstract commands you need to control the aircraft. For most multicopter you just need:
<source lang="xml">
<commands>
<axis name="PITCH" failsafe_value="0"/>
<axis name="ROLL" failsafe_value="0"/>
<axis name="YAW" failsafe_value="0 />
<axis name="THRUST" failsafe_value="0"/>
</commands>
</source>

Each command is also associated with a failsafe value which will be used if no controller is active, for example during initialization of the autopilot board.

=== Motor Mixing ===

This section describes the "mixing" used for your particular multirotor configuration. This section is needed for all ESCs except "asctec_v1" wich do their mixing themselves.

<div class="toccolours mw-collapsible mw-collapsed" style="width:800px">
Used since '''v5.0''', for previous version see [[Rotorcraft_Configuration#Supervision|Supervision]].
<div class="mw-collapsible-content">Differences with the older supervision (used prior to '''v4.9_devel-164-gdb0d004'''):
* names: SUPERVISION -> MOTOR_MIXING
* independent of the actuators, needs to be loaded in the subsystems and call in the command_laws section
* internal values have '''pprz''' format (int16, between [-9600; 9600])
* min and max are not needed, coming from the servos definition
* trim are renamed with more explicit names
</div></div>

This subsystem takes ''roll'', ''pitch'', ''yaw'' and ''thrust'' commands as inputs and "mixes" them to get the final commands for your individual motors according to the layout of them. See [[RotorcraftMixing]] for the details behind this.

Note that after mixing the separate motor commands can "saturate", meaning you can't simply give negative thrust or more than the maximum. If a saturation is reached (desired motor command outside of possible MIN_MOTOR/MAX_MOTOR range), a saturation offset is applied to all motors in order to give attitude commands a higher priority than thrust. This offset is limited to ''MOTOR_MIXING_MAX_SATURATION_OFFSET'' (default is 10% of maximum command).

See also [https://github.com/paparazzi/paparazzi/issues/385 issue #385].

In '''firmware''' section:
<source lang="xml">
<subsystem name="motor_mixing"/>
</source>

Configuration of the motor mixing:
<source lang="xml">
<section name="MIXING" prefix="MOTOR_MIXING_">
<define name="TRIM_ROLL" value="0"/>
<define name="TRIM_PITCH" value="0"/>
<define name="TRIM_YAW" value="0"/>
<define name="NB_MOTOR" value="4"/>
<define name="SCALE" value="256"/>
<define name="ROLL_COEF" value="{ 0 , 0, 256, -256 }"/>
<define name="PITCH_COEF" value="{ 256, -256, 0, 0 }"/>
<define name="YAW_COEF" value="{ -256, -256, 256, 256 }"/>
<define name="THRUST_COEF" value="{ 256, 256, 256, 256 }"/>
</section>
</source>

; ''TRIM_ROLL'' : trim added to roll command
; ''TRIM_PITCH'' : trim added to pitch command
; ''TRIM_YAW'' : trim added to yaw command
; x''_COEF'' : roll/pitch/yaw/thrust coefficients, see [[RotorcraftMixing]] for details or the examples below

In '''command_laws''' section (placed after section MIXING):
<source lang="xml">
<command_laws>
<call fun="motor_mixing_run(autopilot_motors_on, FALSE, values)"/>
<set servo="FRONT" value="motor_mixing.commands[0]/>
<set servo="BACK" value="motor_mixing.commands[1]/>
<set servo="RIGHT" value="motor_mixing.commands[2]/>
<set servo="LEFT" value="motor_mixing.commands[3]/>
</command_laws>
</source>

==== Mixing Examples ====

Hint: If your rotors are spinning '''opposite''' to the '''direction''' shown in the picture, '''reverse signs''' in the YAW_COEF line.

; Plus Cross : [[Image:cross_plus_simple.png|200px]]
Assuming that the order of motors, described in the "servos" section is FRONT, BACK, LEFT, RIGHT.
<source lang="xml">
<define name="ROLL_COEF" value="{ 0, 0, 256, -256 }"/>
<define name="PITCH_COEF" value="{ 256, -256, 0, 0 }"/>
<define name="YAW_COEF" value="{ -256, -256, 256, 256 }"/>
<define name="THRUST_COEF" value="{ 256, 256, 256, 256 }"/>
</source>

; Time Cross : [[Image:cross_time_simple.png|200px]]
Assuming that the order of motors, described in the "servos" section is NE, SE, SW, NW.
<source lang="xml">
<define name="ROLL_COEF" value="{ -256, -256, 256, 256 }"/>
<define name="PITCH_COEF" value="{ 256, -256, -256, 256 }"/>
<define name="YAW_COEF" value="{ -256, 256, -256, 256 }"/>
<define name="THRUST_COEF" value="{ 256, 256, 256, 256 }"/>
</source>

; Octo (time cross): [[Image:octo.jpg|border|200px]]
<source lang="xml">
<define name="ROLL_COEF" value="{ 106, -106, -256, -256, -106, 106, 256, 256 }"/>
<define name="PITCH_COEF" value="{ 256, 256, 106, -106, -256, -256, -106, 106 }"/>
<define name="YAW_COEF" value="{ -256, 256, -256, 256, -256, 256, -256, 256 }"/>
<define name="THRUST_COEF" value="{ 256, 256, 256, 256, 256, 256, 256, 256 }"/>
</source>

; Octo (plus cross): rotor 1 on x-axis (image anyone?)
<source lang="xml">
<define name="ROLL_COEF" value="{ 0, -181, -256, -181, 0, 181, 256, 181 }"/>
<define name="PITCH_COEF" value="{ 256, 181, 0, -181, -256, -181, 0, 181 }"/>
<define name="YAW_COEF" value="{ -256, 256, -256, 256, -256, 256, -256, 256 }"/>
<define name="THRUST_COEF" value="{ 256, 256, 256, 256, 256, 256, 256, 256 }"/>
</source>

If you want to compute mixing for a special configuration, please see the [[RotorcraftMixing]] page.

=== Supervision ===
<div class="toccolours mw-collapsible mw-collapsed">
Prior to '''v5.0''' motor mixing was called supervision. Click expand to see the details.
<div class="mw-collapsible-content">
Valid before '''v4.9_devel-164-gdb0d004'''

<source lang="xml">
<section name="SUPERVISION" prefix="SUPERVISION_">
<define name="STOP_MOTOR" value="0"/> 
<define name="MIN_MOTOR" value="3"/>
<define name="MAX_MOTOR" value="200"/>
<define name="TRIM_A" value="0"/>
<define name="TRIM_E" value="0"/>
<define name="TRIM_R" value="0"/>
<define name="NB_MOTOR" value="4"/>
<define name="SCALE" value="256"/>
<define name="ROLL_COEF" value="{ 0 , 0, 256, -256 }"/>
<define name="PITCH_COEF" value="{ 256, -256, 0, 0 }"/>
<define name="YAW_COEF" value="{ -256, -256, 256, 256 }"/>
<define name="THRUST_COEF" value="{ 256, 256, 256, 256 }"/>
</section>
</source>

; ''STOP_MOTOR'' : actuator specific command value to stop the motors
; ''MIN_MOTOR'' : actuator specific command value for idling motors
; ''MAX_MOTOR'' : actuator specific command value for maximum power
; ''TRIM_A'' : trim added to roll command
; ''TRIM_E'' : trim added to pitch command
; ''TRIM_R'' : trim added to yaw command
; x''_COEF'' : roll/pitch/yaw/thrust coefficients, see [[RotorcraftMixing]] for details or the examples in the above Motor Mixing section
</div>
</div>

=== Guidance ===
There are two sets of parameters for guidance: vertical (altitude) and horizontal (position).

==== vertical guidance ====
<source lang="xml">
<section name="GUIDANCE_V" prefix="GUIDANCE_V_">
<define name="HOVER_KP" value="150"/>
<define name="HOVER_KD" value="80"/>
<define name="HOVER_KI" value="20"/>


<define name="NOMINAL_HOVER_THROTTLE" value="0.5"/>
<define name="ADAPT_THROTTLE_ENABLED" value="TRUE"/>
<define name="REF_MIN_ZD" value="-3.0" unit="m/s"/>
<define name="REF_MAX_ZD" value="3.0" unit="m/s"/>
<define name="MAX_RC_CLIMB_SPEED" value="-3.0" unit="m/s"/>
<define name="MAX_RC_DESCENT_SPEED" value="3.0" unit="m/s"/>
</section>
</source>

; ''HOVER_K''x : PID parameters for vertical hover control loop
; ''NOMINAL_HOVER_THROTTLE'' : expected throttle percentage needed for hovering (default is 0.4 = 40%)
; ''ADAPT_THROTTLE_ENABLED'' : enable adaptive nominal hover throttle estimation (default is TRUE, set to FALSE to disable)
; ''REF_MIN_ZD'' : vertical speed reference lower limit (since z-down is positive -> max speed upwards) (default -3.0m/s)
; ''REF_MAX_ZD'' : vertical speed reference upper limit (since z-down is positive -> max speed downwards) (default 3.0m/s)
; ''MAX_RC_CLIMB_SPEED'' : climb speed at max RC input in RC_CLIMB mode (default is ''REF_MIN_ZD'')
; ''MAX_RC_DESCENT_SPEED'' : descent speed at max RC input in RC_CLIMB mode (default is ''REF_MAX_ZD'')

==== horizontal guidance ====
<source lang="xml">
<section name="GUIDANCE_H" prefix="GUIDANCE_H_">
<define name="PGAIN" value="50"/>
<define name="DGAIN" value="100"/>
<define name="IGAIN" value="20"/>


<define name="AGAIN" value="0"/>
<define name="VGAIN" value="0"/>

<define name="MAX_BANK" value="20" unit="deg"/>
<define name="USE_SPEED_REF" value="TRUE"/>
<define name="REF_MAX_SPEED" value="5.0" unit="m/s"/>
<define name="REF_MAX_ACCEL" value="5.66" unit="m/s2"/>
<define name="REF_OMEGA" value="67" unit="deg"/>
<define name="REF_ZETA" value="0.85"/>
<define name="REF_TAU" value="0.5"/>
<define name="APPROX_FORCE_BY_THRUST" value="FALSE"/>
</section>
</source>

; [PID]''GAIN'' : PID gains for horizontal control
; ''AGAIN'' : acceleration feedforward gain (default 0)
; ''VGAIN'' : velocity feedforward gain (default 0)
; ''MAX_BANK'' : maximum roll/pitch angle that is set from horizontal guidance (default 20deg, max 40deg)
; ''USE_SPEED_REF'' : since v5.1, give velocity commands via RC in GUIDANCE_H_MODE_HOVER (default: TRUE)
; ''REF_MAX_SPEED'' : maximum reference horizontal speed in m/s (default 5.0m/s)
; ''REF_MAX_ACCEL'' : maximum reference horizontal acceleration in m/s² (default tanf(RadOfDeg(30.))*9.81 = 5.66)
; ''REF_OMEGA'' : second order model natural frequency
; ''REF_ZETA'' : second order model damping
; ''REF_TAU'' : first order time constant
; ''APPROX_FORCE_BY_THRUST'' : try to better approximate force commands by taking thrust into account (default FALSE, set to TRUE to use it)

=== Simulation ===
See [[NPS]] (New Paparazzi Sim).

[[Category:Airframe_Configuration]] [[Category:User_Documentation]] [[Category:Rotorcraft]]

Module/GPS UBlox UCenter

2014-06-03T02:52:01Z

Alonsoac: /* Debug */

__TOC__
<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Modules</categorytree>
If you use a µ-blox GPS without flash memory, this module will take over the task of initializing the GPS for you when you power your autopilot.

It has auto-baudrate to detect the current GPS baudrate, and configures all message rates and communication ports. The module will send a DEBUG message (ID 26) that indicates the firmware version in your GPS, the previous baudrate, and the reply for each configuration step. To enable and view the message, you will need to define DEBUG_GPS_UBX_UCENTER as TRUE in your [[Airframe_Configuration|airframe configuration]] file and select to receive that message in your [[Telemetry|telemetry]] file. See the example below for more details.

It will configure the following settings:
* set baudrate to GPS_BAUD (typically either 38400 or 57600)
* enable the NAV_POSLLH, NAV_VELNED, NAV_STATUS, NAV_SVINFO, NAV_SOL
* disable UTM on old Lea4P by not sending NAV_POSUTM
* enable SBAS
* configure it to 3D only fix
* set the internal dynamic model to Airborne 2G

== Basic ==

Add the gps_ubx_ucenter [[Modules|module]] to the "modules" section in your aircraft configuration file:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
...
<load name="gps_ubx_ucenter.xml"/>
</modules>
</source>
}}

== Advanced ==

You can specify to a different dynamic model for the u-blox.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
...
<load name="gps_ubx_ucenter.xml">
<define name="GPS_UBX_NAV5_DYNAMICS" value="NAV5_DYN_PORTABLE" />
</load>
</modules>
</source>
}}

'''Additional details on GPS_UBX_NAV5_DYNAMICS'''

The ublox GPS uses a dynamics model (motion model) to filter the noisy GPS readings and produce smoother results. The dynamics
model will affect what positions and speeds are accurately tracked by GPS. Generally, it is recommend to use NAV5_DYN_PORTABLE for quadcopters and NAV5_DYN_AIRBORNE_2G for fixed wings.

The follow is taken from the ublox protocol specification document:

u-blox positioning technology supports different dynamic platform models to adjust the navigation engine to
the expected application environment. These platform settings can be changed dynamically without performing
a power cycle or reset. The settings improve the receiver's interpretation of the measurements and thus provide
a more accurate position output. Setting the receiver to an unsuitable platform model for the given application
environment results in a loss of receiver performance and position accuracy.

{| border="1"
|+ '''Dynamic Platform Model'''
|-
! scope="row" | NAV5_DYN_PORTABLE
| Applications with low acceleration, e.g. portable devices. Suitable for most situations. MAX Altitude [m]: 12000, MAX Velocity [m/s]: 310, MAX Vertical Velocity [m/s]: 50, Sanity check type: Altitude and Velocity, Max Position Deviation: Medium
|-
! scope="row" | NAV5_DYN_STATIONARY
| Used in timing applications (antenna must be stationary) or other stationary applications. Velocity restricted to 0 m/s. Zero dynamics assumed. MAX Altitude [m]: 9000, MAX Velocity [m/s]: 10, MAX Vertical Velocity [m/s]: 6, Sanity check type: Altitude and Velocity, Max Position Deviation: Small
|-
! scope="row" | NAV5_DYN_PEDESTRIAN
| Applications with low acceleration and speed, e.g. how a pedestrian would move. Low acceleration assumed. MAX Altitude [m]: 9000, MAX Velocity [m/s]: 30, MAX Vertical Velocity [m/s]: 20, Sanity check type: Altitude and Velocity, Max Position Deviation: Small
|-
! scope="row" | NAV5_DYN_AUTOMOTIVE
| Used for applications with equivalent dynamics to those of a passenger car. Low vertical acceleration assumed. MAX Altitude [m]: 6000 (5000 for firmware versions 6.00 and below), MAX Velocity [m/s]: 84 (62 for firmware versions 4.00 to 5.00), MAX Vertical Velocity [m/s]: 15, Sanity check type: Altitude and Velocity, Max Position Deviation: Medium
|-
! scope="row" | NAV5_DYN_SEA
| Recommended for applications at sea, with zero vertical velocity. Zero vertical velocity assumed. Sea level assumed. MAX Altitude [m]: 500, MAX Velocity [m/s]: 25, MAX Vertical Velocity [m/s]: 5, Sanity check type: Altitude and Velocity, Max Position Deviation: Medium
|-
! scope="row" | NAV5_DYN_AIRBORNE_1G
| Used for applications with a higher dynamic range and vertical acceleration than a passenger car. No 2D position fixes supported. MAX Altitude [m]: 50000, MAX Velocity [m/s]: 100, MAX Vertical Velocity [m/s]: 100, Sanity check type: Altitude, Max Position Deviation: Large
|-
! scope="row" | NAV5_DYN_AIRBORNE_2G
| Recommended for typical airborne environment. No 2D position fixes supported. MAX Altitude [m]: 50000, MAX Velocity [m/s]: 250, MAX Vertical Velocity [m/s]: 100, Sanity check type: Altitude, Max Position Deviation: Large
|-
! scope="row" | NAV5_DYN_AIRBORNE_4G
| Only recommended for extremely dynamic environments. No 2D position fixes supported. MAX Altitude [m]: 50000, MAX Velocity [m/s]: 500, MAX Vertical Velocity [m/s]: 100, Sanity check type: Altitude, Max Position Deviation: Large
|}

== Debug ==

You can specify to receive a DEBUG message over telemetry. Make changes to both the airframe and telemetry config files.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
...
<load name="gps_ubx_ucenter.xml">
<define name="GPS_UBX_NAV5_DYNAMICS" value="NAV5_DYN_PORTABLE" />
<define name="DEBUG_GPS_UBX_UCENTER" value="TRUE" />
</load>
</modules>
</source>
}}

{{Box Code|conf/telemetry/myplane.xml|
<source lang="xml">
<mode name="default">
...
<message name="DEBUG" period="0.5"/>
</mode>
</source>
}}

The debug messages has the following information:
* [0] Initial baudrate high
* [1] Initial baudrate low. For example if the baud rate is 9600 you will see 9,6
* [2] ublox software verision high
* [3] ublox software version low
* [4] ublox hardware version high
* [5] ublox hardware version low
* [6] Always 0
* [7] Success of setting CFG-NAV5. For all of these a value of 0 indicates no response, 1 is success and 2 is command rejected by GPS.
* [8] Success of enable NAV-POSLLH
* [9] Success of enable NAV-VELNED
* [10] Success of enable NAV-STATUS
* [11] Success of enable NAV-SVINFO
* [12] Success of enable NAV-SOL
* [13] Success of disabling NAV-POSUTM (typically fails to 0 for non LEA-4P modules)
* [14] Success of enable SBAS
* [15] Success of setting CFG-RATE
* [16] Success of setting RXM-RAW (typically disabled - see USE_GPS_UBX_RXM_RAW flag to enable)
* [17] Success of setting RXM-SFRB (typically disabled - see USE_GPS_UBX_RXM_SFRB flag to enable)
* [18] Success of saving configuration to ublox memory

If you get all zeroes then check cabling and try again. Make sure RX from the GPS is connected to TX on the autopilot.

[[Category:User_Documentation]] [[Category:Modules]]

Module/GPS UBlox UCenter

2014-06-03T02:12:58Z

Alonsoac: /* Debug */ some clarifications and tips

__TOC__
<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Modules</categorytree>
If you use a µ-blox GPS without flash memory, this module will take over the task of initializing the GPS for you when you power your autopilot.

It has auto-baudrate to detect the current GPS baudrate, and configures all message rates and communication ports. The module will send a DEBUG message (ID 26) that indicates the firmware version in your GPS, the previous baudrate, and the reply for each configuration step. To enable and view the message, you will need to define DEBUG_GPS_UBX_UCENTER as TRUE in your [[Airframe_Configuration|airframe configuration]] file and select to receive that message in your [[Telemetry|telemetry]] file. See the example below for more details.

It will configure the following settings:
* set baudrate to GPS_BAUD (typically either 38400 or 57600)
* enable the NAV_POSLLH, NAV_VELNED, NAV_STATUS, NAV_SVINFO, NAV_SOL
* disable UTM on old Lea4P by not sending NAV_POSUTM
* enable SBAS
* configure it to 3D only fix
* set the internal dynamic model to Airborne 2G

== Basic ==

Add the gps_ubx_ucenter [[Modules|module]] to the "modules" section in your aircraft configuration file:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
...
<load name="gps_ubx_ucenter.xml"/>
</modules>
</source>
}}

== Advanced ==

You can specify to a different dynamic model for the u-blox.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
...
<load name="gps_ubx_ucenter.xml">
<define name="GPS_UBX_NAV5_DYNAMICS" value="NAV5_DYN_PORTABLE" />
</load>
</modules>
</source>
}}

'''Additional details on GPS_UBX_NAV5_DYNAMICS'''

The ublox GPS uses a dynamics model (motion model) to filter the noisy GPS readings and produce smoother results. The dynamics
model will affect what positions and speeds are accurately tracked by GPS. Generally, it is recommend to use NAV5_DYN_PORTABLE for quadcopters and NAV5_DYN_AIRBORNE_2G for fixed wings.

The follow is taken from the ublox protocol specification document:

u-blox positioning technology supports different dynamic platform models to adjust the navigation engine to
the expected application environment. These platform settings can be changed dynamically without performing
a power cycle or reset. The settings improve the receiver's interpretation of the measurements and thus provide
a more accurate position output. Setting the receiver to an unsuitable platform model for the given application
environment results in a loss of receiver performance and position accuracy.

{| border="1"
|+ '''Dynamic Platform Model'''
|-
! scope="row" | NAV5_DYN_PORTABLE
| Applications with low acceleration, e.g. portable devices. Suitable for most situations. MAX Altitude [m]: 12000, MAX Velocity [m/s]: 310, MAX Vertical Velocity [m/s]: 50, Sanity check type: Altitude and Velocity, Max Position Deviation: Medium
|-
! scope="row" | NAV5_DYN_STATIONARY
| Used in timing applications (antenna must be stationary) or other stationary applications. Velocity restricted to 0 m/s. Zero dynamics assumed. MAX Altitude [m]: 9000, MAX Velocity [m/s]: 10, MAX Vertical Velocity [m/s]: 6, Sanity check type: Altitude and Velocity, Max Position Deviation: Small
|-
! scope="row" | NAV5_DYN_PEDESTRIAN
| Applications with low acceleration and speed, e.g. how a pedestrian would move. Low acceleration assumed. MAX Altitude [m]: 9000, MAX Velocity [m/s]: 30, MAX Vertical Velocity [m/s]: 20, Sanity check type: Altitude and Velocity, Max Position Deviation: Small
|-
! scope="row" | NAV5_DYN_AUTOMOTIVE
| Used for applications with equivalent dynamics to those of a passenger car. Low vertical acceleration assumed. MAX Altitude [m]: 6000 (5000 for firmware versions 6.00 and below), MAX Velocity [m/s]: 84 (62 for firmware versions 4.00 to 5.00), MAX Vertical Velocity [m/s]: 15, Sanity check type: Altitude and Velocity, Max Position Deviation: Medium
|-
! scope="row" | NAV5_DYN_SEA
| Recommended for applications at sea, with zero vertical velocity. Zero vertical velocity assumed. Sea level assumed. MAX Altitude [m]: 500, MAX Velocity [m/s]: 25, MAX Vertical Velocity [m/s]: 5, Sanity check type: Altitude and Velocity, Max Position Deviation: Medium
|-
! scope="row" | NAV5_DYN_AIRBORNE_1G
| Used for applications with a higher dynamic range and vertical acceleration than a passenger car. No 2D position fixes supported. MAX Altitude [m]: 50000, MAX Velocity [m/s]: 100, MAX Vertical Velocity [m/s]: 100, Sanity check type: Altitude, Max Position Deviation: Large
|-
! scope="row" | NAV5_DYN_AIRBORNE_2G
| Recommended for typical airborne environment. No 2D position fixes supported. MAX Altitude [m]: 50000, MAX Velocity [m/s]: 250, MAX Vertical Velocity [m/s]: 100, Sanity check type: Altitude, Max Position Deviation: Large
|-
! scope="row" | NAV5_DYN_AIRBORNE_4G
| Only recommended for extremely dynamic environments. No 2D position fixes supported. MAX Altitude [m]: 50000, MAX Velocity [m/s]: 500, MAX Vertical Velocity [m/s]: 100, Sanity check type: Altitude, Max Position Deviation: Large
|}

== Debug ==

You can specify to receive a DEBUG message over telemetry. Make changes to both the airframe and telemetry config files.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
...
<load name="gps_ubx_ucenter.xml">
<define name="GPS_UBX_NAV5_DYNAMICS" value="NAV5_DYN_PORTABLE" />
<define name="DEBUG_GPS_UBX_UCENTER" value="TRUE" />
</load>
</modules>
</source>
}}

{{Box Code|conf/telemetry/myplane.xml|
<source lang="xml">
<mode name="default">
...
<message name="DEBUG" period="0.5"/>
</mode>
</source>
}}

The debug messages has the following information:
* [0] Initial baudrate high
* [1] Initial baudrate low. For example if the baud rate is 9600 you will see 9,6
* [2] ublox software verision high
* [3] ublox software version low
* [4] ublox hardware version high
* [5] ublox hardware version low
* [6] Always 0
* [7] Success of setting CFG-NAV5
* [8] Success of enable NAV-POSLLH
* [9] Success of enable NAV-VELNED
* [10] Success of enable NAV-STATUS
* [11] Success of enable NAV-SVINFO
* [12] Success of enable NAV-SOL
* [13] Success of disabling NAV-POSUTM (typically fails to 0 for non LEA-4P modules)
* [14] Success of enable SBAS
* [15] Success of setting CFG-RATE
* [16] Success of setting RXM-RAW (typically disabled - see USE_GPS_UBX_RXM_RAW flag to enable)
* [17] Success of setting RXM-SFRB (typically disabled - see USE_GPS_UBX_RXM_SFRB flag to enable)
* [18] Success of saving configuration to ublox memory

If you get all zeroes then check cabling and try again. Make sure RX from the GPS is connected to TX on the autopilot.

[[Category:User_Documentation]] [[Category:Modules]]

Flight Plans

2014-05-13T01:19:16Z

Alonsoac: /* Sectors */ typo

A '''flight plan''' is a XML document which one can create and store aboard an autopilot. The flight plan will describe how you want your aircraft to travel if released into into the wild blue yonder.

== DTD and Structure ==

The formal description of the flight plan file is given in the [http://en.wikipedia.org/wiki/Document_Type_Definition '''DTD'''] (located in <tt>conf/flight_plans/flight_plan.dtd</tt>). This
DTD must be referenced in the header of your flight plan XML document using the following line:<br>

<source lang="xml"><!DOCTYPE flight_plan SYSTEM "flight_plan.dtd"></source>

The flight plans are stored in the <tt>conf/flight_plans</tt> directory. The [[Flight_Plan_Editor|flight plan editor]] can be used to create basic flight plans via the GUI.

Extract from the [http://en.wikipedia.org/wiki/Document_Type_Definition DTD]:
<tt><!ELEMENT flight_plan (header?,waypoints,sectors?,include*,exceptions?,blocks)></tt>

'''A flight plan is composed of two mandatory elements: [[#waypoints|waypoints]] and [[#blocks|blocks]]'''

The root <tt>flight_plan</tt> element is specified with several attributes:
<tt>'''<flight_plan name lat0 lon0 ground_alt security_height home_mode_height qfu alt max_dist_from_home>'''</tt>
; <tt>'''name'''</tt>: The name of the mission (a text string)
; <tt>'''lat0, lon0'''</tt>: Defines the latitude and longitude coordinates of the reference point {0,0} in WGS84 degree coordinates
; <tt>'''ground_alt'''</tt>: The ground altitude (in meters), Above Sea Level where you are flying. It defines the <tt>GROUND_ALT</tt> constant value which can be used in combination with a waypoint <height> parameter to define a waypoint height
; <tt>'''security_height'''</tt>: The height (over <tt>'''ground_alt'''</tt>) used by the circle-home failsafe procedure and in other flight procedures such as formation flight and anti-collision avoidance. Warnings are produced if you place a waypoint lower than <tt>'''security_height'''</tt> (usually the case for the landing point)
; <tt>'''home_mode_height'''</tt> (optional): This optional attribute available since v4.2 allows to override <tt>'''security_height'''</tt> as failsafe height in home mode. If <tt>'''home_mode_height'''</tt> Is set lower than <tt>'''security_height'''</tt>, the later is used. This attribute is useful if you need to return home at a high altitude rather than a low altitude.
; <tt>'''qfu'''</tt> (optional): defines the global constant <tt>QFU</tt>. It usually is the magnetic heading in degrees (north=0, east=90) of the runway, the opposite of wind direction. This constant may be used in the mission description. It is also used by the simulator as the original course of the aircraft. So if you want to take off and climb to the West you would use qfu=270.
; <tt>'''alt'''</tt>: The default altitude of waypoints ([[Altitude_definitions|Above Sea Level]]). So if your ground altitude is 400 then alt needs to be a value greater than ground altitude and above any obstructions in the flight plan.
; <tt>'''max_dist_from_home'''</tt>: A radius representing the maximum allowed distance (in meters) from the HOME waypoint. Exceeding this value (ie flying outside the circle with this radius) will trigger an exception. It is up to you to define the block to be executed (ie what to do) for the exception.

''Here is an '''example''' of such a line in the top of a flight plan:''

<source lang="xml">
<flight_plan alt="250" ground_alt="185" lat0="43.46223" lon0="1.27289" name="Example Muret" max_dist_from_home="300" qfu="270" security_height="25" >
</source>

Note that a flight plan could also contain optional <tt>include</tt>'s and <tt>exceptions</tt> cases.

In English the above flight plan says the name is Example Muret. The reference coordinates for the 0,0 point is: 43.46223 (lat) and 1.27289 (long). The flying site 0,0 location is 185m above sea level. The security height is 25m above 0,0 point or 210m above sea level. The default (ie if not defined in a waypoint this alt is used) altitude is 250m (above sea level). The home mode block altitude is defined to be 150m above sea level. Also, for security, a circle is defined with a radius that's 300m from 0,0 position. This is the max_dist_from_home value. Fly 301m from 0,0 and an exception is triggered. A useful block is to trigger/go to the home mode block and return to home when the aircraft flies outside the safety circle. Example flight plans are helpful for study before you build your own from scratch.

== Waypoints ==

The waypoints are the geographic locations used to specify the trajectories. A waypoint is specified by it's name and coordinates:
<tt>''' <waypoint name wpx wpy [alt] [height]/> '''</tt>
where wpx and wpy are real positional coordinates ( <tt>'''lat/lon'''</tt> ) '''or''' UTM coordinates ( <tt>'''utm_x0/utm_y0'''</tt> ) '''or''' relative coordinates ( <tt>'''x/y'''</tt> ) in meters from your reference point {0,0} . <tt>alt</tt> is an optional parameter and can be used to assign an altitude to a particular waypoint that is different from the globally defined <tt>alt</tt> parameter of the flightplan. The <tt>height</tt> attribute can be used to set the waypoint height relative to the [[Altitude_definitions|ground altitude]] (<tt>ground_alt</tt>) of the flight plan for this waypoint.

An example:
<source lang="xml">
<waypoints>
<waypoint name="HOME" x="0.0" y="30.0"/>
<waypoint name="BRIDGEOVERRIVER" x="-100.0" y="60.0" alt="270."/>
<waypoint name="MyBarn" x="-130.0" y="217.5" alt="3000."/>
<waypoint name="3" x="-30.0" y="50" height="50."/>
<waypoint name="4" x="-30.0" y="50." alt="ground_alt + 50"/>
<waypoint name="_MYHELPERSPOT" x="-30.0" y="60" height="50."/>
<waypoint name="_MYOTHERHELPERSPOT" x="-70.0" y="90" height="70."/>
<waypoint name="TOWER" lat="48.858249" lon="2.294494" height="324."/>
<waypoint name="MountainCAFE" utm_x0="360284.8" utm_y0="4813595.5" alt="1965."/>
</waypoints>
</source>

'''Tips'''
* Waypoints are easily adjusted with the [[Flight_Plan_Editor|flight plan editor]].
* If a waypoint name starts with an underscore ( _ ), the waypoint is '''not displayed''' in the GCS, except in editor mode.
* The maximum number of waypoints is 254.
* A waypoint named <tt>HOME</tt> is required if the failsafe HOME mode procedure is used.

== Sectors ==

Flat ''Sectors'' can be described as an area defined by list of waypoint corners. Such an area will be displayed in the Ground Control Station (GCS) by colored lines connecting the cornerpoints.
A function is generated to check if a point, usually the aircraft itself, is ''inside'' this sector. Currently, this feature requires that the polygon is <b>convex</b> and described in a <b>clockwise</b> order. For a sector named <tt>MyBigGarden</tt> the generated function for the example here would be <tt>bool_t InsideMyBigGarden(float x, float y);</tt> where <tt>x</tt> and <tt>y</tt> are east and north coordinated, in meters, relative to the geographic reference of the flight plan. If the flight plan is dynamically relocated, such a sector will be relocated but the display is currently not updated on the GCS. It would be great if one would help improving that part of the source code. Note that sector names are not allowed to contain spaces.

For example, with the following element in a flight plan.
<source lang="xml">
<sectors>
<sector name="MyBigGarden" color="red">
<corner name="_1"/>
<corner name="_2"/>
<corner name="_3"/>
<corner name="_4"/>
</sector>
</sectors>
</source>

It is then possible to add an exception clause to your flightplan. For example if the aircraft for some reason flies outside this, defined by us, sector the airframe will fly to a standby waypoint. The exclamation mark (!) means the boolean operator <tt>NOT</tt> in this example. In regular language one would describe "If my airframe is NOT inside the MyBigGarden sector anymore then deroute it to the standby waypoint. In Flightplan "Speak" this is written like:
<source lang="xml">
<exception cond="! InsideMyBigGarden(GetPosX(), GetPosY())" deroute="standby"/>
</source>

NOTE: editing of the waypoints of the sector during the flight will not dynamically update the inside function. It will always check if the position is inside the original sector.

'''Tips'''
* A nice option in the corner notation is that one can add an underscore ( _ ) in front of the name; a corner or waypoint name that starts with an underscore is not displayed in the GCS. Only in editor mode it is visible. It is visible in editor mode, because if you the could not see it, it also would be not possible to edit or drag the corner or waypoint to another position.
* The color indicating the sector borders is not fixed but can be defined by oneself if wished for via the color attribute.

== Includes ==

<tt>include</tt> is used to add some flight plan elements defined in an external procedure. It’s useful to include pre-written procedures with only few arguments and then clarify the flight plan.
Here is the structure:
<tt><include name procedure> [<arg name value />]*[<with from to />]*</include></tt>
where <tt>name</tt> attribute of the include element will be used in this flight plan to prefix the blocks of the <tt>procedure</tt>, the XML referenced file.
Named arguments may be given with their value in the <tt>arg</tt> elements. The <tt>with</tt> tag allows to link labels (e.g. attribute of a deroute instruction or of an exception) from the procedure to blocks of the main flight plan.
Then, each block of the procedure is like any block of the flight plan and is designated with a dotted identifier: block <tt>b</tt> of a procedure named <tt>p</tt> is named <tt>b.p</tt> .

Here is an example:
<source lang="xml">
<includes>
<include name="landing" procedure="landing.xml"/>
</includes>
</source>

== Blocks ==

Block elements are the main part of a flight plan: they describe each unit of the mission.
They are made of various primitives, called stages and exceptions, you can put one after the other. When a
stage (or a block) is finished, the autopilot goes to the next one. The behaviour after the last stage of the last block is undefined.

As described in the DTD, the <tt>blocks</tt> element is composed of <tt>block</tt> elements which are sequence of ''stages'':
<source lang="xml">
<!ELEMENT blocks (block+)>
<!ELEMENT block (exception|while|heading|attitude|go|xyz|set|call|circle|deroute|stay|follow|survey_rectangle|for|return|eight|oval|home|path)*>
</source>

Example:
<source lang="xml">
<block name="circlehome">
<circle radius="75" wp="HOME"/>
</block>
</source>

You can add a button in the [[GCS#Strips|strip of the aircraft]] with the attribute <tt>strip_button</tt>:
<source lang="xml">
<block name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
This button will activate the block. If the attribute <tt>group</tt> is specified, all strip buttons of the same group will be placed vertically on top of each other.

In the same way, a key shortcut can be specified:
<source lang="xml">
<block key="D" name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
Modifiers are allowed, using the syntax of [http://library.gnome.org/devel/gtk/2.15/gtk-Keyboard-Accelerators.html#gtk-accelerator-parse GTK accelerators].

An icon can be specified to display the button. The <tt>strip_button</tt> label then is a tooltip for the icon. The icon must be an image file available in the directory <tt>data/pictures/gcs_icons</tt>:
<source lang="xml"><block name="Takeoff" strip_icon="takeoff.png" strip_button="Takeoff"></source>

You can call functions before or after each execution of the block:
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

==== Expressions ====

Most of the numeric attributes in stages are analyzed as C expressions. The syntax of this C expression is restricted to
* numeric constants
* some internal autopilot variables (not fully documented, see examples)
* Some binary operators: <, >, <=, >=, <>, ==, +, -, /, *
* Some utility functions

Some examples of usable expressions are given in the next sections.
=== Initialization Blocks ===
Most flight plans will have three blocks of flight plan initialization blocks. It is good practice to follow this example below if you first start learing to create flightplans

The first block waits until the GPS fix has been established, as shown below.
<source lang="xml">
<blocks>
<block name="Wait GPS">
<set value="1" var="kill_throttle"/>
<while cond="!GpsFixValid()"/>
</block>
</source>
The second block updates the local waypoints with respect to the UAV.
<source lang="xml">
<block name="Geo init">
<while cond="LessThan(NavBlockTime(), 10)"/>
<call fun="NavSetGroundReferenceHere()"/>
</block>
</source>
This next block prevents the UAV from starting the engine and taking off.
<source lang="xml">
<block name="Holding point">

<set value="1" var="kill_throttle"/>
<attitude roll="0" throttle="0" vmode="throttle"/>
</block>
</source>

=== Exceptions ===

The flight manager can handle exceptions. They consist in conditions checked periodically (at the same pace as the navigation control), allowing the control to jump to a given block. Here is the syntax of exceptions:
<source lang="xml"><exception cond="..." deroute="..."></source>
where <tt>cond</tt> is an expression and <tt>deroute</tt> is the name of the block we want to switch to as soon as the condition is true.

Here are some example of exceptions:
<source lang="xml">
<exception cond="10 > PowerVoltage()" deroute="go_down"/>
<exception cond="(ground_alt+10 > GetPosAlt())" deroute="go_up"/>
<exception cond="(autopilot_flight_time > 840)" deroute="quick_land"/>
</source>

Exceptions can be local to a block or global to the flight plan, in the <tt><exceptions></tt> element. In the following example, time since last reception of a message from the ground station is monitored and the navigation is switched to the <tt>Standby</tt> block if no message have been received for 22s. This exception is valid for '''all''' the blocks.
<source lang="xml">
<flight_plan ...>
<waypoints> ... </waypoints>
<exceptions>
<exception cond="datalink_time > 22" deroute="Standby"/>
</exceptions>
<blocks> ...
</source>

=== Deroute ===

The <tt>deroute</tt> is the ''goto'' directive of the flight plan; it switches the navigation to the given block:
<source lang="xml"><deroute block="landing"/></source>

Note that this primitive should not be used to execute loops which are provided by the following elements.

=== Loops ===

Unbounded loops are written with <tt>while</tt> elements whose <tt>cond</tt> attribute is a boolean expression.
Children of <tt>while</tt> are stages:
<source lang="xml">
<while cond="TRUE">
<go wp="A"/>
<go wp="B"/>
<go wp="C"/>
<while cond="5 > stage_time"/>
</while>
</source>
In this example, we run an infinite loop, lettin the aircraft try to go via waypoints <tt>A</tt>, <tt>B</tt> and <tt>C</tt> and waiting for 5 seconds before repeating.

Bounded loops are written with the <tt>for</tt> tag:
<source lang="xml">
<for var="i" from="0" to="3">
...
</for>
</source>
where the body of the loop will be run four times.

The variable of a <tt>for</tt> loop can be used inside expressions appearing as attributes of the stages:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75" alt="ground_alt+50*$i" until="stage_time>10" />
</for>
</source>

In this example, the aircraft will circle around waypoint '''HOME''' for 10 seconds at and altitude above ground of 50m, 10 seconds at altitude 100 meter (50+50), ... until 250m (5x +50).

Note: Two bounded loops using the same control variable are not allowed in the same block.

=== Navigation modes ===

Navigation modes give the description of the desired trajectory in 3D. While the horizontal mode is specified through
''stages'', the vertical control is specified with various attributes of these stages. The current available navigation stages are
* attitude : just keep a fixed attitude;
* heading : keep a given course;
* go : go to a given waypoint;
* path : list of waypoints linked by ''go''
* circle : circle around a waypoint;
* oval : two half circles with a straight between two nav points
* eight : fly a figure of eight through a waypoint and around another
* stay : hold the position (hard to realize for a fixed-wing aircraft);
* follow : follow another aircraft;
* xyz : circle around a point moveable with the RC transmitter stick (obsolete with the datalink).

The vertical control is achieved using the <tt>vmode</tt> attribute of these stages. The possible values are
* '''alt''' (the default) : the autopilot keeps the desired altitude which is the altitude of the waypoint (if any) or the altitude specified with the <tt>alt</tt> attribute;
* '''climb''' : the autopilot keeps the desired vertical speed specified with the <tt>climb</tt> attribute (in m/s);
* '''throttle''' : the autopilots sets the desired throttle specified with the <tt>throttle</tt> attribute (between 0 and 1);
* '''glide''' : the autopilot keeps the desired slope between two waypoints

The default control is done with the throttle. However, setting the <tt>pitch</tt> attribute to '''auto''' and the <tt>throttle</tt> attribute to a constant allows a vertical control only by controlling the attitude of the A/C.
The <tt>pitch</tt> attribute also can be set to any value (in degrees) while the throttle control is in use: it usually affects the airspeed of the aircraft.

The different navigation modes are detailed in the next sections.

=== Attitude ===

Element <tt>attitude</tt> is the navigation mode which corresponds to the current lowest control loop for horizontal mode.
The autopilot then keeps a constant attitude. The <tt>roll</tt> attribute is required (in degrees, positive to put right wing low).

To fly away, at constant airspeed:
<source lang="xml"><attitude roll="0" vmode="throttle", throttle="0.5"/></source>

To fly around, holding a given altitude:
<source lang="xml"><attitude roll="30" alt="ground_alt+50"/></source>

Note that it is not a ''safe'' navigation mode since the geographic position of the plane is not controlled. However, this mode is useful to tune the roll attitude control loop.

=== Heading ===

<tt>heading</tt> primitive is relative to the second level loop for horizontal mode in the autopilot which will keep the given <tt>course</tt>, a required attribute (in degrees, clockwise, north=0, east=90).

One example to takeoff, following the QFU, 80% throttle, nose up (15 degrees) until height of 30m is reached:
<source lang="xml"><heading course="QFU" vmode="throttle" throttle="0.8" pitch="15" until="(GetPosAlt() > ground_alt+30)"/></source>

=== Go ===

The <tt>go</tt> primitive is probably the most useful one. Basically, the autopilot will try to join a given waypoint (<tt>wp</tt>, the only required attribute). So the simplest thing you can ask for is
<source lang="xml"><go wp="HOME"/></source>
which will set the '''HOME''' waypoint as the desired target position. Note than since <tt>vmode="alt"</tt> is the default, the altitude of the target waypoint is also taken into account. The navigation will switch to the next stage as soon as the target is reached.

It is usually not a good idea to try to join a waypoint without asking for a precise trajectory, i.e. a given line.
Setting the <tt>hmode</tt> attribute to '''route''', the navigation will go over a segment joining two waypoints:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route"/></source>

The target altitude is the altitude of the target waypoint; it can also be set with the <tt>alt</tt> attribute. The following example keeps an altitude with fixed throttle:
<source lang="xml"><go from="wp2" wp="wp3" hmode="route" pitch="auto" throttle="0.75" alt="ground_alt+100"/></source>

The attributes related to the vertical control can also be set to replace the default altitude mode:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" vmode="climb" climb="1.5"/></source>

Finally, the <tt>approaching_time</tt> (in seconds) attribute helps to decide when the target is ''reached''. It can be set
to '''0''' to go over the target waypoint (default value is the '''CARROT''' time, set in the airframe configuration file).
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" approaching_time="1"/></source>

=== Path ===

The <tt>path</tt> primitive is just a shorthand expression for a set of <tt>go</tt> primitives. A list of waypoints defined with the <tt>wpts</tt> attribute is pre-processed into a set of <tt>go</tt> primitives with the <tt>hmode</tt> attribute. For example:
<source lang="xml"><path wpts="wp1, wp2, wp3"/></source>

Other attributes are optional:
<source lang="xml"><path wpts="wp3, wp1, wp2" approaching_time="1" pitch="auto" throttle="0.5"/></source>

=== Circle ===

The <tt>circle</tt> primitive is the second main navigation mode: the trajectory is defined as a circle around a given waypoint with a given radius:
<source lang="xml"><circle wp="HOME" radius="75"/></source>
A positive radius makes the UAS move clockwise, a negative counter-clockwise.

The <tt>until</tt> attribute may be used to control the end of the stage. The following example defines an ascending trajectory at constant throttle, nose up (15 degrees), over growing circles, until the battery level is low:
<source lang="xml"><circle wp="wp1" radius="50+(GetPosAlt()-ground_alt)/2" vmode="throttle" throttle="0.75" pitch="15" until="10>PowerVoltage()"/></source>

=== Oval ===
The oval consists of two half circles that are connected with two straight lines. This flight path is usefull when a IMU is used because the straights allow for level flight.
<source lang="xml"> <oval p1="1" p2="2" radius="nav_radius"/> </source>

=== Eight ===
Fly a figure of eight that consists of two straight legs that pass though the center and the center of the half circle at the end of the two legs is in the turn around waypoint. The altitude of the center waypoint is used for the entire figure. The turn around waypoint is moved to match radius given.
<source lang="xml"> <eight center="1" radius="nav_radius" turn_around="2"/> </source>

=== Follow ===

The <tt>follow</tt> is a special primitive which makes the UAS follow another UAS (real or simulated, named with its <tt>ac_id</tt>) at a given <tt>distance</tt> (in meters) behind and at a given <tt>height</tt> (in meters) above.

In this example, the autopilot will try to follow A/C number '''4''', staying '''50'''m behind and '''20'''m above.
<source lang="xml"><follow ac_id="4" distance="50" height="20"/></source>
Note that the <tt>traffic_info.c</tt> file is required by this feature and the <tt>TRAFFIC_INFO</tt> flag has to be set to enable it. Then, the following lines must be added in the airframe file:
<tt>ap.srcs += traffic_info.c</tt>
<tt>ap.CFLAGS += -DTRAFFIC_INFO</tt>
<tt>sim.srcs += traffic_info.c</tt>
<tt>sim.CFLAGS += -DTRAFFIC_INFO</tt>

=== Stay ===

The <tt>stay</tt> is a mode for UAS's able to hover:
<source lang="xml"><stay wp="HOME" alt="10"/></source>

=== XYZ ===

<tt>xyz</tt> is a special mode where the UAS circles around a user moveable waypoint. This waypoint is moved with the RC sticks:
* YAW channel controls the point over the west-east axis;
* PITCH channel controls the point over the south-north axis;
* ROLL channel controls the altitude.

Example (default radius is '''100'''):
<source lang="xml"><xyz radius="40"/></source>

=== Set ===

The <tt>set</tt> element is a dangerous one which should be used only by expert users: it is used to directly set an internal variable of the autopilot. For example, you can change the value of the default ground altitude, a variable used by the home mode failsafe procedure (and maybe by your own flight plan):
<source lang="xml"><set var="ground_alt" value="ground_alt+50"/></source>
This directive is extremely powerful and has great potential for error - use with caution.

=== Call ===

The <tt>call</tt> allows the user to define its own navigation procedures in C. The <tt>value</tt> must be a call to a boolean function which must return TRUE as long as the stage is not completed (a function which should be called only once would then return immediately FALSE).
This feature is illustrated with the '''line''' pattern:
<source lang="xml">
<call fun="nav_line_init()"/>
<call fun="nav_line(WP_1, WP_2, nav_radius)"/>
</source>
where <tt>nav_line_init()</tt> returns FALSE and <tt>nav_line()</tt> always returns TRUE (this stage never ends).
Such functions usually are defined in a supplementary C file which must be specified in the airframe file (in the <tt>makefile</tt> section)
<tt>ap.srcs += nav_line.c
sim.srcs += nav_line.c</tt>
These functions also must be declared in a header file which must be mentioned in the header element of the flight plan:
<source lang="xml">
<header>
#include "nav_line.h"
</header>
</source>
These C source file and H header file must be located in the <tt>sw/airborne</tt> directory.

You can also call functions before or after each execution of the block:
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

== Advanced Examples ==
Parameters used in a flight plan can be computed expressions. In this example, the plane is asked to perform 5 circles at progressively increasing altitudes for exactly one minute at each altitude:
<source lang="xml">
<for var = "i" from = "1" to = "5">
<circle wp = "HOME" radius="75"
alt = "ground_alt+50*$i"
until = "stage_time>60" />
</for>
</source>

=== Immobilize Actuators ===

h_ctl setpoints variable are set by the h_ctl_attitude_loop() (from fw_h_ctl.c) loop) which can be disabled with the
h_ctl_disabled flag:
<source lang="xml">
<set var="h_ctl_disabled" value="TRUE"/>
<set var="h_ctl_aileron_setpoint" value="0"/>
<set var="h_ctl_elevator_setpoint" value="MAX_PPRZ/2"/>
.... waiting for a condition ...
<set var="h_ctl_disabled" value="FALSE"/>
</source>

== Procedures ==

Procedures are libraries which can be included in flight plans. They are composed of waypoints, sectors and blocks. The header of a procedure may contain some parameters which are replaced by arguments when the procedure is included.

Extract of the DTD: a procedure is a sequence of parameters, waypoints, ...:
<source lang="xml"><!ELEMENT procedure (param*,header?,waypoints?,sectors?,exceptions?,blocks?)></source>

A <tt>param</tt>eter is just a name. A parameter is optional if it is declared with a default value.
An example with a required and an optional parameter:
<source lang="xml">
<param name="alt"/>
<param name="radius" default_value="75"/>
</source>

Procedures are called with the <tt>include</tt> element in a flight plan. A procedure cannot be included twice or by another procedure. A procedure call requires:

* the name of the procedure file, the name given to this inclusion;
* values for the parameters;
* backlinks for block name exits of the procedure.

For example:
<source lang="xml"><include name="landing" procedure="landing.xml"/></source>

Here is the corresponding procedure '''landing.xml''':
<source lang="xml">
<!DOCTYPE procedure SYSTEM "flight_plan.dtd">
<procedure>
<waypoints>
<waypoint name="AF" x="177.4" y="45.1" alt="30"/>
<waypoint name="TD" x="28.8" y="57.0" alt="0"/>
<waypoint name="_BASELEG" x="168.8" y="-13.8"/>
</waypoints>
<blocks>
...
<block name="land">
<call fun="nav_compute_baseleg(WP_AF, WP_TD, WP__BASELEG, nav_radius)"/>
<circle radius="nav_radius" until="NavCircleCount() > 0.5" wp="_BASELEG"/>
<circle radius="nav_radius" until="And(NavQdrCloseTo(DegOfRad(baseleg_out_qdr)-10), 10 > fabs(GetPosAlt()- WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
</block>
...
</blocks>
</procedure>
</source>

Note that the name of procedure '''land''' block will be renamed into '''landing.land''':
<source lang="xml"><deroute block="landing.land"/></source>
will jump to this procedure block.

Suppose you have a go-around condition in your landing procedure. You would write it
<source lang="xml"><exception cond="..." deroute="go-around"/></source>
then you must link this block exit with one of your block (e.g. <tt>Standby</tt>). So you would include the procedure as follows:
<source lang="xml">
<include name="landing" procedure="landing.xml">
<with from="go-around" to="Standby"/>
</include>
</source>

== Tips and Tricks ==

There are many ways to skin a cat just as there are many ways to craft your flight plan. Following the best practices tips can save you from a lot of frustration and mishap.

* Simulate your flight plan before taking it to the sky. Flight plans should always be carefully tested prior to flight, take a look at the [[Simulation|simulation]] page for details on how to simulate your plan.
* Make an subdirectory in the Flight_plan directory with your own name and add your flight plans there. Make sure that the location of the DTD is correct, e.g by using relative directory double dots as in <tt><!DOCTYPE flight_plan SYSTEM "../flight_plan.dtd"></tt>

* Take a good look at other flight plans included with Paparazzi. To learn from example flight plans please visit the [[Flight_Plan_Examples|flight plan examples]] page
* There are several option to build failsafe features into you flightplan, [[Failsafe|for some examples visit the Failsafe page]].
* Some flight plan examples define waypoint locations using relative coordinates. These are relative positions from the fixed lat and lon in the header of the flight plan. When simulating your flight plan the aircraft always use the lat/lon as defined in the flight plan since a regular simulation has no notion of you current position of you local PC where you simulate on. This is something to keep in mind if you test your flight plan in real flights.

[[Category:Software]] [[Category:User_Documentation]]

Flight Plans

2014-05-13T01:18:41Z

Alonsoac: /* Sectors */ insideSector() function has static positions

A '''flight plan''' is a XML document which one can create and store aboard an autopilot. The flight plan will describe how you want your aircraft to travel if released into into the wild blue yonder.

== DTD and Structure ==

The formal description of the flight plan file is given in the [http://en.wikipedia.org/wiki/Document_Type_Definition '''DTD'''] (located in <tt>conf/flight_plans/flight_plan.dtd</tt>). This
DTD must be referenced in the header of your flight plan XML document using the following line:<br>

<source lang="xml"><!DOCTYPE flight_plan SYSTEM "flight_plan.dtd"></source>

The flight plans are stored in the <tt>conf/flight_plans</tt> directory. The [[Flight_Plan_Editor|flight plan editor]] can be used to create basic flight plans via the GUI.

Extract from the [http://en.wikipedia.org/wiki/Document_Type_Definition DTD]:
<tt><!ELEMENT flight_plan (header?,waypoints,sectors?,include*,exceptions?,blocks)></tt>

'''A flight plan is composed of two mandatory elements: [[#waypoints|waypoints]] and [[#blocks|blocks]]'''

The root <tt>flight_plan</tt> element is specified with several attributes:
<tt>'''<flight_plan name lat0 lon0 ground_alt security_height home_mode_height qfu alt max_dist_from_home>'''</tt>
; <tt>'''name'''</tt>: The name of the mission (a text string)
; <tt>'''lat0, lon0'''</tt>: Defines the latitude and longitude coordinates of the reference point {0,0} in WGS84 degree coordinates
; <tt>'''ground_alt'''</tt>: The ground altitude (in meters), Above Sea Level where you are flying. It defines the <tt>GROUND_ALT</tt> constant value which can be used in combination with a waypoint <height> parameter to define a waypoint height
; <tt>'''security_height'''</tt>: The height (over <tt>'''ground_alt'''</tt>) used by the circle-home failsafe procedure and in other flight procedures such as formation flight and anti-collision avoidance. Warnings are produced if you place a waypoint lower than <tt>'''security_height'''</tt> (usually the case for the landing point)
; <tt>'''home_mode_height'''</tt> (optional): This optional attribute available since v4.2 allows to override <tt>'''security_height'''</tt> as failsafe height in home mode. If <tt>'''home_mode_height'''</tt> Is set lower than <tt>'''security_height'''</tt>, the later is used. This attribute is useful if you need to return home at a high altitude rather than a low altitude.
; <tt>'''qfu'''</tt> (optional): defines the global constant <tt>QFU</tt>. It usually is the magnetic heading in degrees (north=0, east=90) of the runway, the opposite of wind direction. This constant may be used in the mission description. It is also used by the simulator as the original course of the aircraft. So if you want to take off and climb to the West you would use qfu=270.
; <tt>'''alt'''</tt>: The default altitude of waypoints ([[Altitude_definitions|Above Sea Level]]). So if your ground altitude is 400 then alt needs to be a value greater than ground altitude and above any obstructions in the flight plan.
; <tt>'''max_dist_from_home'''</tt>: A radius representing the maximum allowed distance (in meters) from the HOME waypoint. Exceeding this value (ie flying outside the circle with this radius) will trigger an exception. It is up to you to define the block to be executed (ie what to do) for the exception.

''Here is an '''example''' of such a line in the top of a flight plan:''

<source lang="xml">
<flight_plan alt="250" ground_alt="185" lat0="43.46223" lon0="1.27289" name="Example Muret" max_dist_from_home="300" qfu="270" security_height="25" >
</source>

Note that a flight plan could also contain optional <tt>include</tt>'s and <tt>exceptions</tt> cases.

In English the above flight plan says the name is Example Muret. The reference coordinates for the 0,0 point is: 43.46223 (lat) and 1.27289 (long). The flying site 0,0 location is 185m above sea level. The security height is 25m above 0,0 point or 210m above sea level. The default (ie if not defined in a waypoint this alt is used) altitude is 250m (above sea level). The home mode block altitude is defined to be 150m above sea level. Also, for security, a circle is defined with a radius that's 300m from 0,0 position. This is the max_dist_from_home value. Fly 301m from 0,0 and an exception is triggered. A useful block is to trigger/go to the home mode block and return to home when the aircraft flies outside the safety circle. Example flight plans are helpful for study before you build your own from scratch.

== Waypoints ==

The waypoints are the geographic locations used to specify the trajectories. A waypoint is specified by it's name and coordinates:
<tt>''' <waypoint name wpx wpy [alt] [height]/> '''</tt>
where wpx and wpy are real positional coordinates ( <tt>'''lat/lon'''</tt> ) '''or''' UTM coordinates ( <tt>'''utm_x0/utm_y0'''</tt> ) '''or''' relative coordinates ( <tt>'''x/y'''</tt> ) in meters from your reference point {0,0} . <tt>alt</tt> is an optional parameter and can be used to assign an altitude to a particular waypoint that is different from the globally defined <tt>alt</tt> parameter of the flightplan. The <tt>height</tt> attribute can be used to set the waypoint height relative to the [[Altitude_definitions|ground altitude]] (<tt>ground_alt</tt>) of the flight plan for this waypoint.

An example:
<source lang="xml">
<waypoints>
<waypoint name="HOME" x="0.0" y="30.0"/>
<waypoint name="BRIDGEOVERRIVER" x="-100.0" y="60.0" alt="270."/>
<waypoint name="MyBarn" x="-130.0" y="217.5" alt="3000."/>
<waypoint name="3" x="-30.0" y="50" height="50."/>
<waypoint name="4" x="-30.0" y="50." alt="ground_alt + 50"/>
<waypoint name="_MYHELPERSPOT" x="-30.0" y="60" height="50."/>
<waypoint name="_MYOTHERHELPERSPOT" x="-70.0" y="90" height="70."/>
<waypoint name="TOWER" lat="48.858249" lon="2.294494" height="324."/>
<waypoint name="MountainCAFE" utm_x0="360284.8" utm_y0="4813595.5" alt="1965."/>
</waypoints>
</source>

'''Tips'''
* Waypoints are easily adjusted with the [[Flight_Plan_Editor|flight plan editor]].
* If a waypoint name starts with an underscore ( _ ), the waypoint is '''not displayed''' in the GCS, except in editor mode.
* The maximum number of waypoints is 254.
* A waypoint named <tt>HOME</tt> is required if the failsafe HOME mode procedure is used.

== Sectors ==

Flat ''Sectors'' can be described as an area defined by list of waypoint corners. Such an area will be displayed in the Ground Control Station (GCS) by colored lines connecting the cornerpoints.
A function is generated to check if a point, usually the aircraft itself, is ''inside'' this sector. Currently, this feature requires that the polygon is <b>convex</b> and described in a <b>clockwise</b> order. For a sector named <tt>MyBigGarden</tt> the generated function for the example here would be <tt>bool_t InsideMyBigGarden(float x, float y);</tt> where <tt>x</tt> and <tt>y</tt> are east and north coordinated, in meters, relative to the geographic reference of the flight plan. If the flight plan is dynamically relocated, such a sector will be relocated but the display is currently not updated on the GCS. It would be great if one would help improving that part of the source code. Note that sector names are not allowed to contain spaces.

For example, with the following element in a flight plan.
<source lang="xml">
<sectors>
<sector name="MyBigGarden" color="red">
<corner name="_1"/>
<corner name="_2"/>
<corner name="_3"/>
<corner name="_4"/>
</sector>
</sectors>
</source>

It is then possible to add an exception clause to your flightplan. For example if the aircraft for some reason flies outside this, defined by us, sector the airframe will fly to a standby waypoint. The exclamation mark (!) means the boolean operator <tt>NOT</tt> in this example. In regular language one would describe "If my airframe is NOT inside the MyBigGarden sector anymore then deroute it to the standby waypoint. In Flightplan "Speak" this is written like:
<source lang="xml">
<exception cond="! InsideMyBigGarden(GetPosX(), GetPosY())" deroute="standby"/>
</source>

NOTE: editing of the waypoints of the sector during the flight will not dinamycally update the inside function. It will always check if the position is inside the original sector.

'''Tips'''
* A nice option in the corner notation is that one can add an underscore ( _ ) in front of the name; a corner or waypoint name that starts with an underscore is not displayed in the GCS. Only in editor mode it is visible. It is visible in editor mode, because if you the could not see it, it also would be not possible to edit or drag the corner or waypoint to another position.
* The color indicating the sector borders is not fixed but can be defined by oneself if wished for via the color attribute.

== Includes ==

<tt>include</tt> is used to add some flight plan elements defined in an external procedure. It’s useful to include pre-written procedures with only few arguments and then clarify the flight plan.
Here is the structure:
<tt><include name procedure> [<arg name value />]*[<with from to />]*</include></tt>
where <tt>name</tt> attribute of the include element will be used in this flight plan to prefix the blocks of the <tt>procedure</tt>, the XML referenced file.
Named arguments may be given with their value in the <tt>arg</tt> elements. The <tt>with</tt> tag allows to link labels (e.g. attribute of a deroute instruction or of an exception) from the procedure to blocks of the main flight plan.
Then, each block of the procedure is like any block of the flight plan and is designated with a dotted identifier: block <tt>b</tt> of a procedure named <tt>p</tt> is named <tt>b.p</tt> .

Here is an example:
<source lang="xml">
<includes>
<include name="landing" procedure="landing.xml"/>
</includes>
</source>

== Blocks ==

Block elements are the main part of a flight plan: they describe each unit of the mission.
They are made of various primitives, called stages and exceptions, you can put one after the other. When a
stage (or a block) is finished, the autopilot goes to the next one. The behaviour after the last stage of the last block is undefined.

As described in the DTD, the <tt>blocks</tt> element is composed of <tt>block</tt> elements which are sequence of ''stages'':
<source lang="xml">
<!ELEMENT blocks (block+)>
<!ELEMENT block (exception|while|heading|attitude|go|xyz|set|call|circle|deroute|stay|follow|survey_rectangle|for|return|eight|oval|home|path)*>
</source>

Example:
<source lang="xml">
<block name="circlehome">
<circle radius="75" wp="HOME"/>
</block>
</source>

You can add a button in the [[GCS#Strips|strip of the aircraft]] with the attribute <tt>strip_button</tt>:
<source lang="xml">
<block name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
This button will activate the block. If the attribute <tt>group</tt> is specified, all strip buttons of the same group will be placed vertically on top of each other.

In the same way, a key shortcut can be specified:
<source lang="xml">
<block key="D" name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
Modifiers are allowed, using the syntax of [http://library.gnome.org/devel/gtk/2.15/gtk-Keyboard-Accelerators.html#gtk-accelerator-parse GTK accelerators].

An icon can be specified to display the button. The <tt>strip_button</tt> label then is a tooltip for the icon. The icon must be an image file available in the directory <tt>data/pictures/gcs_icons</tt>:
<source lang="xml"><block name="Takeoff" strip_icon="takeoff.png" strip_button="Takeoff"></source>

You can call functions before or after each execution of the block:
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

==== Expressions ====

Most of the numeric attributes in stages are analyzed as C expressions. The syntax of this C expression is restricted to
* numeric constants
* some internal autopilot variables (not fully documented, see examples)
* Some binary operators: <, >, <=, >=, <>, ==, +, -, /, *
* Some utility functions

Some examples of usable expressions are given in the next sections.
=== Initialization Blocks ===
Most flight plans will have three blocks of flight plan initialization blocks. It is good practice to follow this example below if you first start learing to create flightplans

The first block waits until the GPS fix has been established, as shown below.
<source lang="xml">
<blocks>
<block name="Wait GPS">
<set value="1" var="kill_throttle"/>
<while cond="!GpsFixValid()"/>
</block>
</source>
The second block updates the local waypoints with respect to the UAV.
<source lang="xml">
<block name="Geo init">
<while cond="LessThan(NavBlockTime(), 10)"/>
<call fun="NavSetGroundReferenceHere()"/>
</block>
</source>
This next block prevents the UAV from starting the engine and taking off.
<source lang="xml">
<block name="Holding point">

<set value="1" var="kill_throttle"/>
<attitude roll="0" throttle="0" vmode="throttle"/>
</block>
</source>

=== Exceptions ===

The flight manager can handle exceptions. They consist in conditions checked periodically (at the same pace as the navigation control), allowing the control to jump to a given block. Here is the syntax of exceptions:
<source lang="xml"><exception cond="..." deroute="..."></source>
where <tt>cond</tt> is an expression and <tt>deroute</tt> is the name of the block we want to switch to as soon as the condition is true.

Here are some example of exceptions:
<source lang="xml">
<exception cond="10 > PowerVoltage()" deroute="go_down"/>
<exception cond="(ground_alt+10 > GetPosAlt())" deroute="go_up"/>
<exception cond="(autopilot_flight_time > 840)" deroute="quick_land"/>
</source>

Exceptions can be local to a block or global to the flight plan, in the <tt><exceptions></tt> element. In the following example, time since last reception of a message from the ground station is monitored and the navigation is switched to the <tt>Standby</tt> block if no message have been received for 22s. This exception is valid for '''all''' the blocks.
<source lang="xml">
<flight_plan ...>
<waypoints> ... </waypoints>
<exceptions>
<exception cond="datalink_time > 22" deroute="Standby"/>
</exceptions>
<blocks> ...
</source>

=== Deroute ===

The <tt>deroute</tt> is the ''goto'' directive of the flight plan; it switches the navigation to the given block:
<source lang="xml"><deroute block="landing"/></source>

Note that this primitive should not be used to execute loops which are provided by the following elements.

=== Loops ===

Unbounded loops are written with <tt>while</tt> elements whose <tt>cond</tt> attribute is a boolean expression.
Children of <tt>while</tt> are stages:
<source lang="xml">
<while cond="TRUE">
<go wp="A"/>
<go wp="B"/>
<go wp="C"/>
<while cond="5 > stage_time"/>
</while>
</source>
In this example, we run an infinite loop, lettin the aircraft try to go via waypoints <tt>A</tt>, <tt>B</tt> and <tt>C</tt> and waiting for 5 seconds before repeating.

Bounded loops are written with the <tt>for</tt> tag:
<source lang="xml">
<for var="i" from="0" to="3">
...
</for>
</source>
where the body of the loop will be run four times.

The variable of a <tt>for</tt> loop can be used inside expressions appearing as attributes of the stages:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75" alt="ground_alt+50*$i" until="stage_time>10" />
</for>
</source>

In this example, the aircraft will circle around waypoint '''HOME''' for 10 seconds at and altitude above ground of 50m, 10 seconds at altitude 100 meter (50+50), ... until 250m (5x +50).

Note: Two bounded loops using the same control variable are not allowed in the same block.

=== Navigation modes ===

Navigation modes give the description of the desired trajectory in 3D. While the horizontal mode is specified through
''stages'', the vertical control is specified with various attributes of these stages. The current available navigation stages are
* attitude : just keep a fixed attitude;
* heading : keep a given course;
* go : go to a given waypoint;
* path : list of waypoints linked by ''go''
* circle : circle around a waypoint;
* oval : two half circles with a straight between two nav points
* eight : fly a figure of eight through a waypoint and around another
* stay : hold the position (hard to realize for a fixed-wing aircraft);
* follow : follow another aircraft;
* xyz : circle around a point moveable with the RC transmitter stick (obsolete with the datalink).

The vertical control is achieved using the <tt>vmode</tt> attribute of these stages. The possible values are
* '''alt''' (the default) : the autopilot keeps the desired altitude which is the altitude of the waypoint (if any) or the altitude specified with the <tt>alt</tt> attribute;
* '''climb''' : the autopilot keeps the desired vertical speed specified with the <tt>climb</tt> attribute (in m/s);
* '''throttle''' : the autopilots sets the desired throttle specified with the <tt>throttle</tt> attribute (between 0 and 1);
* '''glide''' : the autopilot keeps the desired slope between two waypoints

The default control is done with the throttle. However, setting the <tt>pitch</tt> attribute to '''auto''' and the <tt>throttle</tt> attribute to a constant allows a vertical control only by controlling the attitude of the A/C.
The <tt>pitch</tt> attribute also can be set to any value (in degrees) while the throttle control is in use: it usually affects the airspeed of the aircraft.

The different navigation modes are detailed in the next sections.

=== Attitude ===

Element <tt>attitude</tt> is the navigation mode which corresponds to the current lowest control loop for horizontal mode.
The autopilot then keeps a constant attitude. The <tt>roll</tt> attribute is required (in degrees, positive to put right wing low).

To fly away, at constant airspeed:
<source lang="xml"><attitude roll="0" vmode="throttle", throttle="0.5"/></source>

To fly around, holding a given altitude:
<source lang="xml"><attitude roll="30" alt="ground_alt+50"/></source>

Note that it is not a ''safe'' navigation mode since the geographic position of the plane is not controlled. However, this mode is useful to tune the roll attitude control loop.

=== Heading ===

<tt>heading</tt> primitive is relative to the second level loop for horizontal mode in the autopilot which will keep the given <tt>course</tt>, a required attribute (in degrees, clockwise, north=0, east=90).

One example to takeoff, following the QFU, 80% throttle, nose up (15 degrees) until height of 30m is reached:
<source lang="xml"><heading course="QFU" vmode="throttle" throttle="0.8" pitch="15" until="(GetPosAlt() > ground_alt+30)"/></source>

=== Go ===

The <tt>go</tt> primitive is probably the most useful one. Basically, the autopilot will try to join a given waypoint (<tt>wp</tt>, the only required attribute). So the simplest thing you can ask for is
<source lang="xml"><go wp="HOME"/></source>
which will set the '''HOME''' waypoint as the desired target position. Note than since <tt>vmode="alt"</tt> is the default, the altitude of the target waypoint is also taken into account. The navigation will switch to the next stage as soon as the target is reached.

It is usually not a good idea to try to join a waypoint without asking for a precise trajectory, i.e. a given line.
Setting the <tt>hmode</tt> attribute to '''route''', the navigation will go over a segment joining two waypoints:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route"/></source>

The target altitude is the altitude of the target waypoint; it can also be set with the <tt>alt</tt> attribute. The following example keeps an altitude with fixed throttle:
<source lang="xml"><go from="wp2" wp="wp3" hmode="route" pitch="auto" throttle="0.75" alt="ground_alt+100"/></source>

The attributes related to the vertical control can also be set to replace the default altitude mode:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" vmode="climb" climb="1.5"/></source>

Finally, the <tt>approaching_time</tt> (in seconds) attribute helps to decide when the target is ''reached''. It can be set
to '''0''' to go over the target waypoint (default value is the '''CARROT''' time, set in the airframe configuration file).
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" approaching_time="1"/></source>

=== Path ===

The <tt>path</tt> primitive is just a shorthand expression for a set of <tt>go</tt> primitives. A list of waypoints defined with the <tt>wpts</tt> attribute is pre-processed into a set of <tt>go</tt> primitives with the <tt>hmode</tt> attribute. For example:
<source lang="xml"><path wpts="wp1, wp2, wp3"/></source>

Other attributes are optional:
<source lang="xml"><path wpts="wp3, wp1, wp2" approaching_time="1" pitch="auto" throttle="0.5"/></source>

=== Circle ===

The <tt>circle</tt> primitive is the second main navigation mode: the trajectory is defined as a circle around a given waypoint with a given radius:
<source lang="xml"><circle wp="HOME" radius="75"/></source>
A positive radius makes the UAS move clockwise, a negative counter-clockwise.

The <tt>until</tt> attribute may be used to control the end of the stage. The following example defines an ascending trajectory at constant throttle, nose up (15 degrees), over growing circles, until the battery level is low:
<source lang="xml"><circle wp="wp1" radius="50+(GetPosAlt()-ground_alt)/2" vmode="throttle" throttle="0.75" pitch="15" until="10>PowerVoltage()"/></source>

=== Oval ===
The oval consists of two half circles that are connected with two straight lines. This flight path is usefull when a IMU is used because the straights allow for level flight.
<source lang="xml"> <oval p1="1" p2="2" radius="nav_radius"/> </source>

=== Eight ===
Fly a figure of eight that consists of two straight legs that pass though the center and the center of the half circle at the end of the two legs is in the turn around waypoint. The altitude of the center waypoint is used for the entire figure. The turn around waypoint is moved to match radius given.
<source lang="xml"> <eight center="1" radius="nav_radius" turn_around="2"/> </source>

=== Follow ===

The <tt>follow</tt> is a special primitive which makes the UAS follow another UAS (real or simulated, named with its <tt>ac_id</tt>) at a given <tt>distance</tt> (in meters) behind and at a given <tt>height</tt> (in meters) above.

In this example, the autopilot will try to follow A/C number '''4''', staying '''50'''m behind and '''20'''m above.
<source lang="xml"><follow ac_id="4" distance="50" height="20"/></source>
Note that the <tt>traffic_info.c</tt> file is required by this feature and the <tt>TRAFFIC_INFO</tt> flag has to be set to enable it. Then, the following lines must be added in the airframe file:
<tt>ap.srcs += traffic_info.c</tt>
<tt>ap.CFLAGS += -DTRAFFIC_INFO</tt>
<tt>sim.srcs += traffic_info.c</tt>
<tt>sim.CFLAGS += -DTRAFFIC_INFO</tt>

=== Stay ===

The <tt>stay</tt> is a mode for UAS's able to hover:
<source lang="xml"><stay wp="HOME" alt="10"/></source>

=== XYZ ===

<tt>xyz</tt> is a special mode where the UAS circles around a user moveable waypoint. This waypoint is moved with the RC sticks:
* YAW channel controls the point over the west-east axis;
* PITCH channel controls the point over the south-north axis;
* ROLL channel controls the altitude.

Example (default radius is '''100'''):
<source lang="xml"><xyz radius="40"/></source>

=== Set ===

The <tt>set</tt> element is a dangerous one which should be used only by expert users: it is used to directly set an internal variable of the autopilot. For example, you can change the value of the default ground altitude, a variable used by the home mode failsafe procedure (and maybe by your own flight plan):
<source lang="xml"><set var="ground_alt" value="ground_alt+50"/></source>
This directive is extremely powerful and has great potential for error - use with caution.

=== Call ===

The <tt>call</tt> allows the user to define its own navigation procedures in C. The <tt>value</tt> must be a call to a boolean function which must return TRUE as long as the stage is not completed (a function which should be called only once would then return immediately FALSE).
This feature is illustrated with the '''line''' pattern:
<source lang="xml">
<call fun="nav_line_init()"/>
<call fun="nav_line(WP_1, WP_2, nav_radius)"/>
</source>
where <tt>nav_line_init()</tt> returns FALSE and <tt>nav_line()</tt> always returns TRUE (this stage never ends).
Such functions usually are defined in a supplementary C file which must be specified in the airframe file (in the <tt>makefile</tt> section)
<tt>ap.srcs += nav_line.c
sim.srcs += nav_line.c</tt>
These functions also must be declared in a header file which must be mentioned in the header element of the flight plan:
<source lang="xml">
<header>
#include "nav_line.h"
</header>
</source>
These C source file and H header file must be located in the <tt>sw/airborne</tt> directory.

You can also call functions before or after each execution of the block:
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

== Advanced Examples ==
Parameters used in a flight plan can be computed expressions. In this example, the plane is asked to perform 5 circles at progressively increasing altitudes for exactly one minute at each altitude:
<source lang="xml">
<for var = "i" from = "1" to = "5">
<circle wp = "HOME" radius="75"
alt = "ground_alt+50*$i"
until = "stage_time>60" />
</for>
</source>

=== Immobilize Actuators ===

h_ctl setpoints variable are set by the h_ctl_attitude_loop() (from fw_h_ctl.c) loop) which can be disabled with the
h_ctl_disabled flag:
<source lang="xml">
<set var="h_ctl_disabled" value="TRUE"/>
<set var="h_ctl_aileron_setpoint" value="0"/>
<set var="h_ctl_elevator_setpoint" value="MAX_PPRZ/2"/>
.... waiting for a condition ...
<set var="h_ctl_disabled" value="FALSE"/>
</source>

== Procedures ==

Procedures are libraries which can be included in flight plans. They are composed of waypoints, sectors and blocks. The header of a procedure may contain some parameters which are replaced by arguments when the procedure is included.

Extract of the DTD: a procedure is a sequence of parameters, waypoints, ...:
<source lang="xml"><!ELEMENT procedure (param*,header?,waypoints?,sectors?,exceptions?,blocks?)></source>

A <tt>param</tt>eter is just a name. A parameter is optional if it is declared with a default value.
An example with a required and an optional parameter:
<source lang="xml">
<param name="alt"/>
<param name="radius" default_value="75"/>
</source>

Procedures are called with the <tt>include</tt> element in a flight plan. A procedure cannot be included twice or by another procedure. A procedure call requires:

* the name of the procedure file, the name given to this inclusion;
* values for the parameters;
* backlinks for block name exits of the procedure.

For example:
<source lang="xml"><include name="landing" procedure="landing.xml"/></source>

Here is the corresponding procedure '''landing.xml''':
<source lang="xml">
<!DOCTYPE procedure SYSTEM "flight_plan.dtd">
<procedure>
<waypoints>
<waypoint name="AF" x="177.4" y="45.1" alt="30"/>
<waypoint name="TD" x="28.8" y="57.0" alt="0"/>
<waypoint name="_BASELEG" x="168.8" y="-13.8"/>
</waypoints>
<blocks>
...
<block name="land">
<call fun="nav_compute_baseleg(WP_AF, WP_TD, WP__BASELEG, nav_radius)"/>
<circle radius="nav_radius" until="NavCircleCount() > 0.5" wp="_BASELEG"/>
<circle radius="nav_radius" until="And(NavQdrCloseTo(DegOfRad(baseleg_out_qdr)-10), 10 > fabs(GetPosAlt()- WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
</block>
...
</blocks>
</procedure>
</source>

Note that the name of procedure '''land''' block will be renamed into '''landing.land''':
<source lang="xml"><deroute block="landing.land"/></source>
will jump to this procedure block.

Suppose you have a go-around condition in your landing procedure. You would write it
<source lang="xml"><exception cond="..." deroute="go-around"/></source>
then you must link this block exit with one of your block (e.g. <tt>Standby</tt>). So you would include the procedure as follows:
<source lang="xml">
<include name="landing" procedure="landing.xml">
<with from="go-around" to="Standby"/>
</include>
</source>

== Tips and Tricks ==

There are many ways to skin a cat just as there are many ways to craft your flight plan. Following the best practices tips can save you from a lot of frustration and mishap.

* Simulate your flight plan before taking it to the sky. Flight plans should always be carefully tested prior to flight, take a look at the [[Simulation|simulation]] page for details on how to simulate your plan.
* Make an subdirectory in the Flight_plan directory with your own name and add your flight plans there. Make sure that the location of the DTD is correct, e.g by using relative directory double dots as in <tt><!DOCTYPE flight_plan SYSTEM "../flight_plan.dtd"></tt>

* Take a good look at other flight plans included with Paparazzi. To learn from example flight plans please visit the [[Flight_Plan_Examples|flight plan examples]] page
* There are several option to build failsafe features into you flightplan, [[Failsafe|for some examples visit the Failsafe page]].
* Some flight plan examples define waypoint locations using relative coordinates. These are relative positions from the fixed lat and lon in the header of the flight plan. When simulating your flight plan the aircraft always use the lat/lon as defined in the flight plan since a regular simulation has no notion of you current position of you local PC where you simulate on. This is something to keep in mind if you test your flight plan in real flights.

[[Category:Software]] [[Category:User_Documentation]]

Control Loops

2014-05-10T05:37:23Z

Alonsoac: /* mode: GUIDANCE_V_MODE_HOVER */

This page presents the default control loops used by the Paparazzi airborne code for navigation, guidance and control.

= General Information =

All the possible combinations of control loops might not be fully detailed. This is especially the case when using extra features such as '''AGR_CLIMB''', '''STRONG_WIND''', etc.

In the following diagrams, the block '''s''' is used for the '''derivative''' function and '''1/s''' is used for the '''integrator''' function.

The variables' names are the one used in the airborne code (written in '''C'''). Most of this name can the used capitalized in the [[Airframe Configuration]] file in order to define the default value of these variables. If in capital letters in the diagrams, the value is fixed and cannot be changed using [[Settings]] mechanism.

The best way to determine vehicle behavior is to look at the source code. For determining which control loops are engaged by various flight plan blocks and stages, it may be helpful to look at sw/airborne/subsystems/nav.h and the generated flightplan file in var/<AIRCRAFT_NAME>/generated/flight_plan.h.

= Fixed-wing autopilot =

== Global view ==

[[Image:Diagram_general.png|General overview]]

The elements '''servos''', '''rc_commands''', '''commands''' and '''command_laws''' correspond to specific section of the [[Airframe Configuration]] file. Most of the code located in these blocks is generated from the xml of th configuration file.

The value '''+/-9600''' correspond to '''+/-MAX_PPRZ'''. This '''pprz''' unit is used as a normalized internal unit for input and output values of the '''control_laws''' block.

== Navigation loop ==

The navigation loop is located in '''sw/airborne/subsystems/nav.*'''. The navigation routines are called from the [[Flight Plans]]. Advanced navigation routines are in '''sw/airborne/subsystems/navigation/'''.

== Course loop ==

[[Image:Diagram_course_loop.png|Course loop]]

The course loop is the upper stage of the horizontal control.
It is located in '''sw/airborne/firmwares/fixedwing/stabilization/stabilization_attitude.c''' (formerly fw_h_ctl.c).

== Roll loop ==

[[Image:Diagram_roll_loop.png|Roll loop]]

The roll loop is the lower stage of the horizontal control and is used for lateral attitude stabilization. It is located in '''stabilization_attitude.c'''.
If <tt>H_CTL_ROLL_ATTITUDE_GAIN</tt> is undefined, the code will fallback to a attitude-only loop, where <tt>estimator_p</tt> is disregarded and the gain for <tt>estimator_phi</tt> is <tt>H_CTL_ROLL_PGAIN</tt>.

Note; estimator_phi is the measured roll angle, and estimator_p is the measured rate of change in roll angle.

== Altitude loop ==

[[Image:Diagram_altitude_loop.png|Altitude loop]]

The altitude loop is the upper stage of the vertical control.
It is located in '''sw/airborne/firmwares/fixedwing/guidance/guidance_v.c''' (formerly fw_v_ctl.c)
If AGR_CLIMB is defined in the airframe file, the altitude loop also sets the v_ctl_auto_throttle_submode for use in the climb loop.

== Auto Throttle and Auto Pitch climb loops ==

Two climb loops are available. The are called from the [[Flight Plans#Navigation_modes|flight plan]] by changing the vertical navigation mode. The default mode is '''Auto Throttle'''. The '''Auto Pitch''' loop is only available if '''V_CTL_AUTO_PITCH_PGAIN''' is defined. Only one loop is active at a time. Note also that if '''USE_AIRSPEED''' is defined, then the Auto Throttle loop is replaced by the Auto Airspeed loop, see [Control_Loops#Control_loops_using_Airspeed_Sensor|below].

=== Auto throttle loop ===
[[Image:Diagram_auto_throttle_loop.png|Auto Throttle climb loop]]

If '''AGR_CLIMB''' is defined, then the auto throttle submode is used to determine setpoint outputs. This may be the standard control loop outputs, the aggressive outputs (static setpoints defined in airframe file) or a blend of both.

=== Auto pitch loop ===
[[Image:Diagram_auto_pitch_loop.png|924px|Auto Pitch climb loop]]

The climb loop is the intermediate stage of the vertical control. It is located in '''guidance_v.c'''.

== Pitch loop ==

[[Image:Diagram_pitch_loop.png|Pitch loop]]

The pitch loop is the lower stage of the vertical control and is used for longitudinal attitude stabilization. It is located in '''stabilization_attitude.c'''.
The first sum block of the diagram is not completely accurate. The input to the pitch stabilization loop is h_ctl_pitch_setpoint, though v_ctl_pitch_of_vz is not a direct input. Rather h_ctl_pitch_setpoint is assigned in the main autopilot loop from nav_pitch, in general (in auto1, it is assigned directly from the pitch r/c input). The nav_pitch value is obtained in a few ways, depending on which control loop(s) are active. If auto throttle is active, nav_pitch is the sum of v_ctl_pitch_of_vz and a fixed setpoint defined using the pitch attribute in the flightplan. If AGR_CLIMB is set, nav_pitch is either the airframe file defined ascent and descent pitch setpoints, the standard sum, or a blend of each. If auto pitch is active, nav_pitch is defined directly from the output of that loop. If airspeed is active, nav_pitch is defined in the auto airspeed pitch loop.

== Control loops using Airspeed Sensor ==

Adding an airspeed sensor measures actual airspeed resulting in better throttle control and aircraft performance especially in windy conditions. The use of an airspeed sensor is described [[Airspeed_sensor|here]].

[[Image:Diagram_auto_airspeed_loop.png|Auto Airspeed climb loop]]

The auto airspeed cascaded control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop; it is engaged in the same manner in the flight plan. It is located in '''guidance_v.c'''.

== Energy Control loops using Airspeed Sensor ==

Total Energy (speed + height) control for fixed wing vehicles developed by the [http://www.mavlab.info MAVLab] of the Technical [http://www.tudelft.nl University] of Delft. An airspeed sensor is mandatory.
The energy control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop and is located in '''energy_ctrl.c'''.

[[Image:Energycontrol.png|Energy Control loop]]

= Rotorcraft autopilot =

The schemes of the multi-rotor autopilot were made with the drawing tool from Google docs. To edit the drawings, send an e-mail to microuav@gmail.com.

== Overview ==

[[Image:Booz_autopilot_globalview.png]]

The code for this autopilot is located in '''sw/airborne/firmwares/rotorcraft'''.

== Vertical Control ==

Depending on the general mode selected, one of the following vertical modes is used.

=== mode: GUIDANCE_V_MODE_RC_CLIMB (speed control) ===
[[File:Rc_climb.png]]

=== mode: GUIDANCE_V_MODE_CLIMB (speed control) ===
[[File:Climb.png]]

=== mode: GUIDANCE_V_MODE_HOVER (altitude control) ===
[[File:Z_hold.png]]

=== mode: GUIDANCE_V_MODE_NAV ===

== Reference generators ==

z relates to altitude, zd to speed and zdd to acceleration

=== from z set point (desired altitude) ===

[[Image:Refgen_from_z_sp.png]]

=== from z dot set point (desired speed) ===

[[Image:Booz_refgen_zdot.png]]]

The '''adjust accel''' is a simple algorithm to set acceleration to zero when velocity reaches boundaries.

The code for these reference generators is located in '''guidance/guidance_v_ref.c'''

== Vertical loop ==
[[File:vertical_loop_V40.png]]

the source code is located in '''guidance\guidance_v.c'''

NOMINAL_HOVER_THROTTLE is the nominal thrust when hovering. It's calculated by default by an adaptative controller, in '''guidance\guidance_v_adpt.h'''.

Instead of the adaptative controller, NOMINAL_HOVER_TROTTLE can be set manually in the Airframe configuration file with:

<define name="NOMINAL_HOVER_THROTTLE" value="0.5"/>

The value is found after flying manually in hover: NOMINAL_HOVER_THROTTLE= THRUST/MAX_PPRZ (THRUST:mean value of ROTORCRAFT_FP THRUST message in hover, MAX_PPRZ:9600)

In most cases it makes more sense to not specify this explicitly and use the adaptive controller

== Horizontal Control ==

Depending on the general mode selected, one of the following horizontal modes is used.

=== mode: GUIDANCE_H_MODE_RATE ===
[[Image:GUIDANCE_H_MODE_RATE.png]]

=== mode: GUIDANCE_H_MODE_ATTITUDE ===
[[Image:GUIDANCE_H_MODE_ATTITUDE.png]]

=== mode: GUIDANCE_H_MODE_HOVER ===

When this mode is entered, the measured position at the instance of initiation is set as guidance_h_pos_sp. This means that the rotorcraft will hover on that position.

[[Image:GUIDANCE_H_MODE_HOVER.png]]

rotation to body:

<math>\phi_{cmd_{body}}= -\sin \psi \cdot x_{cmd_{earth}} + \cos \psi \cdot y_{cmd_{earth}} </math>

<math>\theta_{cmd_{body}}= -\left( \cos \psi \cdot x_{cmd_{earth}} + \sin \psi \cdot y_{cmd_{earth}} \right) </math>

=== mode: GUIDANCE_H_MODE_NAV ===

The set points guidance_h_pos_sp (x and y coordinates) are obtained from the navigation carrot after a 'NED of ENU' transformation:

guidance_h_pos_sp.x = navigation_carrot.y

guidance_h_pos_sp.y = navigation_carrot.x

[[Image:GUIDANCE_H_MODE_NAV.png]]

Rotation to body is the same as in GUIDANCE_H_MODE_HOVER.

== Reference generators ==

=== from euler attitude angle set point ===

[[Image:Booz_refgen_att.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''stabilization/stabilization_attitude_ref_euler_int.c'''.

=== from angular rate set point ===

[[Image:Booz_refgen_rate.png]]

The code for this reference generator is located in '''stabilization/stabilization_rate.c'''.

=== from pos set point ===

[[Image:Booz_refgen_xy_sp.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''guidance/guidance_h_ref.h'''.

== Attitude loop ==

[[Image:attitude_loop.png]]

The code for this loop is located in '''stabilization/stabilization_attitude_euler_int.c'''.

== Rate loop ==

[[Image:rate_loop.png]]

The code for this loop is located in '''stabilization/stabilization_rate.c'''.

== Guidance horizontal hover loop ==

[[Image:guidance_horizontal_hover.png]]

The code for this loop is located in '''guidance/guidance_h.c'''.

== Guidance horizontal navigation loop ==

[[Image:Booz_horizontal_nav.png]]

The code for this loop is located in '''guidance/guidance_h.c'''

[[Category:Software]] [[Category:Developer_Documentation]]

Control Loops

2014-05-10T05:37:07Z

Alonsoac: /* mode: GUIDANCE_V_MODE_CLIMB */

This page presents the default control loops used by the Paparazzi airborne code for navigation, guidance and control.

= General Information =

All the possible combinations of control loops might not be fully detailed. This is especially the case when using extra features such as '''AGR_CLIMB''', '''STRONG_WIND''', etc.

In the following diagrams, the block '''s''' is used for the '''derivative''' function and '''1/s''' is used for the '''integrator''' function.

The variables' names are the one used in the airborne code (written in '''C'''). Most of this name can the used capitalized in the [[Airframe Configuration]] file in order to define the default value of these variables. If in capital letters in the diagrams, the value is fixed and cannot be changed using [[Settings]] mechanism.

The best way to determine vehicle behavior is to look at the source code. For determining which control loops are engaged by various flight plan blocks and stages, it may be helpful to look at sw/airborne/subsystems/nav.h and the generated flightplan file in var/<AIRCRAFT_NAME>/generated/flight_plan.h.

= Fixed-wing autopilot =

== Global view ==

[[Image:Diagram_general.png|General overview]]

The elements '''servos''', '''rc_commands''', '''commands''' and '''command_laws''' correspond to specific section of the [[Airframe Configuration]] file. Most of the code located in these blocks is generated from the xml of th configuration file.

The value '''+/-9600''' correspond to '''+/-MAX_PPRZ'''. This '''pprz''' unit is used as a normalized internal unit for input and output values of the '''control_laws''' block.

== Navigation loop ==

The navigation loop is located in '''sw/airborne/subsystems/nav.*'''. The navigation routines are called from the [[Flight Plans]]. Advanced navigation routines are in '''sw/airborne/subsystems/navigation/'''.

== Course loop ==

[[Image:Diagram_course_loop.png|Course loop]]

The course loop is the upper stage of the horizontal control.
It is located in '''sw/airborne/firmwares/fixedwing/stabilization/stabilization_attitude.c''' (formerly fw_h_ctl.c).

== Roll loop ==

[[Image:Diagram_roll_loop.png|Roll loop]]

The roll loop is the lower stage of the horizontal control and is used for lateral attitude stabilization. It is located in '''stabilization_attitude.c'''.
If <tt>H_CTL_ROLL_ATTITUDE_GAIN</tt> is undefined, the code will fallback to a attitude-only loop, where <tt>estimator_p</tt> is disregarded and the gain for <tt>estimator_phi</tt> is <tt>H_CTL_ROLL_PGAIN</tt>.

Note; estimator_phi is the measured roll angle, and estimator_p is the measured rate of change in roll angle.

== Altitude loop ==

[[Image:Diagram_altitude_loop.png|Altitude loop]]

The altitude loop is the upper stage of the vertical control.
It is located in '''sw/airborne/firmwares/fixedwing/guidance/guidance_v.c''' (formerly fw_v_ctl.c)
If AGR_CLIMB is defined in the airframe file, the altitude loop also sets the v_ctl_auto_throttle_submode for use in the climb loop.

== Auto Throttle and Auto Pitch climb loops ==

Two climb loops are available. The are called from the [[Flight Plans#Navigation_modes|flight plan]] by changing the vertical navigation mode. The default mode is '''Auto Throttle'''. The '''Auto Pitch''' loop is only available if '''V_CTL_AUTO_PITCH_PGAIN''' is defined. Only one loop is active at a time. Note also that if '''USE_AIRSPEED''' is defined, then the Auto Throttle loop is replaced by the Auto Airspeed loop, see [Control_Loops#Control_loops_using_Airspeed_Sensor|below].

=== Auto throttle loop ===
[[Image:Diagram_auto_throttle_loop.png|Auto Throttle climb loop]]

If '''AGR_CLIMB''' is defined, then the auto throttle submode is used to determine setpoint outputs. This may be the standard control loop outputs, the aggressive outputs (static setpoints defined in airframe file) or a blend of both.

=== Auto pitch loop ===
[[Image:Diagram_auto_pitch_loop.png|924px|Auto Pitch climb loop]]

The climb loop is the intermediate stage of the vertical control. It is located in '''guidance_v.c'''.

== Pitch loop ==

[[Image:Diagram_pitch_loop.png|Pitch loop]]

The pitch loop is the lower stage of the vertical control and is used for longitudinal attitude stabilization. It is located in '''stabilization_attitude.c'''.
The first sum block of the diagram is not completely accurate. The input to the pitch stabilization loop is h_ctl_pitch_setpoint, though v_ctl_pitch_of_vz is not a direct input. Rather h_ctl_pitch_setpoint is assigned in the main autopilot loop from nav_pitch, in general (in auto1, it is assigned directly from the pitch r/c input). The nav_pitch value is obtained in a few ways, depending on which control loop(s) are active. If auto throttle is active, nav_pitch is the sum of v_ctl_pitch_of_vz and a fixed setpoint defined using the pitch attribute in the flightplan. If AGR_CLIMB is set, nav_pitch is either the airframe file defined ascent and descent pitch setpoints, the standard sum, or a blend of each. If auto pitch is active, nav_pitch is defined directly from the output of that loop. If airspeed is active, nav_pitch is defined in the auto airspeed pitch loop.

== Control loops using Airspeed Sensor ==

Adding an airspeed sensor measures actual airspeed resulting in better throttle control and aircraft performance especially in windy conditions. The use of an airspeed sensor is described [[Airspeed_sensor|here]].

[[Image:Diagram_auto_airspeed_loop.png|Auto Airspeed climb loop]]

The auto airspeed cascaded control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop; it is engaged in the same manner in the flight plan. It is located in '''guidance_v.c'''.

== Energy Control loops using Airspeed Sensor ==

Total Energy (speed + height) control for fixed wing vehicles developed by the [http://www.mavlab.info MAVLab] of the Technical [http://www.tudelft.nl University] of Delft. An airspeed sensor is mandatory.
The energy control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop and is located in '''energy_ctrl.c'''.

[[Image:Energycontrol.png|Energy Control loop]]

= Rotorcraft autopilot =

The schemes of the multi-rotor autopilot were made with the drawing tool from Google docs. To edit the drawings, send an e-mail to microuav@gmail.com.

== Overview ==

[[Image:Booz_autopilot_globalview.png]]

The code for this autopilot is located in '''sw/airborne/firmwares/rotorcraft'''.

== Vertical Control ==

Depending on the general mode selected, one of the following vertical modes is used.

=== mode: GUIDANCE_V_MODE_RC_CLIMB (speed control) ===
[[File:Rc_climb.png]]

=== mode: GUIDANCE_V_MODE_CLIMB (speed control) ===
[[File:Climb.png]]

=== mode: GUIDANCE_V_MODE_HOVER ===
[[File:Z_hold.png]]

=== mode: GUIDANCE_V_MODE_NAV ===

== Reference generators ==

z relates to altitude, zd to speed and zdd to acceleration

=== from z set point (desired altitude) ===

[[Image:Refgen_from_z_sp.png]]

=== from z dot set point (desired speed) ===

[[Image:Booz_refgen_zdot.png]]]

The '''adjust accel''' is a simple algorithm to set acceleration to zero when velocity reaches boundaries.

The code for these reference generators is located in '''guidance/guidance_v_ref.c'''

== Vertical loop ==
[[File:vertical_loop_V40.png]]

the source code is located in '''guidance\guidance_v.c'''

NOMINAL_HOVER_THROTTLE is the nominal thrust when hovering. It's calculated by default by an adaptative controller, in '''guidance\guidance_v_adpt.h'''.

Instead of the adaptative controller, NOMINAL_HOVER_TROTTLE can be set manually in the Airframe configuration file with:

<define name="NOMINAL_HOVER_THROTTLE" value="0.5"/>

The value is found after flying manually in hover: NOMINAL_HOVER_THROTTLE= THRUST/MAX_PPRZ (THRUST:mean value of ROTORCRAFT_FP THRUST message in hover, MAX_PPRZ:9600)

In most cases it makes more sense to not specify this explicitly and use the adaptive controller

== Horizontal Control ==

Depending on the general mode selected, one of the following horizontal modes is used.

=== mode: GUIDANCE_H_MODE_RATE ===
[[Image:GUIDANCE_H_MODE_RATE.png]]

=== mode: GUIDANCE_H_MODE_ATTITUDE ===
[[Image:GUIDANCE_H_MODE_ATTITUDE.png]]

=== mode: GUIDANCE_H_MODE_HOVER ===

When this mode is entered, the measured position at the instance of initiation is set as guidance_h_pos_sp. This means that the rotorcraft will hover on that position.

[[Image:GUIDANCE_H_MODE_HOVER.png]]

rotation to body:

<math>\phi_{cmd_{body}}= -\sin \psi \cdot x_{cmd_{earth}} + \cos \psi \cdot y_{cmd_{earth}} </math>

<math>\theta_{cmd_{body}}= -\left( \cos \psi \cdot x_{cmd_{earth}} + \sin \psi \cdot y_{cmd_{earth}} \right) </math>

=== mode: GUIDANCE_H_MODE_NAV ===

The set points guidance_h_pos_sp (x and y coordinates) are obtained from the navigation carrot after a 'NED of ENU' transformation:

guidance_h_pos_sp.x = navigation_carrot.y

guidance_h_pos_sp.y = navigation_carrot.x

[[Image:GUIDANCE_H_MODE_NAV.png]]

Rotation to body is the same as in GUIDANCE_H_MODE_HOVER.

== Reference generators ==

=== from euler attitude angle set point ===

[[Image:Booz_refgen_att.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''stabilization/stabilization_attitude_ref_euler_int.c'''.

=== from angular rate set point ===

[[Image:Booz_refgen_rate.png]]

The code for this reference generator is located in '''stabilization/stabilization_rate.c'''.

=== from pos set point ===

[[Image:Booz_refgen_xy_sp.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''guidance/guidance_h_ref.h'''.

== Attitude loop ==

[[Image:attitude_loop.png]]

The code for this loop is located in '''stabilization/stabilization_attitude_euler_int.c'''.

== Rate loop ==

[[Image:rate_loop.png]]

The code for this loop is located in '''stabilization/stabilization_rate.c'''.

== Guidance horizontal hover loop ==

[[Image:guidance_horizontal_hover.png]]

The code for this loop is located in '''guidance/guidance_h.c'''.

== Guidance horizontal navigation loop ==

[[Image:Booz_horizontal_nav.png]]

The code for this loop is located in '''guidance/guidance_h.c'''

[[Category:Software]] [[Category:Developer_Documentation]]

Control Loops

2014-05-10T05:36:53Z

Alonsoac: /* mode: GUIDANCE_V_MODE_RC_CLIMB */

This page presents the default control loops used by the Paparazzi airborne code for navigation, guidance and control.

= General Information =

All the possible combinations of control loops might not be fully detailed. This is especially the case when using extra features such as '''AGR_CLIMB''', '''STRONG_WIND''', etc.

In the following diagrams, the block '''s''' is used for the '''derivative''' function and '''1/s''' is used for the '''integrator''' function.

The variables' names are the one used in the airborne code (written in '''C'''). Most of this name can the used capitalized in the [[Airframe Configuration]] file in order to define the default value of these variables. If in capital letters in the diagrams, the value is fixed and cannot be changed using [[Settings]] mechanism.

The best way to determine vehicle behavior is to look at the source code. For determining which control loops are engaged by various flight plan blocks and stages, it may be helpful to look at sw/airborne/subsystems/nav.h and the generated flightplan file in var/<AIRCRAFT_NAME>/generated/flight_plan.h.

= Fixed-wing autopilot =

== Global view ==

[[Image:Diagram_general.png|General overview]]

The elements '''servos''', '''rc_commands''', '''commands''' and '''command_laws''' correspond to specific section of the [[Airframe Configuration]] file. Most of the code located in these blocks is generated from the xml of th configuration file.

The value '''+/-9600''' correspond to '''+/-MAX_PPRZ'''. This '''pprz''' unit is used as a normalized internal unit for input and output values of the '''control_laws''' block.

== Navigation loop ==

The navigation loop is located in '''sw/airborne/subsystems/nav.*'''. The navigation routines are called from the [[Flight Plans]]. Advanced navigation routines are in '''sw/airborne/subsystems/navigation/'''.

== Course loop ==

[[Image:Diagram_course_loop.png|Course loop]]

The course loop is the upper stage of the horizontal control.
It is located in '''sw/airborne/firmwares/fixedwing/stabilization/stabilization_attitude.c''' (formerly fw_h_ctl.c).

== Roll loop ==

[[Image:Diagram_roll_loop.png|Roll loop]]

The roll loop is the lower stage of the horizontal control and is used for lateral attitude stabilization. It is located in '''stabilization_attitude.c'''.
If <tt>H_CTL_ROLL_ATTITUDE_GAIN</tt> is undefined, the code will fallback to a attitude-only loop, where <tt>estimator_p</tt> is disregarded and the gain for <tt>estimator_phi</tt> is <tt>H_CTL_ROLL_PGAIN</tt>.

Note; estimator_phi is the measured roll angle, and estimator_p is the measured rate of change in roll angle.

== Altitude loop ==

[[Image:Diagram_altitude_loop.png|Altitude loop]]

The altitude loop is the upper stage of the vertical control.
It is located in '''sw/airborne/firmwares/fixedwing/guidance/guidance_v.c''' (formerly fw_v_ctl.c)
If AGR_CLIMB is defined in the airframe file, the altitude loop also sets the v_ctl_auto_throttle_submode for use in the climb loop.

== Auto Throttle and Auto Pitch climb loops ==

Two climb loops are available. The are called from the [[Flight Plans#Navigation_modes|flight plan]] by changing the vertical navigation mode. The default mode is '''Auto Throttle'''. The '''Auto Pitch''' loop is only available if '''V_CTL_AUTO_PITCH_PGAIN''' is defined. Only one loop is active at a time. Note also that if '''USE_AIRSPEED''' is defined, then the Auto Throttle loop is replaced by the Auto Airspeed loop, see [Control_Loops#Control_loops_using_Airspeed_Sensor|below].

=== Auto throttle loop ===
[[Image:Diagram_auto_throttle_loop.png|Auto Throttle climb loop]]

If '''AGR_CLIMB''' is defined, then the auto throttle submode is used to determine setpoint outputs. This may be the standard control loop outputs, the aggressive outputs (static setpoints defined in airframe file) or a blend of both.

=== Auto pitch loop ===
[[Image:Diagram_auto_pitch_loop.png|924px|Auto Pitch climb loop]]

The climb loop is the intermediate stage of the vertical control. It is located in '''guidance_v.c'''.

== Pitch loop ==

[[Image:Diagram_pitch_loop.png|Pitch loop]]

The pitch loop is the lower stage of the vertical control and is used for longitudinal attitude stabilization. It is located in '''stabilization_attitude.c'''.
The first sum block of the diagram is not completely accurate. The input to the pitch stabilization loop is h_ctl_pitch_setpoint, though v_ctl_pitch_of_vz is not a direct input. Rather h_ctl_pitch_setpoint is assigned in the main autopilot loop from nav_pitch, in general (in auto1, it is assigned directly from the pitch r/c input). The nav_pitch value is obtained in a few ways, depending on which control loop(s) are active. If auto throttle is active, nav_pitch is the sum of v_ctl_pitch_of_vz and a fixed setpoint defined using the pitch attribute in the flightplan. If AGR_CLIMB is set, nav_pitch is either the airframe file defined ascent and descent pitch setpoints, the standard sum, or a blend of each. If auto pitch is active, nav_pitch is defined directly from the output of that loop. If airspeed is active, nav_pitch is defined in the auto airspeed pitch loop.

== Control loops using Airspeed Sensor ==

Adding an airspeed sensor measures actual airspeed resulting in better throttle control and aircraft performance especially in windy conditions. The use of an airspeed sensor is described [[Airspeed_sensor|here]].

[[Image:Diagram_auto_airspeed_loop.png|Auto Airspeed climb loop]]

The auto airspeed cascaded control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop; it is engaged in the same manner in the flight plan. It is located in '''guidance_v.c'''.

== Energy Control loops using Airspeed Sensor ==

Total Energy (speed + height) control for fixed wing vehicles developed by the [http://www.mavlab.info MAVLab] of the Technical [http://www.tudelft.nl University] of Delft. An airspeed sensor is mandatory.
The energy control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop and is located in '''energy_ctrl.c'''.

[[Image:Energycontrol.png|Energy Control loop]]

= Rotorcraft autopilot =

The schemes of the multi-rotor autopilot were made with the drawing tool from Google docs. To edit the drawings, send an e-mail to microuav@gmail.com.

== Overview ==

[[Image:Booz_autopilot_globalview.png]]

The code for this autopilot is located in '''sw/airborne/firmwares/rotorcraft'''.

== Vertical Control ==

Depending on the general mode selected, one of the following vertical modes is used.

=== mode: GUIDANCE_V_MODE_RC_CLIMB (speed control) ===
[[File:Rc_climb.png]]

=== mode: GUIDANCE_V_MODE_CLIMB ===
[[File:Climb.png]]

=== mode: GUIDANCE_V_MODE_HOVER ===
[[File:Z_hold.png]]

=== mode: GUIDANCE_V_MODE_NAV ===

== Reference generators ==

z relates to altitude, zd to speed and zdd to acceleration

=== from z set point (desired altitude) ===

[[Image:Refgen_from_z_sp.png]]

=== from z dot set point (desired speed) ===

[[Image:Booz_refgen_zdot.png]]]

The '''adjust accel''' is a simple algorithm to set acceleration to zero when velocity reaches boundaries.

The code for these reference generators is located in '''guidance/guidance_v_ref.c'''

== Vertical loop ==
[[File:vertical_loop_V40.png]]

the source code is located in '''guidance\guidance_v.c'''

NOMINAL_HOVER_THROTTLE is the nominal thrust when hovering. It's calculated by default by an adaptative controller, in '''guidance\guidance_v_adpt.h'''.

Instead of the adaptative controller, NOMINAL_HOVER_TROTTLE can be set manually in the Airframe configuration file with:

<define name="NOMINAL_HOVER_THROTTLE" value="0.5"/>

The value is found after flying manually in hover: NOMINAL_HOVER_THROTTLE= THRUST/MAX_PPRZ (THRUST:mean value of ROTORCRAFT_FP THRUST message in hover, MAX_PPRZ:9600)

In most cases it makes more sense to not specify this explicitly and use the adaptive controller

== Horizontal Control ==

Depending on the general mode selected, one of the following horizontal modes is used.

=== mode: GUIDANCE_H_MODE_RATE ===
[[Image:GUIDANCE_H_MODE_RATE.png]]

=== mode: GUIDANCE_H_MODE_ATTITUDE ===
[[Image:GUIDANCE_H_MODE_ATTITUDE.png]]

=== mode: GUIDANCE_H_MODE_HOVER ===

When this mode is entered, the measured position at the instance of initiation is set as guidance_h_pos_sp. This means that the rotorcraft will hover on that position.

[[Image:GUIDANCE_H_MODE_HOVER.png]]

rotation to body:

<math>\phi_{cmd_{body}}= -\sin \psi \cdot x_{cmd_{earth}} + \cos \psi \cdot y_{cmd_{earth}} </math>

<math>\theta_{cmd_{body}}= -\left( \cos \psi \cdot x_{cmd_{earth}} + \sin \psi \cdot y_{cmd_{earth}} \right) </math>

=== mode: GUIDANCE_H_MODE_NAV ===

The set points guidance_h_pos_sp (x and y coordinates) are obtained from the navigation carrot after a 'NED of ENU' transformation:

guidance_h_pos_sp.x = navigation_carrot.y

guidance_h_pos_sp.y = navigation_carrot.x

[[Image:GUIDANCE_H_MODE_NAV.png]]

Rotation to body is the same as in GUIDANCE_H_MODE_HOVER.

== Reference generators ==

=== from euler attitude angle set point ===

[[Image:Booz_refgen_att.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''stabilization/stabilization_attitude_ref_euler_int.c'''.

=== from angular rate set point ===

[[Image:Booz_refgen_rate.png]]

The code for this reference generator is located in '''stabilization/stabilization_rate.c'''.

=== from pos set point ===

[[Image:Booz_refgen_xy_sp.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''guidance/guidance_h_ref.h'''.

== Attitude loop ==

[[Image:attitude_loop.png]]

The code for this loop is located in '''stabilization/stabilization_attitude_euler_int.c'''.

== Rate loop ==

[[Image:rate_loop.png]]

The code for this loop is located in '''stabilization/stabilization_rate.c'''.

== Guidance horizontal hover loop ==

[[Image:guidance_horizontal_hover.png]]

The code for this loop is located in '''guidance/guidance_h.c'''.

== Guidance horizontal navigation loop ==

[[Image:Booz_horizontal_nav.png]]

The code for this loop is located in '''guidance/guidance_h.c'''

[[Category:Software]] [[Category:Developer_Documentation]]

Control Loops

2014-05-10T05:32:58Z

Alonsoac: /* from z dot set point (desired speed) */

This page presents the default control loops used by the Paparazzi airborne code for navigation, guidance and control.

= General Information =

All the possible combinations of control loops might not be fully detailed. This is especially the case when using extra features such as '''AGR_CLIMB''', '''STRONG_WIND''', etc.

In the following diagrams, the block '''s''' is used for the '''derivative''' function and '''1/s''' is used for the '''integrator''' function.

The variables' names are the one used in the airborne code (written in '''C'''). Most of this name can the used capitalized in the [[Airframe Configuration]] file in order to define the default value of these variables. If in capital letters in the diagrams, the value is fixed and cannot be changed using [[Settings]] mechanism.

The best way to determine vehicle behavior is to look at the source code. For determining which control loops are engaged by various flight plan blocks and stages, it may be helpful to look at sw/airborne/subsystems/nav.h and the generated flightplan file in var/<AIRCRAFT_NAME>/generated/flight_plan.h.

= Fixed-wing autopilot =

== Global view ==

[[Image:Diagram_general.png|General overview]]

The elements '''servos''', '''rc_commands''', '''commands''' and '''command_laws''' correspond to specific section of the [[Airframe Configuration]] file. Most of the code located in these blocks is generated from the xml of th configuration file.

The value '''+/-9600''' correspond to '''+/-MAX_PPRZ'''. This '''pprz''' unit is used as a normalized internal unit for input and output values of the '''control_laws''' block.

== Navigation loop ==

The navigation loop is located in '''sw/airborne/subsystems/nav.*'''. The navigation routines are called from the [[Flight Plans]]. Advanced navigation routines are in '''sw/airborne/subsystems/navigation/'''.

== Course loop ==

[[Image:Diagram_course_loop.png|Course loop]]

The course loop is the upper stage of the horizontal control.
It is located in '''sw/airborne/firmwares/fixedwing/stabilization/stabilization_attitude.c''' (formerly fw_h_ctl.c).

== Roll loop ==

[[Image:Diagram_roll_loop.png|Roll loop]]

The roll loop is the lower stage of the horizontal control and is used for lateral attitude stabilization. It is located in '''stabilization_attitude.c'''.
If <tt>H_CTL_ROLL_ATTITUDE_GAIN</tt> is undefined, the code will fallback to a attitude-only loop, where <tt>estimator_p</tt> is disregarded and the gain for <tt>estimator_phi</tt> is <tt>H_CTL_ROLL_PGAIN</tt>.

Note; estimator_phi is the measured roll angle, and estimator_p is the measured rate of change in roll angle.

== Altitude loop ==

[[Image:Diagram_altitude_loop.png|Altitude loop]]

The altitude loop is the upper stage of the vertical control.
It is located in '''sw/airborne/firmwares/fixedwing/guidance/guidance_v.c''' (formerly fw_v_ctl.c)
If AGR_CLIMB is defined in the airframe file, the altitude loop also sets the v_ctl_auto_throttle_submode for use in the climb loop.

== Auto Throttle and Auto Pitch climb loops ==

Two climb loops are available. The are called from the [[Flight Plans#Navigation_modes|flight plan]] by changing the vertical navigation mode. The default mode is '''Auto Throttle'''. The '''Auto Pitch''' loop is only available if '''V_CTL_AUTO_PITCH_PGAIN''' is defined. Only one loop is active at a time. Note also that if '''USE_AIRSPEED''' is defined, then the Auto Throttle loop is replaced by the Auto Airspeed loop, see [Control_Loops#Control_loops_using_Airspeed_Sensor|below].

=== Auto throttle loop ===
[[Image:Diagram_auto_throttle_loop.png|Auto Throttle climb loop]]

If '''AGR_CLIMB''' is defined, then the auto throttle submode is used to determine setpoint outputs. This may be the standard control loop outputs, the aggressive outputs (static setpoints defined in airframe file) or a blend of both.

=== Auto pitch loop ===
[[Image:Diagram_auto_pitch_loop.png|924px|Auto Pitch climb loop]]

The climb loop is the intermediate stage of the vertical control. It is located in '''guidance_v.c'''.

== Pitch loop ==

[[Image:Diagram_pitch_loop.png|Pitch loop]]

The pitch loop is the lower stage of the vertical control and is used for longitudinal attitude stabilization. It is located in '''stabilization_attitude.c'''.
The first sum block of the diagram is not completely accurate. The input to the pitch stabilization loop is h_ctl_pitch_setpoint, though v_ctl_pitch_of_vz is not a direct input. Rather h_ctl_pitch_setpoint is assigned in the main autopilot loop from nav_pitch, in general (in auto1, it is assigned directly from the pitch r/c input). The nav_pitch value is obtained in a few ways, depending on which control loop(s) are active. If auto throttle is active, nav_pitch is the sum of v_ctl_pitch_of_vz and a fixed setpoint defined using the pitch attribute in the flightplan. If AGR_CLIMB is set, nav_pitch is either the airframe file defined ascent and descent pitch setpoints, the standard sum, or a blend of each. If auto pitch is active, nav_pitch is defined directly from the output of that loop. If airspeed is active, nav_pitch is defined in the auto airspeed pitch loop.

== Control loops using Airspeed Sensor ==

Adding an airspeed sensor measures actual airspeed resulting in better throttle control and aircraft performance especially in windy conditions. The use of an airspeed sensor is described [[Airspeed_sensor|here]].

[[Image:Diagram_auto_airspeed_loop.png|Auto Airspeed climb loop]]

The auto airspeed cascaded control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop; it is engaged in the same manner in the flight plan. It is located in '''guidance_v.c'''.

== Energy Control loops using Airspeed Sensor ==

Total Energy (speed + height) control for fixed wing vehicles developed by the [http://www.mavlab.info MAVLab] of the Technical [http://www.tudelft.nl University] of Delft. An airspeed sensor is mandatory.
The energy control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop and is located in '''energy_ctrl.c'''.

[[Image:Energycontrol.png|Energy Control loop]]

= Rotorcraft autopilot =

The schemes of the multi-rotor autopilot were made with the drawing tool from Google docs. To edit the drawings, send an e-mail to microuav@gmail.com.

== Overview ==

[[Image:Booz_autopilot_globalview.png]]

The code for this autopilot is located in '''sw/airborne/firmwares/rotorcraft'''.

== Vertical Control ==

Depending on the general mode selected, one of the following vertical modes is used.

=== mode: GUIDANCE_V_MODE_RC_CLIMB ===
[[File:Rc_climb.png]]

=== mode: GUIDANCE_V_MODE_CLIMB ===
[[File:Climb.png]]

=== mode: GUIDANCE_V_MODE_HOVER ===
[[File:Z_hold.png]]

=== mode: GUIDANCE_V_MODE_NAV ===

== Reference generators ==

z relates to altitude, zd to speed and zdd to acceleration

=== from z set point (desired altitude) ===

[[Image:Refgen_from_z_sp.png]]

=== from z dot set point (desired speed) ===

[[Image:Booz_refgen_zdot.png]]]

The '''adjust accel''' is a simple algorithm to set acceleration to zero when velocity reaches boundaries.

The code for these reference generators is located in '''guidance/guidance_v_ref.c'''

== Vertical loop ==
[[File:vertical_loop_V40.png]]

the source code is located in '''guidance\guidance_v.c'''

NOMINAL_HOVER_THROTTLE is the nominal thrust when hovering. It's calculated by default by an adaptative controller, in '''guidance\guidance_v_adpt.h'''.

Instead of the adaptative controller, NOMINAL_HOVER_TROTTLE can be set manually in the Airframe configuration file with:

<define name="NOMINAL_HOVER_THROTTLE" value="0.5"/>

The value is found after flying manually in hover: NOMINAL_HOVER_THROTTLE= THRUST/MAX_PPRZ (THRUST:mean value of ROTORCRAFT_FP THRUST message in hover, MAX_PPRZ:9600)

In most cases it makes more sense to not specify this explicitly and use the adaptive controller

== Horizontal Control ==

Depending on the general mode selected, one of the following horizontal modes is used.

=== mode: GUIDANCE_H_MODE_RATE ===
[[Image:GUIDANCE_H_MODE_RATE.png]]

=== mode: GUIDANCE_H_MODE_ATTITUDE ===
[[Image:GUIDANCE_H_MODE_ATTITUDE.png]]

=== mode: GUIDANCE_H_MODE_HOVER ===

When this mode is entered, the measured position at the instance of initiation is set as guidance_h_pos_sp. This means that the rotorcraft will hover on that position.

[[Image:GUIDANCE_H_MODE_HOVER.png]]

rotation to body:

<math>\phi_{cmd_{body}}= -\sin \psi \cdot x_{cmd_{earth}} + \cos \psi \cdot y_{cmd_{earth}} </math>

<math>\theta_{cmd_{body}}= -\left( \cos \psi \cdot x_{cmd_{earth}} + \sin \psi \cdot y_{cmd_{earth}} \right) </math>

=== mode: GUIDANCE_H_MODE_NAV ===

The set points guidance_h_pos_sp (x and y coordinates) are obtained from the navigation carrot after a 'NED of ENU' transformation:

guidance_h_pos_sp.x = navigation_carrot.y

guidance_h_pos_sp.y = navigation_carrot.x

[[Image:GUIDANCE_H_MODE_NAV.png]]

Rotation to body is the same as in GUIDANCE_H_MODE_HOVER.

== Reference generators ==

=== from euler attitude angle set point ===

[[Image:Booz_refgen_att.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''stabilization/stabilization_attitude_ref_euler_int.c'''.

=== from angular rate set point ===

[[Image:Booz_refgen_rate.png]]

The code for this reference generator is located in '''stabilization/stabilization_rate.c'''.

=== from pos set point ===

[[Image:Booz_refgen_xy_sp.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''guidance/guidance_h_ref.h'''.

== Attitude loop ==

[[Image:attitude_loop.png]]

The code for this loop is located in '''stabilization/stabilization_attitude_euler_int.c'''.

== Rate loop ==

[[Image:rate_loop.png]]

The code for this loop is located in '''stabilization/stabilization_rate.c'''.

== Guidance horizontal hover loop ==

[[Image:guidance_horizontal_hover.png]]

The code for this loop is located in '''guidance/guidance_h.c'''.

== Guidance horizontal navigation loop ==

[[Image:Booz_horizontal_nav.png]]

The code for this loop is located in '''guidance/guidance_h.c'''

[[Category:Software]] [[Category:Developer_Documentation]]

Control Loops

2014-05-10T05:32:20Z

Alonsoac: /* Reference generators */

This page presents the default control loops used by the Paparazzi airborne code for navigation, guidance and control.

= General Information =

All the possible combinations of control loops might not be fully detailed. This is especially the case when using extra features such as '''AGR_CLIMB''', '''STRONG_WIND''', etc.

In the following diagrams, the block '''s''' is used for the '''derivative''' function and '''1/s''' is used for the '''integrator''' function.

The variables' names are the one used in the airborne code (written in '''C'''). Most of this name can the used capitalized in the [[Airframe Configuration]] file in order to define the default value of these variables. If in capital letters in the diagrams, the value is fixed and cannot be changed using [[Settings]] mechanism.

The best way to determine vehicle behavior is to look at the source code. For determining which control loops are engaged by various flight plan blocks and stages, it may be helpful to look at sw/airborne/subsystems/nav.h and the generated flightplan file in var/<AIRCRAFT_NAME>/generated/flight_plan.h.

= Fixed-wing autopilot =

== Global view ==

[[Image:Diagram_general.png|General overview]]

The elements '''servos''', '''rc_commands''', '''commands''' and '''command_laws''' correspond to specific section of the [[Airframe Configuration]] file. Most of the code located in these blocks is generated from the xml of th configuration file.

The value '''+/-9600''' correspond to '''+/-MAX_PPRZ'''. This '''pprz''' unit is used as a normalized internal unit for input and output values of the '''control_laws''' block.

== Navigation loop ==

The navigation loop is located in '''sw/airborne/subsystems/nav.*'''. The navigation routines are called from the [[Flight Plans]]. Advanced navigation routines are in '''sw/airborne/subsystems/navigation/'''.

== Course loop ==

[[Image:Diagram_course_loop.png|Course loop]]

The course loop is the upper stage of the horizontal control.
It is located in '''sw/airborne/firmwares/fixedwing/stabilization/stabilization_attitude.c''' (formerly fw_h_ctl.c).

== Roll loop ==

[[Image:Diagram_roll_loop.png|Roll loop]]

The roll loop is the lower stage of the horizontal control and is used for lateral attitude stabilization. It is located in '''stabilization_attitude.c'''.
If <tt>H_CTL_ROLL_ATTITUDE_GAIN</tt> is undefined, the code will fallback to a attitude-only loop, where <tt>estimator_p</tt> is disregarded and the gain for <tt>estimator_phi</tt> is <tt>H_CTL_ROLL_PGAIN</tt>.

Note; estimator_phi is the measured roll angle, and estimator_p is the measured rate of change in roll angle.

== Altitude loop ==

[[Image:Diagram_altitude_loop.png|Altitude loop]]

The altitude loop is the upper stage of the vertical control.
It is located in '''sw/airborne/firmwares/fixedwing/guidance/guidance_v.c''' (formerly fw_v_ctl.c)
If AGR_CLIMB is defined in the airframe file, the altitude loop also sets the v_ctl_auto_throttle_submode for use in the climb loop.

== Auto Throttle and Auto Pitch climb loops ==

Two climb loops are available. The are called from the [[Flight Plans#Navigation_modes|flight plan]] by changing the vertical navigation mode. The default mode is '''Auto Throttle'''. The '''Auto Pitch''' loop is only available if '''V_CTL_AUTO_PITCH_PGAIN''' is defined. Only one loop is active at a time. Note also that if '''USE_AIRSPEED''' is defined, then the Auto Throttle loop is replaced by the Auto Airspeed loop, see [Control_Loops#Control_loops_using_Airspeed_Sensor|below].

=== Auto throttle loop ===
[[Image:Diagram_auto_throttle_loop.png|Auto Throttle climb loop]]

If '''AGR_CLIMB''' is defined, then the auto throttle submode is used to determine setpoint outputs. This may be the standard control loop outputs, the aggressive outputs (static setpoints defined in airframe file) or a blend of both.

=== Auto pitch loop ===
[[Image:Diagram_auto_pitch_loop.png|924px|Auto Pitch climb loop]]

The climb loop is the intermediate stage of the vertical control. It is located in '''guidance_v.c'''.

== Pitch loop ==

[[Image:Diagram_pitch_loop.png|Pitch loop]]

The pitch loop is the lower stage of the vertical control and is used for longitudinal attitude stabilization. It is located in '''stabilization_attitude.c'''.
The first sum block of the diagram is not completely accurate. The input to the pitch stabilization loop is h_ctl_pitch_setpoint, though v_ctl_pitch_of_vz is not a direct input. Rather h_ctl_pitch_setpoint is assigned in the main autopilot loop from nav_pitch, in general (in auto1, it is assigned directly from the pitch r/c input). The nav_pitch value is obtained in a few ways, depending on which control loop(s) are active. If auto throttle is active, nav_pitch is the sum of v_ctl_pitch_of_vz and a fixed setpoint defined using the pitch attribute in the flightplan. If AGR_CLIMB is set, nav_pitch is either the airframe file defined ascent and descent pitch setpoints, the standard sum, or a blend of each. If auto pitch is active, nav_pitch is defined directly from the output of that loop. If airspeed is active, nav_pitch is defined in the auto airspeed pitch loop.

== Control loops using Airspeed Sensor ==

Adding an airspeed sensor measures actual airspeed resulting in better throttle control and aircraft performance especially in windy conditions. The use of an airspeed sensor is described [[Airspeed_sensor|here]].

[[Image:Diagram_auto_airspeed_loop.png|Auto Airspeed climb loop]]

The auto airspeed cascaded control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop; it is engaged in the same manner in the flight plan. It is located in '''guidance_v.c'''.

== Energy Control loops using Airspeed Sensor ==

Total Energy (speed + height) control for fixed wing vehicles developed by the [http://www.mavlab.info MAVLab] of the Technical [http://www.tudelft.nl University] of Delft. An airspeed sensor is mandatory.
The energy control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop and is located in '''energy_ctrl.c'''.

[[Image:Energycontrol.png|Energy Control loop]]

= Rotorcraft autopilot =

The schemes of the multi-rotor autopilot were made with the drawing tool from Google docs. To edit the drawings, send an e-mail to microuav@gmail.com.

== Overview ==

[[Image:Booz_autopilot_globalview.png]]

The code for this autopilot is located in '''sw/airborne/firmwares/rotorcraft'''.

== Vertical Control ==

Depending on the general mode selected, one of the following vertical modes is used.

=== mode: GUIDANCE_V_MODE_RC_CLIMB ===
[[File:Rc_climb.png]]

=== mode: GUIDANCE_V_MODE_CLIMB ===
[[File:Climb.png]]

=== mode: GUIDANCE_V_MODE_HOVER ===
[[File:Z_hold.png]]

=== mode: GUIDANCE_V_MODE_NAV ===

== Reference generators ==

z relates to altitude, zd to speed and zdd to acceleration

=== from z set point (desired altitude) ===

[[Image:Refgen_from_z_sp.png]]

=== from z dot set point (desired speed) ===

[[Image:Booz_refgen_zdot.png]]]

The '''adjust accel''' is a simple algorithm to set acceleration to zero when velocity reaches boundaries.

The code for these reference generators is located in '''guidance/guidance_v_ref.h'''

== Vertical loop ==
[[File:vertical_loop_V40.png]]

the source code is located in '''guidance\guidance_v.c'''

NOMINAL_HOVER_THROTTLE is the nominal thrust when hovering. It's calculated by default by an adaptative controller, in '''guidance\guidance_v_adpt.h'''.

Instead of the adaptative controller, NOMINAL_HOVER_TROTTLE can be set manually in the Airframe configuration file with:

<define name="NOMINAL_HOVER_THROTTLE" value="0.5"/>

The value is found after flying manually in hover: NOMINAL_HOVER_THROTTLE= THRUST/MAX_PPRZ (THRUST:mean value of ROTORCRAFT_FP THRUST message in hover, MAX_PPRZ:9600)

In most cases it makes more sense to not specify this explicitly and use the adaptive controller

== Horizontal Control ==

Depending on the general mode selected, one of the following horizontal modes is used.

=== mode: GUIDANCE_H_MODE_RATE ===
[[Image:GUIDANCE_H_MODE_RATE.png]]

=== mode: GUIDANCE_H_MODE_ATTITUDE ===
[[Image:GUIDANCE_H_MODE_ATTITUDE.png]]

=== mode: GUIDANCE_H_MODE_HOVER ===

When this mode is entered, the measured position at the instance of initiation is set as guidance_h_pos_sp. This means that the rotorcraft will hover on that position.

[[Image:GUIDANCE_H_MODE_HOVER.png]]

rotation to body:

<math>\phi_{cmd_{body}}= -\sin \psi \cdot x_{cmd_{earth}} + \cos \psi \cdot y_{cmd_{earth}} </math>

<math>\theta_{cmd_{body}}= -\left( \cos \psi \cdot x_{cmd_{earth}} + \sin \psi \cdot y_{cmd_{earth}} \right) </math>

=== mode: GUIDANCE_H_MODE_NAV ===

The set points guidance_h_pos_sp (x and y coordinates) are obtained from the navigation carrot after a 'NED of ENU' transformation:

guidance_h_pos_sp.x = navigation_carrot.y

guidance_h_pos_sp.y = navigation_carrot.x

[[Image:GUIDANCE_H_MODE_NAV.png]]

Rotation to body is the same as in GUIDANCE_H_MODE_HOVER.

== Reference generators ==

=== from euler attitude angle set point ===

[[Image:Booz_refgen_att.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''stabilization/stabilization_attitude_ref_euler_int.c'''.

=== from angular rate set point ===

[[Image:Booz_refgen_rate.png]]

The code for this reference generator is located in '''stabilization/stabilization_rate.c'''.

=== from pos set point ===

[[Image:Booz_refgen_xy_sp.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''guidance/guidance_h_ref.h'''.

== Attitude loop ==

[[Image:attitude_loop.png]]

The code for this loop is located in '''stabilization/stabilization_attitude_euler_int.c'''.

== Rate loop ==

[[Image:rate_loop.png]]

The code for this loop is located in '''stabilization/stabilization_rate.c'''.

== Guidance horizontal hover loop ==

[[Image:guidance_horizontal_hover.png]]

The code for this loop is located in '''guidance/guidance_h.c'''.

== Guidance horizontal navigation loop ==

[[Image:Booz_horizontal_nav.png]]

The code for this loop is located in '''guidance/guidance_h.c'''

[[Category:Software]] [[Category:Developer_Documentation]]

Control Loops

2014-05-10T05:31:04Z

Alonsoac: /* from z dot set point */

This page presents the default control loops used by the Paparazzi airborne code for navigation, guidance and control.

= General Information =

All the possible combinations of control loops might not be fully detailed. This is especially the case when using extra features such as '''AGR_CLIMB''', '''STRONG_WIND''', etc.

In the following diagrams, the block '''s''' is used for the '''derivative''' function and '''1/s''' is used for the '''integrator''' function.

The variables' names are the one used in the airborne code (written in '''C'''). Most of this name can the used capitalized in the [[Airframe Configuration]] file in order to define the default value of these variables. If in capital letters in the diagrams, the value is fixed and cannot be changed using [[Settings]] mechanism.

The best way to determine vehicle behavior is to look at the source code. For determining which control loops are engaged by various flight plan blocks and stages, it may be helpful to look at sw/airborne/subsystems/nav.h and the generated flightplan file in var/<AIRCRAFT_NAME>/generated/flight_plan.h.

= Fixed-wing autopilot =

== Global view ==

[[Image:Diagram_general.png|General overview]]

The elements '''servos''', '''rc_commands''', '''commands''' and '''command_laws''' correspond to specific section of the [[Airframe Configuration]] file. Most of the code located in these blocks is generated from the xml of th configuration file.

The value '''+/-9600''' correspond to '''+/-MAX_PPRZ'''. This '''pprz''' unit is used as a normalized internal unit for input and output values of the '''control_laws''' block.

== Navigation loop ==

The navigation loop is located in '''sw/airborne/subsystems/nav.*'''. The navigation routines are called from the [[Flight Plans]]. Advanced navigation routines are in '''sw/airborne/subsystems/navigation/'''.

== Course loop ==

[[Image:Diagram_course_loop.png|Course loop]]

The course loop is the upper stage of the horizontal control.
It is located in '''sw/airborne/firmwares/fixedwing/stabilization/stabilization_attitude.c''' (formerly fw_h_ctl.c).

== Roll loop ==

[[Image:Diagram_roll_loop.png|Roll loop]]

The roll loop is the lower stage of the horizontal control and is used for lateral attitude stabilization. It is located in '''stabilization_attitude.c'''.
If <tt>H_CTL_ROLL_ATTITUDE_GAIN</tt> is undefined, the code will fallback to a attitude-only loop, where <tt>estimator_p</tt> is disregarded and the gain for <tt>estimator_phi</tt> is <tt>H_CTL_ROLL_PGAIN</tt>.

Note; estimator_phi is the measured roll angle, and estimator_p is the measured rate of change in roll angle.

== Altitude loop ==

[[Image:Diagram_altitude_loop.png|Altitude loop]]

The altitude loop is the upper stage of the vertical control.
It is located in '''sw/airborne/firmwares/fixedwing/guidance/guidance_v.c''' (formerly fw_v_ctl.c)
If AGR_CLIMB is defined in the airframe file, the altitude loop also sets the v_ctl_auto_throttle_submode for use in the climb loop.

== Auto Throttle and Auto Pitch climb loops ==

Two climb loops are available. The are called from the [[Flight Plans#Navigation_modes|flight plan]] by changing the vertical navigation mode. The default mode is '''Auto Throttle'''. The '''Auto Pitch''' loop is only available if '''V_CTL_AUTO_PITCH_PGAIN''' is defined. Only one loop is active at a time. Note also that if '''USE_AIRSPEED''' is defined, then the Auto Throttle loop is replaced by the Auto Airspeed loop, see [Control_Loops#Control_loops_using_Airspeed_Sensor|below].

=== Auto throttle loop ===
[[Image:Diagram_auto_throttle_loop.png|Auto Throttle climb loop]]

If '''AGR_CLIMB''' is defined, then the auto throttle submode is used to determine setpoint outputs. This may be the standard control loop outputs, the aggressive outputs (static setpoints defined in airframe file) or a blend of both.

=== Auto pitch loop ===
[[Image:Diagram_auto_pitch_loop.png|924px|Auto Pitch climb loop]]

The climb loop is the intermediate stage of the vertical control. It is located in '''guidance_v.c'''.

== Pitch loop ==

[[Image:Diagram_pitch_loop.png|Pitch loop]]

The pitch loop is the lower stage of the vertical control and is used for longitudinal attitude stabilization. It is located in '''stabilization_attitude.c'''.
The first sum block of the diagram is not completely accurate. The input to the pitch stabilization loop is h_ctl_pitch_setpoint, though v_ctl_pitch_of_vz is not a direct input. Rather h_ctl_pitch_setpoint is assigned in the main autopilot loop from nav_pitch, in general (in auto1, it is assigned directly from the pitch r/c input). The nav_pitch value is obtained in a few ways, depending on which control loop(s) are active. If auto throttle is active, nav_pitch is the sum of v_ctl_pitch_of_vz and a fixed setpoint defined using the pitch attribute in the flightplan. If AGR_CLIMB is set, nav_pitch is either the airframe file defined ascent and descent pitch setpoints, the standard sum, or a blend of each. If auto pitch is active, nav_pitch is defined directly from the output of that loop. If airspeed is active, nav_pitch is defined in the auto airspeed pitch loop.

== Control loops using Airspeed Sensor ==

Adding an airspeed sensor measures actual airspeed resulting in better throttle control and aircraft performance especially in windy conditions. The use of an airspeed sensor is described [[Airspeed_sensor|here]].

[[Image:Diagram_auto_airspeed_loop.png|Auto Airspeed climb loop]]

The auto airspeed cascaded control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop; it is engaged in the same manner in the flight plan. It is located in '''guidance_v.c'''.

== Energy Control loops using Airspeed Sensor ==

Total Energy (speed + height) control for fixed wing vehicles developed by the [http://www.mavlab.info MAVLab] of the Technical [http://www.tudelft.nl University] of Delft. An airspeed sensor is mandatory.
The energy control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop and is located in '''energy_ctrl.c'''.

[[Image:Energycontrol.png|Energy Control loop]]

= Rotorcraft autopilot =

The schemes of the multi-rotor autopilot were made with the drawing tool from Google docs. To edit the drawings, send an e-mail to microuav@gmail.com.

== Overview ==

[[Image:Booz_autopilot_globalview.png]]

The code for this autopilot is located in '''sw/airborne/firmwares/rotorcraft'''.

== Vertical Control ==

Depending on the general mode selected, one of the following vertical modes is used.

=== mode: GUIDANCE_V_MODE_RC_CLIMB ===
[[File:Rc_climb.png]]

=== mode: GUIDANCE_V_MODE_CLIMB ===
[[File:Climb.png]]

=== mode: GUIDANCE_V_MODE_HOVER ===
[[File:Z_hold.png]]

=== mode: GUIDANCE_V_MODE_NAV ===

== Reference generators ==

=== from z set point (desired altitude) ===

[[Image:Refgen_from_z_sp.png]]

=== from z dot set point (desired speed) ===

[[Image:Booz_refgen_zdot.png]]]

The '''adjust accel''' is a simple algorithm to set acceleration to zero when velocity reaches boundaries.

The code for these reference generators is located in '''guidance/guidance_v_ref.h'''

== Vertical loop ==
[[File:vertical_loop_V40.png]]

the source code is located in '''guidance\guidance_v.c'''

NOMINAL_HOVER_THROTTLE is the nominal thrust when hovering. It's calculated by default by an adaptative controller, in '''guidance\guidance_v_adpt.h'''.

Instead of the adaptative controller, NOMINAL_HOVER_TROTTLE can be set manually in the Airframe configuration file with:

<define name="NOMINAL_HOVER_THROTTLE" value="0.5"/>

The value is found after flying manually in hover: NOMINAL_HOVER_THROTTLE= THRUST/MAX_PPRZ (THRUST:mean value of ROTORCRAFT_FP THRUST message in hover, MAX_PPRZ:9600)

In most cases it makes more sense to not specify this explicitly and use the adaptive controller

== Horizontal Control ==

Depending on the general mode selected, one of the following horizontal modes is used.

=== mode: GUIDANCE_H_MODE_RATE ===
[[Image:GUIDANCE_H_MODE_RATE.png]]

=== mode: GUIDANCE_H_MODE_ATTITUDE ===
[[Image:GUIDANCE_H_MODE_ATTITUDE.png]]

=== mode: GUIDANCE_H_MODE_HOVER ===

When this mode is entered, the measured position at the instance of initiation is set as guidance_h_pos_sp. This means that the rotorcraft will hover on that position.

[[Image:GUIDANCE_H_MODE_HOVER.png]]

rotation to body:

<math>\phi_{cmd_{body}}= -\sin \psi \cdot x_{cmd_{earth}} + \cos \psi \cdot y_{cmd_{earth}} </math>

<math>\theta_{cmd_{body}}= -\left( \cos \psi \cdot x_{cmd_{earth}} + \sin \psi \cdot y_{cmd_{earth}} \right) </math>

=== mode: GUIDANCE_H_MODE_NAV ===

The set points guidance_h_pos_sp (x and y coordinates) are obtained from the navigation carrot after a 'NED of ENU' transformation:

guidance_h_pos_sp.x = navigation_carrot.y

guidance_h_pos_sp.y = navigation_carrot.x

[[Image:GUIDANCE_H_MODE_NAV.png]]

Rotation to body is the same as in GUIDANCE_H_MODE_HOVER.

== Reference generators ==

=== from euler attitude angle set point ===

[[Image:Booz_refgen_att.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''stabilization/stabilization_attitude_ref_euler_int.c'''.

=== from angular rate set point ===

[[Image:Booz_refgen_rate.png]]

The code for this reference generator is located in '''stabilization/stabilization_rate.c'''.

=== from pos set point ===

[[Image:Booz_refgen_xy_sp.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''guidance/guidance_h_ref.h'''.

== Attitude loop ==

[[Image:attitude_loop.png]]

The code for this loop is located in '''stabilization/stabilization_attitude_euler_int.c'''.

== Rate loop ==

[[Image:rate_loop.png]]

The code for this loop is located in '''stabilization/stabilization_rate.c'''.

== Guidance horizontal hover loop ==

[[Image:guidance_horizontal_hover.png]]

The code for this loop is located in '''guidance/guidance_h.c'''.

== Guidance horizontal navigation loop ==

[[Image:Booz_horizontal_nav.png]]

The code for this loop is located in '''guidance/guidance_h.c'''

[[Category:Software]] [[Category:Developer_Documentation]]

Control Loops

2014-05-10T05:30:37Z

Alonsoac: /* from z set point */

This page presents the default control loops used by the Paparazzi airborne code for navigation, guidance and control.

= General Information =

All the possible combinations of control loops might not be fully detailed. This is especially the case when using extra features such as '''AGR_CLIMB''', '''STRONG_WIND''', etc.

In the following diagrams, the block '''s''' is used for the '''derivative''' function and '''1/s''' is used for the '''integrator''' function.

The variables' names are the one used in the airborne code (written in '''C'''). Most of this name can the used capitalized in the [[Airframe Configuration]] file in order to define the default value of these variables. If in capital letters in the diagrams, the value is fixed and cannot be changed using [[Settings]] mechanism.

The best way to determine vehicle behavior is to look at the source code. For determining which control loops are engaged by various flight plan blocks and stages, it may be helpful to look at sw/airborne/subsystems/nav.h and the generated flightplan file in var/<AIRCRAFT_NAME>/generated/flight_plan.h.

= Fixed-wing autopilot =

== Global view ==

[[Image:Diagram_general.png|General overview]]

The elements '''servos''', '''rc_commands''', '''commands''' and '''command_laws''' correspond to specific section of the [[Airframe Configuration]] file. Most of the code located in these blocks is generated from the xml of th configuration file.

The value '''+/-9600''' correspond to '''+/-MAX_PPRZ'''. This '''pprz''' unit is used as a normalized internal unit for input and output values of the '''control_laws''' block.

== Navigation loop ==

The navigation loop is located in '''sw/airborne/subsystems/nav.*'''. The navigation routines are called from the [[Flight Plans]]. Advanced navigation routines are in '''sw/airborne/subsystems/navigation/'''.

== Course loop ==

[[Image:Diagram_course_loop.png|Course loop]]

The course loop is the upper stage of the horizontal control.
It is located in '''sw/airborne/firmwares/fixedwing/stabilization/stabilization_attitude.c''' (formerly fw_h_ctl.c).

== Roll loop ==

[[Image:Diagram_roll_loop.png|Roll loop]]

The roll loop is the lower stage of the horizontal control and is used for lateral attitude stabilization. It is located in '''stabilization_attitude.c'''.
If <tt>H_CTL_ROLL_ATTITUDE_GAIN</tt> is undefined, the code will fallback to a attitude-only loop, where <tt>estimator_p</tt> is disregarded and the gain for <tt>estimator_phi</tt> is <tt>H_CTL_ROLL_PGAIN</tt>.

Note; estimator_phi is the measured roll angle, and estimator_p is the measured rate of change in roll angle.

== Altitude loop ==

[[Image:Diagram_altitude_loop.png|Altitude loop]]

The altitude loop is the upper stage of the vertical control.
It is located in '''sw/airborne/firmwares/fixedwing/guidance/guidance_v.c''' (formerly fw_v_ctl.c)
If AGR_CLIMB is defined in the airframe file, the altitude loop also sets the v_ctl_auto_throttle_submode for use in the climb loop.

== Auto Throttle and Auto Pitch climb loops ==

Two climb loops are available. The are called from the [[Flight Plans#Navigation_modes|flight plan]] by changing the vertical navigation mode. The default mode is '''Auto Throttle'''. The '''Auto Pitch''' loop is only available if '''V_CTL_AUTO_PITCH_PGAIN''' is defined. Only one loop is active at a time. Note also that if '''USE_AIRSPEED''' is defined, then the Auto Throttle loop is replaced by the Auto Airspeed loop, see [Control_Loops#Control_loops_using_Airspeed_Sensor|below].

=== Auto throttle loop ===
[[Image:Diagram_auto_throttle_loop.png|Auto Throttle climb loop]]

If '''AGR_CLIMB''' is defined, then the auto throttle submode is used to determine setpoint outputs. This may be the standard control loop outputs, the aggressive outputs (static setpoints defined in airframe file) or a blend of both.

=== Auto pitch loop ===
[[Image:Diagram_auto_pitch_loop.png|924px|Auto Pitch climb loop]]

The climb loop is the intermediate stage of the vertical control. It is located in '''guidance_v.c'''.

== Pitch loop ==

[[Image:Diagram_pitch_loop.png|Pitch loop]]

The pitch loop is the lower stage of the vertical control and is used for longitudinal attitude stabilization. It is located in '''stabilization_attitude.c'''.
The first sum block of the diagram is not completely accurate. The input to the pitch stabilization loop is h_ctl_pitch_setpoint, though v_ctl_pitch_of_vz is not a direct input. Rather h_ctl_pitch_setpoint is assigned in the main autopilot loop from nav_pitch, in general (in auto1, it is assigned directly from the pitch r/c input). The nav_pitch value is obtained in a few ways, depending on which control loop(s) are active. If auto throttle is active, nav_pitch is the sum of v_ctl_pitch_of_vz and a fixed setpoint defined using the pitch attribute in the flightplan. If AGR_CLIMB is set, nav_pitch is either the airframe file defined ascent and descent pitch setpoints, the standard sum, or a blend of each. If auto pitch is active, nav_pitch is defined directly from the output of that loop. If airspeed is active, nav_pitch is defined in the auto airspeed pitch loop.

== Control loops using Airspeed Sensor ==

Adding an airspeed sensor measures actual airspeed resulting in better throttle control and aircraft performance especially in windy conditions. The use of an airspeed sensor is described [[Airspeed_sensor|here]].

[[Image:Diagram_auto_airspeed_loop.png|Auto Airspeed climb loop]]

The auto airspeed cascaded control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop; it is engaged in the same manner in the flight plan. It is located in '''guidance_v.c'''.

== Energy Control loops using Airspeed Sensor ==

Total Energy (speed + height) control for fixed wing vehicles developed by the [http://www.mavlab.info MAVLab] of the Technical [http://www.tudelft.nl University] of Delft. An airspeed sensor is mandatory.
The energy control loops control both pitch and throttle. This control loop set replaces the Auto Throttle climb loop and is located in '''energy_ctrl.c'''.

[[Image:Energycontrol.png|Energy Control loop]]

= Rotorcraft autopilot =

The schemes of the multi-rotor autopilot were made with the drawing tool from Google docs. To edit the drawings, send an e-mail to microuav@gmail.com.

== Overview ==

[[Image:Booz_autopilot_globalview.png]]

The code for this autopilot is located in '''sw/airborne/firmwares/rotorcraft'''.

== Vertical Control ==

Depending on the general mode selected, one of the following vertical modes is used.

=== mode: GUIDANCE_V_MODE_RC_CLIMB ===
[[File:Rc_climb.png]]

=== mode: GUIDANCE_V_MODE_CLIMB ===
[[File:Climb.png]]

=== mode: GUIDANCE_V_MODE_HOVER ===
[[File:Z_hold.png]]

=== mode: GUIDANCE_V_MODE_NAV ===

== Reference generators ==

=== from z set point (desired altitude) ===

[[Image:Refgen_from_z_sp.png]]

=== from z dot set point ===

[[Image:Booz_refgen_zdot.png]]]

The '''adjust accel''' is a simple algorithm to set acceleration to zero when velocity reaches boundaries.

The code for these reference generators is located in '''guidance/guidance_v_ref.h'''

== Vertical loop ==
[[File:vertical_loop_V40.png]]

the source code is located in '''guidance\guidance_v.c'''

NOMINAL_HOVER_THROTTLE is the nominal thrust when hovering. It's calculated by default by an adaptative controller, in '''guidance\guidance_v_adpt.h'''.

Instead of the adaptative controller, NOMINAL_HOVER_TROTTLE can be set manually in the Airframe configuration file with:

<define name="NOMINAL_HOVER_THROTTLE" value="0.5"/>

The value is found after flying manually in hover: NOMINAL_HOVER_THROTTLE= THRUST/MAX_PPRZ (THRUST:mean value of ROTORCRAFT_FP THRUST message in hover, MAX_PPRZ:9600)

In most cases it makes more sense to not specify this explicitly and use the adaptive controller

== Horizontal Control ==

Depending on the general mode selected, one of the following horizontal modes is used.

=== mode: GUIDANCE_H_MODE_RATE ===
[[Image:GUIDANCE_H_MODE_RATE.png]]

=== mode: GUIDANCE_H_MODE_ATTITUDE ===
[[Image:GUIDANCE_H_MODE_ATTITUDE.png]]

=== mode: GUIDANCE_H_MODE_HOVER ===

When this mode is entered, the measured position at the instance of initiation is set as guidance_h_pos_sp. This means that the rotorcraft will hover on that position.

[[Image:GUIDANCE_H_MODE_HOVER.png]]

rotation to body:

<math>\phi_{cmd_{body}}= -\sin \psi \cdot x_{cmd_{earth}} + \cos \psi \cdot y_{cmd_{earth}} </math>

<math>\theta_{cmd_{body}}= -\left( \cos \psi \cdot x_{cmd_{earth}} + \sin \psi \cdot y_{cmd_{earth}} \right) </math>

=== mode: GUIDANCE_H_MODE_NAV ===

The set points guidance_h_pos_sp (x and y coordinates) are obtained from the navigation carrot after a 'NED of ENU' transformation:

guidance_h_pos_sp.x = navigation_carrot.y

guidance_h_pos_sp.y = navigation_carrot.x

[[Image:GUIDANCE_H_MODE_NAV.png]]

Rotation to body is the same as in GUIDANCE_H_MODE_HOVER.

== Reference generators ==

=== from euler attitude angle set point ===

[[Image:Booz_refgen_att.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''stabilization/stabilization_attitude_ref_euler_int.c'''.

=== from angular rate set point ===

[[Image:Booz_refgen_rate.png]]

The code for this reference generator is located in '''stabilization/stabilization_rate.c'''.

=== from pos set point ===

[[Image:Booz_refgen_xy_sp.png]]

Acceleration is set to zero when rate reaches min or max value.

The code for this reference generator is located in '''guidance/guidance_h_ref.h'''.

== Attitude loop ==

[[Image:attitude_loop.png]]

The code for this loop is located in '''stabilization/stabilization_attitude_euler_int.c'''.

== Rate loop ==

[[Image:rate_loop.png]]

The code for this loop is located in '''stabilization/stabilization_rate.c'''.

== Guidance horizontal hover loop ==

[[Image:guidance_horizontal_hover.png]]

The code for this loop is located in '''guidance/guidance_h.c'''.

== Guidance horizontal navigation loop ==

[[Image:Booz_horizontal_nav.png]]

The code for this loop is located in '''guidance/guidance_h.c'''

[[Category:Software]] [[Category:Developer_Documentation]]

Subsystem/actuators

2014-05-09T23:13:24Z

Alonsoac: /* XML configuration */ remove example of pre-5.0 "supervision" stabilization

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Subsystems</categorytree>
This subsystem only needs be explicitly specified for rotorcrafts where there are several different actuators implementations and you have to add the correct one depending on the ESCs you use.

Currently possible actuators subsystems are
* ''mkk''
* ''asctec''
* ''asctec_v2''
* ''pwm''
* ''skiron''
* ''heli''
* ''ardrone2''

== MKK ==
Mikrokopter ESCs
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="mkk">
<configure name="MKK_I2C_SCL_TIME" value="50"/> 
</subsystem>
<define name="I2C_TRANSACTION_QUEUE_LEN" value="10"/> 
</firmware>
</source>
}}

* ''MKK_I2C_SCL_TIME'' is specific to LPC21x based boards (e.g. booz) and has no effect for STM32 based boards (e.g. Lisa/M/L)

=== XML configuration ===
required defines in section ''ACTUATORS_MKK'':
* ''NB'': number of motors
* ''ADDR'': the I2C addresses of your motors
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<section name="ACTUATORS_MKK" prefix="ACTUATORS_MKK_">
<define name="NB" value="4"/>
<define name="ADDR" value="{ 0x52, 0x54, 0x56, 0x58 }"/>
</section>
</source>
}}
The order of addresses in the list defines the numbering of motors! Warn on this during motor mixing!

You also need the matching [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]].
MKK specific values for SUPERVISION defines:
* ''STOP_MOTOR'' : 0, optional, as the default is already 0
* ''MIN_MOTOR'' : 3
* ''MAX_MOTOR'' : 200

== Asctec v1 ==
These controllers already to the mixing themselves, so the [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]] section is not needed.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="asctec"/>
</firmware>
</source>
}}

== Asctec v2 ==
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="asctec_v2"/>
</firmware>
</source>
}}
=== XML configuration ===
You need the matching [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]].

== PWM Supervision ==
Only for stm32 based autopilot boards (eg. Lisa/M, Lisa/L)
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="pwm">
<define name="SERVO_HZ" value="400"/>
</subsystem>
</firmware>
</source>
}}

The define ''SERVO_HZ'' sets a higher update frequency for the pwm controllers which is needed for good response times on some ESCs. Some newer ESCs are said to work better with lower frequencies. More information should be added here.
=== XML configuration ===
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<servos min="0" neutral="0" max="0xff">
<servo name="FRONT" no="0" min="1000" neutral="1000" max="2000"/>
<servo name="BACK" no="1" min="1000" neutral="1000" max="2000"/>
<servo name="LEFT" no="2" min="1000" neutral="1000" max="2000"/>
<servo name="RIGHT" no="3" min="1000" neutral="1000" max="2000"/>
</servos>
</source>
}}
You also need the matching [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]].

== Dual PWM ==
This driver allows you to generate dual pulses to control for example double servos like those :

[[File:Dual linear servos.jpg]]

The signal we want to generate look like that :

[[File:Dual_pulse.png]]

During the time of a regular pwm pulse (20ms) we got two parts :
* the first 1 with a total period of 4ms. During that part we generate the first pulse that is going to control for exemple the first servo.
* the first 2 with a total period of 16ms. During that part we generate the second pulse that is going to control for exemple the second servo.

=== How to use the driver ===

<span style="color:#FF0000">'''CAUTION!'''</span> <b>This module is only implemented on the lisa M and lisa S boards at the time of writing this documentation (28 mars 2014)</b>

First of all you are going to need to add the subsystem that is going to generate those pulses :

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing">
<target name="ap" board="lisa_s_0.1">
...
</target>

...

<subsystem name="actuators" type="dualPwm">
<define name="DUAL_PWM_ON"/>
</subsystem>

</firmware>
</source>
}}

=== XML configuration ===
Then we will be able to add a servo block into the airframe file (in the same way we would for regular servos). But we have to specify the driver that we are using for thoses servos :

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
...
<servos driver="DualPwm">
<servo name="SWITCH" no="3" min="1100" neutral="1500" max="1900"/>
<servo name="pitchator" no="2" min="1100" neutral="1500" max="1900"/>
</servos>
...
</source>
}}

<span style="color:#FF0000">'''CAUTION!'''</span> <b>The tricky part about this module is that it requires the use of the full timer (that was previously shared between multiple regular pwm). In order to reduce the wast of pins we can only put that type of servos on specifics pins :
* lisa S (version 0.1) : on the servos 2 and 3 (as shown above). The dual PWM will then but outputted on the 5th pin (yes that is not logical).
* lisa M (version 2.0) : on the servos 4 and 5. The dual PWM will be outputted on the 4th pin.
</b>

[[Category:User_Documentation]] [[Category:Subsystems]]

Contributing

2014-05-09T01:21:13Z

Alonsoac: add option for https fork and fix formatting of git urls

== How to contribute ==

It would be fantastic if you add you share to enhance the Paparazzi project. Help is always very welcome for aspects of the project. May this be documentation, wiki, maintenance, electronics or code contributions and fixes. There are lots of ways to contribute to Paparazzi and get involved.

This page will give you a headstart to be able to contribute.

=== Wiki ===

Just create an account and you can start adding information, cleaning it up or just fixing some typo you just noticed :-)

Some information and links on how to edit the wiki can be found at [[Help:Editing]].

Please be aware of past edits and page histories. Try not to remove this; if you are moving/renaming a page, use the '''move''' tab at the top of a page. This ensures the revision history is moved with the page.

=== Software development ===

[[File:AGoodCombinationSTM32ProgressnDebugging.jpg|300px|thumb|Left|Learning Tools]]

We use the distributed version control system [http://git-scm.com/ git]. The [http://github.com/paparazzi/paparazzi/ Papaprazzi master repository is hosted on Github].

Also see the [[Git|Git wiki page]] for more details about setting up Git and cloning the source-code and data repository.

Please also have a look at the [http://docs.paparazziuav.org/latest/styleguide.html Coding Style Guide].

Here is the short version if you already know git:
# Create an account on [http://github.com/ github].
# Fork the [http://github.com/paparazzi/paparazzi/ papaprazzi repo] on github. (After logging in press the '''fork''' button).
# If you want to clone with SSH: '''git clone git@github.com:<yourname>/paparazzi.git'''<br/>Or with HTTPS: '''git clone <nowiki>https://github.com/<yourname>/paparazzi.git</nowiki>'''
# '''git remote add upstream <nowiki>https://github.com/paparazzi/paparazzi.git</nowiki>'''
# '''git fetch upstream'''
# checkout a new branch based on the development branch (master):<br/>'''git checkout -b my_new_feature upstream/master'''
# fix/code and commit in logical units
# push your feature/bugfix branch
# Send us a [http://help.github.com/pull-requests/ pull request] on github. (Or send patches to the mailing list).

=== Defects and Features ===
To report Paparazzi defect, various issues and to submit a feature request use the simple [https://github.com/paparazzi/paparazzi/issues issue tracker on github].

=== Continuous Integration Builds ===
There is a [http://paparazzi.gondwana.com.au build server] running quite some [[Builds/Tests|Continuous Integration tests]].

[[Category:Developer_Documentation]]

Subsystem/stabilization

2014-05-08T21:18:24Z

Alonsoac: fix names of types

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages hideprefix=always>Subsystems</categorytree>
== Stabilization subsystem ==
The ''stabilization'' subsystem provides the attitude controller for rotorcrafts.

Currently possible attitude ''stabilization'' subsystem types are
* ''[[Subsystem/stabilization#Quaternion|int_quat]]''
* ''[[Subsystem/stabilization#Quaternion|float_quat]]''
* ''[[Subsystem/stabilization#Euler|int_euler]]''
* ''[[Subsystem/stabilization#Euler|float_euler]]''

== Attitude Control Implementations ==
There are several different attitude control algorithm implementations.

They use the same ''STABILIZATION_ATTITUDE'' xml configuration section:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<section name="STABILIZATION_ATTITUDE" prefix="STABILIZATION_ATTITUDE_">

<define name="SP_MAX_PHI" value="45." unit="deg"/>
<define name="SP_MAX_THETA" value="45." unit="deg"/>
<define name="SP_MAX_R" value="90." unit="deg/s"/>
<define name="DEADBAND_A" value="0"/>
<define name="DEADBAND_E" value="0"/>
<define name="DEADBAND_R" value="250"/>


<define name="REF_OMEGA_P" value="800" unit="deg/s"/>
<define name="REF_ZETA_P" value="0.85"/>
<define name="REF_MAX_P" value="400." unit="deg/s"/>
<define name="REF_MAX_PDOT" value="RadOfDeg(8000.)"/>

<define name="REF_OMEGA_Q" value="800" unit="deg/s"/>
<define name="REF_ZETA_Q" value="0.85"/>
<define name="REF_MAX_Q" value="400." unit="deg/s"/>
<define name="REF_MAX_QDOT" value="RadOfDeg(8000.)"/>

<define name="REF_OMEGA_R" value="500" unit="deg/s"/>
<define name="REF_ZETA_R" value="0.85"/>
<define name="REF_MAX_R" value="180." unit="deg/s"/>
<define name="REF_MAX_RDOT" value="RadOfDeg(1800.)"/>


<define name="PHI_PGAIN" value="1000"/>
<define name="PHI_DGAIN" value="400"/>
<define name="PHI_IGAIN" value="200"/>

<define name="THETA_PGAIN" value="1000"/>
<define name="THETA_DGAIN" value="400"/>
<define name="THETA_IGAIN" value="200"/>

<define name="PSI_PGAIN" value="500"/>
<define name="PSI_DGAIN" value="300"/>
<define name="PSI_IGAIN" value="10"/>


<define name="PHI_DDGAIN" value="300"/>
<define name="THETA_DDGAIN" value="300"/>
<define name="PSI_DDGAIN" value="300"/>
</section>
</source>
}}

; ''SP_MAX_*'': maximum ''PHI''/''THETA'' (roll/pitch) angles and maximum angular velocity ''R'' around yaw axis
; ''DEADBAND_*'': RC stick deadband around the center for ''A'',''E'',''R'' (roll,pitch,yaw)
; ''REF_*'': parameters for the [[Control_Loops#Reference_generators_2|reference generator]]
; ''[PHI|THETA|PSI]_[PID]GAIN'': gains for the feedback control of the respective axis
; ''[PHI|THETA|PSI]_DDGAIN'': feedforward gains for the respective axis

=== Quaternion ===
Attitude controllers using quaternions (no gimbal lock).
There is a fixed point implementation (recommended) and a floating point implementation for reference and testing.

* fixed point: <source lang="xml"><subsystem name="stabilization" type="int_quat"/></source>
* floating point: <source lang="xml"><subsystem name="stabilization" type="float_quat"/></source>
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="stabilization" type="int_quat"/>
</firmware>
</source>
}}
You also need the ''STABILIZATION_ATTITUDE'' xml configuration section as described above.

=== Euler ===
Attitude controller using Euler Angles. Due to the inherent singularities (e.g. 90deg pitch) of the euler angles representation you can't use this controller if you want to fly in regimes close or at these singularities (e.g. acrobatics or transitioning vehicles).
See [[Control_Loops#Attitude_loop]] for diagrams of the control loop.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="stabilization" type="int_euler"/>
</firmware>
</source>
}}
You also need the ''STABILIZATION_ATTITUDE'' xml configuration section as described above.

== Rate Control ==
There is only one rate control implementation (which is included in the rotorcraft firmware by default). It allows you to fly a rotorcraft like a helicopter by controlling the angular rate directly instead of having (self-leveling) attitude control.
See [[Control_Loops#Rate_loop]] for diagrams of the control loop.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
</firmware>

<section name="STABILIZATION_RATE" prefix="STABILIZATION_RATE_">

<define name="SP_MAX_P" value="10000"/>
<define name="SP_MAX_Q" value="10000"/>
<define name="SP_MAX_R" value="10000"/>
<define name="DEADBAND_P" value="20"/>
<define name="DEADBAND_Q" value="20"/>
<define name="DEADBAND_R" value="200"/>
<define name="REF_TAU" value="4"/>


<define name="GAIN_P" value="400"/>
<define name="GAIN_Q" value="400"/>
<define name="GAIN_R" value="350"/>

<define name="IGAIN_P" value="75"/>
<define name="IGAIN_Q" value="75"/>
<define name="IGAIN_R" value="50"/>


<define name="DDGAIN_P" value="300"/>
<define name="DDGAIN_Q" value="300"/>
<define name="DDGAIN_R" value="300"/>
</section>
</source>
}}

[[Category:User_Documentation]] [[Category:Subsystems]]

Subsystem/actuators

2014-05-08T21:07:31Z

Alonsoac: fix pwm_supervision is not the correct name of the type pwm

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Subsystems</categorytree>
This subsystem only needs be explicitly specified for rotorcrafts where there are several different actuators implementations and you have to add the correct one depending on the ESCs you use.

Currently possible actuators subsystems are
* ''mkk''
* ''asctec''
* ''asctec_v2''
* ''pwm''
* ''skiron''
* ''heli''
* ''ardrone2''

== MKK ==
Mikrokopter ESCs
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="mkk">
<configure name="MKK_I2C_SCL_TIME" value="50"/> 
</subsystem>
<define name="I2C_TRANSACTION_QUEUE_LEN" value="10"/> 
</firmware>
</source>
}}

* ''MKK_I2C_SCL_TIME'' is specific to LPC21x based boards (e.g. booz) and has no effect for STM32 based boards (e.g. Lisa/M/L)

=== XML configuration ===
required defines in section ''ACTUATORS_MKK'':
* ''NB'': number of motors
* ''ADDR'': the I2C addresses of your motors
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<section name="ACTUATORS_MKK" prefix="ACTUATORS_MKK_">
<define name="NB" value="4"/>
<define name="ADDR" value="{ 0x52, 0x54, 0x56, 0x58 }"/>
</section>
</source>
}}
The order of addresses in the list defines the numbering of motors! Warn on this during motor mixing!

You also need the matching [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]].
MKK specific values for SUPERVISION defines:
* ''STOP_MOTOR'' : 0, optional, as the default is already 0
* ''MIN_MOTOR'' : 3
* ''MAX_MOTOR'' : 200

== Asctec v1 ==
These controllers already to the mixing themselves, so the [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]] section is not needed.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="asctec"/>
</firmware>
</source>
}}

== Asctec v2 ==
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="asctec_v2"/>
</firmware>
</source>
}}
=== XML configuration ===
You need the matching [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]].

== PWM Supervision ==
Only for stm32 based autopilot boards (eg. Lisa/M, Lisa/L)
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="actuators" type="pwm">
<define name="SERVO_HZ" value="400"/>
</subsystem>
</firmware>
</source>
}}

The define ''SERVO_HZ'' sets a higher update frequency for the pwm controllers which is needed for good response times on some ESCs. Some newer ESCs are said to work better with lower frequencies. More information should be added here.
=== XML configuration ===
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<servos min="0" neutral="0" max="0xff">
<servo name="FRONT" no="0" min="1000" neutral="1000" max="2000"/>
<servo name="BACK" no="1" min="1000" neutral="1000" max="2000"/>
<servo name="LEFT" no="2" min="1000" neutral="1000" max="2000"/>
<servo name="RIGHT" no="3" min="1000" neutral="1000" max="2000"/>
</servos>
</source>
}}
You also need the matching [[Rotorcraft_Configuration#Motor_Mixing|Motor Mixing section]].
Example PWM specific values for SUPERVISION defines:
* ''STOP_MOTOR'' : 800
* ''MIN_MOTOR'' : 1000
* ''MAX_MOTOR'' : 2000

== Dual PWM ==
This driver allows you to generate dual pulses to control for example double servos like those :

[[File:Dual linear servos.jpg]]

The signal we want to generate look like that :

[[File:Dual_pulse.png]]

During the time of a regular pwm pulse (20ms) we got two parts :
* the first 1 with a total period of 4ms. During that part we generate the first pulse that is going to control for exemple the first servo.
* the first 2 with a total period of 16ms. During that part we generate the second pulse that is going to control for exemple the second servo.

=== How to use the driver ===

<span style="color:#FF0000">'''CAUTION!'''</span> <b>This module is only implemented on the lisa M and lisa S boards at the time of writing this documentation (28 mars 2014)</b>

First of all you are going to need to add the subsystem that is going to generate those pulses :

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing">
<target name="ap" board="lisa_s_0.1">
...
</target>

...

<subsystem name="actuators" type="dualPwm">
<define name="DUAL_PWM_ON"/>
</subsystem>

</firmware>
</source>
}}

=== XML configuration ===
Then we will be able to add a servo block into the airframe file (in the same way we would for regular servos). But we have to specify the driver that we are using for thoses servos :

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
...
<servos driver="DualPwm">
<servo name="SWITCH" no="3" min="1100" neutral="1500" max="1900"/>
<servo name="pitchator" no="2" min="1100" neutral="1500" max="1900"/>
</servos>
...
</source>
}}

<span style="color:#FF0000">'''CAUTION!'''</span> <b>The tricky part about this module is that it requires the use of the full timer (that was previously shared between multiple regular pwm). In order to reduce the wast of pins we can only put that type of servos on specifics pins :
* lisa S (version 0.1) : on the servos 2 and 3 (as shown above). The dual PWM will then but outputted on the 5th pin (yes that is not logical).
* lisa M (version 2.0) : on the servos 4 and 5. The dual PWM will be outputted on the 4th pin.
</b>

[[Category:User_Documentation]] [[Category:Subsystems]]

Lisa/M v2.0

2013-11-26T17:13:50Z

Alonsoac: /* Uploading new software */

<div style="float: right; width: 15%"><categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Autopilots</categorytree></div>
<div style="float: right; width: 45%; overflow: hidden">[[Image:LisaM_V2_0_TopView.JPG|right|500px|Lisa/M V2.0 top view]]</div>
<div style="float: right; width: 40%">__TOC__</div>

Lisa/M is a small, general purpose autopilot designed with flexibility across multiple applications in mind. Small weight and size, with (optional) integrated [[AspirinIMU | Aspirin IMU]] and full size 0.1" servo headers make the Lisa/M suitable for both fixed-wing and rotorcraft vehicles. This autopilot is based on a STM32 processor for extensive peripheral connection and faster processing.

A number of tutorials are being prepared for getting started with Lisa/M:
* [[Lisa/M/Tutorial/FixedWing|Fixedwing tutorial]]
* [[Lisa/M/Tutorial/RotorCraft|Rotorcraft tutorial]]

Please join us in our quest to make the getting started information even more, eh... informative, by adjusting those pages with your own improvements.

== Features ==

Lisa/M is based on the 64 pins STM32F105RCT6 [http://www.st.com/internet/mcu/product/221023.jsp connectivity line family] processor featuring 64k of RAM and 256k of FLASH. All the pins are exposed, providing access to the complete set of the STM32 peripherals.
NOTE: This MCU is different from LISA/L. Lisa/L is based on the 64 pins STM32F103RE processor featuring 64k of RAM and 512k of FLASH, which is part of the [http://www.st.com/internet/mcu/product/164485.jsp high-density performance line family].

* STM32 microcontroller [http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATASHEET/CD00220364.pdf STM32F105RCT6 datasheet] with 256kB flash and 64kB RAM
* Pressure sensor [http://www.bosch-sensortec.com/content/language1/html/3477.htm BMP085] (optional as of 08/2012)
* 7 x Analog input channels
* 3 x Generic digital in-/out-puts
* 2 x 3.3V TTL UART (5V tolerant)
* 8 x Servo PPM outputs (only 6 if second I2C (I2C1) bus in use)
* 1 x CAN bus
* 1 x [http://en.wikipedia.org/wiki/Serial_Peripheral_Interface SPI] bus
* 1 x [http://en.wikipedia.org/wiki/I2c I<sup>2</sup>C] bus (2 x when using only the first 6 Servo PPM outputs)
* 1 x Micro USB
* 4 x status LEDs with attached test point
* 10.8 grams (0.4 oz) (with Aspirin IMU mounted)
* 9.9 grams (0.35 oz) (without Aspirin IMU mounted)
* ~34mm x ~60mm x ~10mm
* 4 layers PCB design

With mounted Aspirin IMU has the following additional sensors on board:

* 3 Axis Gyroscope
* 3 Axis Accelerometer
* 3 Axis Magnetometer
* Barometer MS5611 (as of Aspirin v2.1)

NOTE:
'''Lisa/M has pads for the BMP085 pressure sensor. Lias/M 2 boards made before August 2012 had the BMP085 sensor mounted. Boards made after August 2012 do not have the sensor mounted as they are designed to be used with Aspirin 2.1 which has the new MS5611-01BA03 barometric pressure sensor.'''

The drivers for the MS5611-01BA03 are '''work in progress''' and are available in the master branch of the Paparazzi codebase. All '''help''' with testing and improving the driver are '''very welcome'''!

So, except for a GPS unit you have all necessary sensors for full attitude and altitude stabilization in an extremely small package.

<gallery widths=200px heights=200px>
Image:LisaM_V2_0_TopView.JPG|Lisa/M V2.0 top view
Image:LisaM_V2_0_BottomView.JPG|Lisa/M V2.0 bottom view
</gallery>

== Pinout ==
Pins Name and Type are specified with respect to the Autopilot Board.

<div style="float: right; width: 100%">
[[Image:LisaM_V2_0_top_labeled.png|900px]]
[[Image:LisaM_warning_label.png|200px]]
</div>

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''SERVO1/2/3/4/5/6/7/8'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||SERVOx||OUT||Servo signal (PWM)(See Note 1 below)||style="background:Yellow; color:black"|Yellow
|-
|2||SV||PWR||Servo Bus Voltage Rail (conf w/ JP1)||style="background:red; color:white"|Red
|-
|3||GND||PWR||common ground||style="background:black; color:white"|Black
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''JTAG'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||N/A||N/A||JTAG Debug Header (Pin 1 is +3V3)||style="background:white; color:black"|None
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''UART3'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2||V_IN||PWR||UART Voltage (conf w/ JP6 and JP7)||style="background:Red; color:white"|Red
|-
|3||TX||OUT||USART3 Serial Output (3.3V level)||style="background:Yellow; color:black"|Yellow
|-
|4||RX||IN||USART3 Serial Input (3.3V level)(Pullup to Pin 2 voltage)(5V tolerant)||style="background:Orange; color:white"|Orange
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''UART1/5'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||3.3V Rail from autopilot (conf w/ JP8 and JP9)||style="background:Red; color:white"|Red
|-
|3||RX1||IN||USART1 Serial Input (3.3V level)(Pullup to Pin 2 voltage)(5V tolerant)||style="background:Orange; color:white"|Orange
|-
|4||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|5|| +3V3||PWR||3.3V Rail from autopilot (conf w/ JP8 and JP9)||style="background:Red; color:white"|Red
|-
|6||RX5||IN||UART5 Serial Input (3.3V level)(Pullup to Pin 5 voltage)(5V tolerant)||style="background:Orange; color:white"|Orange
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''GPIO'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||3.3V Rail from autopilot||style="background:Red; color:white"|Red
|-
|4||PC12||I/O||GPIO, connected to PC12 (5V tolerant)||style="background:#FDC579; color:black"|Dark Tan
|-
|5||TRST||I/O||JTAG_TRST (also connected to LED1 cathode)||style="background:#FED6B1; color:black"|Light Tan
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''ANALOG2'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||3.3V Rail from autopilot||style="background:Red; color:white"|Red
|-
|3|| +5V||PWR||5V Rail from autopilot||style="background:Red; color:white"|Red
|-
|4||ADC4||I/O||by default connected to LED_4 cathode (Remove LED/resistor to use as ADC4)||style="background:magenta; color:white"|Magenta
|-
|5||ADC6||I/O||by default connected to LED_3 cathode (Remove LED/resistor to use as ADC6)||style="background:#FFA1B2; color:black"|Pink
|-
|6||BOOT0||I/O||BOOT0||style="background:grey; color:black"|Grey
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''USB'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||N/A||N/A||USB (The USB connections are also available as 0.05" (1.27mm) through hole pads underneath the GPIO header)||style="background:white; color:black"|None
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''I2C1 CAN'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| V_BATT||PWR||V_BATT Bus on autopilot, voltage divider for V_BAT_MEAS, (conf w/ JP2 to connect to V_IN)||style="background:Red; color:white"|Red
|-
|3|| V_IN||PWR||Connected to autopilot voltage regulator inputs (conf w/ JP1, JP2 and JP3)||style="background:Red; color:white"|Red
|-
|4||CANL||I/O||CANL (5V level)||style="background:orange; color:white"|Orange
|-
|5||CANH||I/O||CANH (5V level)||style="background:yellow; color:black"|Yellow
|-
|6||SCL||I/O||SCL (5V level)(See Note 1 below)||style="background:green; color:white"|Green
|-
|7||SDA||I/O||SDA (5V level)(See Note 1 below)||style="background:blue; color:white"|Blue
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''SPI1'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||3.3V Rail from autopilot||style="background:Red; color:white"|Red
|-
|3||MOSI||Out||MOSI||style="background:orange; color:white"|Orange
|-
|4||MISO||In||MISO||style="background:yellow; color:black"|Yellow
|-
|5||SCK||Out||SCK||style="background:green; color:white"|Green
|-
|6||SS||Out||SS||style="background:blue; color:white"|Blue
|-
|7||DRDY||I/O||DRDY||style="background:#FDC579; color:black"|Dark Tan
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''ANALOG1'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||3.3V Rail from autopilot||style="background:Red; color:white"|Red
|-
|3|| +5V||PWR||5V Rail from autopilot||style="background:Red; color:white"|Red
|-
|4||ADC1||In||ADC1 (or LED_6 if populated)||style="background:green; color:white"|Green
|-
|5||ADC2||In||ADC2 (or LED_7 if populated)||style="background:blue; color:white"|Blue
|-
|6||ADC3||In||ADC3 (or LED_8 if populated)||style="background:#FED6B1; color:black"|Light Tan
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''UART2'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||UART Voltage (conf w/ JP4 and JP5)||style="background:Red; color:white"|Red
|-
|3||TX||OUT||USART2 Serial Output (3.3V level)||style="background:Yellow; color:black"|Yellow
|-
|4||RX||IN||USART2 Serial Input (3.3V level)('''NOT 5V TOLERANT''')(Pullup to Pin 2 voltage)||style="background:Orange; color:white"|Orange
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''I2C2'''
!width="7%"|''Pin #''!!width="10%"|''Name''!!width="10%"|''Type''!!''Description''!!width="5%"|''Color''
|-
|1||GND||PWR||common ground||style="background:black; color:white"|Black
|-
|2|| +3V3||PWR||3.3V Rail from autopilot||style="background:Red; color:white"|Red
|-
|3||SCL||I/O||SCL (3.3V level)||style="background:green; color:white"|Green
|-
|4||SDA||I/O||SDA (3.3V level)||style="background:blue; color:white"|Blue
|}

'''NOTE 1''': SERVO7 and SERVO8 are directly connected to I2C1_SCL and I2C1_SDA lines. Therefore one has to choose, either use SERVO7 and SERVO8 '''OR''' have the I2C1 bus available, if that one needs to be used for whatever reason alongside the I2C2 bus. To use the servos 7 and 8 just set the <define name="USE_SERVOS_7AND8"/> in your airframe file and you are good to go. For this to work one must make sure to have the latest Paparazzi sourcecode.

=== LEDs ===
Lisa/M 2.0 has 5 LEDS (+1 power LED). There are 3 additional LEDs (LED_6, LED_7, LED_8) that are not populated by default (in favor of using ADC1-3 on the ANALOG1 connector).
By default the LEDs are use for:
; LED_1, red: ''SYS_TIME_LED'': blinks with 1Hz
; LED_2, green : ''AHRS_ALIGNER_LED'': blinks until the AHRS is aligned (gyro bias initilalized) and then stays on
; LED_3, green : ''GPS_LED'': blinking if trying to get a fix, on if 3D fix
; LED_4, red : ''RADIO_CONTROL_LED'': on if RC signal is ok
; LED_5, green : not set to anything by default

=== Jumper Configuration ===
There are a number of jumpers on Lisa/M used to configure voltage levels and power input.

The default configuration is UART3 VCC at V_IN, UART1/2/5 VCC at +3V3, with the V_SERVO servo voltage rail NOT connected to the autopilot V_IN rail, allowing one to power the autopilot and servos separately. The +5V regulator is NOT bypassed, allowing a regulated +5V on listed headers and for the CAN transceiver and I2C level shifter. The V_BATT connector is NOT connected to V_IN, so one can attach a battery voltage to the V_BATT pin to measure the battery voltage, if so desired.

<gallery widths=380px heights=205px>
Image:LisaM_V2_0_top_jumpers_and_leds.png | Lisa/M v2.0 Top Jumpers and LEDs
Image:LisaM_V2_0_bottom_jumpers.png | Lisa/M v2.0 Bottom Jumpers
</gallery>
<br style="clear:both">

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''Power Jumper Configuration'''
!width="7%"|''Jumper''!!width="20%"|''Bus Connection''!!width="7%"|''Default''!!''Description''
|-
|JP1||SERVO_BUS to V_IN||OPEN||Connects servo header voltage rail SERVO_BUS to autopilot input voltage V_IN rail
|-
|JP2||V_BATT to V_IN||OPEN||Connects I2C1/CAN rail V_BATT to autopilot input voltage V_IN rail
|-
|JP3||V_IN to +5V||OPEN||Connects autopilot input voltage V_IN rail to autopilot +5V rail, bypassing onboard 5V supply
|}

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''UART3 VCC Configuration'''
!width="7%"|''Jumper''!!width="20%"|''Bus Connection''!!width="7%"|''Default''!!''Description''
|-
|JP6||UART3_VCC to V_IN||style="background:black; color:white"|CLOSED||Connects UART3 connector VCC to autopilot input voltage V_IN rail
|-
|JP7||UART3_VCC to +3V3||OPEN||Connects UART3 connector VCC to autopilot +3V3 rail
|}
'''WARNING: UART3 GPS Connector is connected to V_IN, check your GPS input voltage before connecting!!!'''

'''WARNING: DO NOT CLOSE BOTH JP6 AND JP7 SIMULTANEOUSLY!!!'''

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''UART2 VCC Configuration'''
!width="7%"|''Jumper''!!width="20%"|''Bus Connection''!!width="7%"|''Default''!!''Description''
|-
|JP4||UART2_VCC to V_IN||OPEN||Connects UART2 connector VCC to autopilot input voltage V_IN rail '''SEE WARNING BELOW'''
|-
|JP5||UART2_VCC to +3V3||style="background:black; color:white"|CLOSED||Connects UART2 connector VCC to autopilot +3V3 rail
|}
'''WARNING: UART2 RX is NOT 5V TOLERANT. Thus, while possible to connect UART2_VCC to V_IN, DO NOT ATTEMPT THIS. Only use JP5 (the default).

'''WARNING: DO NOT CLOSE BOTH JP4 AND JP5 SIMULTANEOUSLY!!!'''

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''UART1 and UART5 VCC Configuration'''
!width="7%"|''Jumper''!!width="20%"|''Bus Connection''!!width="7%"|''Default''!!''Description''
|-
|JP8||UART1&5_VCC to V_IN||OPEN||Connects UART1 and UART5 connector VCC to autopilot input voltage V_IN rail
|-
|JP9||UART1&5_VCC to +3V3||style="background:black; color:white"|CLOSED||Connects UART1 and UART5 connector VCC to autopilot +3V3 rail
|}
'''WARNING: DO NOT CLOSE BOTH JP8 AND JP9 SIMULTANEOUSLY!!!'''

There are additional jumpers on the board for expert or developer configurations, please see [[Lisa/M_v20#Schematic|schematic]] and [[Lisa/M_v20#Downloads|layout]] for more information.

=== Powering the Board ===

[[Image:LisaM_warning_label.png|right|200px]]

The 3.3V regulator on Lisa/M is a [http://www.micrel.com/page.do?page=/product-info/products/mic5209.shtml MIC5209-3.3YM] capable of delivering up to 500mA. While it is possible to power this regulator with up to 16V, '''DO NOT''' do this. By default, the UART3 RX pin is pulled up to the input voltage V_IN. For this reason, 5V is the maximum input voltage. Note that the UART3 GPS Connector is connected to V_IN, check your GPS input voltage before connecting. If one desires to have V_IN at a higher voltage, the jumpers should be adjusted accordingly. As noted, this regulator can handle up to 16V, though experience has shown that this regulator can become very hot in operation with high input voltages, resulting in potential thermal shutdown while in flight. Depending on the expected current draw, it is best to power this regulator with a lower voltage. 5V is the perfect choice.

The onboard 5V regulator on Lisa/M is a [http://www.national.com/pf/LP/LP2992.html LP2992], a low-noise, low-dropout linear regulator capable of delivering up to 250mA. This regulator can be bypassed with JP3, connecting the autopilot V_IN bus directly to the autopilot 5V bus if, for example, one is using an external 5V regulated supply, and a higher current is needed. Unless external use of 5V is required on the ANALOG1 and ANALOG2 headers, the only 5V usage onboard is for the CAN transceiver and the I2C1 level shifter.

When measuring the supply voltage of a battery with the V_BATT pin (could be connected to V_IN through JP2), it is important to note the maximum voltage limit. The voltage divider on the board for measuring with a 3.3V ADC is --'''V_BAT'''--/\/\'''10k'''/\/\--'''V_BAT_MEAS'''--/\/\'''2k2'''/\/\--'''GND'''--. This means that the maximum allowable voltage on V_BATT is

<math>V\_BAT_{max} = 3.3V*\frac{10k}{2.2k} = 15V</math>

If a higher voltage measurement is desired, another voltage divider is required off-board. Alternatively, one could modify the existing voltage divider (e.g. change 10k resistor to 22k to get 33V maximum). When checking if voltage exceeds the maximum, make sure to consider maximum battery voltage, not nominal voltage (e.g. 4.22V or so for a single lithium cell, not 3.7V nominal, so the maximum number of cells in series is 3, like a 3S LiPo pack).

== Schematic ==
<gallery widths=250px heights=168px>
Image:Lisa_m_v2_0_sheet_1.png | LisaM V2.0 Schematic Sheet 1/3
Image:Lisa_m_v2_0_sheet_2.png | LisaM V2.0 Schematic Sheet 2/3
Image:Lisa_m_v2_0_sheet_3.png | LisaM V2.0 Schematic Sheet 3/3
</gallery>
<br style="clear:both">

== Examples of Airborne Equipment Electrical Connections ==

=== Quadrocopter, Spektrum Satellite Receivers and PWM Motor Controllers (ESC) ===

[[File:LisaM_v2_0_wiring_quadrocopter_spektrum_pwmesc.png|700px]]

This configuration assumes the ESCs have a battery eliminator circuit (BEC) function and provide 5 volts on their 5V pins. Closing JP1 powers Lisa/M and the attached accessories.

When using cheap ATMega or SiLabs-based PWM motor controllers consider replacing their firmware with either [https://github.com/sim-/tgy Simon Kirby] or [https://github.com/bitdump/BLHeli BLHeli] firmware respectively to get useful performance of your multicopter! You can find a firmware compatibility list [https://docs.google.com/spreadsheet/ccc?key=0AhR02IDNb7_MdEhfVjk3MkRHVzhKdjU1YzdBQkZZRlE here].

=== Quadrocopter, Spektrum Satellite Receivers and I2C Motor Controllers (ESC) ===

[[File:LisaM_V2_0_quadrocopter_spektrum_i2c_esc_wiring.png|700px]]

This diagram "should" be the same for AscTec as well as Mikrokopter motor controller based airframes.

=== Fixedwing, Spektrum Satellite Receivers and Elevons Only ===

[[File:LisaM_V2_0_wiring_fixedwing_spektrum_elevons.png|700px]]

This configuration assumes the ESC has a BEC and provides 5 volts on its 5V pin. Closing JP1 powers Lisa/M and the attached accessories.

=== Fixedwing, Spektrum Satellite Receivers ===

[[File:LisaM_V2_0_wiring_fixedwing_spektrum.png|700px]]

This configuration assumes the ESC has a BEC and provides 5 volts on its 5V pin. Closing JP1 powers Lisa/M and the attached accessories.

=== Transitioning [http://wiki.thequadshot.com Quadshot] Using Spektrum Receivers ===

[[File:LisaM_V2_0_wiring_quadshot_spektrum.png|700px]]

The ESCs have BECs and provide 5 volts on their 5V pins. Closing JP1 powers Lisa/M and the attached accessories.

Still need: Large Fixed-wing with advanced power system and/or IC engine, PPM example

== R/C Receivers ==

One can use Spektrum DSM2 or compatible receivers as well as traditional PPM receivers. It is even possible to connect two Spectrum or compatible satellite receivers for better redundancy or to improve RC signal reception. Connecting a RC receiver for flying your aircraft in manual mode during setup and test phase is 99% of the cases a must. Therefore the Paparazzi team made it easy to connect one.

=== Using a Spectrum DSM receiver ===

==== Physically connecting ====

Wiring up a Spektrum or compatible satellite receiver is not to difficult to do.
It is very important to make absolutley sure the connectors are properly made.
Not being precise in this step can mean full RC loss and loss of airframe in the first tuning testflights.

The spektrum satellite receiver should be connected to the UART1 connector on the autopilot board. Make sure the voltage on the AP board UART1 + pin is not to high, or to low for your receiver.

Steps:
# Connect the minus(-) of the receiver to GND of UART1
# The receiver plus(+) to the UART1 Plus(+)
# Data out signal of the receiver to the RX pin on the UART1

==== Binding ====

To get a receiver and transmitter to work together you must perform a binding process.

It is important to '''bind''' your Spectrum DSM receiver to your transmitter '''via''' your '''Lisa board''', not in any other way!

The way to bind is by temporary connecting via fiddly small molex pins.
It is advised to make a small bind plug out of a molex connector for this purpose.
Before you start make sure you have your airframe configuration already uploaded either via USB or a JTAG cable.

The bind procedure:

# On the connector '''ANALOG1''' have a wire between the GND and ADC1 pin, located in the middle of the board
# Power up your autopilot board
# Hold the bind button on your '''transmitter''', while '''keeping it pressed''' switch on your transmitter
#:Wait...! All lights of the receiver blink and then go steady
# Let go of your transmitter bind button
# Power off your Lisa Board
# Remove the wire connecting the GND and ADC1 pins on the ANALOG1 connector
# Repower your board, if you have servos connected and wiggle the RC transmitter sticks some servos should move

That is all, you are done.
The bind procedure only needs to be done '''once''' for your receiver.

=== Using a PPM receiver ===

Using a PPM receiver, a so called '''PPM sum stream''' input is possible. [[RC_Receivers_and_Radios#PPM_Based_Systems | To make it work, you need a PPM sum stream out capable receiver. Find out more following this link]]

==== Connecting ====

Connect the PPM out signal to the RX pin of UART1.

Make sure put this in your airframe file in your AP target section.
<source lang="xml">
...
<subsystem name="radio_control" type="ppm">
<configure name="RADIO_CONTROL_PPM_PIN" value="UART1_RX"/>
</subsystem>
...
</source>

===== Alternative =====

However if in the case you want to use the UART1 port for something else, there is an option to connect the receiver to a servo pin. Yes, that's right, a servo connector is used for receiving a PPM stream '''input'''. If you want to walk that path, the default pin number to capture the PPM sum stream is via servo connector SERVO6

If you connect the PPM ou capable receiver that way make sure to put this in your airframe file in your AP target section:

<source lang="xml">
...
<subsystem name="radio_control" type="ppm">
<configure name="RADIO_CONTROL_PPM_PIN" value="SERVO6"/>
</subsystem>
...
</source>

If you do not have or cannot modify a receiver to a ''PPM out'' able receiver, a [[PPM_Encoder | PPM encoder board]] can be used to avoid opening your receiver for PPM out modification.

== Extras ==

=== UART I/O ===

UART pins can also be used as general purpose I/O, this might come in handy in case all other inputs or your AP board are in use.

=== USB as UART1TX + hardware flow control===

[[File:Lisam-usb-uart1.jpg]]

The USB_VBUS on the Lisa/M 2.0 can be used as UART1 TX. To do this, a diode has to be removed. Make sure to include a series resistor of 100-3000 Ohm to protect the microcontroller from overcurrents. The 2nd and 3th pin of the USB pads are CTS and RTS respactively. It is recommended to include a series resistor in the RTS line, as this is an outgoing line.

If you want to enable flow control in the software, but don't want to use flow control when no cable is connected to the CTS/RTS, a pulldown resistor of 10 kOhm has to be added between the CTS and the GND. If you do this, take care when connecting UART devices that have a large series resistor in their RTS line. The combination of the pulldown resistor and the series resistor might cause the high-level voltage to drop under the high-level treshold of the microcontroller, causing strange behaviour.

For Example the RTS , mostly a purple wire, is the '''pin 10''' on the Xtend module when set in the module with Hardware flow control (use X-CTU)
CTS, most blue, on pin 9 of the Xtend

<gallery widths=380px heights=205px>
Image:Lisam-diode.JPG | Remove this diode. After removing this diode you can not power the board via USB anymore.
Image:Lisam-gpio-usb.JPG | Take care of the small distance between the GPIO pins and the USB pads.
</gallery>

== PCB ==

=== Gerber & Drill Files ===

'''''Download Lisa/M v2.0 gerber & drill files (zip)''''' ''[[Lisa/M_v2.0#Get the design|Get the design]]''

== Assembly ==

To create and assemble a board oneself is possible. It takes some skills however.

For the Lisa/m v2.0 without the Aspirin sensor board a good soldering iron is enough.(smallest components are 0402) For the Aspirin Sensor board you need a hot air soldering station.

In case you wan to follow that path you need the desing. You came to the right place here is the info to get the needed files;

===Components Layout===

''[[Lisa/M_v2.0#Get the design|Get the design]]''

Need some top and bottom of board images and line drawings here.

=== Bill Of Material ===

'''''Download Lisa/M v2.0 Bill Of Material (zipped .xls file)''''' ''[[Lisa/M_v2.0#Get the design|Get the design]]''

Open .sch File in Eagle, execute UPL --> bom.ulp , save as .txt

== PCB and assembled boards suppliers ==

To difficult to creat your own AP board, understandable, thus pre made board available via [[Get_Hardware|Get Hardware]] page... hopefully :)

== Mechanical Dimensions ==

[[Image:LisaM_V2_0_top_mechanical.png|500px|Lisa/M v2.0 Mechanical Dimensions]]

The overall height of the board including the servo connectors is 10mm. Note that the overall length includes the USB connector. The mounting holes are nominal 2mm diameter (with a bit of clearance).

== Get the design ==

'''Source files'''
:*download available on GitHub: ''[https://github.com/paparazzi/paparazzi-hardware/tree/master/controller/lisa_m/v2.0 Lisa/M v2.0 Cadsoft Eagle 6 Design]''
'''Gerber & Drill files'''
:*download ''NOT YET AVAILABLE'' Need generated gerbers and drill files
'''Assembly files'''
:*download ''NOT YET AVAILABLE'' Need Lisa/M v2.0 Components layouts (pdf)
:*download ''NOT YET AVAILABLE'' Need Lisa/M v2.0 Bill Of Material

== Uploading new software ==
New onboard software for the Lisa/M v2.0 can uploaded by connecting your PC via a micro-USB port to the autopilot board. For this the board need to contain the [[Luftboot]] bootloader. All Lisa/M 2.0 from Transition Robotics Inc. come with luftboot already in the board.

An alternative to get your firmware in the board is by using a JTAG connector connected via the 10-pin Samtec connector that is available on the board.

See the [[FirmwareFlashing]] page for an overview of different methods to upload new software to your autopilot.

=== Using luftboot ===
'''This is the default FLASH_MODE for Lisa/M v2.0''', it could be explicitly selected by adding
:<source lang="xml"><configure name="FLASH_MODE" value="DFU"/></source>
to the firmware section of your airframe file. Make sure to set Lisa/M 2.0 as it's target board.

Once USB is plugged in, the board automatically goes to bootloader mode and the status LEDs cycle up and down:

[[File:Luftboot.gif|320px]]

If you have trouble entering the bootloader mode or want to upload/update the bootloader itself, see the [[Luftboot]] page.

=== Using JTAG ===
You still can use a [[JTAG|JTAG adapter]] for [[FirmwareFlashing#JTAG|flashing]] and [[DevGuide/JTAG-Debug|debugging]] your paparazzi firmware. To use [[FirmwareFlashing#JTAG|JTAG flashing]] configure the ''FLASH_MODE'' in your firmware section:
:<source lang="xml"><configure name="FLASH_MODE" value="JTAG"/></source>
Using JTAG will not overwrite the bootloader by default. To overwrite the luftboot bootloader configure
:<source lang="xml"><configure name="NO_LUFTBOOT" value="1"/></source>

Then press upload as normal...

=== Serial Firmware Upload ===
Firmware upload using the factory integrated bootloader can be useful e.g. if you have overwritten [[Luftboot]] accidentally and don´t have access to [[JTAG]].<br/>
Either set the flash mode in the target section of the airframe configuration:
:<source lang="xml"><configure name="FLASH_MODE" value="SERIAL"/></source>
or add it to the commandline invocation:
make AIRCRAFT=<aircraftname> ap.upload FLASH_MODE=SERIAL

Due to hardware constraints, the board has to be modified to make use of the bootloader, which is only accessible on UART1:
# Diode D3 has to be removed (the bigger black brick next to the USB connector). Attention, no more powering via USB after that.
# BOOT1 has to be set to GND by connecting ACC_DRDY(unused) to GND at the Aspirin pads

Now a boot sequence works as follows:
#BOOT1 has to be set to 3.3V by use of a jumper cable
#Connect a 3,3V serial cable (FTDI, MAX232...) to UART1, the TX pin is USB_VBUS
#Power the board and activate the bootloader program

=== Prevent board from going into bootloader mode ===

Normally, if you power up the board with the USB cable connected it will automatically go into bootloader mode, even if the USB cable is not connected to the PC. If you want the board to power up normally with the cable connected you can ground the ADC2 in the ANALOG1 connector.

== Detailed Hardware Revision History ==

=== Changes Between LISA v1.1 and v2.0 ===

* Lots of silkscreen improvements
* Added attributes to all parts to make the usage of bom-ex ulp possible.
* Improved routing to allow teardropping
* Fixed stm32f1, f2 and f4 compatibility circuit. (has to jump to ground not to 3v3)
* Connected existing UART RX pullups to the respective connector power pins instead of 3v3. To prevent connecting 5V over IO pin to the 3v3 power rail.
* Added pullups on all UART RX lines to prevent undesired floatation.
* LED's are connected to 3v3 now. To make sure we don't have an issue with voltage tolerance on the gpio pins.
* ...

== Hardware Change Requests ==

If you have a Lisa/M 2.0 and in the process of using it you come up with something you find annoying, dangerous, or restricting, add your hardware update requests here. Better still, modify the Lisa schematics yourself and show your new improvements if you are skilled enough to do this.

* REQ: Replace BMP085 with MS5611 (the MS5611 seems to be better in performance then the BMP but it is more expensive and seems to be more difficult to obtain.
** A: Using a MS5611 is possible through using a Aspirin v2.1 board

* REQ: Replace 7 Pin CAN with molex with something less risky to be inserted in 7 Pin SPI in relation to powering the board via CAN molex.

* REQ: Separate spot for external power if powered via separate battery. Realizing we can via Servo ports by Bridge J1 but still like to measure board voltage then and have a way to add power without mistakenly insert I2CCAN Molex conector into SPI Molex on board connector. Thus a separate CAN and Power plug. Power on regular four pin molex with GND, V+5, , V_BATT, V_I (Current sense). Option to have thicker wire to be soldered to the board, for power hungry setups and other issues connectors for power are not a good idea.

* REQ: Replace Aspirin IMU board with InvenSense MPU-9150 and bring the MS5611 back onto the Lisa/M board to reduce footprint, mass, and manufacturing cost once the 9150 becomes readily available(if at al with SPI) and is tested to perform well.
[[Category:Lisa]] [[Category:User_Documentation]] [[Category:Autopilots]]

Tuning

2013-09-22T17:12:20Z

Alonsoac: /* Sample/Simple Altitude and Throttle Loop */

== Intro ==

This page provides guidelines for tuning a new aircraft and additional practical tips. Be sure to familiarize yourself with the theory of [[Theory_of_Operation#PID|PID Controllers]] before you begin tuning your airframe. Use of the [[RTPlotter|real time plotter]] may help to visualize and understand the behavior of the control loops. Review [http://paparazzi.enac.fr/w/images/Users_manual.pdf User Manual] as well. Also reading [http://www.av8n.com/how/ See How It Flies, by John S. Denker] is very beneficial to get your airframe tuned well.

==Energy Control==

If you came to this page and want to learn about how to perform your [[Tuning_energy_control_loops | Energy control tuning]], this is '''not''' the page to read, go to [[Tuning_energy_control_loops | tuning energy control loops]].

==Quickstart==

'''Here is the sub-minimal ultra-quick-start guide: note that point 1 and 3 should ALWAYS be performed every time you reflash your plane!!!'''

# Before take-off [[Tuning#Directions|check]] (beware: do not skip a test as it is not because 2 are good that the third will also be good)
## RC-left is aileron-left and up is up in MANUAL.
## RC-left is aileron-left and up is up in AUTO1.
## [[Tuning#Directions|turning the plane-left is aileron-right]] and nose-up is elevator-down with RC in neutral in AUTO1. (to check the [[GCS#PFD|Artificial horizon]] in the [[GCS|GCS]]: use the words: right wing sees the ground to not mess up left and right if uncertain.)
# Fly manual
## [[Tuning#Neutrals|trim your plane]]
## check [[Fixedwing_Configuration#Servos|servo deflections]] are good (sufficient but not aerobatic)
## remember the cruise throttle. (and max/min throttle if you will use aggressive-climb)
# On the ground, after trimming:
## Check with plane flat/cruise attitude on the ground that the ailerons/elevator do not move when you switch from MANUAL to AUTO1. This checks your IMU/Thermopiles are properly aligned and that [[Tuning#Trim|your trim values are in the airframe file and not the RC-transmitter]]
# Test [[Tuning#Auto_1|try AUTO1]]
## When entering AUTO1, make sure you try to turn before your plane is too far away since [[Fixedwing_Configuration#Auto1|AUTO1 circles are usually much larger than manual circles]].
## Make a [[RTPlotter|graph]] on the groundstation of DESIRED->phi/theta and ATTITUDE-phi/theta to see if they match.
## When flying with IMU pay special attention here if after several left turns the plane still turns right too. Plot the IMU_ACC->ax,ay,az to see the average vibration in your plane. If the vibration level is lower than half of gravity (5m/s2) than usually you are OK. If it is much more, you should dampen your IMU more. (in foam, or mounted on your heavy battery, ...)
# Only when AUTO1 works fine you can [[Tuning#Auto_1|go to AUTO2]]
## check that your Throttle is not Killed (RED) in the groundstation
## check that your cruise throttle is correct if you have a powerful motor
## if tuning the altitude loop seems difficult try the [[Tuning#Sample.2FSimple_Altitude_and_Throttle_Loop|simple 3 gain auto_throttle_loop]]

== Sensors ==

=== Neutrals ===
* Put the aircraft in a styrofoam container or completely seal the IR sensors with styrofoam or similar blocks and get a reading of the neutrals for each axis. Also take the gyro neutrals at this time. Update your airframe file, flash the AP and re-check the neutrals.

Using the roll gyro as a worked example: Run up your GCS and ensure it
is communicating with your airframe. Make sure your airframe is roughly
level and that it cannot move. Now run the Messages Tool and the [[RTPlotter|real time plotter]] tool. The messages tool will have lots of flashing lights
indicating when it receives various telemetry packets. In the Messages
tool, Click on Gyro Rates and you should see a list of variables. Click
on Roll_ADC and drag and drop in onto the main window of the Real Time plotter. Now give it a while to build a stable graph.

Once things have been running this way for a while, in the Real Time
Plotter, click on Curves in the menu and select the
1:telemetry:GYRO_RATES:Roll_ADC entry. As you select it, you should see
the average and standard deviation values. We need the average value.
Jot down the number you have. I have -24.536.

Now go edit your airframe file and look for the ADC_ROLL_NEUTRAL value.
In my airframe file the value is 520. As my average value from the Plotter is a
negative figure, it indicates that the roll Neutral is too high, subtract the average value from the present setting. So I edited my airframe file to be 495.464 (520-24.536).

Recompile and reflash (Don't worry about restarting the GCS, The
messages program or the other running processes - they will catch up just
fine after flashing). Once the Board is back up and the plotter continues, reset it from the menu to get rid of the average. Watch it for a while and check that the line and acculmulated average is on or around 0. You are done. Use the same process for the IR sensors!

=== Directions ===
* Reverse any servos and make sure no mechanical binding occurs at the limits of travel in Manual mode.
* Take the plane outside and engage AUTO1. Bank and pitch the plane and verify that the controls respond in the correct direction AND that the PFD in the notebook responds correctly. Note that your body will have a tremendous impact on the measured angles if using IR sensors. If using an IMU, there is no need to be outside. See note.
* Verify that AUTO1 stick movements respond in the correct direction - important! See note.
* Move the plane rapidly to ensure the gyro response resists motion - increase the gain if needed for better visualization.
NOTE: If the PFD responds in the wrong direction to the motion, you should adjust parameters in the INFRARED or IMU parts of the airframe file. If the control surfaces respond in the wrong direction to counteract motion (stabilize the aircraft, bring it back to neutral), reverse the servos in the airframe file. If the manual input from R/C causes the control surfaces to respond in the wrong direction (want them to force motion, not counteract motion), then you must reverse the channel on the R/C transmitter. Be sure to recheck surface neutrals and endpoints after doing such modifications. Also double check the gain signs, make sure none are positive that should be negative.

== R/C, Modem, and GPS ==
* Make sure the GPS signal is strong (outdoors) - you should have a 3-D fix in less than 1 minute and at least some satellite signals above 40dB. The plane should not drift on the map by more than 10 meters.
* Perform a range test of R/C and modem signals.
* Ensure that two way communications are in place. Check that the motor starts up when launch is commanded or move a waypoint and check that it's updated in the autopilot.

== Trim ==
<b>Important: You must never keep any trim, mixers, or rates in your R/C transmitter.</b> R/C trim can be applied in flight but must be corrected and removed on the ground before attempting autonomous flight. Exponential can be useful and will not adversely affect AUTO1 flight but if "low rates" are needed they should be programmed on the same transmitter switch with AUTO1 so that you always have full travel in AUTO1.
* Fly the plane at what you feel is a suitable "cruise" throttle setting and set the trims. Note that setting in the GCS and try to return to that exact setting in subsequent tests. Enter that throttle setting in your airframe file.
* Check maximum pitch and roll response and adjust the mixer parameters or mechanical linkages after landing.
* Land and adjust the linkages. If necessary, the PPM values can be read from the GCS and servo neutrals adjusted electronically, but manual adjustment will produce far better results.
* Fly again to verify trim and control response. If satisfactory, check for any significant throttle-dependent roll. Again, this is best to correct mechanically but can be addressed with the ''AILERON_OF_THROTTLE'' mixer in the autopilot. Check also for any odd behavior at full throttle.
* Make sure that GPS and modem data is reliable during these test flights. Note particularly any tendency for the aircraft to appear to fly sideways on the map - this is an indication of weak GPS signals.

== Auto 1 ==
* Engage Auto1 and ''immediately'' make sure you can turn both left and right!
* Fly at your "cruise" throttle and adjust the ''ROLL_PGAIN'' until the plane doesn't quite oscillate
* Adjust the IR roll neutral as needed
* Verify adequate pitch response and adjust PITCH_PGAIN as needed
* Experiment with different throttle settings and tune P and D gains as needed

If you are alone in the field while tuning, setting values via your RC transmitter may come in handy, see [[Telemetry#R.2FC_Transmitter_Data_Uplink|RC reveiver data uplink]]

== Auto 2 ==
* Engage Auto2 and you're done! Make sure you keep a finger on the Mode switch to take over just in case.

==Alternate Tuning Procedure==
Danstah wrote up a tuning procedure on this website http://www.engr.usu.edu/wiki/index.php/OSAMtuning

==Sample/Simple Altitude and Throttle Loop==

The dash button changes the NOMINAL_CRUISE_THROTTLE to the MAX_CRUISE_THROTTLE while the loiter button changes it to MIN_CRUISE_THROTTLE.

This makes it easy to suddenly make the UAV fly a bit slower or a bit faster. However, when changing the throttle, you also need to change the elevator trim in order not to climb/descend too much. This it what AUTO_THROTTLE_LOITER_TRIM and AUTO_THROTTLE_DASH_TRIM are for. (I think the unit is MAX_PPRZ = 9600 = full deflection?)

The auto-throttle loop is actually the most difficult loop to tune as it has both the speed and altitude that are correlated. Controlling both speed and altitude with high performance is very hard. It is way easier to control 1 entity (e.g. altitude) with higher performance and let the speed change a bit, or have an airspeed controller but then do the altitude slowly...

Sample altitude controller:
---------------------

Step1: outerloop: if altitude is not good -> compute a climb/descend rate. (including ALTITUDE_MAX_CLIMB)

climb_command = altitude_error x alt_pgain

e.g. 10 m too low x 0.1 alt gain = climb_command at 1 m/s
e.g. 50 m too low x 0.1 alt gain = climb at 5 m/s > ALTITUDE_MAX_CLIMB(2) -> climb_command = 2m/s

---------------------

Step2: innerloop: [many many options here, but since you ask for simple I'll only give one robust and simple:]

too low -> pitch up and extra throttle (if you only apply throttle, airspeed will increase and might even start to dive with full throttle if the nose is a bit heavy, if you only apply pitch airspeed will decrease and could lead to stall, with proper tuning you can get a pretty constant speed even while climbing and descending)

pitch_command = climb_command x pitch_of_vz
throttle_command = nominal_cruise_trim_throttle + climb_command x throttle_climb_increment

e.g. climb_command at 1 m/s x pitch_of_vz 0.15 = 0.15 radians pitch = 9 degrees pitch up

e.g. climb_command at 1 m/s x throttle_climb_increment 0.25 with nominal_cruise_trim_throttle 0.5 = 75% throttle

-------------------

If you use AGRESSIVE_CLIMB then if the altitude error is larger than the chosen threshold a precomputed pitch and throttle will be applied.

AUTO_PITCH is for constant throttle and control height with elevator only

auto_throttle_p/i/d_gains are to regulate the climb rate more precisely

==Other Misc things before flying==

It's very important to address the issue of low voltage cut-off before flying (LVC). There's a good chance that the LVC will kick in on the brushless ESC before the Paparazzi detects it. If this happens, the ESC cut's off throttle, and there's no way the autopilot knows this, the plane keeps loosing altitude, the autopilot tries to increase throttle, but the ESC does not respond, almost always leading to a mishap. To avoid this, either turn off the LVC on the ESC, OR, make sure the autopilot kills throttle first, by programming the CATASTROPHIC_BAT_LEVEL to something higher than the ESC LVC. For example, set CATASTROPHIC_BAT_LEVEL to 9.5V, and the ESC LVC at 9V. Don't ask how we know, it was a safe landing into a small tree :) No damage. BUT you cant get lucky always!

[[Category:Software]] [[Category:User_Documentation]]

Radio Control

2013-09-10T03:47:23Z

Alonsoac: /* Radio */

== PPM Radio Configuration ==

This XML file, usually located in the <tt>conf/radios</tt> directory, contains a description of the radio control transmitter PPM signal. It should follow the grammar described in <tt>radio.dtd</tt>. <b>This is only used for PPM transmitters so it does not apply to DSM/DSM2/FASST/FHSS or other 2.4Mhz radios.</b>

The contents are an '''ordered''' sequence of elements describing each channel with its name and its range:

<tt><!DOCTYPE radio SYSTEM "radio.dtd">
<radio name="cockpitMM" data_min="900" data_max="2100" sync_min ="5000" sync_max ="15000" pulse_type="POSITIVE">
<channel ctl="D" function="ROLL" min="2000" neutral="1498" max="1000" average="0"/>
...
<channel ctl="E" function="MODE" min="2000" neutral="1500" max="1000" average="1"/>
...
</radio></tt>

The order of the channels must be the order of the pulses in the PPM signal.

Among the top attributes, we find

* <tt>name</tt>: used only in debug traces.
* <tt>data_min</tt> (resp. <tt>_max</tt>): the minimum (resp. max) width (in microseconds) used to code one channel of the PPM signal.
* <tt>sync_min</tt> (resp. <tt>_max</tt>): the minimum (resp. max) width (in microseconds) between two impulses set of the PPM signal.
* <tt>pulse_type</tt>: the polarity of the PPM pulse. Can be either <tt>POSITIVE</tt> (FUTABA, Hitec, Multiplex etc) or <tt>NEGATIVE</tt> (JR, Graupner etc.).<br/>With <tt>POSITIVE</tt> it will trigger on the rising flank to measure the time of the positive pulse, with <tt>NEGATIVE</tt> on the falling flank (for a negative pulse width).

Each channel is described with its transmitter name (<tt>ctl</tt>), its <tt>function</tt> name, its range in microseconds and its neutral value in microseconds.
These values are used by the autopilot to compute a normalized input from the PPM signal (this file is preprocessed and the produced code is included in the airborne code). Note that the <tt>min</tt> and <tt>max</tt> attributes can be exchanged to reverse the direction of the command.

'''Wrong attributes of the "radio" element will prevent the decoder to recognize any PPM frame; same for a wrong number or channels.'''

=== Number of channels ===

Note that the number of channels in your radio file <b>must exactly match</b> the number of channels in the ppm sum signal the autopilot receives.<br>
Also the ''function'' names must be unique.

* in case of analog 35MHz receivers it is the RC - TRANSMITTER that makes the pulse train (receiver only does RF part)
** radio file depends on transmitter, you could swap to another receiver (and e.g. you can use a 4channel receiver to receive 9 pulses :-) )
* in case of digital receivers it is not the transmitter but the receiver that makes the pulses
** e.g. Futaba Fasst 6017: you can use any compatible transmitter without need to change the radio file
* in case of an encoder it is the encoder that makes the summed pulse
** if the encoder software makes 8 pulses, even with a 5 channel RC connected paparazzi will get 8: so the radio file should read 8

This means if your transmitter sends for example a PPM18 (Graupner/JR) signal you have nine (9) different servo channels. Even if you use a receiver with less channels you must set up <b>all</b> transmitting servos, even if you do not use them then you must use "bogus switches" related to functions. For example a six (6) servo channels out receiver with five (5) functions used in combination with a nine (9) servo channels transmitter would need four (4) bogus entries. (5 + 4 = 9)

...
<channel ctl="NoneA" function="NOTUSEDA" min="1100" neutral="1500" max="1900" average="0"/>
<channel ctl="NoneB" function="NOTUSEDB" min="1100" neutral="1500" max="1900" average="0"/>
<channel ctl="NoneC function="NOTUSEDC" min="1100" neutral="1500" max="1900" average="0"/>
<channel ctl="NoneD" function="NOTUSEDD" min="1100" neutral="1500" max="1900" average="0"/>
...

=== Averaging ===

The <tt>average</tt> attribute must be set to '''1..x''' for ''discrete'' channels for which a trivial averaging filter will be applied. The neutral of a discrete channel need to be halfway through the min and max values. Otherwise it won't be mapped properly by the filter. Note that averaging a channel gives the output an additional small delay.

== Direction ==

The following signs have been used in the radio configuration files distributed in <tt>conf/radios</tt>:

* '''ROLL''': The <tt>min</tt> attribute value stands for the right position of the stick (turning right)
* '''PITCH''': The <tt>max</tt> attribute value stands for the up position of the stick (pitching up)

''' From "v3.9" on this has been changed to follow standard aerospace conventions:'''
* '''ROLL''': The <tt>max</tt> attribute value stands for the right position of the roll stick (banking right)
* '''PITCH''': The <tt>max</tt> attribute value stands for the "up" position of the pitch stick pulled towards you (pitching up)
* '''YAW''': The <tt>max</tt> attribute value stands for the right position of the yaw stick (yawing clock-wise)

=== Practical test ===
In the RC message:
* when the ROLL stick is pulled to the right (aircraft banks right), you should see a value close to -MAX_PPRZ (-9600) in the ROLL channel
* When the PITCH stick is pulled (aircraft pitches up), you should see a value close to MAX_PPRZ (9600) in the PITCH channel

''' From "v3.9" on this has been changed to follow standard aerospace conventions:'''
* when the ROLL stick is pulled to the right (aircraft banks right), you should see a value close to MAX_PPRZ (9600) in the ROLL channel
* When the PITCH stick is pulled (aircraft pitches up), you should see a value close to MAX_PPRZ (9600) in the PITCH channel
* When the YAW stick is pulled to the right (aircraft yawing clock-wise), you should see a value close to MAX_PPRZ (9600) in the YAW channel

This works with all kind of radios (PPM, USB, 2.4GHz)

== Example ==

Below an example of an radio file.
<nowiki>
<?xml version="1.0"?>





<radio name="GraupnerMC20" data_min="950" data_max="2150" sync_min="5000" sync_max="15000" pulse_type="NEGATIVE">
<channel ctl="A" function="THROTTLE" min="1100" neutral="1100" max="1900" average="0"/> 
<channel ctl="B" function="ROLL" min="1100" neutral="1500" max="1900" average="0"/> 
<channel ctl="C" function="PITCH" min="1900" neutral="1500" max="1100" average="0"/> 
<channel ctl="D" function="YAW" min="1100" neutral="1500" max="1900" average="0"/> 
<channel ctl="E" function="MODE" min="1100" neutral="1500" max="1900" average="1"/> 
<channel ctl="F" function="GAIN1" min="1100" neutral="1500" max="1900" average="0"/> 
<channel ctl="G" function="GAIN2" min="1100" neutral="1500" max="1900" average="0"/> 
<channel ctl="H" function="SWITCH1" min="1100" neutral="1500" max="1900" average="1"/> 
<channel ctl="I" function="UNUSED" min="1100" neutral="1500" max="1900" average="1"/> 
</radio>
</nowiki>

== PPM input to output chain ==
The chain from ppm input to servo output has intermediate steps and roughly looks like this:

ppm input --(radio.xml)--> ppm_pulses[] --(radio.xml)--> radio_control.values[] --([[Fixedwing_Configuration#Manual|rc_commands]])--> commands[] --([[Fixedwing_Configuration#Servos|command_laws,servos]])--> actuators_pwm_values[] ppm out

Written in parenthesis is where you configure how to transform one value into the other.

So in a simple case without fancy mixing, e.g. looking at the roll command / aileron servo while in MANUAL mode:
#PPM sum signal is read and split into channels as specified in your radio xml file.<br/>It does some sanity checking on the pulse length and frame lenght according to the top attributes in that file.<br/>This is written to the ppm_pulses array, where you now have the length of the pulse in system ticks.
#Now these get converted to radio_control.values array according to the channels in your radio xml file.<br/>They get scaled to MAX_PPRZ (9600), meaning what you specified as max is 9600, neutral is 0, etc.<br/>radio_control.values[RADIO_ROLL] now has the value 9600 if the pulse width of that channels was "max"
#Mapping of RC commands to the actual commands as specified in rc_commands section.<br/>In your case simply copy radio_control.values[RADIO_ROLL] to commands[COMMAND_ROLL]
#Applying command_laws (mixing) to get the commands for each servo.<br/>Again just copying in your case...
#Scaling from commands with MAX_PPRZ scale to the actual pwm output signal according to the servos section.

== Measuring the PPM time values ==

[[Image:RC_Receiver_Timing_Diagram.jpg|thumb|R/C receiver timing diagram]]

There are two common ways to measure the time characteristics of the PPM signal:
# Using an oscilloscope: easy to achieve with a high level digital scope with capture and measure facilities.
# Using the telemetry of the autopilot: the '''PPM''' message (defined in <tt>conf/messages.xml</tt>) contains the sequence of a (recently) received PPM signal.

With the default telemetry configuration file (<tt>conf/telemetry/default_fixedwing.xml</tt>), this message is '''not''' sent in the '''default''' fbw telemetry mode (numbered 0).

There are two ways to enable this message:
* Use the settings mechanism to change the FBW telemetry mode while the autopilot is already running:<br/>In the GCS: Settings -> telemetry -> tele_FBW -> set to debug (1)
* This mode can be permanently changed to '''debug''' (numbered 1) in the airframe file by setting the '''TELEMETRY_MODE_FBW''' constant in your firmware section:
<tt><define name="TELEMETRY_MODE_FBW" value="1"/></tt>.

'''Since "v3.9" the values in the PPM message are in µs.'''

Before "v3.9" the time unit used in this '''PPM''' message was hardware dependent:
* On the obsolete AVR hardware, 1 microsecond = 16 units (because the crystal is running at 16MHz)
* on the LPC hardware, 1 microsecond = 15 units (because the cristal is running at 12MHz)
*:(<tt>conf/autopilot/tiny.h</tt>), the CPU clock is 5 times more, the peripheral bus is 4 times less, and the timer is not prescaled (<tt>sw/airborne/arch/lpc21/mcu_periph/sys_time_arch.h</tt>) !!!)

== Tips ==

If one has a good servo tester the output values at the receiver side can be measured

[[Category:Software]] [[Category:User_Documentation]]

Radio Control

2013-09-10T03:46:16Z

Alonsoac: clarify that this is not for 2.4mhz radios

== Radio ==

This XML file, usually located in the <tt>conf/radios</tt> directory, contains a description of the radio control transmitter PPM signal. It should follow the grammar described in <tt>radio.dtd</tt>. <b>This is only used for PPM transmitters so it does not apply to DSM/DSM2/FASST/FHSS or other 2.4Mhz radios.</b>

The contents are an '''ordered''' sequence of elements describing each channel with its name and its range:

<tt><!DOCTYPE radio SYSTEM "radio.dtd">
<radio name="cockpitMM" data_min="900" data_max="2100" sync_min ="5000" sync_max ="15000" pulse_type="POSITIVE">
<channel ctl="D" function="ROLL" min="2000" neutral="1498" max="1000" average="0"/>
...
<channel ctl="E" function="MODE" min="2000" neutral="1500" max="1000" average="1"/>
...
</radio></tt>

The order of the channels must be the order of the pulses in the PPM signal.

Among the top attributes, we find

* <tt>name</tt>: used only in debug traces.
* <tt>data_min</tt> (resp. <tt>_max</tt>): the minimum (resp. max) width (in microseconds) used to code one channel of the PPM signal.
* <tt>sync_min</tt> (resp. <tt>_max</tt>): the minimum (resp. max) width (in microseconds) between two impulses set of the PPM signal.
* <tt>pulse_type</tt>: the polarity of the PPM pulse. Can be either <tt>POSITIVE</tt> (FUTABA, Hitec, Multiplex etc) or <tt>NEGATIVE</tt> (JR, Graupner etc.).<br/>With <tt>POSITIVE</tt> it will trigger on the rising flank to measure the time of the positive pulse, with <tt>NEGATIVE</tt> on the falling flank (for a negative pulse width).

Each channel is described with its transmitter name (<tt>ctl</tt>), its <tt>function</tt> name, its range in microseconds and its neutral value in microseconds.
These values are used by the autopilot to compute a normalized input from the PPM signal (this file is preprocessed and the produced code is included in the airborne code). Note that the <tt>min</tt> and <tt>max</tt> attributes can be exchanged to reverse the direction of the command.

'''Wrong attributes of the "radio" element will prevent the decoder to recognize any PPM frame; same for a wrong number or channels.'''

=== Number of channels ===

Note that the number of channels in your radio file <b>must exactly match</b> the number of channels in the ppm sum signal the autopilot receives.<br>
Also the ''function'' names must be unique.

* in case of analog 35MHz receivers it is the RC - TRANSMITTER that makes the pulse train (receiver only does RF part)
** radio file depends on transmitter, you could swap to another receiver (and e.g. you can use a 4channel receiver to receive 9 pulses :-) )
* in case of digital receivers it is not the transmitter but the receiver that makes the pulses
** e.g. Futaba Fasst 6017: you can use any compatible transmitter without need to change the radio file
* in case of an encoder it is the encoder that makes the summed pulse
** if the encoder software makes 8 pulses, even with a 5 channel RC connected paparazzi will get 8: so the radio file should read 8

This means if your transmitter sends for example a PPM18 (Graupner/JR) signal you have nine (9) different servo channels. Even if you use a receiver with less channels you must set up <b>all</b> transmitting servos, even if you do not use them then you must use "bogus switches" related to functions. For example a six (6) servo channels out receiver with five (5) functions used in combination with a nine (9) servo channels transmitter would need four (4) bogus entries. (5 + 4 = 9)

...
<channel ctl="NoneA" function="NOTUSEDA" min="1100" neutral="1500" max="1900" average="0"/>
<channel ctl="NoneB" function="NOTUSEDB" min="1100" neutral="1500" max="1900" average="0"/>
<channel ctl="NoneC function="NOTUSEDC" min="1100" neutral="1500" max="1900" average="0"/>
<channel ctl="NoneD" function="NOTUSEDD" min="1100" neutral="1500" max="1900" average="0"/>
...

=== Averaging ===

The <tt>average</tt> attribute must be set to '''1..x''' for ''discrete'' channels for which a trivial averaging filter will be applied. The neutral of a discrete channel need to be halfway through the min and max values. Otherwise it won't be mapped properly by the filter. Note that averaging a channel gives the output an additional small delay.

== Direction ==

The following signs have been used in the radio configuration files distributed in <tt>conf/radios</tt>:

* '''ROLL''': The <tt>min</tt> attribute value stands for the right position of the stick (turning right)
* '''PITCH''': The <tt>max</tt> attribute value stands for the up position of the stick (pitching up)

''' From "v3.9" on this has been changed to follow standard aerospace conventions:'''
* '''ROLL''': The <tt>max</tt> attribute value stands for the right position of the roll stick (banking right)
* '''PITCH''': The <tt>max</tt> attribute value stands for the "up" position of the pitch stick pulled towards you (pitching up)
* '''YAW''': The <tt>max</tt> attribute value stands for the right position of the yaw stick (yawing clock-wise)

=== Practical test ===
In the RC message:
* when the ROLL stick is pulled to the right (aircraft banks right), you should see a value close to -MAX_PPRZ (-9600) in the ROLL channel
* When the PITCH stick is pulled (aircraft pitches up), you should see a value close to MAX_PPRZ (9600) in the PITCH channel

''' From "v3.9" on this has been changed to follow standard aerospace conventions:'''
* when the ROLL stick is pulled to the right (aircraft banks right), you should see a value close to MAX_PPRZ (9600) in the ROLL channel
* When the PITCH stick is pulled (aircraft pitches up), you should see a value close to MAX_PPRZ (9600) in the PITCH channel
* When the YAW stick is pulled to the right (aircraft yawing clock-wise), you should see a value close to MAX_PPRZ (9600) in the YAW channel

This works with all kind of radios (PPM, USB, 2.4GHz)

== Example ==

Below an example of an radio file.
<nowiki>
<?xml version="1.0"?>





<radio name="GraupnerMC20" data_min="950" data_max="2150" sync_min="5000" sync_max="15000" pulse_type="NEGATIVE">
<channel ctl="A" function="THROTTLE" min="1100" neutral="1100" max="1900" average="0"/> 
<channel ctl="B" function="ROLL" min="1100" neutral="1500" max="1900" average="0"/> 
<channel ctl="C" function="PITCH" min="1900" neutral="1500" max="1100" average="0"/> 
<channel ctl="D" function="YAW" min="1100" neutral="1500" max="1900" average="0"/> 
<channel ctl="E" function="MODE" min="1100" neutral="1500" max="1900" average="1"/> 
<channel ctl="F" function="GAIN1" min="1100" neutral="1500" max="1900" average="0"/> 
<channel ctl="G" function="GAIN2" min="1100" neutral="1500" max="1900" average="0"/> 
<channel ctl="H" function="SWITCH1" min="1100" neutral="1500" max="1900" average="1"/> 
<channel ctl="I" function="UNUSED" min="1100" neutral="1500" max="1900" average="1"/> 
</radio>
</nowiki>

== PPM input to output chain ==
The chain from ppm input to servo output has intermediate steps and roughly looks like this:

ppm input --(radio.xml)--> ppm_pulses[] --(radio.xml)--> radio_control.values[] --([[Fixedwing_Configuration#Manual|rc_commands]])--> commands[] --([[Fixedwing_Configuration#Servos|command_laws,servos]])--> actuators_pwm_values[] ppm out

Written in parenthesis is where you configure how to transform one value into the other.

So in a simple case without fancy mixing, e.g. looking at the roll command / aileron servo while in MANUAL mode:
#PPM sum signal is read and split into channels as specified in your radio xml file.<br/>It does some sanity checking on the pulse length and frame lenght according to the top attributes in that file.<br/>This is written to the ppm_pulses array, where you now have the length of the pulse in system ticks.
#Now these get converted to radio_control.values array according to the channels in your radio xml file.<br/>They get scaled to MAX_PPRZ (9600), meaning what you specified as max is 9600, neutral is 0, etc.<br/>radio_control.values[RADIO_ROLL] now has the value 9600 if the pulse width of that channels was "max"
#Mapping of RC commands to the actual commands as specified in rc_commands section.<br/>In your case simply copy radio_control.values[RADIO_ROLL] to commands[COMMAND_ROLL]
#Applying command_laws (mixing) to get the commands for each servo.<br/>Again just copying in your case...
#Scaling from commands with MAX_PPRZ scale to the actual pwm output signal according to the servos section.

== Measuring the PPM time values ==

[[Image:RC_Receiver_Timing_Diagram.jpg|thumb|R/C receiver timing diagram]]

There are two common ways to measure the time characteristics of the PPM signal:
# Using an oscilloscope: easy to achieve with a high level digital scope with capture and measure facilities.
# Using the telemetry of the autopilot: the '''PPM''' message (defined in <tt>conf/messages.xml</tt>) contains the sequence of a (recently) received PPM signal.

With the default telemetry configuration file (<tt>conf/telemetry/default_fixedwing.xml</tt>), this message is '''not''' sent in the '''default''' fbw telemetry mode (numbered 0).

There are two ways to enable this message:
* Use the settings mechanism to change the FBW telemetry mode while the autopilot is already running:<br/>In the GCS: Settings -> telemetry -> tele_FBW -> set to debug (1)
* This mode can be permanently changed to '''debug''' (numbered 1) in the airframe file by setting the '''TELEMETRY_MODE_FBW''' constant in your firmware section:
<tt><define name="TELEMETRY_MODE_FBW" value="1"/></tt>.

'''Since "v3.9" the values in the PPM message are in µs.'''

Before "v3.9" the time unit used in this '''PPM''' message was hardware dependent:
* On the obsolete AVR hardware, 1 microsecond = 16 units (because the crystal is running at 16MHz)
* on the LPC hardware, 1 microsecond = 15 units (because the cristal is running at 12MHz)
*:(<tt>conf/autopilot/tiny.h</tt>), the CPU clock is 5 times more, the peripheral bus is 4 times less, and the timer is not prescaled (<tt>sw/airborne/arch/lpc21/mcu_periph/sys_time_arch.h</tt>) !!!)

== Tips ==

If one has a good servo tester the output values at the receiver side can be measured

[[Category:Software]] [[Category:User_Documentation]]

Module/Servo switch

2013-08-29T22:46:01Z

Alonsoac: fix some errors

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Modules</categorytree>
This module allows you to easily '''control a servo output like a switch''' (e.g. for a hatch, cam trigger, etc) '''via Flight Plan and GCS''' ('''not via RC!''').

To use it load the servo_switch module:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
...
<load name="servo_switch.xml"/>
</modules>
</source>
}}

Now you only have to declare a servo in your airframe.xml that you
want to use.

By default the servo_switch module looks for a servo called SWITCH.
The switch on value is 2000us and switch off is 1000us by default.
e.g. in my airframe file I have:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<servos>
....
<servo name="SWITCH" no="7" min="1000" neutral="1500" max="2000"/>
</servos>
</source>
}}

If you want to use a different servo/values you can set that in the
modules section, e.g. for a servo named HATCH:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
<load name="servo_switch.xml">
<define name="SERVO_SWITCH_ON_VALUE" value="1100"/>
<define name="SERVO_SWITCH_OFF_VALUE" value="1900"/>
<define name="SERVO_SWITCH_SERVO" value="HATCH"/>
</load>
</modules>
</source>
}}
Of course you only have to set these parameters here If you do not
want to use the DEFAULT servo (SWITCH) or the default on/off values. Switch value will not go outside the range defined on the servo

=== Calling from Flight Plan ===
In your flight plan you just call the macro defined in servo_switch.h
<source lang="xml"><call fun="ServoSwitchOn()"/></source>
or
<source lang="xml"><call fun="ServoSwitchOff()"/></source>
respectively.

=== Buttons in the GCS ===

To get buttons for the servo switch module in the GCS add conf/settings/modules/servo_switch.xml to the settings files of your aircraft.

[[Category:Modules]]

Module/System monitor

2013-08-26T16:25:52Z

Alonsoac:

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Modules</categorytree>
The sys_mon module gives you some information about the timing of the periodic tasks and a rough estimate of cpu load (averaged over 1 sec).

The SYS_MON message contains the following information ('''all times are given in microseconds'''):
; periodic_time : time between two calls of the main periodic function (averaged over 1s)
; periodic_cycle : time it took to execute the main periodic functions (averaged over 1s)
; periodic_cycle_min : minimum time it took to execute the main periodic functions during the last second
; periodic_cycle_max : maximum time it took to execute the main periodic functions during the last second
; event_number : number of times the event loop was called during the last second
; cpu_load : rough estimate of cpu load (averaged over 1 sec)

So your periodic_time should be 1/PERIODIC_FREQUENCY.
The periodic_cycle_max should not be over the periodic_time, otherwise in at least one cycle it took longer to calculate everything and the next one was slightly delayed.

'''The sys_mon module has to run at the full main frequency!'''

'''So either don't specify a ''[[Modules#In_the_airframe_file|main_freq]]'' parameter like in the example below or set your actual main frequency'''

To use it load the sys_mon module:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
...
<load name="sys_mon.xml"/>
</modules>
</source>
}}

[[Category:Modules]]

Advanced Navigation Routines

2013-08-12T19:43:35Z

Alonsoac: correction of waypoint names, as tested with version 5.0 _S2 was not correct, it is just S2

== [http://www.engr.usu.edu/wiki/index.php/OSAM OSAM Team] Navigation Routines ==
To use these navigation routines, you need to change the navigation subsystem type to extra in your airframe file. The navigation extra subsystem includes extra navigation routines like OSAMnav, spiral, poly_survey_advanced, nav_cube, etc.
<subsystem name="navigation" type="extra"/>

Also include OSAMNav.h in your flight plan:

#include "subsystems/navigation/OSAMNav.h"

=== Flower ===
[[Image:FlowerScreenShot.png|thumb|Screen shot of flower routine]]
The flower navigation routine flies the aircraft in a flower pattern defined by two waypoints. The center waypoint defines the center of the flower and the altitude the plane flies at. The edge waypoint defines the radius of the flower.

In our example the waypoints are called "Center" and "Edge":

<waypoint name="Center" x="-20.0" y="-160.0"/>
<waypoint name="Edge" x="-10.0" y="-60.0"/>

Then you can add flower to your flight plan:

<block name="Flower">
<call fun="InitializeFlower(WP_Center,WP_Edge)"/>
<call fun="FlowerNav()"/>
</block>

Note that in the function InitializeFlower the waypoints need the prefix "WP_".

=== Bungee Takeoff ===
The bungee takeoff routine helps to automate takeoff by turning the throttle on after the bungee has been release from the hook. The only waypoint you need for this routine is the position of where the bungee is pegged to the ground. Using this waypoint, a line is drawn from the position of the aircraft to the bungee waypoint. This line is called the launch line and will stop updating once the speed of the plane exceeds the MinSpeed. This allows the user to initialize the routine, move the plane and launch it without having to reinitialize. Once the plane is launched, it will follow the launch line until it crosses the throttle line. The throttle line is a line perpendicular to the launch line at a distance d from the bungee waypoint (see the diagram below). When the plane crosses the throttle line and the speed of the aircraft is greater than MinSpeed, the throttle comes on. After the throttle comes on, the plane keeps going straight until it reaches a specified speed and altitude above the bungee waypoint altitude. When it reaches the takeoff speed and takeoff altitude, the next block in the flight plan is executed. The takeoff speed, takeoff altitude, MinSpeed and the distance d from the bungee waypoint are specified in the airframe file. You will need to add those values to your airframe file like this...

<section name="Takeoff" prefix="Takeoff_">
<define name="Height" value="30" unit="m"/>
<define name="Speed" value="15" unit="m/s"/>
<define name="Distance" value="3" unit="m"/>
<define name="MinSpeed" value="5" unit="m/s"/>
</section>

You can add the bungee takeoff routine to your flight plan like so...

<block name="Takeoff" strip_button="Takeoff (wp CLIMB)" strip_icon="takeoff.png">
<call fun="InitializeBungeeTakeoff(WP_Bungee)"/>
<call fun="BungeeTakeoff()"/>
</block>

To get this routine to work consistantly, you will need to tune the values in the airframe config file. If the prop doesn't automatically turn on when it crosses the throttle line, it could be because the Distance and/or the MinSpeed are too big. If it turns on to early, it could be because the Distance and/or MinSpeed are too small.

<span style="color:#ff0000"> ***Precaution should be taken while tuning the auto takeoff. If the MinSpeed is too low, the prop could turn on while holding the aircraft!***</span>

<gallery>
Image:BungeeTakeoffDiagram.png|Bungee takeoff diagram
Image:BungeeTakeoffInit.png|After bungee takeoff initialization
Image:BungeeTakeoffThrottleOn.png|After crossing the throttle line
</gallery>

=== Polygon Survey ===
==== Explanation ====
With this navigation routine, an aircraft can survey the area of any [http://en.wikipedia.org/wiki/Convex_polygon convex polygon] given an entry point, the number of waypoints which define the polygon, the sweep width and the desired orientation of the sweeps.

The entry point is the first corner of the polygon and the point at which the aircraft will begin surveying the area. When in the entry state, the aircraft will circle around the entry point in order to smoothly transition into the first sweep. The aircraft will also keep circling around the entry point until it gets to the waypoint altitude. After the first sweep is made, the direction of the next sweep is determined by the distance of the entry point to the edges of the polygon. If there is more area above the first sweep, the aircraft will sweep up. If there is more area below the first sweep, the aircraft will sweep down.

The aircraft will keep sweeping back and forth until it reaches the end of the polygon. At this point, the aircraft will sweep back up/down the polygon halfway in between the sweeps previously made by the aircraft (just like the rectangle survey function). The aircraft will keep sweeping up and down the polygon unless the user manually exits the block or unless an exception is used ([[#Exceptions|see below]]).

The orientation of the sweeps can ranges from north south to east west and any where in between (-90 <-> 90 degrees respectively). The side of the polygon the aircraft starts on (ex. north or south) is determined by the side of the polygon the entry point is located.

<gallery>
Image:PolySurveySweepDef.png|Sweep Definition
Image:PolySurveyEntryPic.png|Entry Point
Image:PolySurveySweepBack.png|Sweeping Back
</gallery>

==== Implementation ====
You can add this navigation routine in your flight plan like so...

<block name="Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, NumOfCorners, SweepWidth, Orientation)"/>
<call fun="PolygonSurvey()"/>
</block>

The parameters are the entry waypoint, the number of waypoints in the polygon, the sweep width (meters), and the desired orientation of the sweeps (degrees). The maximum number of waypoints a polygon can have is currently ten (can be changed in the code). If the number of waypoints in the polygon exceeds the maximum number, the routine will exit and move to the next block in the flight plan. The routine will also exit if the orientation is not between -90 and 90 degrees.

Here is an example of how you should declare each of the corners of the polygon.

<waypoint alt="1453.0" name="S1" x="-546.2" y="297.4"/>
<waypoint alt="1453.0" name="S2" x="-129.8" y="744.1"/>
<waypoint alt="1553.0" name="S3" x="1030.5" y="535.5"/>
<waypoint alt="1453.0" name="S4" x="523.0" y="-236.7"/>
<waypoint alt="1453.0" name="S5" x="-285.9" y="-255.7"/>

S1 is the entry waypoint and the first corner. The other corners should be in order clockwise or counter clockwise around the polygon. Even though this group of waypoints must be declared together, where the group appears in the list of waypoints doesn't matter.

If you want the edges of the polygon to show up on the GCS, you can also declare the polygon as a sector. This is not required to run the routine.

<sectors>
<sector name="PolySector">
<corner name="S1"/>
<corner name="S2"/>
<corner name="S3"/>
<corner name="S4"/>
<corner name="S5"/>
</sector>
</sectors>

<gallery caption="A Range of Different Sweep Orientations">
Image:PolySurvey0DegreeEx.png|0 Degrees
Image:PolySurvey30DegreeEx.png|30 Degrees
Image:PolySurvey65DegreeEx.png|65 Degrees
Image:PolySurvey90DegreeEx.png|90 Degrees
</gallery>

==== Alternative configurations ====
If you are wanting to start and stop the Poly Survey this is possible by splitting the Poly Survey code above into the initialization routine and the execution routine. You might want to do this if you are searching for something inside the Poly Survey, think you have found it and then realized you haven't, so you want to continue the survey (not restart it). Using the example above, but with the initialisation and execution code separate:

<block name="Init Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, NumOfCorners, SweepWidth, Orientation)"/>
</block>

<block name="Execute Poly Survey">
<call fun="PolygonSurvey()"/>
</block>

==== Exceptions ====
There are a couple of built in variables which can be used to exit the routine with an exception. PolySurveySweepNum gives the number of sweeps the aircraft has made and PolySurveySweepBackNum gives the number of times the aircraft has gotten to the bottom of the polygon and swept back. The first example would deroute the aircraft to standby after the aircraft made it's second sweep. The second example would deroute the aircraft to standby before it starts to sweep back up the polygon for the first time.

<block name="Poly Survey">
<exception cond="PolySurveySweepNum >= 2" deroute="Standby"/>
<call fun="InitializePolygonSurvey(WP_S1, 5, 200, 45)"/>
<call fun="PolygonSurvey()"/>
</block>

<block name="Poly Survey">
<exception cond="PolySurveySweepBackNum >= 1" deroute="Standby"/>
<call fun="InitializePolygonSurvey(WP_S1, 5, 200, 45)"/>
<call fun="PolygonSurvey()"/>
</block>

=== Flight Line ===
The Flight Line Routine allows the user to map/follow one dimensional areas of interest like roads and rivers. Given two waypoints, the routine will automatically transition into the flight line to ensure full coverage between the waypoints. In addition, distances before and after the flight line can be used to add extra security to the coverage.

[[Image:OSAMFlightLineDiagram.png|Flight Line Diagram]]

To use this navigation routine, you need to include OSAMNav.h in your flight plan and OSAMNav.c to your airframe file. Then add this navigation routine in your flight plan like so...

<block name="Map River">
<call fun="FlightLine(WP_R1,WP_R2,nav_radius,distance_before,distance_after)"/>
</block>

Multiple flight lines can be daisy chained by reusing waypoints as shown below...

<block name="Map River">
<call fun="FlightLine(WP_R1,WP_R2,nav_radius,100,100)"/>
<call fun="FlightLine(WP_R2,WP_R3,nav_radius,100,100)"/>
<call fun="FlightLine(WP_R3,WP_R4,nav_radius,100,100)"/>
<call fun="FlightLine(WP_R5,WP_R6,nav_radius,100,100)"/>
<deroute block="Standby"/>
</block>

However, the previous block can also be implemented using the FlightLineBlock function. The FlightLineBlock function works the same as the FlightLine function except it automatically steps through the waypoints between the given waypoints. Make sure the waypoints are declared in order or else it won't work!

<block name="Map River">
<call fun="FlightLineBlock(WP_R1,WP_R6,nav_radius,100,100)"/>
<deroute block="Standby"/>
</block>

<gallery>
Image:OSAMFlightLineExample.jpg |Multiple Flight Line Example
</gallery>

== misc ==

=== border_line ===

border_line is a nav-routine pretty similar to the nav-line-routine. You can use this nav-routine whenever you want to take care your plane stays on a defined site of a border.
For example you can use this routine to fly along a mountain and always turn away from the wall or you can fly along a road/border without penetrating one site.

Use "extra" navigation subsystem with:
<subsystem name="navigation" type="extra"/>

If you want to use waypoint 1 and 2 you can add border_line in your flight plan like this:
* Include header in "header" section at the beginning
#include "subsystems/navigation/border_line.h"
* Add function in a flight plan block:
<block group="extra_pattern" name="border line">
<call fun="border_line_init()"/>
<call fun="border_line(WP_1, WP_2, -nav_radius)"/>
</block>

<gallery caption="example">
Image:border_line.png|Screen shot of border_line
Image:border_line2.png|Screen shot of border_line2
Image:border_line3.png|Screen shot of border_line3
</gallery>

=== gls (gps landing system) ===

- defined glide path angle

- in flight changeable landing direction without loosing the glide path angle!

- smooth intercept independent of approach angle or wind

- seperation of approach fix, start decent and top of decent

- with fix target speed (in airspeed mode only)

how to setup your airframe.xml:

<section name="GLS_APPROACH" prefix="APP_">
<define name="ANGLE" value="5" unit="deg"/>
<define name="INTERCEPT_RATE" value="0.624"/>
<define name="DISTANCE_AF_SD" value="20"/>
<define name="TARGET_SPEED" value="14"/>
</section>

ANGLE - angle from TOD to TD

DISTANCE_AF_SD - minimum distance (meter) between AF and SD to allow the plane to self stabilize before the intercept starts (e.g. for speed reduction)

You can set the landing direction by moving the approach fix (AF) in relation to the touch down point (TD).
If you try to set the AF close to the TD you will see how the top of decent (TOD) and start decent (SD) is calculated and if necessary the AF is moved backwards.
(please try in simulation)

TARGET_SPEED - desired airspeed from AF to TD

INTERCEPT_RATE -

e.g. no wind: TARGET_SPEED = 14m/s and ANGLE = 10 --> desired decent rate 2.5 m/s (speed * tan(ANGLE))

with an INTERCEPT_RATE of 0.624 m/s/s it will take 4s to intercept the final approach path (desired decent rate / intercept_rate)

the idea is that the INTERCEPT_RATE is unique to each plane and will not change with different approach angles

to find an appropriate value you can start with a lower (to match 8s for example) and increase it until the intercept will be made from above

in general: bigger plane - smaller value!

how to setup your flightplan.xml:

<waypoints>
<waypoint height="150" name="AF" x="-260.6" y="-344.6"/>
<waypoint name="SD" x="-1600." y="-36."/>
<waypoint name="TOD" x="-1600." y="-36."/>
<waypoint height="0.0" name="TD" x="-27.2" y="-243.5"/>
<waypoint height="266.0" name="_BASELEG" x="-1652.1" y="-113.5"/>
</waypoints>

<block name="land">
<call fun="gls_init(WP_AF,WP_SD, WP_TOD, WP_TD)"/>
<call fun="nav_compute_baseleg(WP_AF, WP_TD, WP__BASELEG, nav_radius)"/>
<circle radius="nav_radius" until="NavCircleCount() > 0.5" wp="_BASELEG"/>
<circle radius="nav_radius" until="And(NavQdrCloseTo(DegOfRad(baseleg_out_qdr)-(nav_radius/fabs(nav_radius))*10),
10 > fabs(GetPosAlt() - WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
</block>

<block name="final">
<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/>
<call fun="gls(WP_AF,WP_SD, WP_TOD, WP_TD)"/>
</block>

those pictures match the old gls routine! anyway - the new one is not much different... (POS I = SD)
<gallery caption="theory">
Image:gls1.png|side view
Image:gls2.png|from above
Image:gls3.png|screen shot of flight test
</gallery>

== Multi-UAV ==
For TCAS (Traffic Collision Avoidance System) see the [[MultiUAV]] page.

[[Category:Software]] [[Category:Navigation]] [[Category:User_Documentation]]

GCS Configuration

2013-08-10T06:35:12Z

Alonsoac: explain how to use options

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>GCS</categorytree>
__TOC__

== Paparazzi Center ==
The paparazzi center is launched with the following command:
<tt>./sw/supervision/paparazzicenter</tt>
and is used to launch individual portions of the GCS (''Programs'') or the entire GCS (''Sessions'') with the modem and map settings defined in <tt><b>/conf/control_panel.xml</b></tt>

===Configuration Options===

Here all the commandline parameter to set specific option(s) while launching the GCS. To use these edit the file conf/control_panel.xml in the line that says <program name="GCS" command="sw/ground_segment/cockpit/gcs"> add the options, for example: <br>
<program name="GCS" command="sw/ground_segment/cockpit/gcs -fullscreen"><br>

'''-auto_ortho''', IGN tiles path
'''-b''', <ivy bus> Default is 127.255.255.255:2010
'''-center''', Initial map center (e.g. 'WGS84 43.605 1.443')
'''-center_ac''', Centers the map on any new A/C
'''-edit''', Flight plan editor
'''-fullscreen''', Fullscreen window
'''-maps_fill''', Automatically start loading background maps
'''-maps_zoom''', Background maps zoomlevel (default: 18, max: 22)
'''-ign''', IGN tiles path
'''-lambertIIe''', Switch to LambertIIe projection
'''-layout''', <XML layout specification> GUI layout. Default: horizontal.xml
'''-m''', Map XML description file
'''-maximize''', Maximize window
'''-mercator''', Switch to (Google Maps) Mercator projection, default
'''-mplayer''', Launch mplayer with the given argument as X plugin
'''-no_alarm''', Disables alarm page
'''-maps_no_http''', Switch off downloading of maps, always use cached maps
'''-ortho''', IGN tiles path
'''-osm''', Use OpenStreetMap database (default is Google)
'''-ms''', Use Microsoft maps database (default is Google)
'''-particules''', Display particules
'''-plugin''', External X application (launched with the id of the plugin window as argument)
'''-ref ''',Geographic ref (e.g. 'WGS84 43.605 1.443')
'''-speech''', Enable vocal messages
'''-srtm''', Enable SRTM elevation display
'''-track_size''', Default track length (500)
'''-utm''', Switch to UTM local projection
'''-wid''', <window id> Id of an existing window to be attached to
'''-zoom''', Initial zoom
'''-auto_hide_fp''', Automatically hide flight plans of unselected aircraft
'''-help''', Display a list of options

=== Video plugin ===

The <tt>-mplayer</tt> option of GCS allows to the user to display a video stream in a window of the GCS. The video window can also be exchanged with the map by clicking anywhere inside the frame.
Use the following line in your <tt>/conf/control_panel.xml</tt> to enable the video window.
<tt>path_to_ground_segment/cockpit/gcs -mplayer rtsp://localhost:7070/video</tt>
A useful example follows:
If you have an Avermedia DVB-T usb tuner like the Aver-Tv Hybrid Volar HX (Avermedia finally released Ubuntu Linux drivers)
then in order to use the usb tuner as video input to the GCS you have to complete the following steps:

First download and install the drivers and check that the Usb tuner works well by opening a console window
and typing:

'''mplayer tv:// -tv driver=v4l2:width=320:height=240:norm=NTSC:input=1:device=/dev/video1:noaudio'''

Of course you must connect a video signal to the composite input first.
Then close the console and remove the Usb tuner.
Now it is time to configure the control_panel.xml file by editing the GCS command line.
Locate the line in the "control_panel.xml" usually located in /Your Paparazzi directory/conf/ (mine is in "/paparazzi/conf/")
that looks similar to the below line:

'''<program name="GCS" command="sw/ground_segment/cockpit/gcs -layout horizontal.xml">'''

Then edit it so it looks like this:

'''<program name="GCS" command="sw/ground_segment/cockpit/gcs -layout horizontal.xml -mplayer 'tv:// -tv driver=v4l2:width=320:height=240:norm=NTSC:input=1:device=/dev/video1:alsa:adevice=hw.2,0:amode=1:audiorate=48000:forceaudio:volume=100:immediatemode=0'">'''

The above line is one complete and uninterrupted line but it is just too long to show it in one line here.
(There is a space after the"-tv" like this "-mplayer 'tv:// -tv driver=v4l2:...." but nowhere else after that).
This will load the mplayer, select the composite video input of the tuner and enable the sound input.
Please remember to change the "NTSC" with "PAL" if you do not use the NTSC video system (if your airborne camera is PAL for example).
Read the mplayer documentation so you can tweak the resolution etc. later to suit your particular setup.
The resolution above is set to 320x240 here but you can set it to 640x480 by replacing the numbers in the command line above.

Finally you have to add the plugin widget to your GCS layout configuration file.
If you noticed the GCS command line in the "control_panel.xml" file, a part of it reads "-layout horizontal.xml"
so our configuration file is the "horizontal.xml" which is located always in "/Your Paparazzi directory/conf/gcs/"
(mine is in "/paparazzi/conf/gcs/").
Open the file and add or uncomment the below line (in "horizontal.xml" the plugin widget is there but commented out):

'''<widget NAME="plugin" SIZE="300"/>'''

Now the file should look like this:

'''
<rows>
<widget size="500" name="map2d"/>
<columns>
<rows size="375">
<widget size="200" name="strips"/>
</rows>
<widget size="400" name="aircraft"/>
<widget name="alarms"/>
<widget NAME="plugin" SIZE="300"/>
</columns>
</rows>
'''

All the above work fine in Ubuntu 10.04 LTS but probably the same method should work fine on different versions too.

== Layout ==
The layout of the different components (map, strips, ...) of the gcs is configurable through a ''style'' XML file located in <tt>conf/gcs/</tt>. The specification is done via a combination of rows and columns. The default layout is given in the <tt>horizontal.xml</tt> file:
<tt><!DOCTYPE layout SYSTEM "layout.dtd">
<layout width="1024" height="768">
<rows>
<widget size="500" name="map2d"/>
<columns>
<rows size="350">
<widget size="120" name="strips"/>
<widget name="alarms"/>
</rows>
<widget size="400" name="aircraft"/>
<widget size="00" name="plugin"/>
</columns>
</rows>
</layout></tt>

Default size ('''1024x768''') of the whole window is specified in the root of the tree. The window is then divided in two rows:
* the <tt>map2d</tt> with a requested height of '''500'''
* a set of columns containing
** a set of rows of width '''350''' divided into
**: the '''strips''' frame of height '''120'''
**: the '''alarms''' frame
** the notebook frame ('''aircraft''') of width '''400'''
** the video plugin frame

This second example (<tt>left_col.xml</tt>) sets the map and the notebook on the right and the other frames in a left column:
<tt><!DOCTYPE layout SYSTEM "layout.dtd">
<layout width="1024" height="768">
<columns>
<rows size="360">
<widget size="120" name="strips"/>
<widget size="300" name="plugin"/>
<widget name="alarms"/>
</rows>
<rows>
<widget name="map2d"/>
<widget name="aircraft"/>
</rows>
</columns>
</layout></tt>

This layout file is chosen with the <tt>-layout</tt> option:
<tt>path_to_ground_segment/cockpit/gcs -layout left_col.xml</tt>

[[Category:GCS]] [[Category:User_Documentation]]

Lia

2013-07-30T06:34:21Z

Alonsoac:

'''Lia''' is a lower cost version of [[Lisa/M]] first developed for inclusion with the [http://wiki.thequadshot.com/wiki/The_Mocha Quadshot Mocha].

== Differences from Lisa/M ==

* 0.1" pitch connectors instead of molex picoblade
* No CAN transceiver (footprint still present just not populated) on [http://www.transition-robotics.com Transition Robotics]serial numbers LI1-001 through LI1-200 (populated on serial numbers ≥LI1-201)
* No I2C2 level shifter (footprint still present just not populated)
* No 5V voltage regulator (footprint still present just not populated)
* No JTAG connector (footprint still present just not populated)
* Added servo power inline resistors (by default 0 ohm but can be changed to higher value for balancing the linear voltage regulators of the motor controllers)

== Pictures ==

<gallery>
Image:Lia_1.1_top.jpg|Lia V1.1 top side
Image:Lia_1.1_bottom.jpg|Lia V1.1 bottom side
Image:Lia_1.1_aspirin_bottom.jpg|Lia V1.1 bottom side with Aspirin 2.1 nomag nobaro placed.
</gallery>

== Jumper Configuration ==
There are a number of jumpers on Lia used to configure voltage levels and power input. Their locations and functions are identical to those on the Lisa/M v2.0.<br/>
See the [[Lisa/M_v2.0#Jumper_Configuration|Jumper Configuration section on the Lisa/M v2.0 page]].

Note that the default states of JP8 and JP9 are reversed with respect to the defaults of Lisa/M v2.0; that is:

{|border="1" cellspacing="0" style="text-align:center" cellpadding="2%" width="70%"
|+'''Lia UART1 and UART5 VCC Configuration'''
!width="7%"|''Jumper''!!width="20%"|''Bus Connection''!!width="7%"|''Default''!!''Description''
|-
|JP8||UART1&5_VCC to V_IN||style="background:black; color:white"|CLOSED||Connects UART1 and UART5 connector VCC to autopilot input voltage V_IN rail
|-
|JP9||UART1&5_VCC to +3V3||OPEN||Connects UART1 and UART5 connector VCC to autopilot +3V3 rail
|}
'''WARNING: DO NOT CLOSE BOTH JP8 AND JP9 SIMULTANEOUSLY!!!'''

[[Category:Lisa]]

Modems

2013-07-19T22:20:17Z

Alonsoac: /* Adafruit */

The Paparazzi autopilots generally feature a TTL serial port to interface with any common radio modem. The bidirectional link provides real-time telemetry and in-flight tuning and navigation commands. The system is also capable overlaying the appropriate protocols to communicate thru non-transparent devices such as the Coronis Wavecard or Maxstream API-enabled products, allowing for hardware addressing for multiple aircraft or future enhancements such as data-relaying, inter-aircraft communication, RSSI signal monitoring and automatic in-flight modem power adjustment. Below is a list of some of the common modems used with Paparazzi, for details on configuring your modem see the [[Airframe_Configuration#Telemetry_.28Modem.29|Airframe Configuration]] and [[XBee_configuration|XBee Configuration]] pages.

== Digi XBee modules ==

Digi (formerly Maxstream) offers an increasing variety of Zigbee protocol modems well suited for Paparazzi in 2.4 GHz, 900MHz and 868Mhz frequencies. The "Pro" series are long range, up to 40km! Standard series are slightly smaller/lighter/lower power consumption and very short range. All versions are all pin compatible and weigh around 2 grams with wire antennas. All Digi modems can be operated in transparent mode (as a serial line replacement) or in "API mode" with hardware addressing, managed networking, and RSSI (signal strength) data with the Paparazzi "Xbee" option. Three antenna options are offered: the SMA version is ideal for ground modems, wire antennas for aircraft, and chip antennas for those with very limited space.

* XBee (PRO) ZB (the current series)
* XBee (PRO) ZNet 2.5 (formerly Series 2) (only legacy -> use XBee-PRO ZB)
The XBee & XBee-PRO ZB share hardware (ember stack) with XBee & XBee-PRO ZNet 2.5. As a result, modules can be "converted" from one platform to another by loading different firmware onto a given module.

These two also share the same hardware and can be converted from one to another by flashing a different firmware:
* XBee-PRO 802.15.4 (formerly Series 1)
* XBee-PRO DigiMesh 2.4

'''Note: Modules based on Freescale chipset (formerly Series 1) are not compatible with Ember chipset based modules (Series 2).'''

See the [[XBee_configuration|XBee Configuration]] page. This [http://pixhawk.ethz.ch/tutorials/how_to_configure_xbee tutorial] is also good to configure and get started with XBee Pro.

=== Module Comparison ===
{|border="1"
|-valign="top"
||'''Module'''||'''Point-to-Multipoint'''||'''ZigBee/Mesh'''||'''Chipset'''|||'''Software stack'''||'''Frequency'''||'''TX Power normal/PRO'''||'''Notes'''
|-
|'''XBee ZB'''
|
|yes
|Ember
|EmberZNet PRO 3.1 (ZigBee 2007)
|2.4 GHz
|2mW/50mW
|coordinator needed
|-
|'''XBee ZNet 2.5'''
|
|yes
|Ember
|EmberZNet 2.5 ZigBee
|2.4 GHz
|2mW/50mW
|(only legacy -> use XBee-PRO ZB) coordinator needed
|-
|'''XBee DigiMesh 2.4'''
|
|yes
|Freescale
|
|2.4 GHz
|
|all nodes equal (no special coordinators/routers/end-devices)
|-
|'''XBee 802.15.4'''
|yes
|
|Freescale
|
|2.4 GHz
|
|
|-
|'''XBee-PRO 868'''
|yes
|
|?
|
|868 MHz
|500mW
|Only High Power Frequency allowed in the UK. 2.4GHz limited to 10mW
|}

==== Comparison Conclusion ====

(Copied from DIGI manual)

''If the application strictly needs to communicate in a point-to-point or a point-to-multipoint
fashion, 802.15.4 will be able handle all the communications between your devices and will
be simpler to implement than trying to use a module with ZigBee firmware to accomplish the
same goal. ZigBee is necessary if you need to use repeating or the mesh networking
functionality.''

-Interpretation for paparazzi: if inter-aircraft communication is required one should go for the zigbee ZB series 2 modules.

==== Pinout ====

[[Image:Maxstream_Xbee_pinout.jpg|left|thumb|Maxstream XBee pinout]]
<br style="clear:both">

{|border="1"
|-valign="top"
||''Xbee 20-pin Header''||''Name''||''Notes''||''Suggested Color''||
|-
|1
| +3.3v
| Power
|Red
|-
|2
|DOUT
|Tx output - connect to Autopilot Rx
|Green
|-
|3
|DIN
|Rx input - connect to Autopilot Tx
|Blue
|-
|10
|GND
| Ground
|Black
|}

The image view is from above, top, thus NOT at the side where the connector pins come out

Note : DTR and RTS need to be wired for upgrading firmware

=== GCS Adaptation ===

There are several vendors of hardware to connect the ground XBee radio modem to the GCS computer.

====Adafruit====

[[Image:xbeeadapter_LRG.jpg|thumb|left|Adafruit XBee adapter board]][[Image:xbeeadapterftdi_LRG.jpg|thumb|Adafruit XBee adapter with FTDI cable]]
[http://www.adafruit.com/index.php?main_page=product_info&cPath=29&products_id=126 Adafruit] offers a great adapter board kit for the Xbee modules that includes a 5-3.3V voltage regulator, power and activity LEDs, and pins to connect directly to your FTDI cable for $10! Some assembly required.

<br style="clear:both">

====Droids====

[[Image:XBee_Simple_Board.jpg|thumb|left|XBee Simple Board]]

[[Image:XBee_USB_Board.jpg|thumb|left|XBee USB Board]]

[http://www.droids.it/cmsvb4/content.php?143-990.001-XBee-Simple-Board XBee Simple Board]

Simpler, lighter, smaller footprint, bit more expensive, comes assembled and tested. --GR

[http://www.droids.it/cmsvb4/content.php?152-990.002-XBee-USB-Board XBee USB Board]

For direct connection to USB (no FTDI cable required)

<br style="clear:both">

====PPZUAV====

[[Image:FTDI_Utility_Board.jpg|thumb|left|FTDI Utility Board 1.0‎]]

[https://mini.ppzuav.com/osc/product_info.php?cPath=13&products_id=111 ppzuav.com]

FTDI Utility Board 1.0 (no FTDI cable required)

<br style="clear:both">

====Sparkfun====

[[Image:XBee_Explorer_USB.jpg|thumb|left|XBee Explorer USB]]

[http://www.sparkfun.com/products/8687 sparkfun.com]

XBee Explorer USB (no FTDI cable required)

<br style="clear:both">

=== Digi XBee Pro DigiMesh / 802.15.4 ("Series 1") ===
*Note: Products based on XBee ZNet 2.5 (formerly Series 2) modules do not communicate with products based on XBee DigiMesh / 802.15.4 (formerly Series 1) modules.

These relatively cheap and light modules implement the [http://www.zigbee.org/en/index.asp ZigBee/IEEE 802.15.4] norm. They allow up to 1.6km (1 mile) range (Paparazzi tested to 2.5km (1.5 miles)). The main drawback of using such 2.4Ghz modules for datalink is that it will interfere with the 2.4Ghz analog video transmitters and a inevitable decrease in range when in proximity to any wifi devices. For the plane, get the whip antenna version if you are not planning to build a custom antenna.

{|
|-valign="top"
|[[Image:Xbee_Pro_USB_RF_Modem.jpg|thumb|left|XBee Pro USB Stand-alone Modem (XBP24-PKC-001-UA)]]
|
* Frequency Band 2.4Ghz
* Output Power 100mW (Xbee Pro)
* Sensitivity -100 dBm
* RF Data Rate Up to 250 Kbps
* Interface data rate Up to 115.2 Kbps
* Power Draw (typical) 214 mA TX / 55 mA RX
* Supply Voltage 3.3v
* Range (typical, depends on antenna & environment) Up to 1500m line-of-sight
* Dimensions 24 x 33mm
* Weight 4 grams
* Interface 20-pin mini connector
* Chip antenna, ¼ monopole integrated whip antenna or a U.FL antenna connector (3 versions)
* Price: Approximately $32
|
[[Image:XBee_pro.jpg|thumb|left|XBee Pro OEM Modem]]
|}
Mouser: [http://au.mouser.com/Search/ProductDetail.aspx?qs=sGAEpiMZZMtJacPDJcUJYzVn8vIv7g2fIpf5DCzJqko%3d 888-XBP24-PKC-001-UA]<br>
NOTE: If you wish to use this unit with another XBee type other than the 802.15.4 (i.e. XBee-PRO ZB) then purchase a modem with the U.fl connector.

==== Documentation ====

* [http://www.maxstream.net/products/xbee/xbee-pro-oem-rf-module-zigbee.php product page]
* [http://www.maxstream.net/products/xbee/datasheet_XBee_OEM_RF-Modules.pdf datasheet]
* [http://www.maxstream.net/products/xbee/product-manual_XBee_OEM_RF-Modules.pdf user manual]
* To program your Xbee you need X-CTU you can download it [http://www.digi.com/support/productdetl.jsp?pid=3352&osvid=57&tp=5&s=316 here]. (only windows)
* explanation on X-CTU [http://www.ladyada.net/make/xbee/configure.html here].
* [http://ftp1.digi.com/support/firmware/update/xbee/ Drivers for XB24 and XBP24 modules]

=== Digi XBee Pro ZB / ZNet 2.5 ("Series 2") ===

The low-power XBee ZB and extended-range XBee-PRO ZB use the ZigBee PRO Feature Set for advanced mesh networking.

{|
|-valign="top"
|[[Image:XBee_Pro_2SB.jpg|thumb|left|Digi XBee Pro ZB]]
|
* Low-cost, low-power mesh networking
* Interoperability with ZigBee PRO Feature Set devices from other vendors*
* Support for larger, more dense mesh networks
* 128-bit AES encryption
* Frequency agility
* Over-the-air firmware updates (change firmware remotely)
* ISM 2.4 GHz operating frequency
* XBee: 2 mW (+3 dBm) power output (up to 400 ft RF LOS range)
* XBee-PRO: 50 mW (+17 dBm) power output (up to 1 mile RF LOS range)
* RPSMA connector, U.FL connector, Chip antenna, or Wired Whip antenna
* price : ~34 USD
|
|}
These are available from Mouser:<br>
[http://au.mouser.com/Search/Refine.aspx?Keyword=888-XBP24-Z7WIT-004 888-XBP24-Z7WIT-004] XBee-PRO ZB with whip antenna<br>
[http://au.mouser.com/Search/Refine.aspx?Keyword=XBP24-Z7SIT-004 888-XBP24-Z7SIT-004] XBee-PRO ZB with RPSMA

See [[XBee_configuration|XBee Configuration]] for setup.

==== Documentation ====
* [http://www.digi.com/products/wireless/zigbee-mesh/xbee-zb-module.jsp http://www.digi.com/products/wireless/zigbee-mesh/xbee-zb-module.jsp]

=== Digi XBee Pro 868 ===

'''WARNING - THESE MODEMS HAVE A 10% DUTY CYCLE, AND CURRENTLY HAVE SEVERE ISSUES WITH PAPARAZZI'''

868MHz is a limited band. Please read the [[868MHz Issues]]

XBee-PRO 868 modules are long range embedded RF modules for European applications. Purpose-built for exceptional RF performance, XBee-PRO 868 modules are ideal for applications with challenging RF environments, such as urban deployments, or where devices are several kilometers apart.

{|
|-valign="top"
|[[Image:xbeeproxsc-rpsma.jpg|thumb|left|Maxstream XBee Pro 868]]
|
* 868 MHz short range device (SRD) G3 band for Europe
* Software selectable Transmit Power
* 40 km RF LOS w/ dipole antennas
* 80 km RF LOS w/ high gain antennas (TX Power reduced)
* Simple to use peer-to-peer/point-to-mulitpoint topology
* 128-bit AES encryption
* 500 mW EIRP
* 24 kbps RF data rate
* price : ~70 USD
|
|}

See [[XBee_configuration#XBee_Pro_868_MHZ|XBee Configuration]] for setup.

==== Documentation ====
* [http://www.digi.com/products/wireless/point-multipoint/xbee-pro-868.jsp http://www.digi.com/products/wireless/point-multipoint/xbee-pro-868.jsp]

=== Digi XBee 868LP ===

XBee 868LP modules are a low-power 868 MHz RF module for use in Europe. The range is shorter than it's brother the XBee PRO-868, but it can use the 868 G4 band with hopping which does not have restrictions on it's duty cycle. This is a big advantage if one want to have a good stream of telemetry data

{|
|-valign="top"
|[[Image:868lp.jpg|thumb|left|XBee 868LP]]
|
* 868 MHz short range device (SRD) G4 band for Europe
* 4 km RF LOS w/ u.fl antennas
* 5 mW EIRP
* 80 kbps RF data rate
* price : ~23 USD
|
|}

==== Documentation ====
* [http://www.digi.com/products/wireless-wired-embedded-solutions/zigbee-rf-modules/zigbee-mesh-module/xbee-868lp#overview http://www.digi.com/products/wireless-wired-embedded-solutions/zigbee-rf-modules/zigbee-mesh-module/xbee-868lp#overview]

==== Trial ====

With a quickly crafted and not optimal positioned antenna on the airframe we managed to get the advertised 4000 meter range. Data throughput was not high and the Iridium Telemetry XML configuration document was therefore used. All in all, cheap, easy to setup, pin compatible with regular modules and quite a range and usable in Europe without hassle.

=== Digi XBee Pro 900 (XBEE09P) ===

XBee Pro 900 modules are long range embedded RF modules for US applications. Purpose-built for exceptional RF performance, XBee-Pro 900 modules are ideal for applications with challenging RF environments, such as urban deployments, or where devices are several kilometers apart.

==== Documentation ====
* [ftp://ftp1.digi.com/support/documentation/90000903_a.pdf]

I've been using a pair of these for about 6 months now and they works great. To set it up I just used a serial terminal app like CoolTerm or screen and made sure I could send messages between the two of them. - cwozny

=== Digi XBee Pro XSC 900MHz ===

Maxstream has recently announced a promising new line of modems combining the small size and low cost of their popular Xbee line with the long range and 2.4 GHz video compatibility of their high end 900 MHz models. Sounds like the perfect modem for anyone who can use 900 MHz. Give them a try and post your results here!
{|
|-valign="top"
|[[Image:xbeeproxsc-rpsma.jpg|thumb|left|Maxstream XBee Pro XSC]]
|
* Frequency Band 900 MHz
* Output Power 100 mW (+20 dBm)
* Sensitivity -100 dBm
* Data Rate: 9600 bps
* Range (typical, depends on antenna & environment) Up to 24km (15 miles) line-of-sight
* Interface 20-pin mini connector (Xbee compatible pinout)
* RPSMA, integrated whip antenna or U.FL antenna connector (3 versions)
* price : $39 USD (on DigiKey)
|
|}

==== Documentation ====
* [http://www.digi.com/products/wireless/point-multipoint/xbee-pro-xsc.jsp http://www.digi.com/products/wireless/point-multipoint/xbee-pro-xsc.jsp]
==== Trials ====
Tested one today and it worked great. Going to try a multiUAV test with it soon
--Danstah
<br>
<br>
MultiUAV tests concluded this is probably not the best module to use. Even though it says you can change the baudrate inside x-ctu that is not the case, it is fixed at 9600 bps. This is a great modem however for single UAV's and I do recommend.
--Danstah
<br>
<br>
Why would the European (868 MHz) be good to 24kbps and this only to 9600? When I was altering my XBees (2.4Ghz Pro's) I had this problem altering baud rates until I read you have to send a "commit and reboot" type command after setting the baud rate. Could this be the case? --GR

=== Digi 9XTend ===

These larger units have been tested on the 900Mhz band, but are also available in 2.4Ghz. They are a bit on the heavy side, about 20 grams, but give good performance at range. They have adjustable transmit power settings from 100mW to 1W. Testing has shown range up to 5.6km (3.5 Miles) with XTend set to 100mW with small 3.1dB dipole antenna.

{|
|-valign="top"
|
[[Image:XTend_USB_RF_Modem.jpg|frame|left|9XTend USB Modem]]
|
* Frequency Band 900Mhz and 2.4Ghz (2 versions)
* Output Power 1mW to 1W software selectable
* Sensitivity -110 dBm (@ 9600 bps)
* RF Data Rate 9.6 or 115.2 Kbps
* Interface data rate up to 230.4 Kbps
* Power Draw (typical) 730 mA TX / 80 mA RX
* Supply Voltage 2.8 to 5.5v
* Range (typical, depends on antenna & environment) Up to 64km line-of-sight
* Dimensions 36 x 60 x 5mm
* Weight 18 grams
* Interface 20-pin mini connector
* RF connector RPSMA (Reverse-polarity SMA) or MMCX (2 versions)
* price : ~179 USD
|
[[Image:Xtend_module.jpg|frame|left|9XTend OEM Modem]]
|}

==== Pinout ====

[[Image:Maxstream_9XTend_Pinout.gif|thumb|left|Maxstream 9XTend Pinout]]

{| border="1"
|-valign="top"
||'''''9XTend 20-pin Header'''''||'''''Name'''''||'''''Tiny Serial-1 Header'''''||'''''Notes'''''
|-
||1||GND||1 (GND)||Ground
|-
||2||VCC||2 (5V)||5V power (150mA - 730mA Supplied from servo bus or other 5V source)
|-
||5||RX||8 (TX)||3-5V TTL data input - connect to Tiny TX
|-
||6||TX||7 (RX)||5V TTL data output - connect to Tiny RX
|-
||7||Shutdown||2||This pin must be connected to the 5V bus for normal operation
|}
Notes:<br>
* 9XTend can run on voltages as low as 2.8V but users are strongly advised against connecting any modem (especially high power models) to the sensitive 3.3V bus supplying the autopilot processor and sensors.
<br style="clear:both">

==== Documentation ====

* [http://www.maxstream.net/products/xtend/oem-rf-module.php product page]
* [http://www.maxstream.net/products/xtend/datasheet_XTend_OEM_RF-Module.pdf datasheet]
* [http://www.maxstream.net/products/xtend/product-manual_XTend_OEM_RF-Module.pdf user manual]

==== Configuration ====

These modems need to be carefully configured based on your usage scenario to obtain the best possible range and link quality. In addition, it is always good to make sure the firmware is up to date.

Some typical configurations that may work well, but can still depend your particular situation, are given below. For further details, be sure to consult the XTend users manual. Your application may need a different or modified configuration. The radiomodems do not need identical settings and can in fact be optimized with different settings. A good example is delays and retries: if each radio has the same number of retries and no delay, when a collision occurs each will continuously try to re-transmit, locking up the transmission for some time with no resolution or successful packet delivery. Instead, it is best to set the module whose data should have a lower latency to have no delay and a lower number of retries, while the other module has a delay set (RN > 0) and a greater number of retries. See acknowledged mode example below.

* Acknowledged Polling Mode ('''Recommended'''):
** This causes one radio to be the base and the other(s) to be the remote(s). It eliminates collisions because remotes do not send data unless requested by the base. It can work in acknowledged mode (RR>0), basic reliable mode (MT>0) or in basic mode (no acknowledgement or multiple packets). It is recommended that the lower latency and/or higher data rate side be configured as the base (i.e. if you are sending lots of telemetry then the air module configured as the base is probably a good idea, but if you are using datalink joystick control, the ground side might be better as the base. It may require some experimentation).
* Acknowledged Point-to-(Multi)Point Mode:
** Each radio sends a packet and requests and acknowledgement that the packet was sent from the receiving side. The retries and delays must be set appropriately to ensure packet collisions are dealt with appropriately. It can also work without acknowledgements in basic reliable mode (MT>0) without any acknowledgements (RR=0, MT=0). Some experimentation may be required.

{| border="1"
|-valign="top"
||'''''Setting Name'''''||colspan="2"|'''''Acknowledged Mode'''''||colspan="2"|'''''Polling Mode (Acknowledged)'''''||'''''Notes'''''
|-
|| ||'''''Airside Module'''''||'''''Groundside Module'''''||'''''Base Module'''''||'''''Remote Module'''''||
|-
||BD||6||6||6||6||Adjust to match your configured autopilot and ground station baud rates (default for these is 57600bps)
|-
||DT||default||default||0x02||0x01||Can be adjusted if consistency maintained across addressing functionalities (see manual)
|-
||MD||default||default||3 (0x03)||4 (0x04)||
|-
||MT||0||0||0||0||Use this to enable Basic Reliable transmission, link bandwidth requirement increases (see manual)
|-
||MY||default||default||0x01||0x02||Can be adjusted if consistency maintained across addressing functionalities (see manual)
|-
||PB||default||default||0x02||default||Can be adjusted if consistency maintained across addressing functionalities (see manual)
|-
||PD||default||default||default||default||Can be adjusted to increase polling request rate and DI buffer flush timeout (see manual)
|-
||PE||default||default||0x02||default||Can be adjusted if consistency maintained across addressing functionalities (see manual)
|-
||PL||default||default||default||default||''Transmit power level should be reduced for lab testing!!''
|-
||RN||0 (0x00)||8 (0x08)||default||default||
|-
||RR||6 (0x06)||12 (0x0C)||6 (0x06)||12 (0x0C)||
|}

'''Note:''' All settings are assumed to be default except those listed. Those listed are in decimal unless hex 0x prefix included. Depending on your firmware version, slight modifications may be necessary.

Here is some additional information and alternative instructions to configure the polling mode from the Digi site: [http://www.digi.com/support/kbase/kbaseresultdetl?id=2178 Polling Mode for the 9XTend Radio Modem]

== SiLabs Si1000 SoC based modems ==

The Si1000 radio System on Chip (SOC) produced by SiLabs is found in a number of radio modules, for example the cheap and widely used HopeRf module. There is [https://github.com/tridge/SiK open source firmware] for these radios which makes them suitable for use in MAVs.

Note that (unlike some XBee modules) the SiK firmware does not support mesh topologies, it is strictly a point-to-point link. If you are working with swarming vehicles they may not be the best choice.

Online documentation for the Sik firmware shows how to configure it for various jurisdictions. The firmware supports 433 MHz, 470 MHz, 868 MHz and 900 MHz radios, if you are aware of any hardware supporting the European spectrum licences (868 MHz) please add them to this wiki.

Note: When using a SiK firmware radio with paparazzi, you should set "ATS6=0" (MavLink packing off) and configure paparazzi for transparent serial mode.

[http://www.rfdesign.com.au/index.php/rfd900 This module] is well proven and supports antenna diversity. A combination of 6dbi Yagi plus a dipole on the ground station, with a pair of orthogonality oriented dioples in the airframe, has been extensively tested and proven reliable at >8km range (theoretical range of ~40km).

Alternatively, for shorter range a pair of cheap generic HopeRF-based modems [http://rctimer.com/index.php?gOo=goods_details.dwt&goodsid=815 such as these]

The RFD900 can be paired with cheap generic (single front-end) modules, if for example you use a small short range airframe with a ground station that's also used for long range operations.

== Aerocomm ==
Aerocomm's API mode is already implemented but some system integration is required. Full API more with addressed packets works well and was tested with AC4790-1x1 5mW low power modules. Maximim range achieved with a whip quater-wave antenna was 1Km.

How to use this modem on ground station side? [http://paparazzi.enac.fr/wiki/index.php/User:SilaS#SDK-AC4868-250_ground_modem_part]

See folder paparazzi3 / trunk / sw / aerocomm. It has all the required files to use this modem on the airborne and ground station side. The link.ml file is a direct replacement of the "main" link.ml file of the ground sttaion and will be merged into it in the future.. or you can do it as well.

{|
|
=== AC4868-250 ===
* Frequency Band 868MHz (For Europe). 868MHz is a limited band. Please read the [[868MHz Issues]]
* Output Power (w/ 2dBi antenna) 250 mW
* Sensitivity (@ full RF data rate) -103 dB
* RF Data Rate Up to 28.8 Kbps
* INterface Data Rate Up to 57.6 Kbps
* Power Draw (typical) 240 mA TX / 36 mA RX
* Supply Voltage 3.3v & 5V or 3.3v only
* Range (typical, depends on antenna & environment) Up to 15 kilometers line-of-sight
* Dimensions 49 x 42 x 5mm
* Weight < 21 grams
* Interface 20-pin mini connector
* Antenna MMCX jack Connector
* price : ~80$
|
[[Image:ConnexLink_USB_RF_Modem.jpg|thumb|Aerocomm USB Stand-alone Modem]]
|-
|

=== AC4790-200 ===
* Frequency 902-928MHz (North America, Australia, etc).
* Output Power 5-200mW
* Sensitivity (@ full RF data rate) -110dB
* RF Data Rate up to 76.8 Kbps
* INterface Data Rate Up to Up to 115.2 Kbps
* Power Draw (typical) 68 mA
* Supply Voltage 3.3v & 5.5V
* Range (typical, depends on antenna & environment) Up to 6.4 kilometers line-of-sight
* Dimensions 42 x 48 x 5mm
* Weight < 20 grams
* Interface 20-pin mini connector
* Antenna MMCX jack Connector or internal
* price : ~80$
|
[[Image:ac4868_transceiver.jpg|thumb|left|AC4868 OEM Modem]]
|
|-
|

=== AC4790-1000 ===
* Frequency 902-928MHz (North America, Australia, etc).
* Output Power 5-1000mW
* Sensitivity (@ full RF data rate) -99dB
* RF Data Rate up to 76.8 Kbps
* INterface Data Rate Up to Up to 115.2 Kbps
* Power Draw (typical) 650 mA
* Supply Voltage 3.3V only
* Range (typical, depends on antenna & environment) Up to 32 kilometers with high-gain antenna
* Dimensions 42 x 48 x 5mm
* Weight < 20 grams
* Interface 20-pin mini connector
* Antenna MMCX jack Connector
* price : ~80$
|}

=== Pinout ===

[[Image:Aerocomm_AC4868_pinout.jpg|thumb|left|Aerocomm AC4868 modem pinout]]
[[Image:Aerocomm_AC4490-200_wired.jpg|thumb|left|Aerocomm AC4490 wiring example]]
<br style="clear:both">

{| border="1"
|+ Wiring the Aerocomm AC4868 to the Tiny
|-valign="top"
||'''''AC4868 20-pin Header'''''||'''''Name'''''||'''''Color'''''||'''''Tiny v1.1 Serial-1'''''||'''''Tiny v2.11 Serial'''''||'''''Notes'''''
|-
||2||Tx||green||7||7||''(Note 1)''
|-
||3||Rx||blue||8||8||''(Note 1)''
|-
||5||GND||black||1||1|| -
|-
||10+11||VCC||red||2||3||+3.3v ''(Note 2)''
|-
||17||C/D||white||3||?||Low = Command High = Data
|}
''Note 1 : names are specified with respect to the AEROCOMM module''

''Note 2 : AC4790-1000 needs pins 10 and 11 jumped to work properly''

=== Documentation ===
* [http://www.aerocomm.com/rf_transceiver_modules/ac4790_mesh-ready_transceiver.htm AC4790 product page]
* [http://www.aerocomm.com/docs/Datasheet_AC4790_HI.pdf AC4790 Datasheet]
* [http://www.aerocomm.com/docs/User_Manual_AC4790.pdf AC4790 Manual]
* [http://www.aerocomm.com/rf_transceiver_modules/ac4868_868mhz_rf_transceiver.htm AC4848 product page]
* [http://www.aerocomm.com/docs/Datasheet_AC4868_HI.pdf AC4868 Datasheet]
* [http://www.aerocomm.com/docs/User_Manual_AC4868.pdf AC4868 user manual]

== Laird (ex Aerocomm) ==

=== Laird LT2510 ===

[[Image:Lt2510_prm123.jpg|thumb|LT2510 Modem]]

* Frequency Band 2.4GHz
* Output Power 50mW (European version)
* Sensitivity -98/-94 dBm
* RF Data Rate 280/500 kbps
* Interface data rate Up to 460800 kbps
* Power Draw (typical) 85mA TX / 10mA RX (European version)
* Supply Voltage 3.3v
* Range (typical, depends on antenna & environment) Up to 2400m line-of-sight (European version)
* Dimensions 24 x 33mm
* Weight 4 grams
* Interface 20-pin mini connector (solder pad or XBee compatible)
* Chip antenna, or a U.FL antenna connector
* Price: Approximately $31

The LT2510 uses frequency hopping which needs a client/server model. That means that one modem (most appropriately the ground station modem) needs to be set to server mode. It will transmit a beacon message and have all client modems synchronize to that in a time and frequency hopping scheme manner. For that all modems need to have the same channel (in fact the hopping scheme) and system-id. Clients can be set to auto-channel and auto-system-id to follow any/the first visible server.

All acknowledged messages transmitted need to be adressed to the non-changeable MAC address of the destination modem. There are is a way to automatically set destination adresses but this procedure does have drawbacks (see below).

Make sure you short circuit "D1" if you use the Sparkfun WRL-09132 "XBee Explorer Regulated" adapter. The Laird does not have a pull-up resistor on DIN that Sparkfun assumes.

==== Basic setup ====

You can download a Windows configuration utility from [http://www.lairdtech.com/Products/Wireless-M2M-and-Telematics-Solutions/Proprietary-Radio-Modules/ here], click "Product Information".

Set client to client mode (default).
Set server to server mode.

Set speed on both modems to 57600 baud, the Paparazzi standard.

Choose RF profile with low speed (280kbps) for long range (default).

===== Transparent mode =====

The transparent mode is different from the XBee modems transparent mode. It will only allow two modems to communicate with each other.

====== Transparent mode with hard coded address ======

In this mode the destination MAC address is permanently set in the EEPROMs of the modems. Only these two modems can communicate with each other. The advantage of this mode is that other modems can not confuse the communication. You have to read out both modems MAC adresses as they are not printed on the case.

Set server MAC address in client
Set client MAC address in server

====== Transparent mode with auto-address ======

The server will start emitting beacon messages and the client locks to these, starting to send messages to the servers MAC address. The server will then respond to that clients data messages. In this mode only one server can talk to one client. Any appearance of another server or client modem will confuse/disrupt the communication.

Set server to auto-destination.
Set client to auto-destination and auto-destination-beacons-only.

===== API mode =====

We need at least a simple form of address resolution as the modems own (MAC) address can not be changed. This makes the ground station link and on-board software a little more complicated than the XBee API mode.

tbd

== Radiotronix ==
These Radiotronix modems are used in transparent mode. Use the WI232EUR Evaluation Software for configuring the modems for the set speed. Connect /CMD and CTS for programming. The DTS version for the US market might cause severe interference with GPS reception, it is not recommended. For a nice ground station modem just add a FTDI232 USB->serial cable, a 3.3V regulator with 100nF capacitors from supplies to ground, solder a SMA cable/connector and put it in a nice case. Make sure you only connect RTS to /CMD if you want to reprogram the modem with the Evaluation software (see the open jumper connection in the picture, green wire) and leave it floating otherwise as connected RTS/CTS sporadically leads to a reprogramming of the modem. The ANT-GXD105-FME/F from [http://www.roundsolutions.com Roundsolutions] was used as a ground station antenna at many competitions. Note that a 1/2 wave dipole antenna works best on-board as it doesn't require a ground-plane and has a reasonably omnidirectional radiation pattern.
{|
|
=== WI232EUR ===
* Frequency Band: 868 MHz (for Europe)
* Output Power: 32 mW
* RF Data Rate: Up to 76.8 kbps
* Interface Data Rate: up to 115.2 kbps
* Power Draw (typical): 65 mA TX / 20 mA RX
* Supply Voltage: 3.3v
* Range (typical, depends on antenna & environment): 500 meters line-of-sight
* Dimensions: 24 x 21 x 4mm
* Weight: ~2 grams
* Interface: solder connector
* Antenna: solder connector
* Price: ~25$
|
[[Image:Wi232eur_wiring.jpg|thumb|WI232EUR Modem (picture shows connection to Tiny 1.1)]]
|-
|

=== Pinout ===

<br style="clear:both">

{| border="1"
|+ Wiring the WI232EUR to the Tiny v1.1
|-valign="top"
||'''''WI232 pins'''''||'''''Name'''''||'''''Tiny Serial-1'''''||'''''Notes'''''
|-
||6||TxD||7||''(Note 1)''
|-
||5||RxD||8||''(Note 1)''
|-
||15-18||GND||1|| -
|-
||19||VCC||2||+3.3v
|-
||4||/CMD||-||''(Note 2)''
|-
||7||CTS||-||''(Note 3)''
|}
''Note 1 : names are specified with respect to the Radiotronix module''

''Note 2 : connect to RTS to program device with Evaluation software''

''Note 3 : connect to CTS to program device with Evaluation software''

|
[[Image:Wi232eur_bopla.jpg|thumb|WI232EUR Modem in BOPLA case]]
|-
|
|}
=== Documentation ===
* [http://www.radiotronix.com/datasheets/new/eur_um.pdf WI232EUR data sheet]
* [http://www.radiotronix.com/datasheets/new/rk-eur_um.pdf WI232EUR user's manual]
* [http://www.radiotronix.com/downloads/software/EUR/setup.exe Evaluation software]

== Bluetooth ==
These modems do not give you a great range but Bluetooth can be found in a lot of recent laptops built-in. Maybe not useful for fixed wing aircrafts it might be used for in-the-shop testing or quadcopters. Make sure you get a recent Class 1 EDR 2.0 stick if you buy one for your computer.
{|
|
=== "Sparkfun" Roving Networks (WRL-08497) ===
* Frequency Band 2.4GHz
* Output Power 32 mW
* RF Data Rate up to ~300 kbps in SPP
* Interface Data Rate up to 921 kbps
* Power Draw (typical) 50 mA TX / 40 mA RX
* Supply Voltage 3.3v
* Range (typical, depends on antenna & environment) 100 meters line-of-sight
* Dimensions 26 x 13 x 2mm
* Weight ~1.5 grams
* Interface solder connector
* price : ~45$
|
[[Image:roving_nw_wiring.jpg|thumb|Roving Networks modem wiring]]
|-
|

To connect to it, get the MAC address of the bluetooth modem

me@mybox:~$ hcitool scan
Scanning ...
00:06:66:00:53:AD FireFly-53AD

either make a virtual connection to a Bluetooth serial port each time you connect

sudo rfcomm bind 0 00:06:66:00:53:AD

or configure it once in /etc/bluetooth/rfcomm.conf

rfcomm0 {
bind yes;
device 00:06:66:00:53:AD;
}

now you can use Bluetooth as '''/dev/rfcomm0''' with the Paparazzi 'link'. You might need to restart 'link' in case you get out of range and it disconnects (tbd). Set the Tiny serial speed to 115200 as the modules come preconfigured to that.
|}

== Coronis WaveCard ==

These relatively inexpensive and light modules implement a Coronis proprietary protocol. Low power consumption - high latency - I would not recommend these modules mostly because of the low quality of the distribution and support. The documentation is rather poor and not easily available.

'''Suport for these modems has been removed from the airborne code on Dec 10th, 2007.'''
{|
|-valign="top"
|
* Frequency Band 400MHz, 868Mhz and 915MHz (3 versions)
* Output Power 25mW and 500mW (2 versions)
* Sensitivity -110 dBm (@ 9600 bps)
* Data Rate 100 Kbps
* Power Draw (typical) 45mA (25mW), 450mA (500mW) TX / 15 mA RX
* Supply Voltage ...
* Range (typical, depends on antenna & environment) Up to 1km (25mW) , 5km (500mW) line-of-sight
* Dimensions 30 x 28 x 7mm (25mW), 37 x 30 x 7mm (500mW)
* 50 ohm RF port for antenna connection
|
[[Image:wavecard.jpg|Coronis Wavecard]]
|}

=== Documentation ===

* [http://www.coronis-systems.com/produit.php?lang=EN&id=WCA www.coronis-systems.com]
* [[Media:CS-COM-SPRD-WAVECARD-E03B.pdf|Wavecard datasheet]]

== Telemetry via Video Transmitter==

[[Image:video_tx_small.jpg|thumb|2.4GHz Video Transmitter]]
In order for the UAV to transmit video from an onboard camera, an analog video transmitter can be used. These vary in power, and thus range, and run normally on 2.4Ghz. Small UAVs can get about 600m of range from the 50mW version, and extended range can be achieved using units up to 1W. Weight for these units varies from a couple grams to about 30 for the 1W with shielding. Please check for your countries regulations on 2.4Ghz transmission, as each is different.

It is possible to use the audio channel to send simple telemetry data to the groundstation. Uploading telemetry not possible via analog audio transmitter only.
<br style="clear:both">

== Telemetry via Internet / Raspberry Pi==
!this is unter construction by NeoFromMatrix!

Idead:
A Raspberry PI with UMTS stick is used as Modem, gcs is connected to the internet.
THis resoults in a unlimited range with limited height.

ssh reverse serial tunnel is used --> reconnects if connection is lost, no problems with UMTS stick IP issue
Mostly UMTS USB stick don't have a own IP adress !

current status: working on Raspberry Pi / UMTS stick connection

Instructions:
* Setup the Raspberry with the standard image [http://www.raspberrypi.org/downloads|Take Raspbian "wheezy"|Raspbian download]
* Establish the connection between a UMTS stick and the Raspberry PI, it will take some time, this instructions are not complete ! [http://www.instructables.com/id/Raspberry-Pi-as-a-3g-Huawei-E303-wireless-Edima/step2/Download-and-setup-ppp-UMTSKeeper-and-Sakis3g/|Instructables site]
not tested yet:
*set up ssh tunnel [http://www.tunnelsup.com/tup/2013/05/08/raspberry-pi-phoning-home-using-a-reverse-remote-ssh-tunnel|ssh reverse serial tunnel]
*set up static ip of your gcs [http://www.cyberciti.biz/tips/howto-ubuntu-linux-convert-dhcp-network-configuration-to-static-ip-configuration.html|static IP Ubuntu](or you use a Linux server with static ip, dynamic IP is a bit difficult)
* Maybe use a external UMTS antenna for better signal strengh (double bi quad)

You can also use a Android Smartphone with USB thetering as connection between Raspberry Pi and the Internet.

== Antennas ==

Here are some examples of lightweight and efficient 868MHz antennas developped by the RF laboratory at ENAC.
[[Image:868mhz_twinstar_antenna_1.jpg|thumb|left|868MHz copper foil antenna attached to the aircraft tail]]
[[Image:868mhz_twinstar_antenna_2.jpg|thumb|left|868MHz copper foil antenna bottom view]]
[[Image:868mhz_ground_antenna.jpg|thumb|left|868MHz ground antenna]]
<br style="clear:both">

This wiki page might give some ideas about antennas: http://en.wikipedia.org/wiki/Dipole_antenna

[[Category:Hardware]]

JSBSim

2013-07-19T05:27:23Z

Alonsoac:

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Simulation</categorytree>
__TOC__

[http://jsbsim.org Jsbsim]

== Installation ==

=== Debian Package ===
On Debian/Ubuntu you can install the paparazzi-jsbsim package.
sudo apt-get install paparazzi-jsbsim
If you don't have that in your sources, see [[Installation/Linux#Adding_the_APT_repository]]

=== From Source ===
Compile JSBSIM from source (with specified date to make sure it works and API hasn't changed)
cvs -z3 -d:pserver:anonymous@jsbsim.cvs.sourceforge.net:/cvsroot/jsbsim co -D "12 Jun 2012" -P JSBSim
cd JSBSim
./autogen.sh
./configure --enable-libraries --enable-shared --prefix=/opt/jsbsim
make
sudo make install

If you want to install to a different location, change the ''prefix'' to your liking.
And you need to add a <tt><makefile></tt> section to your airframe file and add the correct flags to point to the include files and libraries, depending on where it is installed.

With the default installation to <tt>/usr/local/</tt>, this would look like
<makefile location="after">
jsbsim.CFLAGS += -I/usr/local/include/JSBSim
jsbsim.LDFLAGS += -L/usr/local/lib
</makefile>

=== On OSX ===
* Install the JSBSim libraries onto your system. This should already be installed with <tt>paparazzi-tools</tt>, but if it isn't:
<code>$ sudo port install jsbsim</code>
It uses code from the cvs repo, so it should be the most up-to-date source.

== Troubleshooting ==
* If you get an error like "undefined reference to `pcre_compile'", edit file conf/Makefile.jsbsim, look for the line that begins with LDFLAGS and add -lpcre, e.g.:
LDFLAGS += $($(TARGET).LDFLAGS) -lpcre

[[Category:Simulation]] [[Category:Software]] [[Category:User_Documentation]]

NPS

2013-07-19T05:25:11Z

Alonsoac: /* Troubleshooting */

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Simulation</categorytree>
__TOC__

NPS is our advanced rotorcraft simulator with sensor models and uses [[JSBSim]] as FDM (FlightDynamicModel) to allow fairly complex airframes.
JSBSim can easily be replaced by the FDM of your choice.

Fixedwing support can also be easily added as soon as someone actually wants to use it ;-)

== Installation ==

See [[Installation|installation of Paparazzi]], [[JSBSim]] and optionally [[FlightGear]].

=== Configuration/Build ===
Add the ''nps'' target to your [[Rotorcraft Configuration|airframe]] with the fdm you want to use:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
<target name="nps" board="pc">
<subsystem name="fdm" type="jsbsim"/>
</target>
...
</firmware>

<section name="SIMULATOR" prefix="NPS_">
<define name="ACTUATOR_NAMES" value="{"front_motor", "back_motor", "right_motor", "left_motor"}" />
<define name="INITIAL_CONDITITONS" value=""reset00"" />
<define name="SENSORS_PARAMS" value=""nps_sensors_params_default.h"" />
</section>
</source>
}}
You can also take a look at the example airframe ''conf/airframes/examples/quadrotor_lisa_m_2_pwm_spektrum.xml'' or use it for your first tests.

The xml file with the JSBSim model of the aircraft is located in ''conf/simulator/jsbsim/aircraft/''
and needs to have the name of the aircraft postfixed with ''.xml''
(e.g. [https://github.com/paparazzi/paparazzi/blob/master/conf/simulator/jsbsim/aircraft/Quad_LisaM_2.xml conf/simulator/jsbsim/aircraft/Quad_LisaM_2.xml])

* ACTUATOR_NAMES: mapping of the motors defined in the [[Rotorcraft_Configuration#Motor_Mixing|MOTOR_MIXING section]] to the actuators in the JSBSim model (the order is important, also make sure that your motors in JSBSim spin in the same direction as your real ones)
* INITIAL_CONDITITONS: the xml file containing the initial conditions (location, attitude, wind) for JSBSim in ''conf/simulator/jsbsim/aircraft/'' (e.g. [https://github.com/paparazzi/paparazzi/blob/master/conf/simulator/jsbsim/aircraft/reset00.xml reset00])
* SENSORS_PARAMS: the parameter file for the sensor simulation (noise/delay) under ''conf/simulator/nps/'' (e.g. [https://github.com/paparazzi/paparazzi/blob/master/conf/simulator/nps/nps_sensors_params_default.h nps_sensors_params_default.h])

Then build the nps target...

== Running the Simulation ==
Since paparazzi version ''v4.9_devel-425'' the most convenient way to start the simulation is via the ''Simulation'' session from the [[Paparazzi Center]].
Just select e.g. the Quad_LisaM_2 example airframe and start the ''Simulation'' session with the simulator, GCS and server.

You can also start it via the generic simulation launcher:
<source lang="bash">sw/simulator/pprzsim-launch --aircraft Quad_LisaM_2 --type nps</source>

In earlier versions, start your tools (e.g. [[GCS]], [[server]] and messages) separately, then launch the nps simulator for your aircraft directly:
<source lang="bash">./var/Quad_LisaM_2/nps/simsitl</source>

=== Options ===
Start the simulator with the ''--help'' option to list them all.

* ''--ivy_bus'': Set ivy bus broadcast address to use (default 127.255.255.255, 224.255.255.255 on OSX)
* ''--rc_script'': Execute script with specified number to emulate RC input.
* ''--js_dev'': Use joystick for radio control (specify index, normally 0), also see [[NPS#Use_a_joystick]].
* ''--spektrum_dev'': Spektrum device to use for radio control (e.g. /dev/ttyUSB0)
* ''--fg_host'': Host for FlightGear visualization (e.g. 127.0.0.1)
* ''--fg_port'': Port on FlightGear host to connect to (Default: 5501)
* ''--fg_time_offset'': FlightGear time offset in seconds (e.g. 21600 for 6h), this is useful if it is currently night at the location you are flying and you want to add an offset to fly in daylight. (Since ''v4.9_devel_413-g9d55d6f)

=== Typical Simulation ===
In general you go through the same steps as with the real aircraft:
* It should start on the ground and you have to wait a few seconds until the AHRS is aligned.
* If you have a (simulated) RC, you can now arm the motors and fly around in manual.
* To fly autonomously, make sure your ''AUTO2'' mode is ''NAV'', you can change it in the GCS->settings->system->auto2.
** Switch to it if you are using an RC, otherwise you should already be in this mode.
** Arm your motors: either via the resurrect button or by going to the ''Start Motors'' block of the [[Flight Plans|Flight Plan]].
** Takeoff: via the takeoff button or the corresponding flight plan block.
* Do your stuff... :-)

=== Pausing or running the sim at a different speed ===
If you start the simulation from a terminal, hit ''CTRL-z'' to pause it. You can then enter a different time factor (default 1.0) to make the simulation run slower or faster than real-time. Hit enter to resume the simulation or ''CTRL-z'' again to suspend it like any normal Unix process (use the ''fg'' (foreground) command to un-suspend it again).

=== Use a Joystick ===
You can use a [[joystick]] (or connect your RC transmitter as a joystick) to control the quad in the simulator.
<source lang="bash">./var/Quad_LisaM_2/nps/simsitl -j</source>
or, with a specific device index (0 is default):
<source lang="bash">./var/Quad_LisaM_2/nps/simsitl --js_dev 0</source>

Joystick support uses the Simple DirectMedia Layer (SDL) library. Rather than specifying an input device name as one normally does on Linux, you just supply an index value (0, 1, 2,...) of the device you wish to use. Typically, the order of devices is the order in which you plugged them into your computer. The sim will display the name of the device being used to double check. If the <tt>-j</tt> option is used with no argument, the sim defaults to using device on index 0 (which is usually correct if you have only one joystick attached).

Also see [[Joystick#Calibration]].

=== Visualization in [[FlightGear]] ===
[[FlightGear#Installation|Install]] and [[FlightGear#Using_FlightGear_for_Visualization|start flightgear]], e.g. with a quadrotor model:
<source lang="bash">fgfs --fdm=null --native-gui=socket,in,30,,5501,udp --prop:/sim/model/path=Models/Aircraft/paparazzi/mikrokopter.xml</source>
restart your simulator with the ''--fg_host'' option:
<source lang="bash">./var/Quad_LisaM_2/nps/simsitl --fg_host 127.0.0.1</source>

=== Troubleshooting ===
* If you get an error like "JSBSim failed to open the configuration file: (null)/conf/simulator/jsbsim/aircraft/BOOZ2_A1.xml", you need to set your $PAPARAZZI_SRC and $PAPARAZZI_HOME environment variables. Add the following to your .bashrc, change paths according to where you put Paparazzi. Open a new terminal and launch the sim again.
export PAPARAZZI_SRC=~/paparazzi
export PAPARAZZI_HOME=~/paparazzi

* If you did not install the jsbsim package your JSBSim installation under /opt/jsbsim will be used and you will have to set your library path (either in your shell startup file or when running the sim on the command line), e.g.:
LD_LIBRARY_PATH=/opt/jsbsim/lib ./var/Quad_LisaM_2/nps/simsitl --fg_host 127.0.0.1

* If you get an error like "fatal error: gsl/gsl_rng.h: No such file or directory", you need to install the GNU Scientific Library and corresponding development packages (libgsl).

* If you get an error like "undefined reference to `pcre_compile'", edit file conf/Makefile.nps, look for the line that begins with LDFLAGS and add -lpcre, e.g.:
LDFLAGS += $($(TARGET).LDFLAGS) -lpcre

== Usage Examples ==

=== Plot the value of a message field ===
Start the [[RTPlotter|real-time plotter]] tool menu of [[Paparazzi Center]] or with
<source lang="bash">./sw/logalizer/plotter</source>
for example drag the label 'int32 phi' from the ROTORCRAFT_FP message to the drawing area of the plotter

* Use the datalink to change the telemetry mode
start 'settings' ( from the tool menu of paparazzi center) or with
./sw/ground_segment/tmtc/settings -ac Quad_LisaM_2
start 'server' to dispatch datalink messages ( from the tool menu of paparazzi center) or with
./sw/ground_segment/tmtc/server
change the field "telemetry" on the first page to "Att loop" and send by pressing the green check button. The label on the left or the drop box should change to "Att loop" confirming your message has been received. "message" should now show that the message "STAB_ATTITUDE_INT" is received

=== Tuning the attitude control loop ===
Here we are going to use the simulator to demonstrate a way of tuning the attitude control loop.

* Restart your previous session
* Set telemetry mode to "attitude_loop"
* Display two real time plotter windows

In the first one, plot the field "m_phi" from the "STAB_ATTITUDE_int" message. This is our estimation of roll angle.
On top of that, plot the field "phi" from the "STAB_ATTITUDE_REF_INT" message. This is our reference roll angle, that is, the roll value we are trying to achieve.

In the second plotter, plot the fields "delta_a_fb" and "delta_a_ff". Those are respectively the feedback and feedforward part of our roll command. The sum of those two terms is what is used as roll command.The feedforward part is the part used to follow our trajectory and the feedback part is the part used to reject perturbations.

* In "Settings", go to the "Att Loop" tab
We notice that the vehicle doesn't follow the step trajectory we are trying to make him do accurately.

Start by setting the value of the proportional gain ('pgain_phi') to 1000 instead of 400. The vehicle now follows the trajectory faster but overshoots. To prevent that, increase the value of the derivative gain ('dgain p') from 300 to 700.

If you look at the plotter where you're plotting the commands, you'll notice that during steps, the feedback command has to work hard. This means that our feedforward command is badly tuned, and namely not working hard enough. Increase the value of the feedforward gain ('ddgain p') from 300 to 540. You'll notice that now the feedback command has become marginal during the steps. This is the right value for the gain. Anything bigger will make the feedback command fight against the feedforward command during steps, anything smaller will make the feedback command have to complement the feedforward command.

[[Category:Simulation]] [[Category:Software]] [[Category:User_Documentation]]

NPS

2013-07-19T05:20:17Z

Alonsoac: troubleshoot missing libgsl

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Simulation</categorytree>
__TOC__

NPS is our advanced rotorcraft simulator with sensor models and uses [[JSBSim]] as FDM (FlightDynamicModel) to allow fairly complex airframes.
JSBSim can easily be replaced by the FDM of your choice.

Fixedwing support can also be easily added as soon as someone actually wants to use it ;-)

== Installation ==

See [[Installation|installation of Paparazzi]], [[JSBSim]] and optionally [[FlightGear]].

=== Configuration/Build ===
Add the ''nps'' target to your [[Rotorcraft Configuration|airframe]] with the fdm you want to use:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
<target name="nps" board="pc">
<subsystem name="fdm" type="jsbsim"/>
</target>
...
</firmware>

<section name="SIMULATOR" prefix="NPS_">
<define name="ACTUATOR_NAMES" value="{"front_motor", "back_motor", "right_motor", "left_motor"}" />
<define name="INITIAL_CONDITITONS" value=""reset00"" />
<define name="SENSORS_PARAMS" value=""nps_sensors_params_default.h"" />
</section>
</source>
}}
You can also take a look at the example airframe ''conf/airframes/examples/quadrotor_lisa_m_2_pwm_spektrum.xml'' or use it for your first tests.

The xml file with the JSBSim model of the aircraft is located in ''conf/simulator/jsbsim/aircraft/''
and needs to have the name of the aircraft postfixed with ''.xml''
(e.g. [https://github.com/paparazzi/paparazzi/blob/master/conf/simulator/jsbsim/aircraft/Quad_LisaM_2.xml conf/simulator/jsbsim/aircraft/Quad_LisaM_2.xml])

* ACTUATOR_NAMES: mapping of the motors defined in the [[Rotorcraft_Configuration#Motor_Mixing|MOTOR_MIXING section]] to the actuators in the JSBSim model (the order is important, also make sure that your motors in JSBSim spin in the same direction as your real ones)
* INITIAL_CONDITITONS: the xml file containing the initial conditions (location, attitude, wind) for JSBSim in ''conf/simulator/jsbsim/aircraft/'' (e.g. [https://github.com/paparazzi/paparazzi/blob/master/conf/simulator/jsbsim/aircraft/reset00.xml reset00])
* SENSORS_PARAMS: the parameter file for the sensor simulation (noise/delay) under ''conf/simulator/nps/'' (e.g. [https://github.com/paparazzi/paparazzi/blob/master/conf/simulator/nps/nps_sensors_params_default.h nps_sensors_params_default.h])

Then build the nps target...

== Running the Simulation ==
Since paparazzi version ''v4.9_devel-425'' the most convenient way to start the simulation is via the ''Simulation'' session from the [[Paparazzi Center]].
Just select e.g. the Quad_LisaM_2 example airframe and start the ''Simulation'' session with the simulator, GCS and server.

You can also start it via the generic simulation launcher:
<source lang="bash">sw/simulator/pprzsim-launch --aircraft Quad_LisaM_2 --type nps</source>

In earlier versions, start your tools (e.g. [[GCS]], [[server]] and messages) separately, then launch the nps simulator for your aircraft directly:
<source lang="bash">./var/Quad_LisaM_2/nps/simsitl</source>

=== Options ===
Start the simulator with the ''--help'' option to list them all.

* ''--ivy_bus'': Set ivy bus broadcast address to use (default 127.255.255.255, 224.255.255.255 on OSX)
* ''--rc_script'': Execute script with specified number to emulate RC input.
* ''--js_dev'': Use joystick for radio control (specify index, normally 0), also see [[NPS#Use_a_joystick]].
* ''--spektrum_dev'': Spektrum device to use for radio control (e.g. /dev/ttyUSB0)
* ''--fg_host'': Host for FlightGear visualization (e.g. 127.0.0.1)
* ''--fg_port'': Port on FlightGear host to connect to (Default: 5501)
* ''--fg_time_offset'': FlightGear time offset in seconds (e.g. 21600 for 6h), this is useful if it is currently night at the location you are flying and you want to add an offset to fly in daylight. (Since ''v4.9_devel_413-g9d55d6f)

=== Typical Simulation ===
In general you go through the same steps as with the real aircraft:
* It should start on the ground and you have to wait a few seconds until the AHRS is aligned.
* If you have a (simulated) RC, you can now arm the motors and fly around in manual.
* To fly autonomously, make sure your ''AUTO2'' mode is ''NAV'', you can change it in the GCS->settings->system->auto2.
** Switch to it if you are using an RC, otherwise you should already be in this mode.
** Arm your motors: either via the resurrect button or by going to the ''Start Motors'' block of the [[Flight Plans|Flight Plan]].
** Takeoff: via the takeoff button or the corresponding flight plan block.
* Do your stuff... :-)

=== Pausing or running the sim at a different speed ===
If you start the simulation from a terminal, hit ''CTRL-z'' to pause it. You can then enter a different time factor (default 1.0) to make the simulation run slower or faster than real-time. Hit enter to resume the simulation or ''CTRL-z'' again to suspend it like any normal Unix process (use the ''fg'' (foreground) command to un-suspend it again).

=== Use a Joystick ===
You can use a [[joystick]] (or connect your RC transmitter as a joystick) to control the quad in the simulator.
<source lang="bash">./var/Quad_LisaM_2/nps/simsitl -j</source>
or, with a specific device index (0 is default):
<source lang="bash">./var/Quad_LisaM_2/nps/simsitl --js_dev 0</source>

Joystick support uses the Simple DirectMedia Layer (SDL) library. Rather than specifying an input device name as one normally does on Linux, you just supply an index value (0, 1, 2,...) of the device you wish to use. Typically, the order of devices is the order in which you plugged them into your computer. The sim will display the name of the device being used to double check. If the <tt>-j</tt> option is used with no argument, the sim defaults to using device on index 0 (which is usually correct if you have only one joystick attached).

Also see [[Joystick#Calibration]].

=== Visualization in [[FlightGear]] ===
[[FlightGear#Installation|Install]] and [[FlightGear#Using_FlightGear_for_Visualization|start flightgear]], e.g. with a quadrotor model:
<source lang="bash">fgfs --fdm=null --native-gui=socket,in,30,,5501,udp --prop:/sim/model/path=Models/Aircraft/paparazzi/mikrokopter.xml</source>
restart your simulator with the ''--fg_host'' option:
<source lang="bash">./var/Quad_LisaM_2/nps/simsitl --fg_host 127.0.0.1</source>

=== Troubleshooting ===
* If you get an error like "JSBSim failed to open the configuration file: (null)/conf/simulator/jsbsim/aircraft/BOOZ2_A1.xml", you need to set your $PAPARAZZI_SRC and $PAPARAZZI_HOME environment variables. Add the following to your .bashrc, change paths according to where you put Paparazzi. Open a new terminal and launch the sim again.
export PAPARAZZI_SRC=~/paparazzi
export PAPARAZZI_HOME=~/paparazzi

* If you did not install the jsbsim package your JSBSim installation under /opt/jsbsim will be used and you will have to set your library path (either in your shell startup file or when running the sim on the command line), e.g.:
LD_LIBRARY_PATH=/opt/jsbsim/lib ./var/Quad_LisaM_2/nps/simsitl --fg_host 127.0.0.1

* If you get an error like "fatal error: gsl/gsl_rng.h: No such file or directory", you need to install the GNU Scientific Library and corresponding development packages (libgsl).

== Usage Examples ==

=== Plot the value of a message field ===
Start the [[RTPlotter|real-time plotter]] tool menu of [[Paparazzi Center]] or with
<source lang="bash">./sw/logalizer/plotter</source>
for example drag the label 'int32 phi' from the ROTORCRAFT_FP message to the drawing area of the plotter

* Use the datalink to change the telemetry mode
start 'settings' ( from the tool menu of paparazzi center) or with
./sw/ground_segment/tmtc/settings -ac Quad_LisaM_2
start 'server' to dispatch datalink messages ( from the tool menu of paparazzi center) or with
./sw/ground_segment/tmtc/server
change the field "telemetry" on the first page to "Att loop" and send by pressing the green check button. The label on the left or the drop box should change to "Att loop" confirming your message has been received. "message" should now show that the message "STAB_ATTITUDE_INT" is received

=== Tuning the attitude control loop ===
Here we are going to use the simulator to demonstrate a way of tuning the attitude control loop.

* Restart your previous session
* Set telemetry mode to "attitude_loop"
* Display two real time plotter windows

In the first one, plot the field "m_phi" from the "STAB_ATTITUDE_int" message. This is our estimation of roll angle.
On top of that, plot the field "phi" from the "STAB_ATTITUDE_REF_INT" message. This is our reference roll angle, that is, the roll value we are trying to achieve.

In the second plotter, plot the fields "delta_a_fb" and "delta_a_ff". Those are respectively the feedback and feedforward part of our roll command. The sum of those two terms is what is used as roll command.The feedforward part is the part used to follow our trajectory and the feedback part is the part used to reject perturbations.

* In "Settings", go to the "Att Loop" tab
We notice that the vehicle doesn't follow the step trajectory we are trying to make him do accurately.

Start by setting the value of the proportional gain ('pgain_phi') to 1000 instead of 400. The vehicle now follows the trajectory faster but overshoots. To prevent that, increase the value of the derivative gain ('dgain p') from 300 to 700.

If you look at the plotter where you're plotting the commands, you'll notice that during steps, the feedback command has to work hard. This means that our feedforward command is badly tuned, and namely not working hard enough. Increase the value of the feedforward gain ('ddgain p') from 300 to 540. You'll notice that now the feedback command has become marginal during the steps. This is the right value for the gain. Anything bigger will make the feedback command fight against the feedforward command during steps, anything smaller will make the feedback command have to complement the feedforward command.

[[Category:Simulation]] [[Category:Software]] [[Category:User_Documentation]]

Installation/Manual

2013-07-11T19:12:42Z

Alonsoac: mention patch needed in xml-light 2.2

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Installation</categorytree>
__TOC__
'''Users of recent Debian/Ubuntu distributions are advised to use the binary packages as described in [[Installation/Linux]].'''

Users of other Linux flavors or anyone needing manual control of each individual package can install them independently. The list of dependencies of the Debian package is located in the [https://github.com/paparazzi/paparazzi-portability-support/blob/master/linux/paparazzi-dev/debian/control <tt>debian/control</tt>] file and may help users of other distributions.

Some corresponding source tarballs can be downloaded from [https://launchpad.net/~paparazzi-uav/+archive/ppa/+packages paparazzi-uav ppa] on launchpad.

For distributions using RPM packaging, the [http://packages.debian.org/unstable/source/alien alien] tool can be used to translate a .deb package into a .rpm package.

For Fedora (Core8) users, you can install the following packages from standard repository:
* ocaml.i386
* ocaml-camlimages-devel.i386
* ocaml-lablgtk-devel.i386
* ocaml-xml-light-devel.i386
* boa.i386
* libgnomecanvas-devel.i386
* libusb-devel.i386
* pcre-devel.i386
* arm-gp2x-linux-gcc.i386
* arm-gp2x-linux-binutils.i386
* glade2.i386
* and gcc, make, subversion, gnuplot, imagemagik...

Note that ocaml-xml-light version 2.2 in its official source release and in some distribution packages requires a patch in order to function properly with paparazzi. Find patch [https://github.com/OCamlPro/opam-repository/blob/master/packages/xml-light.2.2/files/fix_dtd_trace.patch here].

Then you need [http://packages.debian.org/unstable/source/alien alien] tool to convert packages from the paparazzi repository:
* ivy-c
* ivy-c-dev
* ivy-ocaml (WARNING: debian and fedora have different path for ocaml (/usr/lib/ocaml/<version> vs. /usr/lib/ocaml), so you need to move by hand the files in /usr/lib/ocaml/<version> to /usr/lib/ocaml)
* lpc21isp

These Ivy binary packages will only work with the corresponding version of ocaml. Ivy repository is located [http://www.eei.cena.fr/products/ivy/download/packages/ here].

== Using 32Bit on 64Bit ==

If you want to run the 32bit versions on a 64bit machine for whatever reason...

In these cases, a chroot is a good compromise, while avoiding the overhead of a virtual machine (and USB device problems which may occur).
Initial instructions are here for now: https://help.ubuntu.com/community/DebootstrapChroot
The command you use for the bootstrap needs to reflect your architecture - I used

sudo debootstrap --variant=buildd --arch i386 lucid /var/chroot/lucid http://gb.archive.ubuntu.com/ubuntu/

The format for schroot config files has changed as of lucid however - here is mine:

$ cat /etc/schroot/chroot.d/lucid-i386
[lucid]
description=Ubuntu 10.04 Lucid for i386
directory=/var/chroot/lucid
personality=linux32
root-users=my_user
type=directory
users=my_user

Once you've installed the ubuntu minimal package, make sure you also enable the uni- and multiverse repos (the easiest way for me is to simply copy my host's /etc/apt/sources.lst to /var/chroot/lucid/etc/apt/sources.lst).
Then follow the standard instructions above. You may need to manually set the PAPARAZZI_HOME and PAPARAZZI_SRC environment variables. You will also have to set the DISPLAY environment variable to :0.0 like so:

export DISPLAY=:0.0

Please note, this is more advanced than the standard paparazzi installation and therefore you may encounter strange problems.

[[Category:Software]] [[Category:User_Documentation]] [[Category:Installation]]