Aux Mag Setup and Calibration

Important General Information.  Please read it carefully at least once.
- The only aux mag available in LP 15.09 is the OpenPilot GPSv9 (GpsPlatinum).  Two new forms of aux mag support are scheduled to be included in release 16.09 and are available in the Release Candidates.  These are DJI/Naza GPS support (including the embedded mag) and APM/PixHawk style aux mag support (also known as I2C aux mag support).
- You are here because you want to use the mag that is built into your GPS/mag.  There are some rather technical details to be discussed.
- MainPort does not do I2C, so (on Revo and Nano) you must use FlexiPort for I2C Aux Mag.  Sparky2 can use either FlexiPort or I2CPort.  The DJI/Naza GPS will run on MainPort or FlexiPort on Revo, Nano, or Sparky2.
- Perhaps because of differences in signal level or pull-up resistors, some I2C aux mag units will not work well on Sparky2 I2CPort.  Try using FlexiPort and see if that works.
- This document sometimes mentions making changes to AuxMagSettings and describes making these changes manually, on the System page.  There is now a GUI (GCS Configuration -> Attitude -> Magnetometer) for making and testing these changes.  You should use the GUI instead of making the changes manually.
- Be aware that mag is 3D and that (above the equator) the north magnetic direction is also pointing downward steeply; more than 60 degrees down in continental USA.  Mag is used for more than just compass direction.  For instance, it helps with direction of down (imagine for instance a zero G fall where accels don't know where down is).  INS13 gets very confused if the mag says that down is one direction and the accels (at rest) say it is in another direction.  Because of this, you will get crazy looking attitude in your GCS display if the GPS/mag and FC are not firmly mounted to the frame and the angle between GPS/mag and level hover in attitude mode (FC mounting plus "rotate virtual" setting) is not set correctly in AuxMagSettings -> BoardRotation.  Note that this also means how the mag chip is mounted on the GPS/mag board, so it can be different for different brands of GPS/mag.
- Default AuxMagSettings -> BoardRotation of 0,0,0 was chosen to make OP GPSV9 work correctly with default settings on a vehicle where frame is level in hover, and both FC and GPS are mounted level to frame and pointing forward, and that does not have tilted motors.  0,0,0 also works with the DJI/Naza GPS/mag.  If you have the APM/PixHawk style mag (with vehicle setup just described) you will probably have to set this to Pitch=180 (details later).  Be aware that if you adjust "Rotate Virtual" -> Roll/Pitch (to get level hover in Attitude mode), you will also need to change AuxMagSettings -> BoardRotation -> Roll/Pitch by the same amount but opposite sign.  The phrase "change by this amount" is important.  Do not just set it to that value.  Add/subtract with whatever value may already be there for other reasons.
- "Plug in flight battery" means plug the battery into a correctly wired system.  That will give 5 volt power to the flight controller.  Never connect a flight battery directly to the flight controller.  It must go through a BEC (typically inside the ESC) to reduce the voltage to 5 volts.
- If you have an APM/PixHawk Aux Mag, you should always boot by plugging in the flight battery with USB initially disconnected.  If you want USB, plug it in after the flight battery.  Without that, the mag is not powered and I2C init to mag fails and even adding power later does not fix it (you must power off and boot with flight battery (without USB power) to fix it).
- If flight battery is already attached, you can also boot by using GCS -> Firmware -> Reset, but if you have problems, unplug USB and boot by plugging in flight battery before reporting problems.
- Pick a port to use: FlexiPort or I2CPort
- - I2CPort is only available on Sparky2
- If you have an aux mag, it is important that every time you change "rotate virtual" you also change AuxMagSettings -> BoardRotation by the same amount but in the opposite direction.
- Arithmetic refresher: Decreasing a -5 by one results in -6 which is even more negative.  :)
- General reminder: Never adjust your transmitter trims.  Set them to neutral before doing transmitter wizard and never touch them.
- This document assumes you are using INS13 for your "Attitude Estimation Algorithm" (GCS Configuration -> Attitude -> Settings).

Getting your APM / PixHawk (I2C) Aux Mag working
- Make sure the AuxMag connector is disconnected from your flight controller board
- - Sparky2 will lock up on boot if something is plugged in the I2C port, but it is not powered
- - - Ports (MainPort, FlexiPort, I2CPort) don't have power unless a battery is plugged in
- - - Remember this the next time Sparky2 won't boot with just USB for power (you can unplug the Sparky2 I2CPort Aux Mag to get it to boot)
- In the Configuration -> Hardware page, set FlexiPort/I2CPort to I2C and Save
- The following 5 lines tells how to make manual changes to AuxMagSettings.  It is recommended that you use the GUI as discussed previously.
- In the System -> Settings page set AuxMagSettings.Type to Flexi/I2C (depending on which port it is plugged in) and AuxMagSettings.Usage to AuxOnly
- Click on "AuxMagSettings" and it will turn blue (if not blue already).
- - clicking the "outer object" instead of the "inner field" will operate on all the fields you modified.
- Press the red up arrow (Save) at the top of the screen.  This will save these values permanently.
- - some objects/fields are active immediately on Save, and some require a reboot.
- Power off the flight controller board
- Connect AuxMag connector to FlexiPort/I2CPort (the port you just configured it to use)
- Make sure the Aux Mag actually has power connected.  That usually means that your flight battery must be plugged in and the GPS connector must be plugged into the FC also.  Usually, both the GPS (4 wires) and mag (2 wires) get power through the GPS connector, but on some GPS's the mag has separate power that must have 3.3V going to the mag connector.  In this case the mag will usually also have 4 wires.
- Power on

