gpsd/www/ubxtool-examples.adoc

:Author: Gary E. Miller
:Email: <gem@rellim.com>
:Date: 11 June 2020
:Description: U-blox GNSS receiver configuration examples
:keywords: u-blox, examples, configuration

= ubxtool recipes

WARNING: This document assumes you are using gpsd version 3.20 or higher.  Not
all u-blox 9 examples work in version 3.20.  Using older gpsd versions
will fail in strange ways.

== Introduction

The u-blox GNSS receivers have a huge number of configuration options.
Most users will be perfectly happy running their receiver in its default
configuration, but there are often times when users get the itch to
change settings to see what happens.  Sometimes even for good reasons.

IMPORTANT: Feel free to jump around this document to recipes that
interest you, but be sure to first read all of, and comply with, the
section on Initial Setup.

Many of the recipes repeat text from other recipes so that recipes can
stand alone.  Except all recipes require the Initial Setup section.

== Initial Setup

All the examples here assume that gpsd is running on the local host and
that cgps is showing current and valid data from the receiver.

If cgps is not showing any data, then do not bother to continue reading
this document.

You also need a copy of the "Interface Description" for your exact
u-blox device.  The examples here will refer to a lot of messages and
variables that are defined in that document.  Keep it open while reading
this document and refer to it often.

=== Protocol Version

All the examples below require that you know the protocol version of
your u-blox receiver.

----
$ ubxtool -p MON-VER
----

Buried in the data will be a data block that similar one of these
examples.

A u-blox 6, assume protocol version 12

----
UBX-MON-VER:
  swVersion 6.02 (36023)
  hwVersion 00040007
----

A u-blox 8, protocol version 15

----
UBX-MON-VER:
  swVersion 2.01 (75331)
  hwVersion 00080000
  extension PROTVER 15.00
  extension GPS;SBAS;GLO;BDS;QZSS
----

The shortcut to find the PROTVER for u-blox 8 and up:

----
$ ubxtool -p MON-VER | fgrep PROT
extension PROTVER=18.00
----

The above shows the protocol version is 18.00.

The ubxtool program needs to know the protocol version (PROTVER) of
the connected receiver to send commands matched to your exact receiver's
needs.  Use the "-P XX" option for this, where XX is your version.  This
is easy to forget, and annoying to type repeatedly, so add it to your
environment and ubxtool will use it.  For example if you have an early
u-blox 8:

----
$ export UBXOPTS="-P 15"
----

You can add "-v 2" for a little more verbosity.

----
$ export UBXOPTS="-P 18 -v 2"
----


=== Default Configuration

A common problem when dealing with a u-blox GNSS receiver is left over
configuration from earlier experiments.  The u-blox receivers are very
picky about competing configuration options, and may fail to warn the
unwary of conflicts.  Best to always revert to factory defaults before
starting a new configuration.

----
$ ubxtool -p RESET
----

After a few seconds the receiver will only be sending NMEA, you will
want to enable u-blox binary messages, and disable NMEA messages.  Best
to do it in that order so the receiver does not go totally silent.  This
is one place where the "-P", set in UBXOPTS, is critically important, to
get the correct messages for your firmware.

----
$ ubxtool -e BINARY
$ ubxtool -d NMEA
----

== Dynamic Platform Model

The most common variable mis-configured in a u-blox receiver is the
Dynamic Platform Model.  The receiver uses noisy measurements of
satellite signals and attempts to interpret those as single PVT fix.
By default the receiver assumes the receiver is "Portable" and not
experiencing large accelerations.  Place that receiver in a car or
airplane, and the smoothing will act perversely on the fix.  Take a
moment now to read the section on Platform Settings in your u-blox
documentation.  Different receivers support different models, so no
generic recommendations are possible.

Check your current Dynamic Platform Model:

----
$ ubxtool -p CFG-NAV5
UBX-CFG-NAV5:
 mask 0xffff dynModel 0 fixmode 3 fixedAlt 0 FixedAltVar 10000
 minElev 5 drLimit 0 pDop 250 tDop 250 pAcc 100 tAcc 350
 staticHoldThresh 0 dgpsTimeOut 60 cnoThreshNumSVs 0
 cnoThresh 0 res 0 staticHoldMaxDist 0 utcStandard 0
 reserved x0 0
   dynModel (Portable) fixMode (Auto 2D/3D) utcStandard (Default)
   mask (dyn minEl posFixMode drLim posMask timeMask staticHoldMask
         dgpsMask cnoThreshold utc)
----

That shows the receiver is in the default Portable model.

To change the active model to Automotive (4), and check it again,
is simply:

----
$ ubxtool -p MODEL,4
[...]
$ ubxtool -p CFG-NAV5
UBX-CFG-NAV5:
 mask 0xffff dynModel 4 fixmode 3 fixedAlt 0 FixedAltVar 10000
 minElev 5 drLimit 0 pDop 250 tDop 250 pAcc 100 tAcc 350
 staticHoldThresh 0 dgpsTimeOut 60 cnoThreshNumSVs 0
 cnoThresh 0 res 0 staticHoldMaxDist 0 utcStandard 0
 reserved x0 0
   dynModel (Automotive) fixMode (Auto 2D/3D) utcStandard (Default)
   mask (dyn minEl posFixMode drLim posMask timeMask staticHoldMask
         dgpsMask cnoThreshold utc)
