GNSS

The Global Navigation Satellite System can be accessed using different tools: gpsd provides a useful toolset and the gnss-mgr provides configuration possibilities.

gpsd

gpsd is used as the interface between the GNSS receiver and other location aware applications. Multiple applications can access the GNSS receiver via TCP connections on port 2947 at the same time, solving the problem of multiple applications requiring access to the same tty interface. gpsd includes several tools to interface to the GNSS receiver, like cpgs, gpsctl, gpscat and ubxtool.

Connecting ubxtool

The ubxtool might not establish a stable connection to the modem (interruptions, connection issues, …) depending on how the modem is connected internally. The following command helps to get a stable connection with ubxtool:

ser2net -C "2947:raw:0:/dev/gnss0: 115200 8DATABITS NONE 1STOPBIT NOBREAK"

NEO-M8L

The NEO-M8L module is a GNSS receiver by u-blox with the following key features:

  • Automotive Grade

  • GPS / QZSS, GLONASS, Galileo and BeiDou

  • Dead Reckoning using built in IMU

NEO-M9V

The NEO-M9V module is the replacement of the NEO-M8 and provided similar features.

gnss-mgr

gnss-mgr provides GNSS receiver configuration possibilities and replaces the obsolete gnss-config, gnss-save-on-shutdown and neom8tool. This tool operates directly on the serial interface before gpsd is staring up and comes with different functionalities like:

  • initialization (runs on each boot-up)
    • configuring the communciation bitrate of the receiver if necessary

    • configuring the used NMEA protocol version if necessary

    • clearing latest receiver state (save on shutdown)

  • save on shutdown (SoS) features like persisting/clearing/verifying receiver state to/from internal storage

  • configuring the receiver using a configuration file (in ini file format, see below)

  • control functions
    • persist the actual configuration into non-volatile storage

    • cold-start the receiver

    • resetting the receiver’s configuration to default

The gnss-mgr is set up as systemd service (gnss-mgr.service).

On each boot-up the gnss-mgr checks and if necessary configures the bitrate and the NMEA protocol version. The gnss-mgr configures the recevier with volatile parameters, i.e. the configuration is not persisted and when the power is cut, the receiver looses your configuration (the receiver then re-applies its internally stored setup at the next power-up). Additionally after successfully starting up the gnss services, some basic information about the GNSS receiver can be found at /run/gnss/gnss0.conf.

root@am335x-nmhw21:~# cat /run/gnss/gnss0.config
Vendor:                             ublox
Model:                              NEO-M8L-0
Firmware:                           ADR 4.21 (Deprecated)
ubx-Protocol:                       19.20
Supported Satellite Systems:        GPS;GLO;GAL;BDS
Supported Augmentation Services:    SBAS;IMES;QZSS
SW Version:                         EXT CORE 3.01 (1ec93f)
HW Version:                         00080000

Capabilities

The command gnss-mgr --help shows the entire capabilities of the gnss-mgr:

root@am335x-nmhw21:~# gnss-mgr --help
usage: gnss-mgr [-h] [-V] [-v] [-q] device {init,sos,config,control} ...

Manages GNSS modem

positional arguments:
  device                local serial device to which GNSS modem is connected
                        (e.g. /dev/gnss0)

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -v, --verbose         be verbose, show debug output
  -q, --quiet           be quiet, only show warnings and errors

command:
  {init,sos,config,control}
                        select command
    init                sets up GNSS modem
    sos                 save on shutdown operations
    config              configures GNSS modem
    control             performs GNSS modem control function

Each command (init, sos, config and control) provides a sub-help:

root@am335x-nmhw21:~# gnss-mgr /dev/gnss0 init --help
usage: gnss-mgr device init [-h] [-f RUNFILE]

optional arguments:
  -h, --help            show this help message and exit
  -f RUNFILE, --file RUNFILE
                        path to run file

----------------------------

root@am335x-nmhw21:~# gnss-mgr /dev/gnss0 sos --help
usage: gnss-mgr device sos [-h] {save,clear}