Viewing AuxMagSensor to check if your mag is working
- Look at System Health
- - red/yellow/orange/green all mean "functioning at some level" for GPS and MAG.  Black or "red X" are bad.
- - Sparky2 (I2C) mag health color seems broken right now.  It is black when the aux mag is actually working.
- - For Atti and Stab to be green when using INS13, GPS must get a fix, HomeLocation must be set, and MAG must be calibrated (and away from disturbance).
- - I2C and SENSOR must be green or something is wrong (did you boot with USB disconnected and then plug in flight battery?)
- After this you can see if it is working by looking in GCS -> System -> Data Objects -> AuxMagSensor to see some numbers moving.
- Default for these numbers is "report to GCS every 10 seconds".  Change that to 1 second for quicker viewing.
- To do that, click the eyeball at the top of System page, enable "Show MetaData".
- Expand "Data Objects -> AuxMagSensor -> MetaData"
- Change "Flight Telemetry Update Period" to 1000 (ms)
- Click on "Flight Telemetry Update Period" and it will turn blue (if not blue already).
- Press the green up arrow (Send) at the top of the screen.  This will send this value to the board and begin using it immediately, but it will not make it permanent.  You probably don't want 1000ms while flying with telemetry as it will add to the telemetry unnecessarily.  If you press the red up arrow (Save) at the top of the page, it will use it immediately and also make it permanent in your FC settings.  Beware that metadata is not stored in an exported uav file, so even importing settings will not change metadata.  You must change it by hand.  N.B. "Erase Settings" sets all metadata back to default.  To reset all metadata, export settings, erase settings, import settings.

Set and verify AuxMagSettings.BoardRotation
- Generally your BoardRotation will either be all zeros (GPSv9 / DJI) or it will be Pitch=180 (PixHawk I2C Aux Mag)
- Set GCS -> System -> Settings -> AuxMagSettings -> BoardRotation (based on your mag brand)
- - Look up (Google) "magnetic inclination" for your location.  For me in USA it is about 62 degrees down.  This is not used in the BoardRotation setting, but is used as part of the definition of "north" in this section, so north for me is north and 62 degrees down.
- - https://en.wikipedia.org/wiki/File:World_Magnetic_Inclination_2010.pdf
- - When making these changes, use the red up arrow (Save) at the top of the screen.  That will make it permanent, and also put it into effect immediately (no reboot required for changes to this setting).
- - Watch AuxMagSensor.  You will know that BoardRotation is correct if you point the nose of the GPS/mag north (and e.g. 62 down) and see a high positive number (+400) for X and flip the GPS/mag so tail is now pointing north and you see X has become a large negative number (-400).  These +-400 can easily be +100-800 or +600-300 for example.  If you are truly pointing the GPS/mag north, X will be the largest change and the change will make the number a lot more negative (about 800 more negative, taking it from about +400 to about -400).
- - Same for Right side pointing north and watching Y (flip to left side for negative Y).
- - Same for Bottom side pointing north and watching Z (flip to top side pointing north).
- - For APM/PixHawk I2C mag, you will probably have to make BoardRotation.Pitch=180 to get these numbers correct.
- - If your board needs some other set of rotations, you will have to figure it out.  Do this:  Only use multiples of +-90.   The way you figure it out is to start with which board rotation makes the Z change in the correct way and enter/save that, then it is just a matter of what Yaw you need to add to make X and Y work with the correct board face and in the correct direction.

Tilt motors / tilt FC mount / tilt (GPS/)mag mount
- Get AuxMagSettings.BoardRotation set correctly for your GPS/mag board when it is held in your hand, then use the following to add/subtract from those values.
- If you have the simple case of tilted motors, with FC and GPS mounted level to frame, you will have to adjust Configuration->Attitude->Settings->RotateVirtual->Pitch for level hover in Attitude mode.  This is just the negative of the motor tilt angle assuming that you tilt the motors forward for a racing quad.  You must determine and set that Pitch and then adjust (usually add the motor tilt angle) System->Settings->AuxMagSettings->BoardRotation->Pitch by the same amount (or the nearest integer).  So if you have 15 degree motor tilt for a racing quad and used auxmag pitch of 180 to get your mag sensor axes correct, then you need -15 for rotate virtual pitch and 195 for auxmag pitch.
- If you have tilt motors or tilt mounted FC you should generally follow this: Start with Complementary (Basic) Attitude -> Settings -> "Attitude Estimation Algorithm".  Standard Racer tilt motors with FC level and motors tilted forward (or a tilt mount FC with FC tilted backwards) will know their motor (FC) angle from vertical (level).  Put the negative of that into Attitude -> Settings -> "Rotate Virtual" -> Pitch.  CAREFULLY test fly it in Attitude mode and adjust "Rotate Virtual" for good hover.
- If you have some stranger setup, measure the angle between the average motor angle and the FC and use that for "Rotate Virtual" -> Pitch.  FC tilted back compared to motors needs negative Pitch.  Measure the angle between GPS/mag and average motor angle and adjust AuxMagSettings->BoardRotation->Pitch by that amount (or the nearest integer).  GPS/mag tilted back compared to motors needs negative Pitch.