----


=== Changing Dynamic Platform Model with Configuration Items

If the receiver is a 9-series one then you can change the model using
Configuration Items.  These allow you to get, set and delete individual
settings in the receiver. before continuing this section, read the
ubxtool man page on Configuration Items.

The CFG-NAVSPG Configuration Item group includes the CFG-NAV5 items
of interest here.  So take a look at them, in the ram layer:

----
# ubxtool -g CFG-NAVSPG,0
[...]
UBX-CFG-VALGET:
 version 1 layer 0 position 0
  layers (ram)
    item CFG-NAVSPG-18/0x10110012 val 0
    item CFG-NAVSPG-INIFIX3D/0x10110013 val 0
    item CFG-NAVSPG-20/0x10110014 val 1
    item CFG-NAVSPG-21/0x10110015 val 1
    item CFG-NAVSPG-22/0x10110016 val 1
    item CFG-NAVSPG-24/0x10110018 val 1
    item CFG-NAVSPG-USE_PPP/0x10110019 val 0
    item CFG-NAVSPG-27/0x1011001b val 0
    item CFG-NAVSPG-ACKAIDING/0x10110025 val 0
    item CFG-NAVSPG-70/0x10110046 val 1
    item CFG-NAVSPG-82/0x10110052 val 0
    item CFG-NAVSPG-83/0x10110053 val 0
    item CFG-NAVSPG-USE_USRDAT/0x10110061 val 0
    item CFG-NAVSPG-129/0x10110081 val 0
    item CFG-NAVSPG-130/0x10110082 val 0
    item CFG-NAVSPG-131/0x10110083 val 0
    item CFG-NAVSPG-FIXMODE/0x20110011 val 3
    item CFG-NAVSPG-26/0x2011001a val 18
    item CFG-NAVSPG-UTCSTANDARD/0x2011001c val 0
    item CFG-NAVSPG-32/0x20110020 val 100
    item CFG-NAVSPG-DYNMODEL/0x20110021 val 1
    item CFG-NAVSPG-34/0x20110022 val 0
    item CFG-NAVSPG-35/0x20110023 val 0
    item CFG-NAVSPG-36/0x20110024 val 1
    item CFG-NAVSPG-38/0x20110026 val 0
    item CFG-NAVSPG-66/0x20110042 val 2
    item CFG-NAVSPG-67/0x20110043 val 3
    item CFG-NAVSPG-68/0x20110044 val 1
    item CFG-NAVSPG-69/0x20110045 val 1
    item CFG-NAVSPG-81/0x20110051 val 0
    item CFG-NAVSPG-INFIL_MINSVS/0x201100a1 val 3
    item CFG-NAVSPG-INFIL_MAXSVS/0x201100a2 val 32
    item CFG-NAVSPG-INFIL_MINCNO/0x201100a3 val 6
    item CFG-NAVSPG-INFIL_MINELEV/0x201100a4 val 5
    item CFG-NAVSPG-INFIL_NCNOTHRS/0x201100aa val 0
    item CFG-NAVSPG-INFIL_CNOTHRS/0x201100ab val 0
    item CFG-NAVSPG-CONSTR_DGNSSTO/0x201100c4 val 60
    item CFG-NAVSPG-213/0x201100d5 val 0
    item CFG-NAVSPG-SIGATTCOMP/0x201100d6 val 0
    item CFG-NAVSPG-WKNROLLOVER/0x30110017 val 2029
    item CFG-NAVSPG-OUTFIL_PDOP/0x301100b1 val 250
    item CFG-NAVSPG-OUTFIL_TDOP/0x301100b2 val 250
    item CFG-NAVSPG-OUTFIL_PACC/0x301100b3 val 100
    item CFG-NAVSPG-OUTFIL_TACC/0x301100b4 val 350
    item CFG-NAVSPG-OUTFIL_FACC/0x301100b5 val 150
    item CFG-NAVSPG-USRDAT_DX/0x40110064 val 0.0
    item CFG-NAVSPG-USRDAT_DY/0x40110065 val 0.0
    item CFG-NAVSPG-USRDAT_DZ/0x40110066 val 0.0
    item CFG-NAVSPG-USRDAT_ROTX/0x40110067 val 0.0
    item CFG-NAVSPG-USRDAT_ROTY/0x40110068 val 0.0
    item CFG-NAVSPG-USRDAT_ROTZ/0x40110069 val 0.0
    item CFG-NAVSPG-USRDAT_SCALE/0x4011006a val 0.0
    item CFG-NAVSPG-CONSTR_ALT/0x401100c1 val 0
    item CFG-NAVSPG-CONSTR_ALTVAR/0x401100c2 val 10000
    item CFG-NAVSPG-209/0x401100d1 val 0
    item CFG-NAVSPG-210/0x401100d2 val 0
    item CFG-NAVSPG-211/0x401100d3 val 0
    item CFG-NAVSPG-USRDAT_MAJA/0x50110062 val 6378137.0
    item CFG-NAVSPG-USRDAT_FLAT/0x50110063 val 298.257223563