positional arguments:
  {save,clear}  selects sos operation to perform

optional arguments:
  -h, --help    show this help message and exit

----------------------------

root@am335x-nmhw21:~# gnss-mgr /dev/gnss0 config --help
usage: gnss-mgr device config [-h] [-f CONFIGFILE]

optional arguments:
  -h, --help            show this help message and exit
  -f CONFIGFILE, --file CONFIGFILE
                        path to config file

----------------------------

root@am335x-nmhw21:~# gnss-mgr /dev/gnss0 control --help
usage: gnss-mgr device control [-h] {cold-start,persist,factory-reset}

positional arguments:
  {cold-start,persist,factory-reset}
                        selects action to perform

optional arguments:
  -h, --help            show this help message and exit

Configuring the GNSS Receiver

The gnss-mgr configures the GNSS receiver by using configuration files in ini format. Writing the configuration is managed by feeding the appropriate file to the gnss-mgr.

Warning

A misconfigured GNSS with Dead Reckoning (DR) generates worse results as a GNSS receiver only!

Note

When running the GNSS receiver at 9600 baud some UBX packets might be lost which results in overall worse GNSS performance. Therefore it is strongly recommended to let the receiver operate with 115200 baudto. Additionally it is recommended to configure the GNSS receiver persistent (see example Persistent configuration of the GNSS receiver below.

Configuration files

Use the configuration file /etc/gnss/gnss0.conf as template to properly configure the GNSS receiver.

Warning

The IMU angles (yaw, pitch, roll) are different between NEO-M9 and M8

The following example of gnss0 config file shows the configuration capabilities of the gnss-mgr. The comments show how to setup each parameter:

root@am335x-nmhw21:~# cat /etc/gnss/gnss0.conf
#
# This file is part of gnss-mgr service
# To make changes, edit the values in this file and reload
# gnss-mgr service.
#
# Any empty value will use the default or persistent configuration
# of the receiver.

[default]
# Indicates the version of this config file, it should not be modified.
# If unsure of its value, sample config file can always be found in
# /usr/etc/gnss/
#
# Change history
# version 3: Added field navigation.dead-reckoning
# version 4: Added "time" section
version=4

# Select measurement and navigation output rate
# Allowed values : 1 - 10  [Hz]
update-rate=
#update-rate=1


#
# Navigation settings
#
[navigation]
# Enables or disables dead reckoning
# Supported values:
#   enable, disable
dead-reckoning=
#dead-reckoning=disable

# Selects dynamic mode
# Supported values:
#   stationary, vehicle
mode=
#mode=vehicle

#
# Selects GNSS systems
# Allowed values:
#   GPS;GLONASS;SBAS
#   GPS;Galileo;Beidou;SBAS
systems=
#systems=GPS;GLONASS;SBAS
#systems=GPS;Galileo;Beidou;SBAS


#
# Installation settings
# For details on this section, see the relevant documentation
#
[installation]

#
# IMU orientation in degrees [°]
#
# ! Be careful, the IMU orientation may be different between
#   NEO-M8 and NEO-M9
#
# ! Also configuring these angles will disable auto-alignment
#
#   yaw: value in degrees (0 to  360)
#   pitch: value in degrees (-90 to  90)
#   roll: value in degrees (-180 to 180)
yaw=
pitch=
roll=

# Lever arm lengths in meters [m]
# Format x;y;z
# Example:
#   vrp2antenna=1.0;1.5;0.3
vrp2antenna=
vrp2imu=


#
# Configurations related to time
# For details on this section, see the relevant documentation
#
[time]

#
# Enables or disables the time pulse (PPS) line
# If it is not set, the default or already configured
# state of the receiver will be used.
#
# NB: This feature may not be available on all systems
# Handling of the PPS line must also be done.
#
timepulse=
#timepulse=enable
#timepulse=disable


#
# Sets the frequency [Hz] of the time pulse (PPS) line
#
# If not set the default or already configured value is used
#
timepulse-frequency=
#timepulse-frequency=1
#timepulse-frequency=20

Lever Arm Lengths

The following figure shows an installation example and how to configure the receiver’s lever arm lengths.

Lever Arm Lengths Example

Installation and positioning

LeverConfiguration with values
  • vrp2antenna=1.6;0;1.7

  • vrp2imu=2.1;0.6;0.8

Timepulse configuration

The timepulse can be enable or disabled and configured in the [time] section. This feature sends a pulse every 1/X seconds. Note that the PPS line must be handled outside of gnss-mgr: depending on the system, it may be:

  • not connected

  • connected directly to the CPU and in this case handled by the “time” software

  • connected to an external component

Examples

Configuring the GNSS receiver:

gnss-mgr /dev/gnss0 config -f /etc/gnss/gnss0.conf

Persisting the configuration of the GNSS receiver:

gnss-mgr /dev/gnss0 control persist

Resetting the receiver’s configuration to default:

gnss-mgr /dev/gnss0 control factory-reset

Troubleshooting

If the receiver is no longer accessible, the issue most seen is that baud rates of serial interface (ttyS3) and receiver are not matching.

Save on Shutdown

The u-blox GNSS receivers can be instructed to save their current state to the internal non-volatile memory and restore it after a power cycle.

Note that the receiver state and the receiver configuration must be distinguished: Saving the state before the system is shut-down can help your GNSS receiver to get a faster fix after booting. Save on shutdown does however not save any configuration done by the user. The receiver configuration needs to be saved manually to the receiver’s internal non-volatile memory (only once), see Example Persiting the configuration of the GNSS receiver.

The gnss-mgr service instructs the GNSS receiver to save its state whenever your linux system receives a shutdown or reboot instruction. Upon reboot the same service logs if the GNSS receiver state has been successfully restored.

Examples

Storing the state to the GNSS receiver’s internal storage:

gnss-mgr /dev/gnss0 sos save

Clearing the state in the GNSS receiver’s internal storage:

gnss-mgr /dev/gnss0 sos clear

Firmware update (specific to u-blox NEO-M8L)

The firmware of the module u-blox NEO-M8L can be upgraded as explained in Updating firmware.:

Testing

To test the GNSS function connect an active GNSS antenna to X3300 “GNSS”.

Run “cgps” tool

Your output should look like this. Typically it takes 3..20 seconds for a fix.

┌───────────────────────────────────────────┐┌─────────────────────────────────┐
│    Time:       2018-07-05T06:49:00.000Z   ││PRN:   Elev:  Azim:  SNR:  Used: │
│    Latitude:    47.31890666 N             ││   6    18    082    28      Y   │
│    Longitude:    7.97375949 E             ││  17    15    039    30      Y   │
│    Altitude:   1641.076 ft                ││  19    35    052    27      Y   │
│    Speed:      0.14 mph                   ││  32    32    305    16      Y   │
│    Heading:    0.0 deg (true)             ││  66    27    311    23      Y   │
│    Climb:      0.00 ft/min                ││  74    43    076    28      Y   │
│    Status:     3D FIX (3 secs)            ││  84    46    063    21      Y   │
│    Longitude Err:   +/- 33 ft             ││                                 │
│    Latitude Err:    +/- 111 ft            ││                                 │
│    Altitude Err:    +/- 200 ft            ││                                 │
│    Course Err:      n/a                   ││                                 │
│    Speed Err:       +/- 152 mph           ││                                 │
│    Time offset:     7176.328              ││                                 │
│    Grid Square:     JN37xh                ││                                 │
└───────────────────────────────────────────┘└─────────────────────────────────┘

Access gps interface

If direct interface access is required, the gps device is available under /dev/gnss0. Be aware that gnss0 is just a symlink to the real device managed by udev. If you need to know the real device, follow the symlink with:

Example output:

root@am335x-nmhw21:~# ls -l /dev/gnss0
lrwxrwxrwx 1 root root 5 Jul  2 07:06 /dev/gnss0 -> ttyS3