1  
  2  Introduction
  3  ============
  4  
  5  .. image:: https://readthedocs.org/projects/adafruit-circuitpython-gps/badge/?version=latest
  6      :target: https://circuitpython.readthedocs.io/projects/gps/en/latest/
  7      :alt: Documentation Status
  8  
  9  .. image :: https://img.shields.io/discord/327254708534116352.svg
 10      :target: https://adafru.it/discord
 11      :alt: Discord
 12  
 13  .. image:: https://github.com/adafruit/Adafruit_CircuitPython_GPS/workflows/Build%20CI/badge.svg
 14      :target: https://github.com/adafruit/Adafruit_CircuitPython_GPS/actions/
 15      :alt: Build Status
 16  
 17  GPS parsing module.  Can parse simple NMEA data sentences from serial GPS
 18  modules to read latitude, longitude, and more.
 19  
 20  
 21  Dependencies
 22  =============
 23  This driver depends on:
 24  
 25  * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
 26  
 27  Please ensure all dependencies are available on the CircuitPython filesystem.
 28  This is easily achieved by downloading
 29  `the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 30  
 31  Installing from PyPI
 32  ====================
 33  
 34  On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
 35  PyPI <https://pypi.org/project/adafruit-circuitpython-gps/>`_. To install for current user:
 36  
 37  .. code-block:: shell
 38  
 39      pip3 install adafruit-circuitpython-gps
 40  
 41  To install system-wide (this may be required in some cases):
 42  
 43  .. code-block:: shell
 44  
 45      sudo pip3 install adafruit-circuitpython-gps
 46  
 47  To install in a virtual environment in your current project:
 48  
 49  .. code-block:: shell
 50  
 51      mkdir project-name && cd project-name
 52      python3 -m venv .env
 53      source .env/bin/activate
 54      pip3 install adafruit-circuitpython-gps
 55  
 56  Usage Example
 57  =============
 58  
 59  See examples/gps_simpletest.py for a demonstration of parsing and printing GPS location.
 60  
 61  Important: 
 62  Feather boards and many other circuitpython boards will round to two decimal places like this:
 63  
 64  .. code-block:: python
 65  
 66      >>> float('1234.5678')
 67      1234.57
 68  
 69  This isn't ideal for GPS data as this lowers the accuracy from 0.1m to 11m. 
 70  
 71  This can be fixed by using string formatting when the GPS data is output.
 72  
 73  An implementation of this can be found in examples/gps_simpletest.py
 74  
 75  .. code-block:: python
 76  
 77      import time
 78      import board
 79      import busio
 80  
 81      import adafruit_gps
 82  
 83      RX = board.RX
 84      TX = board.TX
 85  
 86      uart = busio.UART(TX, RX, baudrate=9600, timeout=30)
 87  
 88      gps = adafruit_gps.GPS(uart, debug=False)
 89  
 90      gps.send_command(b'PMTK314,0,1,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0')
 91  
 92      gps.send_command(b'PMTK220,1000')
 93  
 94      last_print = time.monotonic()
 95      while True:
 96  
 97          gps.update()
 98  
 99          current = time.monotonic()
100          if current - last_print >= 1.0:
101              last_print = current
102              if not gps.has_fix:
103                  print('Waiting for fix...')
104                  continue
105              print('=' * 40)  # Print a separator line.
106              print('Latitude: {0:.6f} degrees'.format(gps.latitude))
107              print('Longitude: {0:.6f} degrees'.format(gps.longitude))
108  
109  
110  These two lines are the lines that actually solve the issue:
111  
112  .. code-block:: python
113  
114      print('Latitude: {0:.6f} degrees'.format(gps.latitude))
115      print('Longitude: {0:.6f} degrees'.format(gps.longitude))
116     
117  
118  Note: Sending multiple PMTK314 packets with gps.send_command() will not work unless there is a substantial amount of time in-between each time gps.send_command() is called. A time.sleep() of 1 second or more should fix this.
119  
120  About NMEA Data
121  ===============
122  This GPS module uses the NMEA 0183 protocol.
123  
124  This data is formatted by the GPS in one of two ways.
125  
126  The first of these is GGA. GGA has more or less everything you need.
127  
128  Here's an explanation of GGA:
129  ::
130  
131                                                          11
132             1         2       3 4        5 6 7  8   9  10 |  12 13  14   15
133             |         |       | |        | | |  |   |   | |   | |   |    |
134      $--GGA,hhmmss.ss,llll.ll,a,yyyyy.yy,a,x,xx,x.x,x.x,M,x.x,M,x.x,xxxx*hh
135  
136  
137  1. Time (UTC)
138  2. Latitude
139  3. N or S (North or South)
140  4. Longitude
141  5. E or W (East or West)
142  6. GPS Quality Indicator,
143  
144     * 0 - fix not available,
145     * 1 - GPS fix,
146     * 2 - Differential GPS fix
147      
148  7. Number of satellites in view, 00 - 12
149  8. Horizontal Dilution of precision
150  9. Antenna Altitude above/below mean-sea-level (geoid)
151  10. Units of antenna altitude, meters
152  11. Geoidal separation, the difference between the WGS-84 earth ellipsoid and mean-sea-level (geoid), "-" means mean-sea-level below ellipsoid
153  12. Units of geoidal separation, meters
154  13. Age of differential GPS data, time in seconds since last SC104 type 1 or 9 update, null field when DGPS is not used
155  14. Differential reference station ID, 0000-1023
156  15. Checksum
157  
158  The second of these is RMC. RMC is Recommended Minimum Navigation Information.
159  
160  Here's an explanation of RMC:
161  ::
162  
163                                                                 12
164             1         2 3       4 5        6 7   8   9   10   11|
165             |         | |       | |        | |   |   |    |   | |
166      $--RMC,hhmmss.ss,A,llll.ll,a,yyyyy.yy,a,x.x,x.x,xxxx,x.x,a*hh
167  
168  1. Time (UTC)
169  2. Status, V = Navigation receiver warning
170  3. Latitude
171  4. N or S
172  5. Longitude
173  6. E or W
174  7. Speed over ground, knots
175  8. Track made good, degrees true
176  9. Date, ddmmyy
177  10. Magnetic Variation, degrees
178  11. E or W
179  12. Checksum
180  
181  
182  `Info about NMEA taken from here
183  <https://www.tronico.fi/OH6NT/docs/NMEA0183.pdf>`_.
184  
185  Contributing
186  ============
187  
188  Contributions are welcome! Please read our `Code of Conduct
189  <https://github.com/adafruit/Adafruit_CircuitPython_gps/blob/master/CODE_OF_CONDUCT.md>`_
190  before contributing to help this project stay welcoming.
191  
192  Documentation
193  =============
194  
195  For information on building library documentation, please check out `this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.