----

We can now use CFG-NAVSPG-DYNMODEL to change the model back to
Pedestrian, and then confirm the setting:

----
$ ubxtool -z CFG-NAVSPG-DYNMODEL,0
[...]
$ ubxtool -z CFG-NAVSPG-DYNMODEL,0
[...]
UBX-CFG-VALGET:
 version 1 layer 0 position 0
  layers (ram)
    item CFG-NAVSPG-DYNMODEL/0x20110021 val 0
----

== Rate Settings

There can be a good need to change the rate at which your receiver take
measurements, or how many measurements it uses to compute its navigation
solution (fix).  Slow down the measurement rate to save power.  Or speed
it up in fast moving dynamic environments.  Using several measurements
sets for each fix computation may remove some noise.  No one size
fits all.

NOTE: Not all u-blox can take measurements faster than 1 Hz.

The current configuration can be seen this way:

----
$ ubxtool -p CFG-RATE
[...]
UBX-CFG-RATE:
 measRate 1000 navRate 1 timeRef 1 (GPS)
----

To change to a 10 Hz measurement and fix rate, then check your work:

----
$ ubxtool -p RATE,100
[...]
$ ubxtool -p CFG-RATE
[...]
UBX-CFG-RATE:
 measRate 000 navRate 1 timeRef 1 (GPS)
----

=== Rate Settings with Configuration Items

If the receiver is a 9-series one then you can change the rate at which
the receiver takes measurements and/or computes the navigation solution
(fix) using Configuration Items.  These allow you to get, set and delete
individual settings in the receiver. before continuing this section,
read the ubxtool man page on Configuration Items.

The CFG-NAVSPG Configuration Item group includes the CFG-NAV5 items
of interest here.  So take a look at them, in the ram layer:

----
# ubxtool -g CFG-RATE,0
[...]
UBX-CFG-VALGET:
 version 1 layer 0 position 0
  layers (ram)
    item CFG-RATE-TIMEREF/0x20210003 val 1
    item CFG-RATE-MEAS/0x30210001 val 1000
    item CFG-RATE-NAV/0x30210002 val 1
----

You can change the measurement rate to 0.1 Hz, and check it, this way:

----
$ ubxtool -z CFG-RATE-MEAS,10000,1
sent:
UBX-CFG-VALSET:
 version 0 layer 0x1 transaction 0x0 reserved 0
  layers (ram) transaction (Transactionless)
    item CFG-RATE-MEAS/0x30210001 val 10000

UBX-ACK-ACK:
  ACK to Class x06 (CFG) ID x8a (VALSET)
[...]
$ ubxtool -g CFG-RATE-MEAS,1
[...]
UBX-CFG-VALGET:
 version 1 layer 0 position 0
  layers (ram)
    item CFG-RATE-MEAS/0x30210001 val 10000
----

== Logging

Sometimes you want your GNSS receiver to be able to log PVT fixes for
later retrieval.  This allows the host to go into sleep mode to save
power.  Logs are stored in external flash memory.  Some GNSS receivers,
like the NEO-M8B, allow the receiver to go into sleep mode between fixes
to save even more power.

Be sure you have performed all the steps in Initial Setup before
proceeding to the following logging specific steps.

=== Logging Prerequisites

For Logging, you need:

1. u-blox 7, 8 or 9 GNSS receiver (protocol version 15+)

2. External SQI flash memory with a valid Flash Information Structure (FIS).

By default EVK boards and other commercial products with flash will
already have a valid FIS.  Added or replaced flash will need to have
an FIS created.  If your receiver has flash, but no valid FIS, you can
create a new FIS with u-center.

If you do not meet the above prerequisites, then you can stop reading
this section now.

The easy way to see if your firmware supports logging is to ask it:

----
$ ubxtool -p LOG-INFO
----

There are three possible results.

One, the receiver does not return ACK-ACK, ACK-NAK, or any UBX-LOG-INFO
message.  That means your receiver does not support logging.  Game over,
your receiver does not support logging.

Two, the receiver returns something similar to this:

----
    UBX-LOG-INFO:
      version 1 reserved1 x0 x0 filestoreCapacity 0 reserved2 x0 x0
      currentMaxLogSize 0 currentLogSize 0 entryCount 0
      oldestYear 0 oldestMonth 0 oldestDay 0
      oldestHour 0 oldestMin 0 oldestSec 0 reserved3 x0
      newestYear 0 newestMonth 0 newestDay 0
      newestHour 0 newestMin 0 newestSec 0 reserved4 x0
      status x10 reserved5 x0 x0
----

The filestoreCapacity of zero means you have no flash for logging to
use.  Game over, your receiver does not support logging.

Three, the receiver returns something similar to this:

----
    UBX-LOG-INFO:
      version 1 reserved1 x0 x0 filestoreCapacity 487680 reserved2 x9600 x24900
      currentMaxLogSize 134400 currentLogSize 61 entryCount 0
      oldestYear 0 oldestMonth 0 oldestDay 0
      oldestHour 0 oldestMin 0 oldestSec 0 reserved3 x0
      newestYear 0 newestMonth 0 newestDay 0
      newestHour 0 newestMin 0 newestSec 0 reserved4 x0
      status x20 reserved5 x0 x0
