GPS--and-Compass-setup.md

   1 INAV supports Ublox, DJI NAZA, and NMEA. NMEA is not recommended for navigation, due to its slower update rate.
   2
   3 Recommended GPS are M8N or later models.
   4
   5 Modules known to work reasonably well:
   6 * [Beitian BN-880](https://inavflight.com/shop/p/BN880)
   7 * [Ublox NEO-M8N APM version](https://inavflight.com/shop/s/bg/1035454)
   8
   9 Older versions as M6N and M7N also work, but the newer M8N (and later, M9N, M10N) are far superior.
  10 Most GPS modules have a built in magnetometer (compass), but there are also some available without e.g. [Beitian BN-180](https://inavflight.com/shop/p/BN180) or [Beitian BN-220](https://inavflight.com/shop/p/BN220) which are perfect for planes and flying wings.
  11
  12 With default settings INAV will configure the GPS automatically, **there is no need for configuring it manually** using software like `u-center`. Nevertheless you have to configure your FC with INAV to receive the GPS signals.
  13
  14 For INAV before 1.9, it is also necessary to perform some [manual configuration of UBLOX 3.01 firmware GPS](https://github.com/iNavFlight/inav/wiki/Ublox-3.01-firmware-and-Galileo) to use Galileo satellites.
  15
  16 With INAV 1.9 and later, Galileo can be enabled with the CLI setting `set gps_ublox_use_galileo = ON` (the default is off).
  17
  18 If you want to use the external magnetometer (built in in your GPS) and you have a FC with the same magnetometer (HMC5883L is very common), you have to disable it physically on your FC: remove chip from board or cut a trace. You can't use two identical chips/magnetometers on the same I2C bus.
  19   * When using DJI NAZA gps this is not the case, DJI NAZA sends compass over serial and does not use the I2C bus)
  20   * On MPU9250 board internal magnetometer is an AK8963, most GPS pucks are HMC5883L. So no need to remove hardware, only choose which one to use with cli command `mag_hardware`
  21
  22 If  you elect to use the internal FC magnetometer you are highly likely to have poor results due to magnetic interference (not recommended).
  23
  24 ## Installing the GPS unit
  25
  26 Just to avoid the mistake many people do while installing a GPS unit (aka pointing the antenna towards the ground): _(thanks to Phil-MC for the images)_
  27
  28 This side has to point towards the sky
  29
  30 ![TOP_bn-880](https://user-images.githubusercontent.com/65187658/129952395-29948465-76ec-48ac-a1b7-7e1c1e539f07.jpg)
  31
  32 This side has to point towards the ground
  33
  34 ![BOTTOM_bn-880](https://user-images.githubusercontent.com/65187658/129951933-6df4d873-b50a-4fe7-b12f-f4041402a4a9.jpg)
  35
  36
  37 ## Setting up the compass alignment
  38
  39 Before attempting any navigation modes, you should verify that the compass alignment is correct (Configurator or CLI `set align_mag`)
  40 * Perform any tests away of sources of magnetic interference. Domestic appliances or even audio speakers can cause erroneous affects.
  41 * Use an analogue compass in preference to a digital (mobile phone) compass. The compass in your phone is likely to be a similar chip to that on your aircraft, and is as susceptible to errors of interference and calibration
  42 * Alternatively, if you know the orientation of surrounding landmarks (e.g. my house is pretty much N/S), then you can do  static tests against land orientation.
  43
  44 Check your machine at cardinal points (North (0°), East (90°), South (180°), West (270°)). Degree perfect alignment is not necessary (and probably not measurable), but you should aim for +/- 5° of known magnetic direction.
  45
  46 * If the values are incorrect by a multiple of 90°, then the numeric alignment needs to be changed
  47 * If the values are just randomly wrong across the cardinal points, then FLIP is probably wrong (as well).
  48
  49 * If external Compass module is mounted at 30 degree.
  50 For example at top of a Cam mount,
  51 free alignment is possible by Cli commands.
  52 Cli setting Align_mag must be set to
  53  `Align_mag = default`
  54  `save`
  55
  56 For example cw270flip, this value is to ADD manualy.
  57 For free Alignment, all three axis need to set manualy.
  58 A sensor flip is always to realise
  59 over the pitch axis.
  60 For example cw270flip:
  61
  62     set align_mag_pitch = 1800
  63     set align_mag_roll = 0
  64     set align_mag_yaw = 2700
  65     save
  66
  67 * For 30 Degree Backwards tilted GPS/Compass Module, reduce align_mag_roll about 300
  68
  69     set align_mag_roll = -300
  70     save
  71
  72 * Because Magnetometer with cw270° has its roll axis in relation to the Pitch Axis of the FC
  73
  74 Enhanced Explanation in #6232
  75 [How to Align and Check if your readings are Correct ](https://github.com/iNavFlight/inav/issues/6232#issuecomment-727636397)
  76
  77 Painless360 done a superior Video on this
  78 [Setup non Flat mounted External Compass. (Tilted) ](https://youtu.be/tjKPD69Lrgg)
  79
  80 There is an online (web based) software tool to help with alignment [Alignment Tool](https://kernel-machine.github.io/INavMagAlignHelper/); this tool is built into the INAV configurator for INAV 5.0 and later.
  81
  82 ## Initial flight tests
  83
  84 Once  you're content that the static configuration of the compass is correct, it's time to go flying. There is still no guarantee that the machine will not generate interference, so it's advisable to do some controlled testing before attempting more advanced navigation modes:
  85
  86 * In a clear space (no trees!) attempt a simple line of sight POSHOLD. If the craft fails to hold (toilet bowling, or ever increasing circles (in range and speed)), be prepared to disengage PH and take manual control.
  87
  88 To confirm magnetic interference, blackbox logging is most useful:
  89
  90 * Fly at a reasonable speed (> 5m/s) in straight lines, as close as possible to a 90° crossing paths, or a square / rectangular pattern.
  91
  92 * The blackbox can be analysed to compare the course over the ground (from GPS) with the compass readings (`GPS_ground_course` v. `attitude[2]/10`). Run `blackbox_decode` with the `--merge-gps` option to get GPS fields in the log.
  93
  94 * If you need help doing this, post the log in the INAV RC Groups forum (or Discord / Telegram channel) and ask for help. There are a number of users familiar with this type of analysis who can assist.
  95
  96 * It is necessary to fly at a reasonable speed in order to get useful GPS data. Just hovering is not useful as the GPS cannot detect direction without movement.
  97
  98 * If you use mwp as a ground station with telemetry, then mwp logs can also provide useful analysis, but blackbox is preferred, as there is more data and it is also possible to analyse throttle affects.
  99
 100 Only when you're content that the compass reads correctly for all throttle settings and directions should you progress to more advanced navigation feature (way points, return to home). The majority of navigation failures are due to poorly performing compasses.
 101
 102 ## Getting started with Ublox GPS
 103 - Physically connect your GPS to your FC using UART (preferred) or softserial (not recommended). Connect RX from GPS to TX on FC, TX from GPS to RX on FC
 104 - Activate GPS in the ports tab in INAV configurator and set it to 57600 or 115200 using UART or 19200 using softserial (on your chosen port)
 105 - Activate GPS in the configuration tab, set it to ublox.
 106
 107 - Using external compass:
 108  * Connect the magnetometer to I2C ports (SCL/SDA) Be aware that with SDA/SLC lines connected the flight battery must often be connected to access configurator and power up the magnetometer.
 109  * Select your newly connected magnetometer by using `mag_hardware` CLI command. Example `set mag_hardware = auto` if you only have one magnetometer connected.
 110  * Most built in magnetometers are on the underside and rotated 180 degrees, use example `set align_mag = CW180FLIP`. If compass is not working properly in all directions then either think and figure out the direction of your mag, or go through them all until it works as expected.
 111  * F3 based board and newer uses default automatic magnetic declination, if your on F1 board or want to change magnetic declination manually you have to set correct declination of your spesific location, which can be found here: www.magnetic-declination.com. If your magnetic declination readings are e.g. +3° 34' , the value entered in the INAV configurator is 3.34 (3,34 in some locales). In the CLI, the same effect would be `set mag_declination = 334`. For west declination, use a minus value, e.g. for 1° 32' W, `set mag_declination = -132`. In all cases (both CLI and GUI), the least significant digits are **minutes**, not decimal degrees.
 112  * Calibrate your compass according to [compass calibration](https://github.com/iNavFlight/inav/wiki/Sensor-calibration#compass-calibration)
 113
 114
 115 Note to change magnetic declination manually on F3 or later board you have to turn off automatic function. `set inav_auto_mag_decl = OFF`.
 116
 117 ## NEO-M8N PixHawk GPS Unit / BN-880
 118
 119 A readily available GPS unit is the "NEO-M8N" unit that is available from eBay, Amazon, Banggood & so on...
 120
 121 They are cheap and use multiple satellite networks in addition to GPS (GLONASS, Galileo) so obtaining a GPS fix is quicker and you can be flying around with anywhere between 15 to 30 satellites.
 122
 123 Also as a bonus with such units they have a magnetometer (a compass) on the underside of the board too!
 124
 125 <img src="https://img2.banggood.com/thumb/large/upload/2015/09/SKU287158/SKU287158-1.jpg">
 126
 127 ![BN-880_arrow](https://user-images.githubusercontent.com/65187658/130331246-c5d3bc55-be7a-4481-b202-a51ff40d57eb.jpg)
 128
 129 An important note is that on top of the protective shell of the MN-M8N there is an arrow, this needs to point towards the front of your model. The BN-880 plug needs to point down and to the rear of your model. It is also recommended to [encase](https://www.thingiverse.com/search?q=bn-880&dwh=665c615230c1cbf) the BN-880 as it is quite fragile.
 130
 131 **Important**:
 132 You need to switch the Rx and Tx wires around. So you connect your GPS Tx wire (yellow) to your desired Rx pin and the GPS Rx wire (White) to your Tx pin on your flight controller.
 133
 134 A video showing you how to do this for a Omnibus F4 V2 board is in [this video on YouTube](https://www.youtube.com/watch?v=nQCQXuqQSd8)
 135
 136 Other boards (e.g. MATEK) may not power 5V when on USB. In order to power the GPS it is necessary to connect the battery or use another power source (a 4.5V source may be powered by USB). The onboard 3.3V will be powered by USB, but may not provide adequate voltage, as the GPS regulator typically requires 3.6V minimum.
 137
 138 Once you have connected the GPS to your flight control board
 139
 140 - Open the INAV Configurator
 141 - Enable GPS on your desired UART port
 142 - Set the the baud rate to 115200
 143 - Press "Save & Reboot"
 144 - Then go to the "Configuration" tab in the INAV Configurator
 145 - Enable GPS
 146 - Set the "Protocol" to UBLOX7
 147 - Set the "Ground Assistance Type" to "Auto Detect"
 148 - set MAG Alignment to CW270FLIP
 149 - Press "Set & Reboot"
 150  You can confirm the GPS unit is working by going to the GPS tab in the INAV Configurator and if it is working you will see the "Total Messages" count on the left incrementing in numbers.
 151
 152 If it is the first time you have connected the GPS unit, then it can take several minutes for a GPS fix to be obtained. This is perfectly normal.
 153
 154 **Note:** For the GPS unit to work & pick up satellites it needs an unobstructed view to the sky (so if using indoors, don't expect any satellites to be picked up!)
 155
 156
 157 ## Getting started with DJI NAZA GPS
 158
 159 - Physically connect your GPS to your FC using UART. Connect RX from GPS to TX on FC, TX from GPS to RX on FC
 160 - Activate GPS in the ports tab in INAV configurator and set it to 115 200 on correct UART
 161 - Type this in CLI
 162
 163    feature GPS
 164    set gps_provider = NAZA
 165    set mag_hardware = GPSMAG
 166    set align_mag = CW180FLIP
 167
 168 Default DJI GPS puck pointing forward is set with CW180FLIP, but can be changed with CW0FLIP, CW90FLIP, CW180FLIP or CW270FLIP
 169
 170  * Inav since 1.5 version and newer uses default automatic magnetic declination, if your on old verion or want to change magnetic declination manually you have to set correct declination of your spesific location, which can be found here: www.magnetic-declination.com. If your magnetic declination readings are e.g. +3° 34' , the value entered in the INAV configurator is 3.34 (3,34 in some locales). In the CLI, the same effect would be `set mag_declination = 334`. For west declination, use a minus value, e.g. for 1° 32' W, `set mag_declination = -132`. In all cases (both CLI and GUI), the least significant digits are **minutes**, not decimal degrees.
 171  * Calibrate your compass according to [compass calibration](https://github.com/iNavFlight/inav/wiki/Sensor-calibration#compass-calibration)
 172
 173 Note to change magnetic declination manually on F3 or newer board you have to turn off automatic function. `set inav_auto_mag_decl = OFF`.
 174
 175
 176 Thats it!
 177
 178
 179 ## SBAS
 180
 181 When using a UBLOX GPS the SBAS mode can be configured using `gps_sbas_mode`.
 182
 183 The default is AUTO.
 184
 185 | Value    | Region        |
 186 | -------- | ------------- |
 187 | AUTO     | Global        |
 188 | EGNOS    | Europe        |
 189 | WAAS     | North America |
 190 | MSAS     | Asia          |
 191 | GAGAN    | India         |
 192 | NONE     | NONE         |
 193
 194 If you use a regional specific setting you may achieve a faster GPS lock than using AUTO, but keep in mind to change it if you change your location for holidays etc.
 195
 196 This setting only works when `gps_auto_config= ON`
 197
 198
 199 ## Issues
 200 - **`X!`** in the OSD `GPS Satellites` field indicates the flight controller isn't receiving a valid data signal from the GPS.
 201 - No GPS lock: often due to electric noise from flight controller or other equipment such as 1.2ghz video TX. Try getting the GPS as far away as possible from electric noise emitting parts as the FC, ESCs or power cables. Placing the GPS on a mast is also a common way, you can further try shielding with aluminum or copper foil. Don´t place the GPS inside the frame.
 202 - "Toilet bowling": in the beginning the copter holds its position and then starts to make bigger and bigger circles, you probably have your magnetometer not calibrated correctly or it’s interfered from the magnetic field of your power lines or the beeper.
 203 If you are using your FC onboard mag, try to place the the FC as far away as possible from the magnetic interference causing parts e.g. mounting it on/under the top plate on small racers.
 204 - 3.3V GPS units, such as the GPS from 3DR should not be powered by the flight controller's 3.3V pin along with a Spektrum (or other DSM) receiver. The current draw can cause the Spektrum receiver to brownout. Instead use a 3.3V regulator and power the GPS from the BEC or separate battery.