# Adafruit Ultimate GPS with gpsd ## Introduction ![](https://cdn-learn.adafruit.com/assets/assets/000/003/714/medium800/raspberry_pi_gps_pi_usbconnection2.jpg?1396801034) How easy is it to get your Raspberry Pi eavesdropping on satellites 20,000 km up in the sky? Wonderfully easy thanks to Linux, and affordable thanks to Adafruit's [Ultimate GPS Breakout](http://www.adafruit.com/products/746)! This quick learning guide will show you everything you need to do to add position tracking to your Pi project using the open source GPS daemon 'gpsd' and an inexpensive [USB to TTL adapter cable](http://www.adafruit.com/products/954 "Link: http://www.adafruit.com/products/954") or via direct-wiring to the built-in Pi UART pins Danger: If you don't need **gpsd** , click below to follow the pure-python GPS tutorial [Using the Ultimate GPS directly with Python / CircuitPython](https://learn.adafruit.com/adafruit-ultimate-gps/circuitpython-parsing) # What you'll need: - [A Raspberry Pi](https://www.adafruit.com/products/998) - An [Ultimate GPS Breakout](https://www.adafruit.com/products/746) - A [USB to TTL Adapter](https://www.adafruit.com/products/954) Cable (or something compatible) **[Don't forget to also read our Ultimate GPS tutorial which has a lot of information about this GPS module and datasheets/example code that you will find handy!](http://learn.adafruit.com/adafruit-ultimate-gps "Link: http://learn.adafruit.com/adafruit-ultimate-gps")** # Adafruit Ultimate GPS with gpsd ## Setting Everything Up The easiest way to get started is to use an inexpensive [USB to TTL adapter cable](http://www.adafruit.com/products/954) with your GPS module. You can of course use the HW UART directly on the Pi, but as you can see in this tutorial ([Freeing UART on the Pi](http://learn.adafruit.com/adafruit-nfc-rfid-on-raspberry-pi/freeing-uart-on-the-pi)) it's a bit more complicated, and there are no secondary consequences with the USB adapter. This tutorial will assume that we are using the USB to TTL cable mentioned above, and that we are running on Raspbian. Raspbian already has the drivers for PL2303-based cables pre-installed, so you just need to plug it in and it should show up as **/dev/ttyUSB0** ). # Hooking The Breakout Up The first thing you'll need to do is to hook your Ultimate GPS Breakout up to the Pi with the adapter cable. The following diagram shows you what you need to know, essentially just connecting the cables of the same color together. - **GPS Vin**   to **USB** **5V** or **3V** (red wire on USB console cable) - **GPS Ground** to **USB Ground** (black wire) - **GPS RX** to **USB TX** (green wire) - **GPS TX** to **USB RX** (white wire) ![](https://cdn-learn.adafruit.com/assets/assets/000/062/846/medium800/sensors_usbgps_bb.png?1538428053) While the module on the Ultimate GPS Breakout has an exceptionally sensitive antenna and may work indoors as is, you may want to pick up an [external GPS Antenna](http://www.adafruit.com/products/960) and an [SMA to u.FL adapter cable](http://www.adafruit.com/products/851 "Link: http://www.adafruit.com/products/851") if this is for indoor use. This will allow you to keep the Pi and GPS breakout indoors, but run the antenna out a window or at least near one for improved reliability and signal integrity. # Setting up the USB Adapter Once you plug the USB cable into the Pi, the adapter should show up as /dev/ttyUSB0 (though the '0' may be different if you have other ttyUSB adapters present). You can see a list of all ttyUSB devices by entering the following into the console (I'm using the 'terminal' feature in Adafruit's browser-based WebIDE here for convenience sake!): ```auto ls /dev/ttyUSB* ``` ![](https://cdn-learn.adafruit.com/assets/assets/000/003/708/medium800/raspberry_pi_ls.png?1396800943) If you have any problems, you can enter the following command to see the USB devices on your Pi: ```auto sudo lsusb ``` Which should show you the USB adapter (Prolific PL2303), as follows: ![](https://cdn-learn.adafruit.com/assets/assets/000/003/707/medium800/raspberry_pi_lsusb.png?1396800934) If you just want to do a quick check to see what data is coming out of the GPS, you can enter the following command, followed by **Ctrl-C** to quit: ```auto sudo cat /dev/ttyUSB0 ``` # Installing a GPS Daemon (gpsd) The next step is installing some software on your Raspberry Pi that understands the serial data that your GPS module is providing via /dev/ttyUSB0. Thankfully other people have already done all the hard work for you of properly parsing the raw GPS data, and we can use (amongst other options) a nice little package named 'gpsd', which essentially acts as a layer between your applications and the actual GPS hardware, gracefully handling parsing errors, and providing a common, well-defined interfaces to any GPS module. To install gpsd, simply run the following commands from the console: ```auto sudo apt-get install gpsd gpsd-clients ``` ... which will install the required packages (an internet connection will be required for this step!) ## Raspbian Jessie systemd service fix Note if you're using the Raspbian Jessie or later release you'll need to disable a systemd service that gpsd installs.  This service has systemd listen on a local socket and run gpsd when clients connect to it, however it will also interfere with other gpsd instances that are manually run (like in this guide).  You will need to disable the gpsd systemd service by running the following commands: ```auto sudo systemctl stop gpsd.socket sudo systemctl disable gpsd.socket ``` Should you ever want to enable the default gpsd systemd service you can run these commands to restore it (but remember the rest of the steps in this guide won't work!): ```auto sudo systemctl enable gpsd.socket sudo systemctl start gpsd.socket ``` After disabling the gpsd systemd service above you're ready to try running gpsd manually.  Now run the following command to manually start gpsd and point it at the GPS breakout on the USB serial adapter port: ```auto sudo gpsd /dev/ttyUSB0 -F /var/run/gpsd.sock ``` ... which will point the gps daemon to our GPS device on the USB to TTY adapter cable (simply substitute '/dev/ttyUSB0' for another destination if required). # Testing it Out After a few seconds, gpsd should open up the proper socket and if the GPS is locked we should be able to get some data from the GPS module. To test this, we can use the following command: ```auto cgps -s ``` If you have a fix, you'll see something like the following information in the terminal window: ![](https://cdn-learn.adafruit.com/assets/assets/000/003/709/medium800/raspberry_pi_cgps.png?1396800953) Danger: ```auto sudo killall gpsd sudo gpsd /dev/ttyUSB0 -F /var/run/gpsd.sock ``` # Adafruit Ultimate GPS with gpsd ## Using your GPS Now that your GPS is up and running, and gpsd is playing nice with it, it's time to do something with the data! The easiest way to get started is using a bit of Python code to access gpsd.  First, install the `gps` module from PyPI: ```auto pip3 install gps ``` Next, use `nano` or the text editor of your choice to save the following code in a file called `gpstest.py`: ```auto import gps # Listen on port 2947 (gpsd) of localhost session = gps.gps("localhost", "2947") session.stream(gps.WATCH_ENABLE | gps.WATCH_NEWSTYLE) while True: try: report = session.next() # Wait for a 'TPV' report and display the current time # To see all report data, uncomment the line below # print(report) if report['class'] == 'TPV': if hasattr(report, 'time'): print(report.time) except KeyError: pass except KeyboardInterrupt: quit() except StopIteration: session = None print("GPSD has terminated") ``` This should give you something similar to the following (with an update every second or so): ![](https://cdn-learn.adafruit.com/assets/assets/000/062/823/medium800/gps_Screenshot-2018-10-01-14_18_29.png?1538425118) Looking for position data rather than just the timestamp? Essentially, all you have to do is parse the 'report' data following the example above. To see what data is available, you can uncomment the `print(report)` line, and then just look at the different values and class names and pick and choose whatever you want. ![](https://cdn-learn.adafruit.com/assets/assets/000/062/850/medium800/gps_Screenshot-2018-10-01-15_11_04.png?1538428590) For example, you could use the following code to get the current speed using the TPV class: ```auto if report['class'] == 'TPV': if hasattr(report, 'speed'): print(report.speed * gps.MPS_TO_KPH) ``` That's it! It's pretty painless, and now it's up to you to figure out what you want to do with you latitude, longitude, date and time, speed, altitude, etc.! # Adafruit Ultimate GPS with gpsd ## Using UART instead of USB If you wish to use HW UART instead of the USB cable, it's perfectly possible - you just need to do a bit more work to free the UART up on your Pi. To get started, hook the GPS module up to your Pi as follows, cross-connecting the TX and RX pins (TX on one device goes to RX on the other and vice versa), and supply 5V from the Pi to the VIN pin on the GPS module: Danger: - **GPS Vin**   to **3.**** 3V** (red wire) - **GPS Ground** to **Ground** (black wire) - **GPS RX** to **TX** (green wire) - **GPS TX** to **RX** (white wire) ![sensors_uartgps_bb.png](https://cdn-learn.adafruit.com/assets/assets/000/062/851/medium640/sensors_uartgps_bb.png?1538428733) # Disable Serial console and Enable UART Run **sudo raspi-config** and select the following: **Interfacing Options** ![gps_sensors_inter.png](https://cdn-learn.adafruit.com/assets/assets/000/059/452/medium640/gps_sensors_inter.png?1534704800) **Serial** ![gps_sensors_inter.png](https://cdn-learn.adafruit.com/assets/assets/000/059/453/medium640/gps_sensors_inter.png?1534704919) Select **No** on enabling the login shell ![gps_sensors_inter.png](https://cdn-learn.adafruit.com/assets/assets/000/059/454/medium640/gps_sensors_inter.png?1534704952) Select **Yes** on enabling serial port hardware ![gps_sensors_inter.png](https://cdn-learn.adafruit.com/assets/assets/000/059/455/medium640/gps_sensors_inter.png?1534704977) Once complete you should have no console and yes on serial interface: [![sensors_image.png](https://cdn-learn.adafruit.com/assets/assets/000/059/447/medium800/sensors_image.png?1534652609) ](https://learn.adafruit.com/assets/59447) Then **reboot** Once you've rebooted, you can use the built in UART via `/dev/ttyS0` or `/dev/serial0`. # Reboot your Pi After rebooting the Pi for the above changes to take effect, you can proceed with running gpsd   # Restart GPSD with HW UART Restart gpsd and redirect it to use HW UART instead of the USB port we pointed it to earlier. Simply entering the following two commands. For the **Raspberry Pi 1 or 2** (but **NOT** the 3!) run these commands: ```auto $ sudo killall gpsd $ sudo gpsd /dev/ttyAMA0 -F /var/run/gpsd.sock ``` And for the **Raspberry Pi 3** or the **Pi Zero** **W** , run these commands to use the different serial port: ```auto sudo killall gpsd sudo gpsd /dev/serial0 -F /var/run/gpsd.sock ``` As with the USB example, you can test the output with: ```auto $ cgps -s ``` # Adafruit Ultimate GPS with gpsd ## Further Resources [Don't forget to also read our bigger tutorial on the Ultimate GPS which has lots more details, datasheets and examples for setting the sentences, update rate, etc!](http://learn.adafruit.com/adafruit-ultimate-gps "Link: http://learn.adafruit.com/adafruit-ultimate-gps") The following tutorials may be useful to you if you want to dig into this a bit further, and do something a bit more advanced with your GPS data: - [GETTING GPS TO WORK ON A RASPBERRY PI](http://blog.retep.org/2012/06/18/getting-gps-to-work-on-a-raspberry-pi/ "Link: http://blog.retep.org/2012/06/18/getting-gps-to-work-on-a-raspberry-pi/"). - [GPSD Client How-To](http://wiki.ros.org/gpsd_client/Tutorials/Getting%20Started%20with%20gpsd_client "Link: http://wiki.ros.org/gpsd\_client/Tutorials/Getting%20Started%20with%20gpsd\_client") - [A nice writeup of using GPSd with python using threads to make it faster](http://www.danmandle.com/blog/getting-gpsd-to-work-with-python/) Doing something fun with GPS and tracking data? Be sure to post about it in the [Adafruit forums](http://forums.adafruit.com/) so everyone else can get inspired by it! ## Featured Products ### Adafruit Ultimate GPS Breakout - 66 channel w/10 Hz updates [Adafruit Ultimate GPS Breakout - 66 channel w/10 Hz updates](https://www.adafruit.com/product/746) We carry a few different GPS modules here in the Adafruit shop, but none that satisfied our every desire - that's why we designed this little GPS breakout board. We believe this is the **Ultimate** GPS module, so we named it that. It's got everything you want and... Out of Stock [Buy Now](https://www.adafruit.com/product/746) [Related Guides to the Product](https://learn.adafruit.com/products/746/guides) ### GPS Antenna - External Active Antenna - 3-5V 28dB 5 Meter SMA [GPS Antenna - External Active Antenna - 3-5V 28dB 5 Meter SMA](https://www.adafruit.com/product/960) Give your Ultimate GPS V3 a boost with this external active antenna. This GPS antenna draws about 10mA and will give you an additional 28 dB of gain. It's got a 5 meter long cable so it will easily reach wherever you need it to. The antenna is magnetic so it will stick to the top of a car... In Stock [Buy Now](https://www.adafruit.com/product/960) [Related Guides to the Product](https://learn.adafruit.com/products/960/guides) ### SMA to uFL/u.FL/IPX/IPEX RF Adapter Cable [SMA to uFL/u.FL/IPX/IPEX RF Adapter Cable](https://www.adafruit.com/product/851) This RF adapter cable is super handy for anyone doing RF work. Often times, small electronics save space by having a pick-and-placeable u.FL connector (also called uFL, IPEX, IPAX, IPX, MHF, and AM). But most antennas have SMA or RP-SMA connectors on them. This little cable will bridge the... In Stock [Buy Now](https://www.adafruit.com/product/851) [Related Guides to the Product](https://learn.adafruit.com/products/851/guides) ### USB to TTL Serial Cable - Debug / Console Cable for Raspberry Pi [USB to TTL Serial Cable - Debug / Console Cable for Raspberry Pi](https://www.adafruit.com/product/954) The cable is easiest way ever to connect to your microcontroller/Raspberry Pi/WiFi router serial console port. Inside the big USB plug is a USB\<-\>Serial conversion chip and at the end of the 36" cable are four wire - red power, black ground, white RX into USB port, and green TX out... In Stock [Buy Now](https://www.adafruit.com/product/954) [Related Guides to the Product](https://learn.adafruit.com/products/954/guides) ### Raspberry Pi Model B 512MB RAM [Raspberry Pi Model B 512MB RAM](https://www.adafruit.com/product/998) Adafruit ships the **Raspberry Pi Model B 512MB RAM** as of 10/18/2012. The Raspberry Pi® is a single-board computer developed in the UK by the Raspberry Pi Foundation with the intention of stimulating the teaching of basic computer science in schools. The Raspberry... No Longer Stocked [Buy Now](https://www.adafruit.com/product/998) [Related Guides to the Product](https://learn.adafruit.com/products/998/guides) ## Related Guides - [Esenciales para CircuitPython](https://learn.adafruit.com/esenciales-para-circuitpython.md) - [CircuitPython Essentials](https://learn.adafruit.com/circuitpython-essentials.md) - [Adafruit Ultimate GPS](https://learn.adafruit.com/adafruit-ultimate-gps.md) - [Adafruit Ultimate GPS Logger Shield](https://learn.adafruit.com/adafruit-ultimate-gps-logger-shield.md) - [Adding a Single Board Computer to Blinka](https://learn.adafruit.com/adding-a-single-board-computer-to-blinka.md) - [Reverse Geocache Box](https://learn.adafruit.com/reverse-geocache-engagement-box.md) - [GPS Dog Collar](https://learn.adafruit.com/gps-dog-collar.md) - [CircuitPython Libraries on Linux and the NVIDIA Jetson Nano](https://learn.adafruit.com/circuitpython-libraries-on-linux-and-the-nvidia-jetson-nano.md) - [Arduino GPS Clock](https://learn.adafruit.com/arduino-clock.md) - [Adafruit Mini GPS PA1010D Module](https://learn.adafruit.com/adafruit-mini-gps-pa1010d-module.md) - [How to register your drone in the US](https://learn.adafruit.com/how-to-register-your-drone-in-the-usa.md) - [Windows IoT Core Application Development: Headless Blinky](https://learn.adafruit.com/windows-iot-application-development-headless-application.md) - [Flora Wearable GPS](https://learn.adafruit.com/flora-wearable-gps.md) - [Adafruit's Raspberry Pi Lesson 3. Network Setup](https://learn.adafruit.com/adafruits-raspberry-pi-lesson-3-network-setup.md) - [Processing on the Raspberry Pi & PiTFT](https://learn.adafruit.com/processing-on-the-raspberry-pi-and-pitft.md)