----

That means your receiver has almost 500 kB of flash, and about 134 kB is
available for logging.  Congratulations, your receiver supports logging.
Proceed to the next section on configuration.

=== Logging Configuration

Be sure you have completed the instructions in the section
Initial Setup before continuing here.

Erase any exiting log:

----
$ ubxtool -p LOG-ERASE
[...]
sent:
UBX-LOG-ERASE:
  Erase Logged Data
UBX-ACK-ACK:
  ACK to Class x21 (LOG) ID x03 (ERASE)
----

Create new log:

----
$ ubxtool -p LOG-CREATE
[...]
sent:
UBX-LOG-CREATE:
  version 0 logCfg x1 reserved1 x0 logSize 0
  userDefinedSize 0

UBX-ACK-ACK:
  ACK to Class x21 (LOG) ID x07 (CREATE)
----

Start logging:

----
$ ubxtool -e LOG
[...]
sent:
UBX-CFG-LOGFILTER:
 version 1 flags x5 minInterval 0 timeThreshold 0
 speedThreshold 0 positionThreshold 0

UBX-ACK-ACK:
  ACK to Class x06 (CFG) ID x47 (LOGFILTER)
----

Wait, then verify that the receiver is logging data:

----
$ ubxtool -p LOG-INFO -v 2
UBX-LOG-INFO:
  version 1 reserved1 x0 x0 filestoreCapacity 487680 reserved2 x9600 x24900
  currentMaxLogSize 134400 currentLogSize 88 entryCount 8
  oldestYear 2020 oldestMonth 5 oldestDay 22
  oldestHour 22 oldestMin 33 oldestSec 56 reserved3 x0
  newestYear 2020 newestMonth 5 newestDay 22
  newestHour 22 newestMin 26 newestSec 41 reserved4 x0
  status x28 reserved5 x0 x0
      status (recording circular)
----

Add a string:

----
$ ubxtool -p LOG-STRING -v 2
[...]
UBX-ACK-ACK:
  ACK to Class x21 (LOG) ID x04 (STRING)
----

Wait for a few more fixes to be logged, then turn off logging.

----
$ ubxtool -d LOG -v 2
[...]
sent:
UBX-CFG-LOGFILTER:
 version 1 flags x0 minInterval 0 timeThreshold 0
 speedThreshold 0 positionThreshold 0
   flags ()

UBX-ACK-ACK:
  ACK to Class x06 (CFG) ID x47 (LOGFILTER)
----

Verify that logging is indeed off:

----
$ ubxtool -p LOG-INFO -v 2
[...]
UBX-LOG-INFO:
  version 1 reserved1 x0 x0 filestoreCapacity 487680 reserved2 x9600 x24900
  currentMaxLogSize 134400 currentLogSize 288 entryCount 33
  oldestYear 2020 oldestMonth 5 oldestDay 22
  oldestHour 22 oldestMin 33 oldestSec 56 reserved3 x0
  newestYear 2020 newestMonth 5 newestDay 22
  newestHour 22 newestMin 34 newestSec 11 reserved4 x0
  status x20 reserved5 x0 x0
      status (circular)
----

Retrieve log data:

----
$ ubxtool -p LOG-RETRIEVE -v 2
[...]
UBX-LOG-RETRIEVEPOS:
  entryIndex 12 lon -1213142510 lat 440688770 hMSL 1128900 hAcc 7000
  gSpeed 90 heading 28500000 version 0 fixType 3
  year 2020 month 5 day 22 hour 22 min 34 sec 2
  reserved1 x0 numSV 7 reserved2 x0
      fixType (3D Fix)

UBX-LOG-RETRIEVEPOSEXTRA:
  entryIndex 13 version 0 reserved1 x0
  year 2020 month 5 day 22 hour 22 minute 34 seconds 2
  reserved2 x0 0 distance 1252489 reserved3 x0 0 0

UBX-LOG-RETRIEVESTRING:
  entryIndex 14 version 0 reserved2 x0
  year 2020 month 5 day 22 hour 22 min 34 sec 2
  reserved2 x0 byteCount 2
  bytes "Hi"

UBX-LOG-RETRIEVEPOS:
  entryIndex 15 lon -1213142470 lat 440688690 hMSL 1128600 hAcc 7000
  gSpeed 240 heading 26300000 version 0 fixType 3
  year 2020 month 5 day 22 hour 22 min 34 sec 3
  reserved1 x0 numSV 8 reserved2 x0
      fixType (3D Fix)
[...]
----

Erase and clear existing log, before you can enable log again:

----
$ ubxtool -p LOG-ERASE
$ ubxtool -p LOG-CREATE
----

== Batching

U-blox batching is like logging, but logging is saved in flash memory,
and batching is saved in RAM memory.  Not all u-blox receivers have RAM
available for batching.

Be sure you have performed all the steps in Initial Setup before
proceeding to these batching specific steps.

=== Batching Prerequisites

For batching, you need:

1. u-blox 8 or 9 GNSS receiver (protocol version 23.01+)

2. RAM memory

If you do not meet the above prerequisites, then you can stop reading
now.

