PaparazziUAV - User contributions [en]

Pan Tilt Camera

2017-10-18T22:25:08Z

Rijesh: added Cam_Footprint link

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

== Pan/Tilt Video Camera Mechanism ==

Paparazzi currently allows to automatically move (follow a waypoint) a one axis pitch or roll camera as well as a two axis yaw-fixed-then-pitch camera. A [[Cam_Footprint|cam footprint]] can also be enabled on the GCS.

[[Image:Glotzer_cam_xy.jpg|thumb|left|Two axis yaw-fixed, pitch-move mechanism]]
[[Image:Black_one_roll.jpg|thumb|left|One axis roll]]
[[Image:Red_one_pitch.jpg|thumb|left|One axis pitch]]
<br style="clear:both">

The camera control is made of normal servos. Usually servos have a turn angle of about 90°. This is changed electrically so that they can do a 180°. It is achieved by adding two serial resistors at both sides of the potentiometer (P1), one for increasing the usable angle (R1) and the other for moving the middle position to a useful angle (R2). Therefore a servo with a 270° potentiometer is needed. Very small and light servos have 180° potentiometers, these do not allow a 180° degrees sweep. Cut the outer two connections between the potentiometer and the board to insert the resistors. The values for R1 and R2 should be found out by testing as there might be serial resistors on the servo board that affect the values. Start with about 1/2 the value of P1 for R1 and change R1 until you get a little more than 180° sweep. Then insert and modify R2 to set neutral back to the middle position of the potentiometer.

<tt>
^
/
----------
*-------I / I-------*
I ---------- I
I / P1 I
I I I
I I I
--- I ---
I I I I I
I I I I I
I I I I I
--- R1 I --- R2
I I I
I I I
</tt>

If you don't want to bother modifying your servo to 180°, use a 180° servo strecher for your standard servo [[http://www.servocity.com/html/180o_servo_stretcher.html ServoCity]] or [[http://www.robotmarketplace.com/products/0-FRMRT180.html RobotMarketPlace]] or buy a 180° servo [[http://www.servocity.com/html/hs-645mg_ultra_torque.html ServoCity]] or [[http://www.modellbau-bichler.com/servobeckers100s180gradjr-p-8221.html?osCsid=b3f7a1d078e0fa1d0433e29ed16da866 Becker]]

The Paparazzi software makes planes circle clockwise (use negative radius for counter-clockwise) so the default view is to the right side of the plane. The pan servo neutral makes the camera look to the right with 0° given, 90° is to the back and -90° is to the front. The tilt servo neutral makes the camera look down with 0° given, 90° is to the right and -90° is to the left (all values are used in radian in the software). If the camera looks to the right side of the plane, the picture is upright. It is upside down when looking to the left. That is corrected with the MPEG decoding software on the laptop by mirroring. The pan servo is fixed in the plane and the tilt servo is moved by the pan servo and moves the camera.

pan servo, tilt set to 90°, looking from top:

plane front
<tt>
^
I
I 45°
I /
I/
I------- 0°
I\
I \
I -45°
I
</tt>
plane rear

tilt servo, pan set to 0°, looking from back:
<tt>
plane left --------------- plane right
/ I \
/ I \
-45° I 45°
0°
</tt>
tilt servo is moved by the pan servo and moves the camera.

Add this to your Aircraft file to the right place:
<source lang="xml">
<servo name="CAM_PAN" no="3" min="2000" neutral="1550" max="1000"/>
<servo name="CAM_TILT" no="6" min="1000" neutral="1550" max="2000"/>

<axis name="CAM_TILT" failsafe_value="0"/>
<axis name="CAM_PAN" failsafe_value="0"/>

<set command="CAM_PAN" value="@YAW"/>
<set command="CAM_TILT" value="@GAIN1"/>

<set servo="CAM_PAN" value="@CAM_PAN"/>
<set servo="CAM_TILT" value="@CAM_TILT"/>

<section name="CAM" prefix="CAM_">
<define name="TILT_MAX" value="30"/>
<define name="TILT_NEUTRAL" value="0"/>
<define name="TILT_MIN" value="-30"/>
<define name="TILT0" value="0" />

<define name="PAN_MAX" value="45"/>
<define name="PAN_NEUTRAL" value="0"/>
<define name="PAN_MIN" value="-45"/>
<define name="PAN0" value="0"/>
</section>

<modules main_freq="60">
<load name="cam_point.xml">
<define name="POINT_CAM_PITCH_ROLL" value="1"/>
<define name="SHOW_CAM_COORDINATES" value="1"/>
</load>
</modules>
</source>

It make use of cam.c and point.c in sw/airborne/modules/cam_control/

When you load cam.xml in your settings of your aircraft session you can tune this:

THE MODE:

OFF =0

ANGLES=1 (look at angle that you chose in the angle tap)

NADIR=2 (look down)

XY_TARGET=3 (looks to the coordinates where you activate it, look here)

WP_TARGET=4 (looks to the way point that you chose in the target tap, cam_target_wp)

AC_TARGET=5 (looks at an aircraft, activate traffic_info.c)

ANGLES:

set your pan tilt angle for the Angles mode=1

TARGET:

set the way point you want to look at

1=home

2=... (see your way point file)

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

GCS

2017-10-18T22:23:42Z

Rijesh: Added cam footprint link

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

Ground Control Station

