.. include:: ../urls.rst .. include:: ../overview/images.rst .. _l5_troubleshooting_gnss: GNSS ==== GNSS (Global Navigation Satellite System) allows the Librem 5 to determine its physical locaiton. The Librem 5 supports the GPS, BeiDou, and Galileo constellations in the default configuration. GLONASS is also supported, but it is not enabled by default as it cannot be used in combination with BeiDou. The regional QZSS constellation (Asia-Oceanea, with focus on Japan) is also supported, but is not enabled by default on the Librem 5. .. _l5_troubleshooting_gnss_agps: Assisted GNSS ------------- `Assisted GNSS `_ (A-GNSS) is essential for fast location fixes. It provides current information about the positions of GNSS satellites to the phone. Before doing any further troubleshooting, perform these steps to obtain current A-GNSS data. A-GNSS data generally remains valid for a few days. #. Open the Terminal application #. Install Git and socat if you have not installed them before: ``sudo apt install git socat`` #. Obtain the latest A-GNSS scripts: ``git clone https://source.puri.sm/snippets/1207.git; cd 1207`` * Or, if you have cloned this before, to update: ``cd 1207; git pull origin --ff-only`` #. Open a second tab in the Terminal #. In the second tab, monitor the GNSS module: ``sudo unix:///var/run/gnss-share.sock`` * You will be prompted for your password by ``sudo``, type it and press Enter. For security, nothing is shown on the screen while typing your password. * This powers on the GNSS module if it is not already on, and you will see the communication with the module. #. Return to your first tab, and load the current A-GNSS data from Purism's server: ``sudo ./agps.py -i -c /dev/gnss0`` * Again, you will be prompted for your password by ``sudo``. * Wait for this to complete. #. Return to the second tab. #. Wait for the GNSS module's CPU usage to drop to around 15-30% before exiting ``socat``, this indicates it has finished processing the data. Module CPU usage is indicated in the ``$PSTMCPU`` lines. When complete, press Ctrl+C to terminate ``socat``. With the assisted GNSS data, the Librem 5 can typically get a fix within about 10 seconds once it has a clear view of the sky. Remember that clouds, tall buildings, and other structures will reduce GNSS signal for any device. Typically, if GNSS is used with a good signal for roughly 30-60 minutes per day, the module will be able to keep these data updated by receiving new data from the sky. There is still an advantage to running the process every few days though, as this provides the current ephemerides for all satellites. Troubleshooting --------------- To troubleshoot the module, view the module's output in a terminal: #. Open the Terminal application #. Monitor the GNSS module: ``sudo unix:///var/run/gnss-share.sock`` * Again, you will be prompted for your password by ``sudo``. The output displays NMEA sentences produced by the module. Check for visible satellites and signal ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Check to see if the module reports any visible satellites in lines labeled ``$GPGSV`` (GPS), ``$GAGSV`` (Galileo), and ``$BDGSV`` (BeiDou). Visible satellites should be reported if the A-GNSS data is loaded correctly, even if indoors. .. code-block:: $GPGSV,3,1,11,04,82,208,,03,54,103,,09,46,238,,06,39,306,*74 $GPGSV,3,2,11,31,32,054,,19,21,264,,01,21,163,,28,13,036,*7A $GPGSV,3,3,11,17,11,239,,11,10,321,,26,09,087,,,,,*44 In this output: * ``$GPGSV`` - these are GPS satellites. ``$GAGSV`` and ``$BDGSV`` follow the same format for Galileo and BeiDou. * ``3`` - number of output lines in this group * ``1``, ``2``, ``3`` - line numbers * ``11`` - number of satellites visible * Remaining fields - groups of 4 values indicating each satellite. The fourth value is the signal level, which is blank if we are not receiving a signal. In this example, 11 satellites are visible, but the module is not receiving a signal from any. (The signal level fields are all empty, this is an indoor example.) With a good view of the sky, you should see satellites with a signal level, such as: .. code-block:: $GPGSV,3,1,10,05,77,249,25,20,61,042,14,29,46,312,25,11,41,073,17*78 ^^ ^^ ^^ ^^ The marked fields show that a signal is received from these satellites. If there are no visible satellites, :ref:`load updated A-GNSS data `. If there are visible satellites but no signal, ensure you have a clear view of clear sky. If you have previously disassembled the phone, ensure that the :ref:`GNSS grounding clip ` was not damaged and contacts the phone frame. Check for tracked satellites ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When receiving a signal, the module should select some satellites to track. The ``$GNGSA`` statement indicates which satellites are tracked. It appears once each for GPS, Galileo, and BeiDou (but uses the same label, unlike visible satellites). With tracked satellites, it will indicate satellite numbers: .. code-block:: $GNGSA,A,3,29,11,13,05,12,25,,,,,,,3.1,1.4,2.7*26 ^^ ^^ ^^ ^^ ^^ ^^ If there are no tracked satellites, there will be no satellite numbers: .. code-block:: $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0*1E Check for a fix ^^^^^^^^^^^^^^^ When there are enough tracked satellites, the module will obtain a location fix. The ``$GPGLL`` statement reports the location status. The second-to-last field is either ``A`` for a valid fix, or ``V`` for no fix. The preceding fields report the coordinates and time. Coordinates may be reported if there is no fix, so check the fix status. (These may be coordinates from the last fix or initial approximate coordinates from loading AGPS data). With a location fix: .. code-block:: $GPGLL,4187.81130,N,08762.97995,W,211515.000,A,N*54 ^ Without a location fix: .. code-block:: $GPGLL,4187.81130,N,08762.97995,W,211515.000,V,N*54 ^ The coordinates in these examples are 41.8781130 N, 87.6297995 W. The remaining number is a timestamp.