The easy way to see if your firmware supports batching is to ask it:

----
$ ubxtool -p MON-BATCH
----

If the receiver does not ACK, or NAK, that request, then it does not
support batching.  Game over, do not bother to continue with this
example.

If your receiver does support batching, you will see something
similar to this:

----
$ ubxtool -p MON-BATCH
ubxtool: poll MON-BATCH

sent:
UBX-MON-BATCH:
  Poll request

UBX-MON-BATCH:
   version 0 reserved1 0 0 0 fillLevel 128
   dropsAll 65535 dropsSinceMon 4 nextMsgCnt 166
----

Check your u-blox documentation for what UBX-MON-BATCH just told you.

=== Batching Configuration

Be sure you have completed the instructions in the section
Initial Setup before continuing here.

Enable batching:

----
$ ubxtool -e BATCH
----

Wait, then verify:

----
$ ubxtool -p CFG-BATCH -p MON-BATCH -v 2
[...]
UBX-CFG-BATCH:
  version 0 flags xd bufsize 128 notifThrs 0
  pioId 0 reserved1 0
      flags (enable extraPvt extraOdo)

UBX-ACK-ACK:
  ACK to Class x06 (CFG) ID x93 (BATCH)

UBX-MON-BATCH:
   version 0 reserved1 0 0 0 fillLevel 128
   dropsAll 321 dropsSinceMon 15 nextMsgCnt 38
[...]
----

Wait a while, for some fixes to be saved in the BATCH.  Then check
UBX-MON-BATCH and get all the batch entries:

----
$ ubxtool -p LOG-RETRIEVEBATCH -v 2
[...]
UBX-MON-BATCH:
   version 0 reserved1 0 0 0 fillLevel 128
   dropsAll 65535 dropsSinceMon 1310 nextMsgCnt 166

UBX-LOG-BATCH:
  version 0 contentValid x3 msgCnt 166 iTow 510334000
  year 2020 month 5 day 22 hour 21 min 45 sec 16 valid x37
  tAcc 30 fracSec 104291 fixType 3 flags x11 flags2 xa numSV 5
  lon -1213142428 lat 440690573 height 1130139 hMSL 1151489
  hAcc 9541 vAcc 11092
  vel N 288 E 111 D -29 gSpeed 274 headMot 2104222 sAcc 786 headAcc 4232547
  pdep 432 reserved1 x0 distance 1249842 totalDistance 1249842
  distanceStd 4880 reserved2 x0
      contentValid (extraPvt extraOdo) valid (validDate validTime)
      fixType (3D Fix)
      flags (gnssFixOK) psmState (Power Optimized Tracking)
----

There will be a number of UBX-LOG-BATCH with each of the individual
batches fixes.

End batching:

----
$ ubxtool -d BATCH
----

== Survey-In and RTCM

Sometimes your GNSS antenna is fixed and instead of having your receiver
compute its position, you want it to use the known position to provide a
more accurate PPS.  Or to compute the errors it sees in the signals it
measures.  Then transmit those corrections to a nearby receiver.

The receiver with the fixed antenna is called the base, and the nearby
receiver is a rover.  The corrections are usually in one of the many
RTCM2 or RTCM3 variants.

Some u-blox receivers with protocol versions of 20 or greater output
RTCM3 corrections.  None output RTCM2 corrections.

Be sure you have completed the instructions in the section Initial Setup
before continuing here.  To understand the following example you should
have read the Survey-in section from the u-blox documentation for your
receiver.

=== Survey-In and RTCM Prerequisites

For base mode, you need a u-blox receiver that supports UBX-CFG-TMODE2
or UBX-CFG-TMODE3. This is usually limited to Time & Frequency Sync, Time
Sync, or High Precision products.

Your receiver supports the High Precision messages if it answers the
UBX-NAV-SVIN message:

----
$ ubxtool -p NAV-SVIN -P 27.11
ubxtool: poll NAV-SVIN

sent:
UBX-NAV-SVIN:
  Poll request

[...]
UBX-NAV-SVIN:
  version 0 reserved1[0 0 0] iTOW 256297000 dur 100
  meanX -238605675 meanY -392219737 meanZ 441436428
  meanXHP -30 meanYHP 9 meanZHP -14 reserved2 0 meanAcc 199922
  obs 101 valid 1 active 0
----

Your receiver supports the Timing messages if it answers the
UBX-TIM-SVIN message:

----
# ubxtool -p TIM-SVIN -P 22
ubxtool: poll TIM-SVIN

sent:
UBX-TIM-SVIN:
  Poll request
[...]
UBX-TIM-SVIN:
  dur 30 meanX -238607642 meanY -392219170 meanZ 441436506 meanV 163464256
  obs 31 valid 0 active 0
----

If your receiver responds to neither request, then you can use Survey-in.

=== Survey-In Configuration

If your receiver responded to UBX-NAV-SVIN, then you start the default
survey this way:

----
# ubxtool -e SURVEYIN3 -P 27
ubxtool: enable SURVEYIN3