Mag Calibration (GCS -> Configuration -> Attitude -> Magnetometer Calibration)
The following is good advice for onboard as well as aux mags.
- Prior to magnetometer calibration, the Home Location needs to be set, see the Setting Home location page.
- Mag calibration continuously gathers data; not just when you press "Save Position".  You must keep the board being calibrated away from the ground, away from metal (like automobiles), away from power lines, etc the whole time you are calibrating.  You should pick a magnetically clean area for calibration, even if you will be flying in a less clean area.
- You can press "Save Position" 5 times and then do all your calibration positions (with say a 3 second pause at each position) and then press the final "Save Position"
- Do the calibration with the FC and mags mounted in the vehicle in a fully operational configuration, battery installed and plugged in, etc.
- Mag calibration is best done via permanently installed telemetry.  It appears that even a USB plug plugged into the FC will influence onboard mag calibration.  This might be reduced by using power from your flight battery.  This is certainly less an issue with an aux mag mounted on a pole (as long as you keep the USB cable away from the aux mag).
- Do the calibration
- After calibration verify (GCS -> Flight Data -> System Health gadget) that your mag health is green most of the time and in most orientations.  Never red.

Fine Tuning Your Hover To Stop Drift (Not Required)
Do not do this if your version is higher than 16.09.  Current "next" and the versions following 16.09 effectively use a "heading only" / 2D mag to make mag setup easier.
When using Basic (Attitude Estimation Algorithm) only the accels are used to know where "down" is.  When using INS13, the mags are used as an additional source of direction to know where "down" is.  The Earth's magnetic field is modeled approximately in the flight firmware and can't be known exactly without measuring it locally.  These two facts taken together mean that if your hover is perfectly level in Basic, that it probably won't be perfectly level in INS13.  This procedure will get it level in both.  First you adjust the accels while flying with Basic so Basic hovers without drift, then you adjust only the mags while flying with INS13 so INS13 hovers without drift and because you didn't change the accels, Basic still hovers without drift.
Tip: Once you have run the transmitter wizard to set up your transmitter, never adjust your transmitter trims.  Do this instead.
These numbers are changes to the hover angle, in degrees.
- Hover using Basic and Attitude mode.
- If the quad drifts forward, decrease Configuration->Attitude->Settings->RotateVirtual -> Pitch
- If the quad drifts left, decrease Configuration->Attitude->Settings->RotateVirtual -> Roll
- Repeat until it is correct
- Hover using INS13 and Attitude mode.
- Remember that you can use the GCS GUI (Configuration->Attitude->Magnetometer->BoardRotation) for the following changes to AuxMagSettings
- If the quad drifts forward, increase decrease System->Settings->AuxMagSettings->BoardRotation -> Pitch
- If the quad drifts left, increase decrease System->Settings->AuxMagSettings->BoardRotation -> Roll
- Repeat until it is correct, but be aware that needing more than a 5 degree change from default (defaults usually being 0,0,0 or 0,180,0 or 180,0,180) should be avoided because it is probably a sign that something else wrong.

Mag calibration positions
Horizontally,    Nose pointing north
Nose down,       Right side west
Right side down, Nose west
Upside down,     Nose east
Nose up,         Left side north
Left side down,  Nose south

Final Thoughts
If you have problems like lockup at boot time or bad colors in System Health, first make sure there are no bent pins in your board connectors, then make sure that your connectors are plugged in and seated fully, and especially that you have it configured correctly.  Configuration -> Hardware page must have the port where auxmag is connected (Flexi or I2C) set to I2C, AuxMagSettings.Type must be set to that port type (Flexi or I2C), and the mag must be powered (typical mag gets power from GPS connection) and plugged in the correct port.


OP FlexiPort pinout (Serial is the same on MainPort)
Color   JST-SH pin      Voltage         Serial   I2C      DSM      SRXL
Black   1               GND             GND      GND      GND      GND
Red     2               4,3V - 6V       VccUnreg VccUnreg VccUnreg VccUnreg
Blue    3               3,3V            TX       SCL
Orange  4               3,3V(5V tol)    RX       SDA      TX(sig)  Tx(sig)