[[PageOutline]]


[=#gnss]
= Global Navigation Satellite Systems (GNSS) =
GNSS (Global Navigation Satellite System) is a satellite system that is used to pinpoint the geographic location of a receiver anywhere in the world.

Each of the following GNSS systems employ a constellation of orbiting satellites working in conjunction with a network of ground stations:
 * GNSS systems are currently in operation:
  - the United States' NAVSTAR Global Positioning System (GPS)
  - the Russian Federation's Global Orbiting Navigation Satellite System (GLONASS)
 * GNSS systems not currently at full capacity:
  - Europe's Galileo is slated to reach full operational capacity by 2020

The following are similar navigation systems that do not have world-wide coverage:
 * China's !BeiDou Navigation Satellite System
 * India's GPS Aided GEO Augmented Navigation (GAGAN) and Indian Regional Navigation Satellite System (IRNSS)

References:
 * https://en.wikipedia.org/wiki/Satellite_navigation

[=#gps]
== United States NAVSTAR Global Positioning System (GPS) ==
The United States NAVSTAR Global Positioning System (GPS) operates at a frequency of 1575.42MHz referred to as {{{L1C/A}}}. It has world-wide coverage originally using 24 satellites which began deployment in 1973 and became fully operational in 1995.

Reference:
 * https://en.wikipedia.org/wiki/Global_Positioning_System

[=#glonass]
== Russian Federation Global Orbiting Navigation Satellite System (GLONASS) ==
The Russian Federation Global Orbiting Navigation Satellite System (GLONASS) operates at a frequency of 1602MHz + k*562.5 (where k = -7,...,5,6) referred to as {{{L1OF}}}. It is a space-based system providing an alternative to US GPS. Deployment began in 1982 and was originally completed in 1995 but followed with a decline in capacity until fully restored to 24 satellites in 2011.

Reference:
 * https://en.wikipedia.org/wiki/GLONASS

[=#beidou]
== !BeiDou Navigation Satellite System (China) ==
The !BeiDou Navigation Satellite System covers China and is planned to begin serving global customers upon its completion in 2020.

[=#galileo]
== Galileo Navigation Satellite System (EU) ==
Galileo is the GNSS that is currently being created by the European Union (EU) and the European GNSS Agency (GSA). The system became operational in October 2011 and as of Dec 2016 the system has 18 of 30 satellites in orbit and is expected to reach full operational capability in 2019 with the complete 30-satellite system (24 operational and 6 active spares) expected by 2020.

Reference:
 * [https://en.wikipedia.org/wiki/Galileo_(satellite_navigation)]

[=#sbas]
== Satellite-Based Augmentation System (SBAS) ==
A Satellite-Based Augmentation System (SBAS) is a system that supports wideo-area or regional augmentation of positioning systems.

There are several common SBAS implementations:
 * [https://en.wikipedia.org/wiki/Wide_Area_Augmentation_System Wide Area Augmentation System] (WAAS) operated by the United States Federal Aviation Administration (FAA)
 * [https://en.wikipedia.org/wiki/European_Geostationary_Navigation_Overlay_Service European Geostationary Navigation Overlay Services] (EGNOS) operated by the European Satellite Services Provider (ESSP)
 * [https://en.wikipedia.org/wiki/Multi-functional_Satellite_Augmentation_System Multi-functional Satellite Augmentation System] (MSAS) operated by Japan's Ministry of Land, Infrastructure and Transport Japan Civil Aviation Bureau (JCAB)
 * [https://en.wikipedia.org/wiki/Quasi-Zenith_Satellite_System Quasi-Zenith Satellite System] (QZSS) operated by Japan Aerospace Exploration Agency (JAXA)


[=#software]
= Software Links =
For '''using the GPS in software''', please see the Operating Systems pages:
 * OpenWrt GPS - [wiki:OpenWrt/GPS See here for more information]
 * Yocto GPS - [wiki:Yocto/GPS See here for more information]


= Gateworks on-board GPS GNSS Hardware =
Gateworks has several products that have on-board GNSS modules.

The advantage of using a Gateworks product with an on-board modules are:
 * Active Antenna support (with auto-short-circuit detect/protect/recovery for some models)
 * PPS signal for time synchronization
 * Tighter integration

Refer to the details below as well as the individual product manuals for details of connection such as:
 * Data serial port
 * PPS GPIO
 * Active antenna detect/protect/recovery support

Note the only external GPS that Gateworks offers is the GW16143 high precision GNSS Mini-PCIe card, read more on the [wiki:expansion/gw16143 GW16143 Wiki Page]

== Example On-Board GPS Connector ==
The average Gateworks SBC with GPS installed will have a gold MMCX connector like pictured below:

[[Image(gpsexample.png,300px)]]



[=#uart]
== Hardware UART and Device Mappings ==
The GPS devices used on Gateworks products communicate with the host processor over a serial UART:
 * Venice:
  * GW7401/GW7301/GW7201: /dev/ttymxc0 [#zoem8q u-blox ZOE-M8Q] 9600bd NMEA 0183 output 1Hz
 * Newport:
  * GW6104/GW6204/GW6304/GW6404: /dev/ttyAMA1 [#zoem8q u-blox ZOE-M8Q] 9600bd NMEA 0183 output 1Hz
  * Note must disable echo on serial port, Read more in troubleshooting section [#zoem8q here]
 * Ventana:
  * GW5100: /dev/ttymxc0 [#w2sg0008i Wi2Wi W2SG0008i] 4800bd NMEA 0183 output 1Hz
  * GW52xx (rev A-D) / GW53xx (rev A-F) / GW54xx (rev C-F) : /dev/ttymxc4 [#w2sg0008i Wi2Wi W2SG0008i] 4800bd NMEA 0183 output 1Hz
  * GW52xx (rev E+) / GW53xx (rev G+) / GW54xx (rev G+) : /dev/ttymxc4 [#zoem8q u-blox ZOE-M8Q] 9600bd NMEA 0183 output 1Hz
  * GW553x: /dev/ttymxc3  [#evam8m u-blox EVA-M8M] 9600bd NMEA 0183 output of GGA/GLL/GSA/GSV/RMC/VTG/TXT GPS, GLONASS, and SBAS enabled
 * Laguna: [#condor Trimble Condor]
  * GW2391: /dev/ttyS2 (Gateworks 'specials' can alternately map this /dev/ttyS1)
  * GW2388: /dev/ttyS2 (Gateworks 'specials' can alternately map this /dev/ttyS1)
  * GW2380: /dev/ttyS1


[=#hardware]
== Hardware Devices Used ==

=== u-blox ZED-F9P

This module is a high precision GNSS/GPS module for providing up to 2CM accuracy with RTK. It is used on the GW16143 Mini-PCIe Card. Read more on the [wiki:expansion/gw16143 GW16143 Wiki Page].

[=#zoem8q]
=== '''u-blox ZOE-M8''' (Venice & Newport Family of SBC's and Specific Ventana Models) ===
References:
- ZOE-M8 Datasheet (UBX-16008094)
- u-blox M8 Receiver Protocol Specification (UBX-13003221)

Features:
 * 72-channel u-blox M8 concurrent position receiver engine supporting multiple concurrent Global Navigation Satellite System's (GNSS):
  - [#gps GPS]: L1C/A (1575.42MHz)
  - [#glonass GLONASS]: L1OF (1602MHz)
  - [#beidou !BeiDou]: B1l
  - [#galileo Galileo]: E1B/C
  - [#qzss QZSS]: L1C/A (1575.42MHz)
  - [#sbas SBAS]: WAAS/EGNOS/MSAS: L1C/A (1575.42MHz)
 * [#dgps Differential GPS] (DGPS): [#rtcm RTCM] 10402.3:
 * Navigation Update Rate: 10Hz (GPS&GLONASS) or 18Hz (GPS)  
 * Accuracy:
  - Velocity: 0.05m/s
  - Heading: 0.3degrees
  - Horiz position: Autonomous 2.5m / SBAS 2.0m
  - PPS: 30ns RMS, 99% 60ns
 * Sensitivity:
  - Tracking & Navigation: -167dBm (GPS&GLONASS) -166dBm (GPS) -166dBm (GLONASS) -160dBm (!BeiDou) -159dBm (Galileo)
  - Re-acquisition: -159dBm
  - Cold start: -147dBm
 * Acquisition:
  - Cold start Time-to-First-Fix (TTFF): 27s (GPS&GLONASS) or 30s (GPS only)
  - Hot start Time-to-First-Fix (TTFF): 1s
 * [#pps PPS]:
  - 30ns accuracy, configurable via UBX-CFG-TP5 with rate 0.25Hz to 10Mhz, high or low polarity, 0 to 2^32^ ms pulse width (see u-blox M8 Receiver Description UBX-13003221 Chapter 18)
  - Default is 1Hz rising edge 100ms length
  - Note that for best PPS accuracy it is recommended to disable the SBAS subsystem
 * Communication:
  - 9600 baud, 8bit no parity, 1 stop bit, no flow control supporting multiple protocols:
   - [#nmea0183 NMEA]: Input / Output ASCII 0183 version 4.0 (configurable for 2.3 or 4.1)
   - [#ubx UBX]: Input / Output binary u-blox proprietary (see [wiki:gps#ubx ubx] below)
   - [#rtcm RTCM]: Input, messages 1,2,3,9
 * Active Antenna: 15dB to 50dB recommended
 * Power Consumption (not including active antenna power consumption):
  - ~40mA@1.8V 72mW (Continuous)
  - ~12.5mA@1.8V 22.5mW (PSM, 1Hz)

Power-on Defaults:
 * 9600 baud, 8 data bits, no parity, 1 stop bit:
 * GPS & GLONASS enabled
 * SBAS enabled
 * output: NMEA: GGA, GLL, GSA, GSV, RMC, VTG, TXT messages
 * input: UBX, NMEA, RTCM
 * PPS: 100ms active high pulse at 1Hz

Note that the GPS is not connected to an RTC, battery backup, or external flash on Gateworks designs (which disallows for permanent configuration storage and firmware upgrade)

The ZOE-M8 GPS has the following improvements over the EVA-M8:
 - Has built in SAW and LNA for passive antenna support whereas the EVA-M8 can't support passive antenna
 - Uses an internal TCXO (temperature compensated) oscillator to provide improved accuracy over the EVA-M8 which uses a crystal
 - Smaller footprint (4.5mm x 4.5mm x 1.0mm) device vs (7mm x 7mm x 1.1mm)
 - Supports Galileo and !BeiDou. EVA-8M only supports GPS GLONASS
 - Improved sensitivity (-167dBm vs -164dBm)
 - Faster acquisition time (26s vs 33s)

'''Troubleshooting'''
 * The following message may be seen on the GPS line:
{{{
$GNTXT,01,01,01,NMEA unknown msg*46
}}}
  * This happens when echo is enabled on the serial line. To disable it, use the following command, adjusting the device in the example below where appropriate:
{{{
stty -F /dev/ttyAMA1 -echo
}}}


[=#evam8m]
=== '''u-blox EVA-M8M-0''' (GW553x) ===
References:
- [https://www.u-blox.com/sites/default/files/products/documents/EVA-M8M-FW3_DataSheet_%28UBX-16007405%29.pdf EVA-M8M Datasheet]
- u-blox M8 Receiver Protocol Specification (UBX-13003221)

Features:
 * 72-channel u-blox M8 concurrent position receiver engine supporting multiple concurrent Global Navigation Satellite System's (GNSS):
  - [#gps GPS]: L1C/A (1575.42MHz)
  - [#glonass GLONASS]: L1OF (1602MHz)
  - [#qzss QZSS]: L1C/A (1575.42MHz)
  - [#sbas SBAS]: WAAS/EGNOS/MSAS: L1C/A (1575.42MHz)
 * [#dgps Differential GPS] (DGPS): [#rtcm RTCM] 10402.3:
 * Navigation Update Rate: 10Hz (GPS&GLONASS) or 18Hz (GPS)  
 * Accuracy:
  - Velocity: 0.05m/s
  - Heading: 0.3degrees
  - Horiz position: Autonomous 2.5m / SBAS 2.0m
  - PPS: 30ns RMS, 99% 60ns
 * Sensitivity:
  - Tracking & Navigation: -164dBm (GPS&GLONASS) -163dBm (GPS)
  - Re-acquisition: -159dBm
  - Cold start: -147dBm
 * Acquisition:
  - Cold start Time-to-First-Fix (TTFF): 27s (GPS&GLONASS) or 30s (GPS only)
  - Hot start Time-to-First-Fix (TTFF): 1s
 * [#pps PPS]:
  - 30ns accuracy, configurable via UBX-CFG-TP5 with rate 0.25Hz to 10Mhz, high or low polarity, 0 to 2^32^ ms pulse width (see u-blox M8 Receiver Description UBX-13003221 Chapter 18)
  - Note that for best PPS accuracy it is recommended to disable the SBAS subsystem
 * Communication:
  - 9600 baud, 8bit no parity, 1 stop bit, no flow control supporting multiple protocols:
   - [#nmea0183 NMEA]: Input / Output ASCII 0183 version 4.0 (configurable for 2.3 or 4.1)
   - [#ubx UBX]: Input / Output binary u-blox proprietary
   - [#rtcm RTCM]: Input, messages 1,2,3,9
 * Active Antenna: 15dB to 50dB recommended
 * Power Consumption (not including active antenna power consumption):
  - ~27mA (90mW) during acquisition for GPS & GLONASS, 22mA for GPS/QZSS/SBAS
  - ~25mA (83mW) during continuous mode tracking for GPS & GLONASS, 19mA for GPS/QZSS/SBAS
  - ~5.5mA (18mW) during 1Hz power-save mode tracking (for GPS/QZSS/SBAS only)

Power-on Defaults:
 * 9600 baud, 8 data bits, no parity, 1 stop bit:
 * GPS & GLONASS enabled
 * SBAS enabled
 * output: NMEA: GGA, GLL, GSA, GSV, RMC, VTG, TXT messages
 * input: UBX, NMEA, RTCM
 * PPS: 100ms active high pulse at 1Hz

Note that the EVA-M8M is not connected to an RTC, battery backup, or external flash on Gateworks designs (which disallows for permanent configuration storage and firmware upgrade)

[=#ubx]
==== u-blox Receiver Protocol (UBX) ====
UBX (u-blox Receiver Protocol) is a u-blox proprietary binary communication protocol used in their GNSS engines described in detail in M8 Receiver protocol: UBX-13003221


==== NMEA considerations for EVA-M8M ====
The following need to be taken into consideration when operating in multi-GNSS mode (Note that the power-on default is GPS & GLONASS):
 - multiple sets of GSV messages will be output back to back, 1 for each system
 - multiple sets of GSA and GRS messages are output for each fix, one for each GNSS

The main Talker ID (the two-letter identifier) will vary based on GNSS configuration:
 * GPS/SBAS/QZSS - '''GP'''
 * GLONASS - '''GL'''
 * GNSS - '''GN''' (message pertaining to any type of GNSS)


[=#w2sg0008i]
=== '''Wi2Wi W2SG0008i''' (GW54xx rev C-F, GW53xx rev A-F, GW52xx rev A-D, GW51xx) ===
References:
 * [http://dev.gateworks.com/datasheets/W2SG0008i.pdf Product Brief]
 * [http://dev.gateworks.com/datasheets/W2SG0008i_Datasheet_Rev1.48.pdf Product Datasheet]
 * NMEA Reference Manual (CS-129435-MA-1)
 * One Socket Protocol Interface Control Document (OSP_ICD) (CS-129291-DC-15)

Features:
 * CSR/SiRF SiRFStarIV GSD4e
 * 48 channel continuous tracking receiver (reports best 12 of 48):
  - [#gps GPS]: L1C/A (1575.42MHz) 
  - [#sbas SBAS]: WAAS/EGNOS/MSAS/GAGAN: L1C/A (1575.42MHz)
 * [#dgps Differential GPS] (DGPS)
 * Navigation Update Rate 1-5Hz
 * Acquisition:
  * Hot Start TTFF@-136dBm: 0.6sec
  * Min Acquisition Signal: -153dBm
 * Sensitivity: Tracking -163dBm / Acquisition -148dBm
 * Accuracy:
  * 3m stationary horizontal (with DGPS), 15m stationary horizontal (without DPGS)
 * Communication:
  * 8 data bits, no parity, 1 stop bit (aka '''8N1''' or '''cs8'''), no flow control
  * baudrate: can vary between 4800 and 115200 (see below)
  * [#nmea0183 NMEA 0183] v3.01, configurable 1 to 255 seconds between messages, supports: GGA, GLL, GSA, GSV, RMC, VTG, ZDA messages
  * [#osp OSP™] (SiRF BINARY™) proprietary protocol
 * [#pps PPS]:
  * ±1us accuracy, rising edge 1Hz 200ms width active-high when there are 5+ satellites used in a fix (not configurable)
 * Internal LNA Gain:
  * High Gain Mode '''(default)''' intended for use with passive antennas
  * Low Gain Mode intended for use with active antennas (that have their own LNA)

Power-on Default configuration:
 * 4800 baud
 * NMEA 0183 output 1Hz
 * LNA high gain mode


==== W2SG0008i (SiRFStarIV) NMEA Command Reference: ====
References:
 * NMEA Reference Manual (CS-129435-MA-1)

Notes:
 * NMEA 4800bd 8N1 (8 data bits, no parity, 1 stop bit) is the default power-on communication mode of the W2SG0008i
 * Flow control is not used between the GPS and the host processor and thus should be disabled
 * SiRF NMEA reports a maximum of 12 satellites in its GSV messages even though more may be visible (use [#osp OSP] protocol if you want more detail on the 48 channels)


Examples:
 * The proprietary PSRF100 command will change the baudrate and data format. Consult the reference manual (above) section 2-3 for more info.
  * Example: '''To change the baud from the power-on default 4800bd to 9600bd''':
{{{#!bash
# set tty for current baudrate and data format
stty -F /dev/gpsdevice 4800 cs8
# send a PSRF100 command to set the format (1=NMEA mode) baudrate (9600) and data format
echo "\$PSRF100,1,9600,8,1,0*0D" > /dev/gpsdevice
# set new tty baudrate for further communication
stty -F /dev/gpsdevice 9600
}}}
   * 1,9600,8,1 is the data payload. Specifically, the first '1' specifies that this is a NMEA message, while the rest of the payload determines the speed of the GPS receiver.
   * ensure that /dev/gpsdevice corresponds to the correct tty above in the [#hardware hardware mappings section]
   * if changing the above NMEA sentence, be sure to [http://www.hhhh.org/wiml/proj/nmeaxor.html update the checksum]
 * The proprietary PSRF103 command will set the rates of the various NMEA messages.  Consult the reference manual (above) section 2-6 for more info.
  * Example: '''To set the period of all messages to one every 1 seconds''':
{{{#!bash
# set tty for current baudrate and data format assuming power-on default of 4800bd 8N1
stty -F /dev/ttymxc4 4800 cs8
echo "\$PSRF103,00,00,01,01*26" > /dev/gpsdevice # GGA every 2 sec
echo "\$PSRF103,01,00,01,01*25" > /dev/gpsdevice # GLL every 2 sec
echo "\$PSRF103,02,00,01,01*28" > /dev/gpsdevice # GSA every 2 sec
echo "\$PSRF103,03,00,01,01*27" > /dev/gpsdevice # GSV every 2 sec
echo "\$PSRF103,04,00,01,01*22" > /dev/gpsdevice # RMC every 2 sec
echo "\$PSRF103,05,00,01,01*21" > /dev/gpsdevice # VTG every 2 sec
}}}
   * if changing the above NMEA sentences, be sure to [http://www.hhhh.org/wiml/proj/nmeaxor.html update the checksum]
   * ensure that /dev/gpsdevice cooresponds to the correct tty above in the [#hardware hardware mappings section]


[=#osp]
==== One Socket Protocol (OSP), aka SiRF Binary Protocol ====
One Socket Protocol (OSP), also known as the SiRF BINARY™ protocol, is a binary communication protocol available with the SiRFstar family of GPS receiver products from SiRF (which was purchased by CSR). In general, there are more message types and data available when using this protocol over NMEA 0183.

References:
 * One Socket Protocol Interface Control Document (OSP_ICD) (CS-129291-DC-15)

Examples:
 * '''To switch from NMEA 4800bd 8N1 to OSP at 9600 baud''', you can use the following bash script:
{{{
#!/bin/sh

# Make sure we talk to the device at its current configured data format
# (assuming power-on default of 4800 8N1)
stty -F /dev/gpsdevice 4800 cs8

# change to mode=0 (OSP/SiRF binary) 9600bd 8N1
echo "\$PSRF100,0,9600,8,1,0*0C" > /dev/gpsdevice

# set new tty baudrate for future communication
stty -F /dev/gpsdevice 9600
}}}
  * if changing the above NMEA sentences, be sure to [http://www.hhhh.org/wiml/proj/nmeaxor.html update the checksum]
  * ensure that /dev/gpsdevice cooresponds to the correct tty above in the [wiki:gps#HardwareUARTMappings hardware mappings section]
 * '''To switch from OSP at 9600bd back to NMEA 4800bd''', you can use the following bash script:
{{{
#!/bin/sh
send_hex() {
  while [ "$1" ]; do
    printf "\x$1"
    shift
  done
}

# Make sure we talk to the device at its current configured data format
# (assuming it has been changed to 9600bd)
stty -F /dev/gpsdevice 9600 cs8

# send MID 129: Switch to NMEA protocol
send_hex A0 A2 00 18 > /dev/gpsdevice # start sequence and payload length (24 bytes)
send_hex 81 02 01 01 01 01 01 01 01 01 01 01 01 01 00 01 00 01 00 01 00 00 12 C0 > /dev/gpsdevice # payload specifying baudrate and msg rates
send_hex 01 64 B0 B3 > /dev/gpsdevice # checksum and end sequence

# set new tty baudrate for future communication
stty -F /dev/gpsdevice 4800
}}}
  * Note that MID 129 also specifies the period of the various NMEA messages.  If changing the above data you need to also re-calculate the checksum.  See [http://www.wi2wi.com/mgr/docs/One_Socket_Protocol_Interface_Control_Document_(OSP_ICD)_(CS-129291-DC-15).pdf here] section 5.4 for more info on the MID 129 message
  * ensure that /dev/gpsdevice cooresponds to the correct tty above in the [wiki:gps#HardwareUARTMappings hardware mappings section]
 * '''To enable SBAS based DGPS assuming you are already in 9600bd OSP mode''':
{{{
#!/bin/sh

send_hex() {
  while [ "$1" ]; do
    printf "\x$1"
    shift
  done
}

# Make sure we talk to the device at its current configured data format
# (assuming it has been changed to 9600bd)
stty -F /dev/gpsdevice 9600 cs8

# send MID 133: DGPS Source
send_hex A0 A2 00 07 > /dev/gpsdevice # start sequence and payload length (7 bytes)
send_hex 85 02 00 00 00 00 00 > /dev/gpsdevice # payload specifying DPGS Source (Table 5.43)
send_hex 00 87 B0 B3 > /dev/gpsdevice # checksum and end sequence
}}}
  * when DPGS is enabled GGA NMEA messages will show a ''position fix indicator'' of 2 to indicate a DGPS fix vs 1 to indicate a GPS fix.
  * use MID 170 to set SBAS parameters if you need to change the SBAS mode or region between WAAS/EGNOS/MSAS/GAGAN


[=#w2sg0008i-lna]
==== W2SG0008i LNA Gain ====
The W2SG0008i used on most Gateworks Ventana boards defaults on power-up to use its internal high gain LNA which is appropriate for passive antennas but not necessarily appropriate for active-antennas which have their own LNA at the antenna.

While Gateworks has tested,,1,, and found no adverse affects in terms of GPS sensitivity and accuracy when using the [http://shop.gateworks.com/index.php?route=product/product&path=70_71&product_id=51 GW10044 Active GPS antenna] with the default power-up high-gain internal LNA your results may vary depending on your antenna and system characteristics.

If you wish to configure the Ws2G0008i internal LNA for low-gain you must do the following according to the [http://dev.gateworks.com/datasheets/W2SG0008i_Datasheet_Rev1.48.pdf W2SG0008i datasheet] section 6.4.1:
 1. Switch GPS Communication Protocol from NMEA to OSP mode.
 2. Send Tracker Configuration Message (OSP MID 178, 02) - (Disable Internal LNA and drive GPS_EXT-LNA_EN signal)
 3. Wait for SiRFStarIV ACK
 4. Perform a Hot Start reset; Tracker Configuration setting requests in message (OSP MID 178, 02) will apply after performing this reset.
 5. Wait for SiRFStarIV ACK
 6. Switch GPS Communication Protocol back to NMEA.

The gateworks-gps-utils.tar.gz attached at the bottom of this page contains source for a C application "sirf_osp" that will do the above in a short series of commands. After building the application for your BSP run the following commands to put the gps module into LNA low gain mode:
{{{#!bash
DEVICE="/dev/ttymxc4" # Refer to Hardware UART Mappings section above to verify device
./sirf_osp $DEVICE 4800 osp 115200  # Changes board from default NMEA/4800 to OSP/115200
./sirf_osp $DEVICE 115200 lna low   # Sends OSP command for LNA low mode
./sirf_osp $DEVICE 115200 config    # Prints configuration to verify LNA mode of low ("LNA:1")
}}}
 ,,1 See Indoor GPS Testing section below for test details and complete sirf_osp usage example


[=#condor]
===  '''Trimble Condor''' 68674-00 C1011 (GW2380, GW2382, GW2383, GW2387, GW2388, GW2389, GW2391) ===

References:
 * [http://dev.gateworks.com/datasheets/CONDOR_UG_2C_75263-00.pdf Trimble Condor User Guide]
 * [http://dev.gateworks.com/datasheets/Condor_DS.pdf Datasheet]
 * Trimble TSIP reference manual (obtain from Trimble)
 * Trimble TAIP Protocol Reference (obtain from Trimble)

Features:
 * 22-channel continuous tracking receiver:
  - [#gps GPS]: L1C/A (1575.42MHz)
  - [#sbas SBAS]: WAAS: L1C/A (1575.42MHz) (disabled by default)
 * [#dgps Differential GPS] (DGPS)
 * Acquisition: cold start - 38 sec 50%
 * Sensitivity: Tracking -160dBm / Acquisition -146dBm
 * Accuracy:
  * Horizontal w/o SBAS: <2.5m 50%, <5m 90%
  * Horizontal w/ SBAS: <2.0m 50%, <4m 90%
  * Altitude w/o SBAS: <5m 50%, <8m 90%
  * Altitude w/ SBAS: <3m 50%, <5m 90%
  * Velocity: 0.06m/sec
  * PPS: +25ns 1 sigma
 * Communication:
  * 8 data bits, no parity, 1 stop bit (aka '''8N1''' or '''cs8'''), no flow control
  * baudrate: can vary between 4800 and 115200 - refer to user guide for details on changing baudrate
  * [#nmea0183 NMEA 0183] v3.0, 1Hz - 5Hz NMEA update rate, supports: GLL, RMC, VTG, GGA, GSA, GSV, ZDA messages
  * TSIP (Trimble Standard Interface Protocol)
  * TAIP (Trimble ASCII Interface Protocol)
 * [#pps PPS]:
  * ±25ns 1 sigma accuracy, configurable pulse width between 61ns and 998ms and configurable delay between 61ns and 998ms (see [http://dev.gateworks.com/datasheets/CONDOR_UG_2C_75263-00.pdf PMTK_API_SET_OUTPUT_CTL (PMTK324)])
  * need to increase the PPS pulse width from the default 4.2us for pps-gpio to detect:
{{{#!bash
echo -n -e "\$PMTK324,0,0,1,0,1639344*24\r\n" > /dev/ttyS2 # 100ms pulse width on fix
}}}
  * if you want to also assert PPS when GPS position is not yet fixed:
{{{#!bash
echo -n -e "\$PMTK324,0,0,1,1,1639344*25\r\n" > /dev/ttyS2 # 100ms pulse width no fix
}}}

Power-on Default configuration:
 * 9600 baud
 * output NMEA {{{RMC}}}, {{{GGA}}}, {{{GSV}}}, and {{{GSA}}} messages 1 time for every position fix (1Hz)
 * PPS: 4.2us active-high with no GPS fix required ('''see above for details on increasing pulse-width if you want to use PPS''')

==== NMEA Configuration ====
The types of NMEA messages and their rates can be configured by sending {{{PMTK}}} messages.

Refer to the User guide for a full listing.

Notes:
 * be sure to re-calculate the checksum using the [http://www.hhhh.org/wiml/proj/nmeaxor.html online NMEA sentence checksum calculator]
 * be sure to choose the correct serial port and baudrate found [#hardware above]

Common configuration items:
 * PMTK251 - Set NMEA baud rate
 * PMTK313 - Set SBAS enable
 * PMTK314 - Set NMEA sentence types and frequency (only RMC, GGA, GSV, and GSA are enabled by default)
 
Examples:
 * To turn on {{{VTG}}} messages at 1Hz (course over ground and ground speed) (disabled by default):
{{{#!bash
stty -F /dev/gpsdevice 4800 cs8
echo -n -e "\$PMTK314,1,1,1,1,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0*28\r\n" > /dev/gpsdevice
}}}


[=#antenna]
== Antennas ==
GPS receivers can use active or passive GPS antennas. An active antenna is powered and uses an LNA (Low Noise Amplifier) at the antenna instead of at the GPS receiver making it more sensitive than a typical passive antenna.

Some of the GPS modules can be used with passive antenna. See the modules datasheet for more information. Gateworks provides 3.3V for the active antenna DC voltage on all boards.

Gateworks typically uses a 50 ohm MMCX connector on it's board however as a special configuration a U.FL connector can be loaded in the same location.

Here is an SMA antenna we sell in our shop that is 50 Ohm and 27-28 dBi (+- 3-4dBi) - GW10044:
 * Shop [http://shop.gateworks.com/index.php?route=product/product&path=70_71&product_id=51 Gateworks Shop - GPS Antenna]
 * [http://dev.gateworks.com/datasheets/Trimble_GPS_Antennas.pdf Datasheet]

Antenna Adapter Cables:
 * GW10074 SMA to MMCX: [http://shop.gateworks.com/index.php?route=product/product&product_id=59&search=gw10074 GW10074]
 * GW10036 SMA to U.FL: [http://shop.gateworks.com/index.php?route=product/product&product_id=42&search=gw10036 GW10036]
 * GW10053 SMA to U.FL: (long barrel for thick enclosures): [http://shop.gateworks.com/index.php?route=product/product&product_id=15&search=gw10053 GW10053]
 * GW10037 SMA to N-Male: [http://shop.gateworks.com/index.php?route=product/product&product_id=43&search=gw10037 GW10037]
 * GW10080 Fakra to MMCX(special order, contact factory): [http://shop.gateworks.com/index.php?route=product/product&product_id=62&search=gw10080 GW10080]

=== u-blox EVA-M8M (Ventana product family) ===
Maximum Antenna Gain:
 * 15dB to 50dB recommended

Please also consult the manual / datasheet [#evam8m above].

=== Wi2Wi module (Ventana product family) ===
Maximum Antenna Gain:
 * In high gain mode, a passive antenna acts as input. Total RF gain (sum of internal LNA gain, cable and filter losses) of ≤ 5 dB is considered acceptable.
 * In low gain mode, an active antenna acts as input. Total RF gain (sum of external antenna gain, internal LNA gain, cable and filter losses) of '''14 to 24 dB is considered acceptable'''.

Please also consult the manual / datasheet [#w2sg0008i above].

=== Trimble Condor (Laguna product family) ===
Maximum Antenna Gain:
 * Passive: Does not support
 * Active: 36dB

Please also consult the manual / datasheet [#condor above].


=== Active Antenna Short Circuit Detect / Recover ===
All Gateworks boards with on-board GPS support active (powered) GPS antenna connections. On many boards that have a [wiki:gsc Gateworks System Controller] the antenna power is periodically monitored (1Hz) for short circuit and automatically disabled/re-enabled to allow resolving the GPS antenna without power cycling the unit.

See the product manual for your board to determine if it has this capability.


[=#usb]
= Add-in cards supporting GPS =
There are many GPS receivers that communicate over UART or USB-UART. Some of these are in the miniPCIe form-factor which provides USB to the connector (Note that USB is not routed to all Gateworks miniPCIe connectors - consult the product user manual for details on your board).

References:
 * [wiki:wireless/modem#SpecificModemNotes Modem Notes]
 * Option GTM6xx:
  * [http://www.option.com/download/?file=GTM6xx_Nyos_AT_Command_GPS_v015ext.pdf AT command set]



[=#nmea0183]
= NMEA 0183 =
NMEA 0183 is a combined electrical and data specification for communication between marine electronics such as echo sounder, sonars, anemometer, gyrocompass, autopilot, GPS receivers and many other types of instruments. It has been defined by, and is controlled by, the National Marine Electronics Association. It replaces the earlier NMEA 0180 and NMEA 0182 standards.[1] In marine applications, it is slowly being phased out in favor of the newer NMEA 2000 standard.

Most GPS receivers use this standard for communication, however typically they may only use a subset of the standard, add their own proprietary commands, and use different baudrates.  Refer to the specific GPS receiver documentation being used for details.

Most GPS devices allow customizing the NMEA output such as the UART baudrate, the types of messages, and the rate at which they are sent. Please see sections above for the particular GPS device you are interested in configuring

NMEA messages end with a checksum and most devices will ignore messages with an invalid checksum. You can use the [http://www.hhhh.org/wiml/proj/nmeaxor.html online NMEA sentence checksum calculator] to aid you.

References:
 * [http://en.wikipedia.org/wiki/NMEA_0183 Wikipedia NMEA 0183]
 * NMEA reference - http://www.gpsinformation.org/dale/nmea.htm
 * NMEA sentence checksum calculator - http://www.hhhh.org/wiml/proj/nmeaxor.html


[=#pps]
= Time synchronization via PPS (Pulse-Per-Second) =
One handy feature of an on-board GPS is that it can deliver Pulse-Per-Second (PPS) signal.  This signal can be used to get a high-precision time reference that an application can use to adjust system clock time.

PPS is supported by the Linux kernel by the {{{pps-gpio}}} driver (CONFIG_PPS_CLIENT_GPIO). This adds a pps device to {{{/sys/class/pps}}} which you can interact with:
{{{#!bash
# cat /sys/class/pps/pps0/assert
170026870.983207967#8
}}}
 * The above shows the most recent timestamp and sequence number that has been asserted via PPS

Common use is to configure the Network Time Protocol Daemon (NTPD) with a PPS source to obtain a wallclock-time with sub-millisecond synchronization to UTC.

The various Gateworks Board Support Packages includes PPS support (if a GPS is present). However, in order to hook NTPD with a PPS source, you have to have the fully featured ntpd package (i.e. not busybox).

Note that the {{{gpsd}}} app will keep your NTP service syncrhonized to the time from a GPS:
 - see [#gpsd]
 - see https://gpsd.gitlab.io/gpsd/gpsd-time-service-howto.html

The PPS signal is also routed to a spare pin on the miniPCIe slots of many models:
||= Model =||= Revision Introduced =||= Pin =||= PCIe Slot =||= Resistor Loading =||
|| GW51xx || Rev C               || 49       || J6    || R118            ||
|| GW52xx || Rev C               || 49       || J7,J8 || R190/J8 R191/J7 ||
|| GW53xx || Rev C               || 49       || J7,J8 || R212/J7 R213/J8 ||
|| GW553x || Rev A               || 49       || J5    || R31             ||
|| GW54xx || Rev E               || 49       ||       ||                 ||

Reference:
 - [https://www.kernel.org/doc/Documentation/pps/pps.txt Linux PPS Documentation]
 - [http://linuxpps.org/doku.php LinuxPPS]
 - [http://www.catb.org/gpsd/gpsd-time-service-howto.html GPSD Time Service] - Lots of examples relating to gpsd
 - [http://tools.ietf.org/html/rfc2783 RFC 2783] - Pulse-Per-Second API for UNIX-like Operating Systems.  This describes the Linux OS API for userland applications to access a PPS source.
 - [http://lxr.linux.no/linux+v2.6.38.8/Documentation/ABI/testing/sysfs-pps Documentation/ABI/testing/sysfs-pps] - Linux sysfs pps class documentation (sysfs API for Userland apps to interface with PPS from LinuxPPS kernel support above)
 - [http://lxr.linux.no/linux+v2.6.38.8/include/linux/pps.h include/linux/pps.h] - Linux ioctl pps documentation/support (ioctl API for Userland apps to interface with PPS from LinuxPPS kernel support above)


[=#gpsd]
= gpsd
gpsd is a service daemon that monitors one or more GPS devices via serial or USB making all the data on location/course/velocity available to be queried on a TCP port. There are multiple client applications that can connect to a gpsd server.

Example:
 * Ubuntu Focal:
  1. Install apps
{{{#!bash
root@focal-venice:~# apt update
root@focal-venice:~# apt-get install gpsd gpsd-dbg gpsd-clients
}}}
  2. Configure gpsd via /etc/defaults/gpsd
{{{
root@focal-venice:~# cat /etc/default/gpsd
# Default settings for the gpsd init script and the hotplug wrapper.

# Start the gpsd daemon automatically at boot time
START_DAEMON="true"

# Use USB hotplugging to add new USB devices automatically to the daemon
USBAUTO="true"

# Devices gpsd should collect to at boot time.
# They need to be read/writeable, either by user gpsd or the group dialout.
DEVICES=""

# Other options you want to pass to gpsd
GPSD_OPTIONS=""
root@focal-venice:~# cat /etc/default/gpsd
root@focal-venice:~# sed -i 's;DEVICES="";DEVICES="/dev/ttymxc0";' /etc/default/gpsd
}}}
   * replace the above with the proper GPS device for your system - see [#uart]
  3. Restart the gpsd service
{{{#!bash
root@focal-venice:~# systemctl restart gpsd.socket
}}}
  4. Verify gpsd is listening:
{{{#!bash
root@focal-venice:~# netstat -a | grep gpsd
tcp        0      0 localhost:gpsd          0.0.0.0:*               LISTEN     
tcp6       0      0 localhost:gpsd          [::]:*                  LISTEN     
unix  2      [ ACC ]     STREAM     LISTENING     23508    /run/gpsd.sock
}}}
  4. Verify gpsd is working using one of its client apps, for example cgps which is a simple terminal client:
{{{#!bash
root@focal-venice:~# cgps
}}}


Troubleshooting:
 * you can run gpsd manually in foreground with the '-N' parameter and enable debugging with the '-D' parameter to see any errors. Make sure nothing is running that is listening to the gpsd port first
{{{#!bash
root@focal-venice:~# systemctl stop gpsd.socket
root@focal-venice:~# netstat -a | grep gps
root@focal-venice:~# gpsd -N -D3 /dev/ttymxc0
gpsd:INFO: launching (Version 3.21)
gpsd:INFO: listening on port gpsd
gpsd:INFO: stashing device /dev/ttymxc0 at slot 0
gpsd:INFO: running with effective group ID 20
gpsd:INFO: running with effective user ID 108
gpsd:INFO: startup at 2021-10-08T21:30:00.000Z (1633728600)
}}}


[=#dgps]
= Differential GPS (DGPS) =
[http://en.wikipedia.org/wiki/Differential_GPS Differential Global Positioning System] (DGPS) is an enhancement to GPS that provides improved location accuracy from the 15-meter nominal GPS accuracy to about 10cm in the case of the best implementations.


[=#rtcm]
== Radio Technical Commission for Maritime Services (RTCM) ==
The standards applying to Differential Global Navigation Satellite Systems (DGNS) are defined by the Special Committee 104 of the [http://www.rtcm.org/about.html#Standards Radio Technical Commission for Maritime Services] (RTCM). Except for RTCM, there exist other proprietary DGPS standards, such as Trimble Compact Measurement Record (CMR).

References:
 * http://www.navipedia.net/index.php/DGNSS_Standards#RTCM_Standards


== Traditional land-based beacon DGPS ==
Traditional DGPS uses a network of fixed ground-based reference stations that broadcast the difference between their known location and the location determined via GPS.  These stations would broadcast using VHF/UHF which traditionally were available on maritime vessels where GPS was originally intended to be used.

To use this you must have a receiver that can receive both GPS broadcasts as well as the VHF/UHF broadcasts from the land-based beacons.  In addition you need to be in an area that has such land based beacons.  The U.S. Coast Guard and Canadian Coast Guard operate these near large waterways.


[=#waas]
== Wide Area Augmentation System (WAAS) ==
An alternative system was developed called Wide Area Augmentation System (WAAS) which uses satellites in geostationary orbit that receive broadcasts from fixed ground-based stations.  In this system the additional satellites periodically broadcast (about every 5 seconds) a Deviation Correction (DC) created from the data continually received from the ground based reference systems.  This signal can be received with the same receiver used to receive signals from traditional GPS satellites.

To use this you need only a receiver that can receive GPS broadcasts, however you still need to be in an area that both has ground based reference stations and need to have at least 1 SBAS capable satellite in view.  This system was created for North America however there are SBAS based systems being developed in Europe and Asia as well:
 * SBAS - North America / Hawaii Satellite-Based Augmentation System
 * EGNOS - European Geostationary Navigation Overlay Service
 * MSAS - Jpanase Multi-functional Satellite Augmentation System
 * GAGAN - Indian GPS Aided Geo Augmented Navigation


[=#test]
= Indoor GPS Testing =
Gateworks uses a GPS repeater when doing in-building GPS testing. These can be found from a variety of vendors:

The unit we use is the [http://www.amazon.com/Signal-Repeater-Amplifier-Transfer-Distance/dp/B00IIEEJUW/ref=br_lf_m_ckrph3puz9ft7ot_1_1_ttl?ie=UTF8&s=gps Sumalink SL1500] available for $200 and features:
 * L1 GPS: 1575±5MHz
 * 5V DC input
 * Interference suppression: >=20dB;
 * Reflection loss: -14dB
 * Range: 15 meters (re-transmission range)
 * Cable: 30 meters (cable from rooftop receiver to transmitter)

[[Image(SL1500.jpg,400px)]]

We use various test software including:
 * [http://trac.gateworks.com/attachment/wiki/gps/test_gps test_gps] - shell script that parses GSV, GGA, GSA messages and provides fix, average satellites in view, and signal strength details
 * gpsd and related clients (gpxlogger can capture a path to an XML file, GPS Babel can convert GPX log to KML, Google Earth can view KML files)
 * sirf_osp - C application used for sending commands and receiving messages from ventana gps devices

An example of a test procedure carried out on our gps devices was the verification of optimal LNA mode for Ventana boards when using our standard active antenna. The procedure for this test is defined as follows:
 1. Power on the device with antenna connected
 2. Download the gateworks-gps-utils.tar.gz (see bottom attachments) and extract
 3. Use the Makefile provided to build the sirf_osp application (refer to your BSP's 'Building' wiki for help)
 4. Make the application executable {{{chmod +x sirf_osp}}}
 5. Put the device into osp mode {{{./sirf_osp <device> <baud> osp 115200}}}
 6. Set the LNA mode of the device {{{./sirf_osp <device> 115200 lna <low/high>}}}
 7. Verify the LNA mode via the "LNA:X" field of {{{./sirf_osp <device> 115200 config}}}
 8. Begin storing gps fix data to file {{{./sirf_osp <device> 115200 csv <filename>}}}
 9. Use gps visualization tool of your choice to analyze gathered data (e.g. Google My Maps)

 ,,*Note: If any sirf_osp command results in a stream of gps data, retrying the command with the correct arguments will typically solve the problem.