sent:
UBX-CFG-TMODE3:
  version 0 reserved1 0 flags x1
  ecefXOrLat 0 ecefYOrLon 0 ecefZOrAlt 0
  ecefXOrLatHP 0 ecefYOrLonHP 0 ecefZOrAltHP 0
  reserved2 0 fixedPosAcc 0 svinMinDur 300 svinAccLimit 500000
  reserved3 0 0

UBX-ACK-ACK:
  ACK to Class x06 (CFG) ID x71 (TMODE3)
----

For receivers that responded to UBX-TIM-SVIN, simply change SURVEYIN3 to
SURVEYIN.  You can optionally provide the svinMinDur and svinAccLimit
variables on the command line.  For example, to survey-in for 60 seconds
and 20 meters accuracy:

----
$ ubxtool -e SURVEYIN3,60,200000  -v 2 -P 27
ubxtool: enable SURVEYIN3,60,200000
[...]
----

To check the progress of your survey:

----
$ ubxtool -p NAV-SVIN -P 27
ubxtool: poll NAV-SVIN

sent:
UBX-NAV-SVIN:
  Poll request
[...]
UBX-NAV-SVIN:
  version 0 reserved1[0 0 0] iTOW 257578000 dur 23
  meanX -238605582 meanY -392219750 meanZ 441436474
  meanXHP -46 meanYHP -48 meanZHP -50 reserved2 0 meanAcc 392629
  obs 23 valid 0 active 1
----

Replace NAV-SVIN with TIM-SVIN above for Timing products. "active 1"
tells you a survey-in is in progress, but "valid 0" tells you it is
not complete.  It may never complete if it cannot reach the position
accuracy requested.

Your survey is complete when valid is 1.  At that point NAV-PVT will
show a fixType of 5 to show you it has entered fixed base mode.

----
$ ubxtool -p NAV-SVIN -P 27
[...]
UBX-NAV-SVIN:
  version 0 reserved1[0 0 0] iTOW 260515000 dur 300
  meanX -238605429 meanY -392219715 meanZ 441436264
  meanXHP -39 meanYHP 17 meanZHP -14 reserved2 0 meanAcc 328065
  obs 301 valid 1 active 0

UBX-NAV-PVT:
  iTOW 260516000 time 2020/6/3  0:21:38 valid x37
  tAcc 26 nano -29221 fixType 5 flags x1 flags2 xea
  numSV 19 lon -1213140873 lat 440688410 height 1109817
  hMSL 1131166 hAcc 26786 vAcc 18941
  velN 0 velE 0 velD 0 gSpeed 0 headMot 33945561
  sAcc 10 headAcc 16986464 pDOP 9999 reserved1 0 26042 11331
  headVeh 2900837 magDec 0 magAcc 0
    valid (validDate ValidTime fullyResolved) fixType (Surveyed)
    flags (gnssFixOK)
    flags2 (confirmedAvai confirmedDate confirmedTime)
    psmState (Not Active)
    carrSoln (None)
----

=== RTCM3 Configuration

This RTCM3 example currently only works on the USB port of a 9-series
Time, Frequency and Time, or High Precision device.  It generates a
LOT of data.

To enable the RTCM 3 output on the USB port:

----
$ ubxtool -e RTCM3 -P 27 -v 2 
ubxtool: enable RTCM3

sent:
UBX-CFG-PRT:
 PortID 3 (USB) reserved1 0 txReady 0x0
  reserved2 [0 0]
  inProtoMask 0x23 outProtoMask 0x23
  reserved3 0 reserved4 0
    inProtoMask (UBX NMEA RTCM3)
    outProtoMask (UBX NMEA RTCM3)

sent:
UBX-CFG-MSG:
  Rate set Class xf5 (RTCM) ID x05 (1005) Rate 1
[A lot of RTCM3 messages are enabled ...]
RTCM3 packet: type 1077
[A ton of RTCM3 messages are output ...]
----

To be able to do anything else, you must disable the RTCM3:

----
$ ubxtool -d RTCM3 -P 27 -v 2 
ubxtool: disable RTCM3
[...]
----

=== Exiting Survey-in

To restore your receiver to normal mode:

----
$ ubxtool -d SURVEYIN3
ubxtool: disable SURVEYIN3

sent:
UBX-CFG-TMODE3:
  version 0 reserved1 0 flags x0
  ecefXOrLat 0 ecefYOrLon 0 ecefZOrAlt 0
  ecefXOrLatHP 0 ecefYOrLonHP 0 ecefZOrAltHP 0
  reserved2 0 fixedPosAcc 0 svinMinDur 300 svinAccLimit 50000
  reserved3 0 0

UBX-ACK-ACK:
  ACK to Class x06 (CFG) ID x71 (TMODE3)
----

Or for a Timing product:

----
$ ubxtool -d SURVEYIN2
ubxtool: disable SURVEYIN2
[...]
----

== Constellations

For unknown reasons, one of the first things newbies want to play with
is the constellation settings.  If you are headed to the polar regions,
into space, or to Asia, then these settings will be of interest to you.
Otherwise, unless you have a Rubidium atomic clock handy, or run 12-hour
experiments with gpsprof, it will be hard for you to improve on the
defaults.  If you still must fiddle, then read on, after completing the
above section on Initial Setup.

=== Changing Constellations