{|
|-valign="top"
|__TOC__
|
[[Image:gcs.jpg|frame|left|The Paparazzi Ground Control Station is the heart of the system and the user's primary interaction interface.]] [[Image:GCSParrotardroneandpaparazzi.jpg|frame|right|The GCS is very flexible in the way you can change the look and add functionality. One only need to change a configuration file. For example, the look when using the configuration GCS setting for Paparazzi Parrot AR Drone 2]]
|}

= Introduction =

The [[GCS_Configuration | versatile]] Paparazzi Ground Control Station is an operator control unit ground control software for unmanned aircraft. It allows to visualize and control an unmanned aircraft during development and operation, both indoors and outdoors. With a flexible software architecture it supports multiple UA types/autopilot projects. The purpose of the '''G'''round '''C'''ontrol '''S'''tation is real-time monitoring of an UA.

= Features =

The Paparazzi GroundControlStation is a feature-rich application with fully customizable views, each containing a collection of the most useful interface components for a particular purpose.

* Simultaneous flying '''multi UAS''' support
* Multi-system support (multiple procotols, multiple autopilots/projects) by writing a IVY Plugin
* 2D Map capable of displaying Google Satellite, OpenStreetMaps Images and Microsoft Satellite Maps
* Mission planning
* '''Realtime movable waypoints'''
* Realtime flightplan adjustments if needed
* System status overview
* '''Realtime''' Airframe '''in Air tuning''' and calibration
* Supports rotary and fixed-wing e.g. Airplanes, helicopters, coaxial and quadrotors
* Definable '''Hotkeys''' for quick simple in the field control
* '''Voice''' status output
* Full freely '''configurable GUI layout'''

= Configuration Options =
The [[GCS_Configuration|GCS is highly configurable]] and modules can be added, removed, or resized as needed. In addition to this the GCS has many '''command line options''' which can be used when launching the GCS
<br>
See the [[GCS_Configuration|'''GCS configuration''']] page for details.

= Simulation of Flightplan =
Your flight plans can, and should, always be tested prior to a real autonomous flight. Testing end adjusting is possible from within the same GCS. See the [[Simulation|simulation]] page for details.

= Options =

== Strips ==

Each A/C has an associated strip that displays information about the A/C and provides buttons for common commands. The strip has the following layout by default. Paparazzi GCS is very flexible and the strip can have more or less buttons according to your configuration.

[[Image:strip.png|Aircraft information strip]]

=== Displayed information ===

* Left: Flight information
* Center: Navigation information
* Right: Navigation control
* Bottom: Custom navigation and setting buttons

=== Actions ===

Every change in the waypoints (position or/and [[Altitude_definitions|altitude]]) must be confirmed with the dialog box that appears after the move. A modified waypoint remains animated on the map and the GCS continues to re-send the move request until confirmation is received from the aircraft.
When clicked, the '''Mark''' button places a mark on the map at the A/C position. A snapshot from the video plugin is associated to this mark and can be viewed by moving the mouse over the mark. A click on the mark opens a dialog box allowing to delete the mark.
A click on the colored bar at the top selects the corresponding A/C in the [[#notebook|Notebook]].

== Map ==

[[Image:GCSmap.png|thumb|400px|Sample map showing the various features]]

=== Display ===

The map display contains the following information:
* The A/C track: it can be erased ''via'' the ''Clear track'' option from the A/C menu.
* The A/C label (in clear blue near the A/C) contains the name of the A/C (Plaster), it's altitude (218 m) and it's ground speed (11.99 m/s). This option default is off. It can be activated with the ''A/C label'' option from the A/C menu.
* The carrot (the orange triangle). This is the point the A/C is following during autonomous navigation.
* The waypoints defined in the flight plan (blue diamonds).
* The intended trajectory is shown as a green line, in this example a circle around waypoint 2.
* The default background is black. [[Maps|Maps]] can be loaded to provide navigation reference.
* The camera footprint (the grey polygon) is representative of the swath of land currently seen by the onboard camera. This option default is off. It can be activated with the ''[[Cam_Footprint|Cam footprint]]'' option from the A/C menu. see also [[Pan_Tilt_Camera]]
* The WGS84 coordinates of the mouse cursor are displayed at the top right hand corner (43.462019 1.270474).
* A UTM kilometric grid can be added to the background ''via'' the ''UTM grid'' option from the ''Nav'' menu.
* The [[Altitude_definitions|height Above Ground Level (AGL)]] displays the ground altitude of the mouse near the geographic position in the top right hand corner. The [http://srtm.usgs.gov/ SRTM] option must be enabled in the ''Nav'' menu and the height data must be downloaded as described [[Maps#Height_Data|here]]. If SRTM data is not enabled and downloaded, the height above mean sea level [[Altitude_definitions#MSL|MSL]] will be displayed instead.

=== Navigation ===

You can pan/zoom the map using the following:
* Pan with the blue arrows on the map or use the arrow keys on the keyboard
* zoom in/out with the mouse scroll wheel, the page up/page down buttons or the small up/down buttons at the top right hand corner where the zoom factor is displayed
* fit the map to the window, in order to see all the waypoints and A/C, with the '''f''' key or the ''Fit'' option from the ''Nav'' menu;
* center the map on an A/C with the ''Center A/C'' option from the corresponding A/C menu.

=== Map Photo Tiles ===
The default black background can be automatically filled with calibrated satellite photo tiles from Openstreetmaps, Google Maps or MS Maps. Note: If you download too much map data from Google into the GCS you may be blocked for downloading further map data for 24 hours. With OpenStreetmaps data and MS data there is no such limitation.
<br>
See the [[Maps]] page for more info.

=== Waypoint Editing ===

The properties of any waypoint in the currently loaded flight plan can be modified by two methods:
* Drag and drop the waypoints to a new location (a confirmation dialog will appear).
* A single left click on a waypoint opens a dialog box where you can edit the waypoint's coordinates and altitude.

Waypoint edits are sent to the aircraft immediately upon confirmation in the dialog box. The GCS will re-send the data and the waypoint will animate until the aircraft confirms receipt of the move request. New waypoints cannot be added during flight.
<br>
See the [[Flight_Plans|Flight plans]] and [[Flight_Plan_Editor|Flight Plan Editor]] pages for more information on waypoints.

== Notebook ==

The notebook frame contains one page for each running aircraft. Each aircraft page is itself divided into subpages displaying telemetry data and giving access to the autopilot tuning parameters.

Note that the colored tabs at the top of this section allow the user to select among multiple aircraft.

=== Flight Plan ===

<center>
[[Image:GCSfp.png|Flight plan tree]]
</center>

The full tree of the flight plan is given in this page. The current block and the current stage are highlighted. A double-click on a block allows the operator to immediately switch navigation to this block.
<br>
See the [[Flight_Plans|Flight plans]] and [[Flight_Plan_Editor|Flight Plan Editor]] pages for more information on flight plans.

=== Settings ===
<center>
[[Image:GCSsettings.png|Settings tab]]
</center>
The setting page allows the operator to change variable values during flight. The layout of the page is generated from the <tt>dl_settings</tt> section of the settings.xml file, one tab is associated to every section and sub-section.

On each line is displayed (from left to right), the name of the variable, its current value (periodically sent by the A/C), a slider or radio buttons for user input, and commit/undo buttons. Also note, clicking on the current value will send a request to obtain the current value from the aircraft.
<br>
See the [[Telemetry#Settings|Telemetry]] page for more information on settings.
<br>
The save button of this tab opens the following popup which proposes to the user to save the current values in the airframe file (according to the <tt>param</tt> attribute in the [[Telemetry#Settings|setttings]] configuration file). The values of the checked rows will be saved in the airframe file (or any other file) for further use. Units (e.g. deg or rad) are taken into account. '''It is recommended to backup the airframe file before overwriting it with this utility''' (even if time-stamped copy of the airframe file is actually automatically done).

Symetrically, the Upload button of this dialog button will send all the checked values of the airframe file to the live aircraft.
<center>
[[Image:Save settings.png|Settings tab]]
</center>

=== PFD ===

[[Image:GCSpfd.png|Primary Flight Display]]

The Primary Flight Display contains an artificial horizon and two scales displaying the current ground speed (left side) and the altitude (right side). Minimum and maximum speeds are shown under and above the speed scale. A click on the scale resets these values to the current speed value.

=== GPS, Infrared, Wind ===

The '''GPS''' page gives the list of satellites tracked by the receiver and their respective signal strengths in dB.
(35 is low, 45 is excellent) and if they are used to compute the fix (green: used, red:not used). This page may help to tune the position of the receiver on the aircraft relatively to other components (e.g. datalink and video transmitters).

The '''Infrared''' page is only used for aircraft not equipped with the vertical infrared sensor. This page reports the required pre-flight calibration value as well as the evolution of the in-flight calibration correction factor (from hybridization with the GPS information).

The '''Misc''' page displays the estimated wind velocity computed by the ground station during flight and relayed back to the aircraft. Wind velocity is estimated by vector addition of the GPS-measured ground speed in many different directions during level flight. This computation may soon be performed by the autopilot instead of the ground station.

== Video Plugin ==

The <tt>-mplayer</tt> option of GCS allows the user to display a video stream in this window. The video window can also be exchanged with the map by clicking anywhere inside the frame or from the menu.
Use the following line in your [[Control_panel.xml|control panel]] to enable the video window.
<tt>(paparazzi folder path)/sw/ground_segment/cockpit/gcs -mplayer rtsp://localhost:7070/video -layout appropriate_layout.xml</tt>
Note that a <tt>plugin</tt> widget must be specified in the used layout:
<source lang="xml"> <widget size="300" name="plugin"/> </source>
A useful example of how to configure the GCS to show video from a USB DVB-T tuner with composite input 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 connecting a video signal to the composite input
and then opening a console window and typing:

'''mplayer tv:// -tv driver=v4l2:width=320:height=240:norm=NTSC:input=1:device=/dev/video1:noaudio'''

Remember to change the "device=/dev/video1" in the above line with whatever your new usb tuner is registered with (if needed).
Type "dmesg" in a console immediately after you connect the usb tuner and you should see a line stating the video device your usb tuner got registered with.
If it says video0 change "device=/dev/video1" with "device=/dev/video0"
Mine is registered as "video1" because "video0" is the built in laptop camera.
If everything is ok then a blue or similar LED on the usb tuner dongle should light up indicating that the tuner driver is loaded
and you should be able to watch the video on the pc screen (no audio yet).
Now close the console and remove the Usb tuner as it is time to configure the control_panel.xml file by editing the GCS command line.
Locate the line in the "control_panel.xml" file, usually located in "/Your Paparazzi directory/conf/" (mine is in "/paparazzi/conf/"),
that starts with "<program name="GCS" command="sw/ground_segment/cockpit/gcs......".
For example let's say that the complete line looks like this:

<source lang="xml"> <program name="GCS" command="sw/ground_segment/cockpit/gcs -layout horizontal.xml"> </source>

Now add the below line at the end (before the quotes) of the original line:

'''-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 original line should look now 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.
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).
This will load the mplayer, select the composite video input of the tuner and enable the sound input.
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, it has a part that reads "-layout horizontal.xml"
so our layout 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):

<source lang="xml"><widget NAME="plugin" SIZE="300"/> </source>

Now the file should look like this:

<source lang="xml">
<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>
</source>

That's it, Enjoy!

Tested in Ubuntu 10.04 LTS but probably the same method should work fine on different versions too.

See this [http://www.youtube.com/watch?v=7OCcMA4vluM screen capture] as an example of the resulting GCS (Y-UAV).

The <tt>-plugin</tt> option is another way to use the plugin widget: the X subwindow id is given to the provided command:
<tt>(paparazzi folder path)/sw/ground_segment/cockpit/gcs -plugin "mplayer video_stream -wid " -layout appropriate_layout.xml</tt>
<tt>(paparazzi folder path)/sw/ground_segment/cockpit/gcs -plugin "cvlc video_stream --drawable-xid=" -layout appropriate_layout.xml</tt>
The <tt>--vout-event=3</tt> option can be used for vlc to disable mouse and keyboard events handling

== Altitude graph widget ==
<center>
[[Image:altgraph.png|400px|The GCS with the altitude graph]]
</center>

An altitude graph can be displayed in the GCS by adding the widget ''altgraph'' in the layout configuration (See the [[GCS_Configuration|GCS configuration]] page). An example is provided in conf/gcs/alt.xml. To use this layout add -layout alt.xml to the /conf/control_panel.xml file. This type of layout is more suited to a multi UAV set up. The Papget ruler is a much less intrusive and better tool when you are only flying a single aircraft.

==Papgets==
Graphical objects can be added to 2D maps: text, rule, gauge, buttons, .... These objects are named ''papgets''. The following snapshot
shows an example with buttons (left side), gauges (lower left corner), text (upper right corner) and ruler (right side). This example
has been produced with a layout file provided in the distribution:

.../gcs -layout papgets.xml

<center>
[[Image:papgets.png|516px|A 2D map augmented with papgets]]
</center>

===Telemetry data report===
The easiest way to create a papget displaying telemetry data is to drag&drop a message field from the Messages window onto the 2D map of the GCS. The default rendering is then a string of text. Clicking on it allows the user to change its type (currently text, ruler or gauge) and some of its attributes (color, size, range for a gauge, format for a text ...). A papget can be moved by simply dragging it.

<center>
[[Image:papget_editor.png|Main characteristics of a papget can be dynamically edited]]
</center>

Papgets can be saved in the layout of the GCS (from the Nav menu). The description is saved in an XML file (in <tt>conf/gcs/</tt> folder) which can be manually edited:

<source lang="xml">
<papget type="message_field" display="gauge" x="47" y="414">
<property name="field" value="BAT:voltage"/>
<property name="scale" value="0.1"/>
<property name="min" value="0."/>
<property name="max" value="15."/>
<property name="size" value="50."/>
<property name="text" value="Bat(V)"/>
</papget>
</source>

The file is used later by giving it to the gcs process:

<pre>
.../gcs -layout my_fancy_papgets.xml
</pre>

===Buttons===
In the same way, user buttons from the strip can be dragged&dropped on the 2D map. However, they currently cannot be directly edited, and
attributes changes have to be done in the XML file. Two types of button are provided to jump to a block or to set a value:
<source lang="xml">
<papget type="goto_block" display="button" x="10" y="300">
<property name="block_name" value="Standby"/>
<property name="icon" value="home.png"/>
</papget>
<papget type="variable_setting" display="button" x="10" y="250">
<property name="variable" value="launch"/>
<property name="value" value="1."/>
<property name="icon" value="launch.png"/>
</papget>
</source>

===Video on Papget===
A video stream can be rendered in a <tt>video_plugin</tt> papget, using the ''mplayer'' player:
<source lang="xml">
<papget type="video_plugin" display="mplayer" x="300" y="250">
<property name="video_feed" value="my video source"/>
<property name="width" VALUE="320"/>
<property name="height" VALUE="240"/>
</papget>
</source>
or any video player which takes in option the X window id, here for example ''VLC'':
<source lang="xml">
<papget type="video_plugin" display="plugin" x="300" y="250">
<property name="command" value="cvlc video_source --drawable-xid="/>
<property NAME="width" VALUE="320"/>
<property NAME="height" VALUE="240"/>
</papget>
</source>

===Aircraft binding===
Upto Paparazzi '''v5.4''', Papgets could not not bound to a specific aircraft. This had the effect that it will work with any of them, and when multiple aircraft are flying the display of messages is mixed and the buttons will send command or settings to all active aircraft.

Since Paparazzi '''v5.6''', Papgets are bound to a single aircraft, which means that they can safely be used with several active aircraft. It is also possible to add a property to the GCS layout file to specify the aircraft ID:
<source lang="xml">
<property name="ac_id" value="10"/>
</source>

Valid IDs are from 1 to 255 (0 being reserved to GCS). '''When''' this property is '''not''' defined, the Papget will bind to '''any aircraft like before'''. This can be useful if you intent to build a generic layout. When saving a layout from the GCS, if their are some Papgets to save, a question box will prompt the user to ask if the <tt>ac_id</tt> property should be saved or not.

===Papget Development===
Graphical appearence of papgets is defined in <tt>sw/lib/ocaml/papget_renderer.ml</tt>. A renderer must implement the Papget_renderer.t class type interface (<tt>canvas_text</tt> is probably the simpler example) and listed in the <tt>renderers</tt> list to be available
in the edit popup box.

The XML configuration is parsed in <tt>sw/ground_segment/cockpit/papgets.ml</tt>: a new created papget identifier must listed here.

== Alarms ==

The alarm window displays a list of recent errors such as:
* Low battery warning
* Low altitude warning
* Autopilot mode changes (i.e. Manual, Auto2)
* Flight plan block changes

These alarms can be provided via the speaker using the [[speech]] function.

== Airframe Specific GCS Customizations ==

Items related to the ''aircraft icon'', ''altitude shift values'', ''speech id'', and the overall ''icon theme'' of the GCS can be customized in each aircraft's [[Airframe_Configuration#GCS|airframe configuration file GCS section]].

=Related Links=

* [[GettingTheGCSRunningonAGumstixBoard | Getting the GCS running on a Gumstix board]]
* [[RaspberryPi | Getting the GCS running on a Raspberry Pi board]]
* [[PPRZonDroid | PPRZonDroid: a Remote GCS Android application]]

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

Cam Footprint

2017-10-18T22:22:19Z

Rijesh: Added cam footprint page

The paparazzi GCS has the ability to plot a camera footprint onto the map.
By default the footprint will be for a camera pointing straight down.

The camera's horizontal field of view and vertical field of view can be set in the airframe file:

<source lang="xml">
<section name="CAM">
<define name="CAM_HFV" value="65.1"/>
<define name="CAM_VFV" value="40.2"/>
</section>
</source>

A gimbaled camera will need to send a pan/tilt message to the server. A [[Pan_Tilt_Camera|cam point module]] is available that will point a pan/tilt camera using servos.

If a custom gimbal and module is being used, then the custom module will need to send the CAM message to the server.

<source lang="xml">
<message name="CAM" id="20">
<field name="pan" type="int16" unit="deg"/>
<field name="tilt" type="int16" unit="deg"/>
<field name="target_x" type="int16" unit="m"/>
<field name="target_y" type="int16" unit="m"/>
</message>
</source>

The server code is capable of mixing a full 3 axis gimbal with modifications. The modifications required to do this involve sending the new rotation in the cam message and enabling the use of that field in server.ml. The Quaternion used in the mixing takes Tait-Bryan as input angles.

Plotting shapes onto GCS

2016-08-15T18:22:19Z

Rijesh: Adding information about shape message

Messages can be sent over the IVY bus to plot shapes onto the GCS.

These shapes include circles, polygons, lines and text.
Shapes such as circles and polygons may have a fill with varying opacity.

<big>Message Definition</big>
<message name="SHAPE" id="38">
<description>
The SHAPE message used to draw shapes onto the Paparazzi GCS.
Field name shape is used to define the type of shape i.e. Circle, Polygon, Line, or Text.
This is indexed from 0-3 respectively.
Each shape drawn must have an id number associated with it.
This id number in conjunction with the shapetype will be needed to update or delete the shape.
A circle can be defined with the same id as a polygon but since they have different shape types they are considered unique.
linecolor and fillcolor take in a color string ie: "red", "blue"
opacity will change the level of transparency of the fill.
0 - Transparent
1 - Light Fill
2 - Medium Fill
3 - Opaque
Passing a status of 0 will create or update the shape specified by id and type.
Passing a status of 1 will delete the shape specified by id and type.
latarr is an array of coordinates that contain the latitude coordinate for each point in the shape.
The array is comma separated.
lonarr is similar to latarr but contain the longitude coordinate for each point in the shape.
Circle and Text type will take the first coordinates given to place the shape.
Polygon will take all the coordinates given.
Line will take the first two coordinates given.
Radius is only used for the circle.
Text will always be populated with each message using the first set of coordinates.
The text field can not be blank or have spaces.
If text is not desired for a shape then pass "NULL" into the text field.
</description>
<field name="id" type="uint8"/>
<field name="linecolor" type="string"/>
<field name="fillcolor" type="string"/>
<field name="opacity" type="uint8" values="Transparent|Light|Medium|Opaque"/>
<field name="shape" type="uint8" values="Circle|Polygon|Line"/>
<field name="status" type="uint8" values="create|delete"/>
<field name="latarr" type="int32[]" unit="1e7deg" alt_unit="deg" alt_unit_coef="0.0000001"/>
<field name="lonarr" type="int32[]" unit="1e7deg" alt_unit="deg" alt_unit_coef="0.0000001"/>
<field name="radius" type="float" unit="m"/>
<field name="text" type="string"/>
</message>

<big>Example Messages:</big>

Module/Mag HMC58xx

2015-07-29T23:01:26Z

Rijesh: added links

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

= Introduction =

Paparazzi allows the use of external Magnetometers. This module supports the use of the Honeywell HMC5843 and HMC5883 magnetometers.
These magnetometers can be connected to your autopilot board via i2c.

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware>
...
<define name="USE_I2C2" />
...
<subsystem name="ahrs" type="float_cmpl_quat">
<define name="AHRS_XXX_MAG_ID" value="MAG_HMC58XX_SENDER_ID"/>
</subsystem>
</firmware>
...
<modules>
<load name="mag_hmc58xx.xml">
<define name="MODULE_HMC58XX_UPDATE_AHRS"/>
<define name="MAG_HMC58XX_I2C_DEV" value="i2c2"/>
</load>
</modules>

</source>
}}

You will need to specify the AHRS_XXX_MAG_ID value. See [http://wiki.paparazziuav.org/wiki/Subsystem/ahrs#Enabling_External_Sensors AHRS External Sensors]

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

Module/Mag HMC58xx

2015-07-29T22:58:13Z

Rijesh: Documented HMC58xx module

= Introduction =

Paparazzi allows the use of external Magnetometers. This module supports the use of the Honeywell HMC5843 and HMC5883 magnetometers.
These magnetometers can be connected to your autopilot board via i2c.

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware>
...
<define name="USE_I2C2" />
...
<subsystem name="ahrs" type="float_cmpl_quat">
<define name="AHRS_XXX_MAG_ID" value="MAG_HMC58XX_SENDER_ID"/>
</subsystem>
</firmware>
...
<modules>
<load name="mag_hmc58xx.xml">
<define name="MODULE_HMC58XX_UPDATE_AHRS"/>
<define name="MAG_HMC58XX_I2C_DEV" value="i2c2"/>
</load>
</modules>

</source>
}}

You will need to specify the AHRS_XXX_MAG_ID value. See [http://wiki.paparazziuav.org/wiki/Subsystem/ahrs#Enabling_External_Sensors AHRS External Sensors]

Subsystem/ahrs

2015-07-29T22:25:08Z

Rijesh: Added how to enable ABI messages from external Mag

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages hideprefix=always>Subsystems</categorytree>
== AHRS subsystem ==
The '''A'''ttitude and '''H'''eading '''R'''eference '''S'''ystem subsystem specifies which attitude estimation filter you are using.

Currently possible AHRS subsystem types are:

{| class="wikitable" style="text-align:center" border="1"
! Type !! Point type !! Firmwares !! Notes
|-
|'''[[Subsystem/ahrs#Complementary_Quaternion_.28fixed_point.29|int_cmpl_quat]]''' || fixed || all ||
|-
|'''[[Subsystem/ahrs#Complementary_Quaternion.2FRotation_Matrix_.28floating_point.29|float_cmpl]]''' || floating || all ||
|-
|'''[[Subsystem/ahrs#DCM_.28floating_point.29|float_dcm]]''' || floating || fixedwing ||
|-
|'''[[Subsystem/ahrs#Complementary_Euler_.28fixed_point.29|int_cmpl_euler]]''' || fixed || rotorcraft ||
|-
|'''[[Subsystem/ahrs#Kalman_Filter_Quaternion|float_mlkf]]''' || floating || rotorcraft ||
|-
| '''[[Subsystem/ahrs#Infrared|infrared]]''' || || fixedwing? ||
|}

e.g. for the latest complementary filter:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<subsystem name="ahrs" type="int_cmpl_quat"/>
</firmware>
</source>
}}

== Implementations ==

There is a test program ( sw/airborne/test/ahrs/compare_ahrs.py ) to compare different AHRS implementations on simple test cases.

<span style="color:#FF0000">'''Caution!'''</span> '''Please also see [https://github.com/paparazzi/paparazzi/issues/93 issue 93] about proper handling of BODY_TO_IMU in all AHRS algorithms.'''

=== Complementary Quaternion (fixed point) ===

To measure attitude angles, gyrometers measurements are integrated. The result of integration is accurate for short term, but gyro bias is accumulated, which results in long term errors (drift).
On the other hand, accelerometers can be used to measure angles directly, but they suffer from noise due to vibrations. The measurement is then only accurate when averaged over a long term. Also, accelerometers alone are unable to give accurate angles when the vehicle is accelerating.
Complementary filter takes advantage of both sensors, using a low-pass filter on accelerometer readings and high pass filter on gyrometers readings, to estimate attitude angles.
* No danger of [http://en.wikipedia.org/wiki/Gimbal_lock gimbal lock], since quaternions are used.
* The arithmetic is [http://en.wikipedia.org/wiki/Fixed-point_arithmetic fixed point] and is thus suitable if the processor (on your board) has no [http://en.wikipedia.org/wiki/Floating_point_unit FPU].
* Estimates the gyro bias.
* For rotorcrafts: uses magnetometer for heading. Needs calibration!<br/>You can add <source lang="xml" enclose="none"><configure name="USE_MAGNETOMETER" value="TRUE"/></source> to be explicit about it.
* Also suitable for fixedwings, but you need GPS.
** Compensation of centrifugal force via GPS speed (to fly in circles with a fixedwing).<br/>Enabled with AHRS_GRAVITY_UPDATE_COORDINATED_TURN which is set by default for a fixedwing firmware.
** Uses GPS course for heading estimation and disable magnetometer, add <source lang="xml" enclose="none"><configure name="USE_MAGNETOMETER" value="FALSE"/></source> if you want to be explicit.

Other flags of interest are:
*AHRS_PROPAGATE_LOW_PASS_RATES : apply a low pass filter on rotational velocity
*AHRS_MAG_UPDATE_ALL_AXES : use mag to also update roll/pitch and not only yaw (not recommended in most cases)

* NEW since [https://github.com/paparazzi/paparazzi/commit/b40da0ae56e861e088017c01426d0c4ed7c43350 v5.1_devel-455-gb40da0a]:
** Proper scaling of corrections for 100Hz fixedwing or 500Hz for rotorcraft.
** Allow tuning of the accel and mag correction natural freqency and damping.
** Tunable gravity_heuristic_factor to reduce accelerometer influence only when the vehicle is accelerating (norm of ax,ay,az ~ 9,81 m/s2).

* Flags of interest in master branch are:
** AHRS_PROPAGATE_FREQUENCY: IMU gyrometer reading frequency ( Hz, depend on IMU subsystem used and its configuration)
** AHRS_CORRECT_FREQUENCY: IMU accelerometer reading frequency (Hz)
** AHRS_MAG_CORRECT_FREQUENCY: IMU magnetometer reading frequency (Hz)
** AHRS_ACCEL_OMEGA: Complementary filter accelerometer cut-off frequency (rd/s). Default is 0.063 rd/s, the accelerometer reading are "averaged" over 100 seconds (= 2*pi/0.063) to correct gyro bias. Lower the cut-off frequency reduce the influence of accelerometers. WARNING: if ACCEL_OMEGA is set at a lower frequency, the gyro bias variations may not be corrected fast enough. As a result, the computed attitude may show significant static (or low frequency) errors. If accel_omega is set higher, the gyro bias will be well corrected and the static accuracy of the computed angle will be very good, but the dynamic error of the computed angle may be bad.
** AHRS_ACCEL_ZETA: Complementary filter accelerometer damping. Default is 0.9
** AHRS_MAG_OMEGA:Complementary filter magnetometer cut-off frequency (rd/s). Default is 0.04 rd/s. Acts the same as accelerometer but on the yaw axis.
** AHRS_MAG_ZETA:Complementary filter magnetometer damping. Default is 0.9
** AHRS_GRAVITY_HEURISTIC_FACTOR: Default is 30. Reduce accelerometer cut-off frequency when the vehicle is accelerating: norm(ax,ay,az) ~ 9,81 m/s2. WARNING: when the IMU is not well damped, the norm of accelerometers never equals to 9,81 m/s2. As a result, the GRAVITY_HEURISTIC_FACTOR will reduce the accelerometer bandwith even if the vehicle is not accelerating. Set AHRS_GRAVITY_HEURISTIC_FACTOR = 0 in case of vibrations.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<subsystem name="ahrs" type="int_cmpl_quat"/>
</firmware>

<section name="AHRS" prefix="AHRS_">
<define name="H_X" value=" 0.51562740288882"/>
<define name="H_Y" value="-0.05707735220832"/>
<define name="H_Z" value=" 0.85490967783446"/>
</section>
</source>
}}

Also see the [[Subsystem/ahrs#Local_Magnetic_Field|Local Magnetic Field]] section.

To use '''int_cmpl_quat''' for fixedwings without magnetometer (GPS based heading estimation instead):
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing">
...
<subsystem name="ahrs" type="int_cmpl_quat"/>
<configure name="USE_MAGNETOMETER" value="FALSE"/>
</firmware>
</source>
}}

=== Complementary Quaternion/Rotation Matrix (floating point) ===
* Estimates the gyro bias.
* By default uses magnetometer for heading for rotorcrafts.
* You need to define either ''AHRS_PROPAGATE_RMAT'' or ''AHRS_PROPAGATE_QUAT'' (select if the propagation is done in rotation matrix or quaternion representation).
* For fixedwings:
** Compensation of centrifugal force via GPS speed (to fly in circles with a fixedwing).<br/>Enabled with AHRS_GRAVITY_UPDATE_COORDINATED_TURN which is set by default for a fixedwing firmware.
** GPS based heading estimation: https://github.com/paparazzi/paparazzi/issues/130
Other flags of interest are:
* AHRS_PROPAGATE_LOW_PASS_RATES : apply a low pass filter on rotational velocity
* AHRS_MAG_UPDATE_ALL_AXES : use mag to also update roll/pitch and not only yaw (not recommended in most cases)
* AHRS_GRAVITY_UPDATE_NORM_HEURISTIC: lower the gain of the gravity update based on a acceleration norm heuristic (e.g. good for bungee takeoff)

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft or fixedwing">
...
<subsystem name="ahrs" type="float_cmpl_rmat">
<define name="AHRS_PROPAGATE_QUAT"/>
</subsystem>
</firmware>

<section name="AHRS" prefix="AHRS_">
<define name="H_X" value=" 0.51562740288882"/>
<define name="H_Y" value="-0.05707735220832"/>
<define name="H_Z" value=" 0.85490967783446"/>
</section>
</source>
}}

Also see the [[Subsystem/ahrs#Local_Magnetic_Field|Local Magnetic Field]] section.

<p>
No danger of [http://en.wikipedia.org/wiki/Gimbal_lock gimbal lock], since quaternions are used.
<br/>
Suitable for fixedwings. Needs GPS!
<br/>
Suitable for rotorcraft if the magnetometer is calibrated.
<br/>
The arithmetic is [http://en.wikipedia.org/wiki/Floating_point floating point] and is thus '''not''' suitable if the processor (on your board) has '''no''' [http://en.wikipedia.org/wiki/Floating_point_unit FPU].
</p>

=== DCM (floating point) ===
* No direct gyro bias estimation, but also compensates for attitude drift.
* Uses GPS speed for heading.
* Compensation of centrifugal force via GPS speed (to fly in circles with a fixedwing).
* '''Careful, it doesn't handle all BODY_TO_IMU rotations (mounting positions) correctly!'''

The algorithm was developed by William Premerlani and Paul Bizard. The theory can be found here: [[Media:DCMDraft2.pdf|DCMDraft2.pdf]] The algorithm is also used in the AHRS systems of the AdruIMU.
The name DCM for the algorithm is really a misnomer, as that just means that the orientation is represented as a '''D'''irection'''C'''osine'''M'''atrix (rotation matrix). But since people already know it under that name, we kept it.

Other flags of interest are:
*USE_MAGNETOMETER : use magnetometer to update yaw (UNTESTED. The magnetometer code has to be improved, since ferromagnetic materials affect the magnetic field. This is currently not implemented.)
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing">
...
<subsystem name="ahrs" type="float_dcm"/>
</firmware>
</source>
}}

=== Complementary Euler (fixed point) ===
* Not recommended for fixedwings, as this filter doesn't compensate for centrifugal force when flying turns.
* Magnetometer is always only used for heading (yaw).
* '''Does not handle the accel and mag updates correctly if BODY_TO_IMU is used for more than just adjustment by a few degrees.'''
* In general, rather use ''[[Subsystem/ahrs#Complementary_Quaternion_.28fixed_point.29|int_cmpl_quat]]''

Optional flags/defines are:
* FACE_REINJ_1 : defaults to 1024
* IMU_MAG_OFFSET : offset to subtract from the heading calculated by the magnetometer
* USE_NOISE_FILTER : apply a simple filter on the rate and accel inputs
* USE_NOISE_CUT : cut rate input at 1 rad/s and accel input at 20m/s²

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="ahrs" type="int_cmpl_euler"/>
</firmware>

<section name="MISC">
<define name="FACE_REINJ_1" value="1024"/> 
</section>
</source>
}}

<p>
Possible danger of [http://en.wikipedia.org/wiki/Gimbal_lock gimbal lock], since quaternions are not used.
<br/>
Repeat from above: '''Not''' suitable for fixedwings.
<br/>
Suitable for rotorcraft. The magnetometer is used to determine the yaw and needs to be calibrated.
Recommended replacement: [[Subsystem/ahrs#Complementary_Quaternion_.28fixed_point.29|int_cmpl_quat]]
<br/>
The arithmetic is [http://en.wikipedia.org/wiki/Fixed-point_arithmetic fixed point] and is thus suitable if the processor (on your board) has no [http://en.wikipedia.org/wiki/Floating_point_unit FPU].
</p>

=== Kalman Filter Quaternion ===
Multiplicative Linearized [http://en.wikipedia.org/wiki/Kalman_filter Kalman Filter] in quaternion formulation.
* Available in v5.0 and later
* Estimates the gyro bias.
* Uses magnetometer to update all 3 axes.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
...
<subsystem name="ahrs" type="float_mlkf"/>
</firmware>

<section name="AHRS" prefix="AHRS_">
<define name="H_X" value=" 0.51562740288882"/>
<define name="H_Y" value="-0.05707735220832"/>
<define name="H_Z" value=" 0.85490967783446"/>
</section>
</source>
}}

Also see the [[Subsystem/ahrs#Local_Magnetic_Field|Local Magnetic Field]] section.

<p>
No danger of [http://en.wikipedia.org/wiki/Gimbal_lock gimbal lock], since quaternions are used.
<br/>
'''Not''' suitable for fixedwings!
<br/>
Suitable for rotorcraft. The magnetometer is used and needs to be well calibrated.
Estimates attitude and heading. Does not use GPS.
<br/>
The arithmetic is [http://en.wikipedia.org/wiki/Floating_point floating point] and is thus '''not''' suitable if the processor (on your board) has '''no''' [http://en.wikipedia.org/wiki/Floating_point_unit FPU].
</p>

=== Infrared ===
For use with infrared sensors that detect aircraft attitude and the [[Module/infrared| infrared module]].

== Local Magnetic Field ==
[[Image:Noaa_mag_data.png|thumb|right|200px|Screenshot of noaa page]]
[[Image:Normalised_mag_fields.png|thumb|right|200px|Screenshot of scilab page]]
'''This is needed if the magnetometer should be used !'''<br/>
Take also a look at [[ImuCalibration#Calibrating_for_the_Earth_magnetic_field| magnetometer calibration]] which should be done to increase accuracy !

First the values of the local magnetic field vector are needed. They can be found at the states geological institute.

USA [http://www.ngdc.noaa.gov/geomag-web/#igrfwmm ngdc.noaa.gov]

Needed values are:
* north component (x)
* east component (y)
* vertical component (z)

The vector components are in nanotesla (nT) but AHRS needs these values as a unit vector (the length of a unit vector is 1), so they need to be normalized.

'''Convert them:'''

Copy the north(x), east(y), and vertical(z) component values into scilab and execute "X/norm(X)" or run this in ipython:

<source lang=python>
import numpy as np
x = np.array([20875.1, 8480.2, -51279.8])
x/np.linalg.norm(x)
</source>

or enter this into [http://wolframalpha.com Wolfram Alpha]:
<source lang=python>
Normalize[{20875.1, 8480.2, -51279.8}]
</source>

Lastly, enter the results into your airframe file as H_X, H_Y, and H_Z:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<section name="AHRS" prefix="AHRS_">
<define name="H_X" value="0.372692"/>
<define name="H_Y" value="0.151401"/>
<define name="H_Z" value="-0.915521"/>
</section>
</source>
}}

=== Update geomagnetic field vector based on GPS ===
You can also add the [http://docs.paparazziuav.org/latest/module__geo_mag.html geo_mag.xml module], which will update the normalized magnetic field at startup using GPS fix:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<modules>
<load name="geo_mag.xml"/>
</modules>
</source>
}}

== Enabling External Sensors ==

By default the AHRS algorithms will utilize onboard sensors. Paparazzi currently has support for external Magnetometers. In order to use an external sensor you must specify the ABI Message ID of the sensor.

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<subsystem name="ahrs" type="float_cmpl_quat">
<define name="AHRS_FC_MAG_ID" value="MAG_HMC58XX_SENDER_ID"/>
</subsystem>
</source>
}}

{| class="wikitable" style="text-align:center" border="1"
! Type !! AHRS_XXX_MAG_ID
|-
|'''[[Subsystem/ahrs#Complementary_Quaternion_.28fixed_point.29|int_cmpl_quat]]''' || AHRS_ICQ_MAG_ID
|-
|'''[[Subsystem/ahrs#Complementary_Quaternion.2FRotation_Matrix_.28floating_point.29|float_cmpl]]''' || AHRS_FC_MAG_ID
|-
|'''[[Subsystem/ahrs#DCM_.28floating_point.29|float_dcm]]''' || AHRS_DCM_MAG_ID
|-
|'''[[Subsystem/ahrs#Complementary_Euler_.28fixed_point.29|int_cmpl_euler]]''' || AHRS_ICE_MAG_ID
|-
|'''[[Subsystem/ahrs#Kalman_Filter_Quaternion|float_mlkf]]''' || AHRS_MLKF_MAG_ID
|}

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