First you must understand what your GNSS receiver is capable of.  Find
this out with the UBX-MON-GNSS message.

----
$ ubxtool -p MON-GNSS
----

If your receiver does not return an ACK-ACK message, then it is 7-series
or earlier, and only receives from GPS satellites.  Owners of 7-series,
or older receivers can stop reading this section now.

A u-blox 8 may return something like this:

----
UBX-MON-GNSS:
   version 0 supported 0x7 defaultGnss 0x3 enabled 0x3
   simultaneous 2 reserved1 0 0 0
     supported (GPS Glonass Beidou)
     defaultGnss (GPS Glonass)
     enabled (GPS Glonass)
----

That 8 can support GPS, GLONASS, and BeiDou, but only two at a time.

A u-blox 9 might return something like this:

----
UBX-MON-GNSS:
   version 0 supported 0xf defaultGnss 0xf enabled 0xd
   simultaneous 4 reserved1 0 0 0
     supported (GPS Glonass Beidou Galileo)
     defaultGnss (GPS Glonass Beidou Galileo)
     enabled (GPS Beidou Galileo)
----

That 9 can support GPS, GLONASS, BeiDou, and Galileo, and all at the same
time.  But in that case, GLONASS is turned off.

There are more details to see with UBX-CFG-GNSS.  A u-blox 8 might
show:

----
$ ubxtool -p CFG-GNSS -v 2
[...]
UBX-CFG-GNSS:
 msgVer 0  numTrkChHw 32 numTrkChUse 32 numConfigBlocks 5
  gnssId 0 TrkCh  8 maxTrCh 16 reserved 0 Flags x01010001
   GPS L1C/A enabled
  gnssId 1 TrkCh  1 maxTrCh  3 reserved 0 Flags x01010001
   SBAS L1C/A enabled
  gnssId 3 TrkCh  8 maxTrCh 16 reserved 0 Flags x01010000
   BeiDou B1I
  gnssId 5 TrkCh  0 maxTrCh  3 reserved 0 Flags x01010001
   QZSS L1C/A enabled
  gnssId 6 TrkCh  8 maxTrCh 14 reserved 0 Flags x01010001
   GLONASS L1 enabled
----

That shows 5 constellations, not 2.  Since GPS, SBAS and QZSS all use
the same frequency and modulation, they were lumped together by MON-GNSS
as simply GPS.

An L2 capable 9-series may look like this:

----
UBX-CFG-GNSS:
 msgVer 0  numTrkChHw 60 numTrkChUse 60 numConfigBlocks 5
  gnssId 0 TrkCh  8 maxTrCh 16 reserved 0 Flags x11110001
   GPS L1C/A L2C enabled
  gnssId 2 TrkCh 10 maxTrCh 18 reserved 0 Flags x21210001
   Galileo E1 E5b enabled
  gnssId 3 TrkCh  4 maxTrCh  5 reserved 0 Flags x11010001
   BeiDou B1I enabled
  gnssId 5 TrkCh  0 maxTrCh  3 reserved 0 Flags x11110001
   QZSS L1C/A L2C enabled
  gnssId 6 TrkCh  8 maxTrCh 12 reserved 0 Flags x11110001
   GLONASS L1 L2 enabled
----

There are several things to note.  SBAS is not shown.  Outside of FAA
requirements, SBAS no longer has any value to the user, and is simply
not supported.  Multiple signals per constellation are shown, and can be
individually enabled.

=== Changing Constellations

The 9-series receives a large number of signals in parallel, so other than
for testing, there is no need to change the defaults that listen to
everything.

Stepping back a bit, the 8-series is more problematic.  Many of them
can only listen to two out of the three possible frequency bands:  GPS,
GLONASS and BeiDou.  Most default to GPS and GLONASS, but GPS and Beidou
may work better.  This is partly because most GPS-only antenna can
receiver BeiDou, but fail to receive GLONASS.  Partly because BeiDou and
GLONASS sats cover different regions of the earth.

If we first try to enable BeiDou, that will fail, as that would enable
3 constellations when only 2 are supported.  So disable GLONASS, then
enable BeiDou, then check.  Always check as u-blox does not reliably report
errors.

----
$ ubxtool -d GLONASS
[...]
$ ubxtool -e BEIDOU
[...]
$ ubxtool -p CFG-GNSS
[...]
UBX-CFG-GNSS:
 msgVer 0  numTrkChHw 32 numTrkChUse 32 numConfigBlocks 5
  gnssId 0 TrkCh  8 maxTrCh 16 reserved 0 Flags x01010001
   GPS L1C/A enabled
  gnssId 1 TrkCh  1 maxTrCh  3 reserved 0 Flags x01010001
   SBAS L1C/A enabled
  gnssId 3 TrkCh  2 maxTrCh 16 reserved 0 Flags x01010001
   BeiDou B1I enabled
  gnssId 5 TrkCh  0 maxTrCh  3 reserved 0 Flags x01010001
   QZSS L1C/A enabled
  gnssId 6 TrkCh  8 maxTrCh 14 reserved 0 Flags x01010000
   GLONASS L1
----

After a few minutes, if you are in a location which BeiDou covers, then
you should start to see BeiDou sats in the cgps sat list.  The 8-series
has many other constraints on setting CFG-GNSS, the masochistic will
need to spend a lot of quality time with the u-blox documentation to
lean the many ways to shoot yourself in the foot.

While the need for changing what the 9-series listens for is less, the
complexity of doing so is increased.  Not only must the constellation
be selected, but also the signals within the constellation.

Let us disable GLONASS on a ZED-F9P, then enable it, and check the
results:

----
$ ubxtool -d GLONASS
[...]
$ ubxtool -e GLONASS
[...]
$ ubxtool -p CFG-GNSS
[...]
UBX-CFG-GNSS:
 msgVer 0  numTrkChHw 60 numTrkChUse 60 numConfigBlocks 5
  gnssId 0 TrkCh  8 maxTrCh 16 reserved 0 Flags x11110001
   GPS L1C/A L2C enabled
  gnssId 2 TrkCh 10 maxTrCh 18 reserved 0 Flags x21210001
   Galileo E1 E5b enabled
  gnssId 3 TrkCh  4 maxTrCh  5 reserved 0 Flags x11010001
   BeiDou B1I enabled
  gnssId 5 TrkCh  0 maxTrCh  3 reserved 0 Flags x11110001
   QZSS L1C/A L2C enabled
  gnssId 6 TrkCh  8 maxTrCh 12 reserved 0 Flags x11110000
   GLONASS L1 L2
----

Note that GLONASS is still disabled.  Determining why is left as an
exercise to the reader.  The receiver must be told to enable both
frequencies before it complies:

----
$ ubxtool -e GLONASS,2
[...]
$ ubxtool -p CFG-GNSS
[...]
UBX-CFG-GNSS:
 msgVer 0  numTrkChHw 60 numTrkChUse 60 numConfigBlocks 5
  gnssId 0 TrkCh  8 maxTrCh 16 reserved 0 Flags x11110001
   GPS L1C/A L2C enabled
  gnssId 2 TrkCh 10 maxTrCh 18 reserved 0 Flags x21210001
   Galileo E1 E5b enabled
  gnssId 3 TrkCh  4 maxTrCh  5 reserved 0 Flags x11010001
   BeiDou B1I enabled
  gnssId 5 TrkCh  0 maxTrCh  3 reserved 0 Flags x11110001
   QZSS L1C/A L2C enabled
  gnssId 6 TrkCh  8 maxTrCh 12 reserved 0 Flags x11110001
   GLONASS L1 L2 enabled
----

Another reason to always check your work when using ubxtool.

=== Changing Constellations with Configuration Items

The astute will have noticed that the canned ubxtool commands, like
"-e GLONASS", send one or binary messages that may change a handful
or variables at once.  The 9-series avoids this mess with Configuration
Items.  These allow you to get, set and delete individual settings in
the receiver.  before continuing this section, read the ubxtool
man page on Configuration Items.

The CFG-SIGNAL Configuration Item group includes the CFG-GNSS items
of interest here.  So take a look at them, in the ram layer:

----
$ ubxtool -g CFG-SIGNAL,0
[...]
UBX-CFG-VALGET:
 version 1 layer 0 position 0
  layers (ram)
    item CFG-SIGNAL-GPS_L1CA_ENA/0x10310001 val 1
    item CFG-SIGNAL-GPS_L2C_ENA/0x10310003 val 1
    item CFG-SIGNAL-GAL_E1_ENA/0x10310007 val 1
    item CFG-SIGNAL-GAL_E5B_ENA/0x1031000a val 1
    item CFG-SIGNAL-BDS_B1_ENA/0x1031000d val 1
    item CFG-SIGNAL-BDS_B2_ENA/0x1031000e val 0
    item CFG-SIGNAL-QZSS_L1CA_ENA/0x10310012 val 1
    item CFG-SIGNAL-QZSS_L2C_ENA/0x10310015 val 1
    item CFG-SIGNAL-GLO_L1_ENA/0x10310018 val 1
    item CFG-SIGNAL-GLO_L2_ENA/0x1031001a val 1
    item CFG-SIGNAL-GPS_ENA/0x1031001f val 1
    item CFG-SIGNAL-GAL_ENA/0x10310021 val 1
    item CFG-SIGNAL-BDS_ENA/0x10310022 val 1
    item CFG-SIGNAL-QZSS_ENA/0x10310024 val 1
    item CFG-SIGNAL-GLO_ENA/0x10310025 val 1
    item CFG-SIGNAL-39/0x10310027 val 1
[...]
----

Notice that the BeiDou B2 signal is not enabled.  That might be because
when the firmware was written there were not B2 signals from space to
test.  Or maybe not, who knows, but we want to enable it to see if
anything changes.  So we will use the "-z" command to enable it, and
the "-g" command to check it in layer 0.

----
$ ubxtool -z CFG-SIGNAL-BDS_B2_ENA,1
[...]
$ ubxtool -g CFG-SIGNAL-BDS_B2_ENA,0
[...]
UBX-CFG-VALGET:
 version 1 layer 0 position 0
  layers (ram)
    item CFG-SIGNAL-BDS_B2_ENA/0x1031000e val 1
----


// vim: set syntax=asciidoc: