Quadrino GPS Integrators Guide

Robotshop.com FlyingEinstein.com

The QuadrinoGPS can be purchased from RobotShop.ca at: http://www.robotshop.com/ca/en/flyingeinstein-gps-quadrino.html

The QuadrinoGPS can communicate with any host that supports I2C. This guide explains how to connect to three popular embedded hosts:

Arduino

Raspberry Pi (RPi3)

BeagleBoard Black (BBB)

Table of Contents Preface TL;DR version Quick Facts My Personal Favorite >>> Files <<< Connecting to an Arduino Alternative wiring to Arduino Nano using the ICSP header. This alternative wiring is valid for RaspberryPi, BeagleBone and other embedded boards as well. Quadrino GPS on Linux Wiring to Raspberry Pi Wiring to BeagleBone Black Installing the Linux I2C tools and developer libs (RPi) Re-configure the raspberry to enable i2c: (RPi) Checking QuadrinoGPS electrical connection QuadrinoGPS on Linux from Scratch (...if you absolutely must)

Comparison Between Boards for Source Builds Raspberry PI BeagleBone Black Other Embedded Boards Retrieving the current kernel configuration

Compiling the QuadrinoGPS I2C client driver Configuring the QuadrinoGPS client driver on the I2C bus

Using the /sys interface Configuring the driver to load at boot time

Testing the QuadrinoGPS client driver Installing the GPSD tools

GPSD Clients Configuring GPSD (GPS device & listen on all interfaces)

Appendix A Command Log for preparing RaspberryPi image

Appendix B Command Log for preparing BeagleBone Black image

Appendix C Updating the Firmware on the QuadrinoGPS

Flashing Firmware

Preface This document is available online as a Google Doc at http://tinyurl.com/quadrinogps. This was done so you will always have the latest updates to the document and you are welcome to add feedback via comments which will be read by the authors and used to improve this document. Please, help us make this document better for the community!

TL;DR version Arduino: You’re only a few steps away, review the Arduino wiring diagram and download the sample sketches. Upload a sketch and start the Arduino Serial Monitor. Linux: Download pre-made SD images for your linux board and burn to a new SD card and enjoy...you’re good as a crunchy roll with any GPSd client (including Windows). Otherwise, be ready to build a linux kernel, driver source, and RTFM! So grab some beer, send your wife to the day spa. TL;DR won’t work for you, this document is now your best friend. ;-) (You’re a woman? No worries. Give the man the beer, grab your favorite wobbly pop.)

Quick Facts If you’re a seasoned developer you may just be interested in the following facts:

● Logs to SD card if present, LED startup sequence indicates SD card status. SD card must be formatted as FAT16 or FAT32 filesystem.

● GPS listens at I2C address 0x20 (7bit) and supports “repeated starts”. ● Read the 0x00 register for status information such as 2D/3D fix and number of satellites ● For location read two 32bit integers starting at register 0x07 which are latitude and

longitude. Encoding is fixed-point decimal degrees x10’000’000. ● Refer to Quadrino_gps_registers.h for list of I2C registers including GPS date/time,

altitude, ground speed, etc. ● QuadrinoGPS has an on-board Arduino (like Nano v3) that you can reprogram to suite

your needs. See Customizing QuadrinoGPS firmware.

My Personal Favorite The RPi3 has a quad-core processor and is currently my favorite embedded Linux board. In my experience the BeagleBoneBlack (BBB) was comparable to the performance of the RPi2 with a slight advantage in speed but the BBB was a better overall experience. However the latest RPi3 now sports a quad-core vs BBB’s single core and it’s a faster per-core GHz so it’s currently in a class of it’s own. The RPi3 is also 64bit where the BBB is 32bit, however, the RPi3 is still using the 32bit Linux ARM kernel so this isn’t an advantage yet. I do still like the BBB quick-start process more than any RPi. The BBB team went the extra distance of configuring the BBB as a USB flash drive and web server with documentation and samples on it and a web interface that includes a great web IDE, Node.js and GPIO tools. The BBB is immediately ready to jump into the world of IoT without a single shell command. The RPi is basically like an installation of Ubuntu or Debian Linux on a desktop computer, it’s just as capable as the BBB for IoT but requires a higher Linux skillset. Whatever your favorite may be the operation of the QuadrinoGPS won’t change. So let’s begin.

>>> Files <<<

Arduino Firmware & Sample Files

Download here or from GitHub. The included sample projects read from the GPS and print basic location information. The included firmware can be used to update the GPS device to the current version.

Raspberry Pi Image RPi

SD card image provides the fastest and simplest way to get the Quadrino GPS connected to an RPi. This image requires at least an 8GB SD-card. http://flyingeinstein.com/downloads/raspbian-jessie-quadrinogps.zip

BeagleBone Black Image BBB

SD card image provides the fastest and simplest way to get the Quadrino GPS connected to a BBB, although compiling on an existing BBB linux is easy compared to the RaspberryPi so go either way. http://flyingeinstein.com/downloads/bone-debian-8.4-quadrino-gps.zip

Quadrino GPS Linux Driver RPi, BBB, LInux

Kernel driver provides a TTY interface /dev/ttyGPS0 that can be used with GPSd or custom programs written in python, Node.js, C/C++, bash or other languages. https://github.com/flyingeinstein/quadrino-gps-driver

Connecting to an Arduino This example connects to an Arduino Nano V3 board from Gravitech. The process for any other Arduino is the same but you may need to lookup the pin-out for i2c wiring and in the Arduino IDE select the proper board.

FYI You may be interested to know that the Quadrino GPS already contains an Arduino-like chip on it and the firmware on that chip is coded in Arduino and open-source. You only need an off-the-shelf usb-serial adapter to reprogram the firmware. If your project is small enough you may want to just modify the existing firmware to include your project code and not need a second Arduino!

The basic steps to getting your Quadrino GPS wired to an Arduino board is as follows: 1. Wire the GPS to the Arduino (See example Arduino Nano v3 below) 2. Download the QuadrinoGPS sample files for Arduino IDE 3. Open one of the samples in Arduino IDE (We suggest Arduino_QGPS_Maps ) 4. Select your Board Type and the Serial Port from the menu 5. Click Compile and Upload 6. Open the Arduino Serial Monitor to see the sample code output

As a reference the table below shows where I2C pins are located on various Arduino boards.

Arduino Board SDA SCL Arduino Nano v3 from Gravitech Uno / Ethernet / Nano A4 A5

Mega2560 20 21

Leonardo 2 3

Due 20 21

Example Wiring to Arduino Nano v3 from Gravitech. Plug the Nano into USB and you are ready to roll!

In this image, The Green wire is SCL (clock) and the yellow wire is SDA (data). The pins on the Arduino Nano are labeled for GND (black), 5V (red) and A5 (green) and A4 (yellow), where A5 is SCL and A4 is SDA. The pins on the Quadrino GPS are labelled CLK (green) and DATA (yellow) but for power the labels are icons on the top

side ICSP header indicating GND and 5V.

Alternative wiring to Arduino Nano using the ICSP header. This alternative wiring is valid for RaspberryPi, BeagleBone and other embedded boards as well.

Quadrino GPS on Linux The easiest way to start using the QuadrinoGPS is to download our pre-made image for RPi or BBB. Burn the image to an SD card, wire the GPS, boot and enjoy! The image contains the QuadrinoGPS tty driver, GPSd daemon, and python gps clients.

● Download the RPi SD card image o RaspberryPi o BBB

● Wire the GPS to the board, see Wiring the RPi or BBB chapter. ● Boot the board ● Login using pi/raspberry on RPi or debian/temppwd on BBB ● Test the GPS

o From Gnome/x-windows run xgps o From ssh, run gpsmon o From ssh, cat /dev/ttyGPS0

Wiring to Raspberry Pi This example connects to a Raspberry Pi version 3 (latest). There should be no changes for RPi2. There may be minor changes for RPi1, if you encounter any issues please contact me so I can update this document.

Wiring to BeagleBone Black The BeagleBone Black has 3 I2C ports with 2 of them available externally, but only I2C port 2 is shows in the pin-out diagram so we’ll wire our GPS to this port as shown in the image below. This is on expansion header P9 pins 19 (SCL) & 20 (SDA). Once connected and powered on you can confirm proper wiring using the command i2cdetect -y -r 2.

Installing the Linux I2C tools and developer libs (RPi) On RaspberryPi, Install i2c tools and developer libs. This provides some useful user-space i2c commands and the development libraries for writing gps applications. These tools are installed by default on BeagleBone Black.

sudo apt-get install i2c-tools libi2c-dev

Re-configure the raspberry to enable i2c: (RPi) You need to run the raspi-config program (as root) and select the modules (SPI or I2C) that you wish to load/unload there and reboot. This will create the i2c device control directory:

/sys/devices/platform/soc/3f804000.i2c/i2c-1

There is more information here: https://www.raspberrypi.org/forums/viewtopic.php?f=28&t=97314

sudo raspi-config

● Select Advanced Options | I2C ● Enable both the ARM I2C interface and i2c kernel module

Checking QuadrinoGPS electrical connection We can check that the proper wiring connection to the GPS has been made by using the i2c-tools to scan the i2c bus. We should find a device on bus address 0x20 (7bit). Raspberry Pi:

sudo i2cdetect -y 1 BeagleBone Black:

sudo i2cdetect -y -r 2

Returns: 0 1 2 3 4 5 6 7 8 9 a b c d e f 00: -- -- -- -- -- -- -- -- -- -- -- -- -- 10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 20: UU -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 70: -- -- -- -- -- -- -- --

The UU at row 20 indicates the tool found the GPS device connected. In particular, UU indicates the device is also associated with a device driver (gps_quadrino). If UU is instead “20” then it still indicates that the GPS device was found but that no i2c client driver is tied to it yet. To attach a driver to an i2c address see Using the /sys interface.

QuadrinoGPS on Linux from Scratch (...if you absolutely must) If you don’t have an RPi3 or BBB or otherwise can’t use the pre-installed SD image you can follow this tutorial on setting up the GPS on an existing Linux installation. This isn’t for the faint of heart though, this is deep Linux stuff. Typically on Linux you can compile a kernel module by downloading the headers or source for your existing kernel version (determined by uname -r) but for whatever reason the Raspian folks decided not to include header or source packages for the current kernel in the Raspbian repository. I also tried using vanilla Linux kernel sources that matched the kernel version and I got a driver compiled but couldn’t load it even by force. It takes little effort, just compile time, to compile and install the latest RPI kernel so I suggest taking this less head-banging approach.

Comparison Between Boards for Source Builds

This comparison assumes you are starting with the default SD card images which are found

Raspberry PI

Download the RaspberryPi “Raspian” linux image and follow the Installation Guide mentioned on this page: https://www.raspberrypi.org/downloads/raspbian/ Once booted up, follow the instructions at the raspberrypi.org web site to download and rebuild the Linux kernel: https://www.raspberrypi.org/documentation/linux/kernel/building.md You can choose between cross-compilation or building on the RPi device. I chose building on the RPi3 device and it only took about 2 hours. I hear it takes about 13 hours on an RPi2. Clone the Quadrino GPS Driver repository from GitHub and compile the module. Install the module using make install, load it using insmod and configure using the /sys interface. Monitor GPS device using: cat /dev/ttyGPS0

BeagleBone Black

Download the Recommended Debian image and follow the Getting Started Guide on this page: https://beagleboard.org/latest-images Once booted up, you do not need to rebuild the Linux kernel, on default BBB Debian Linux you already have kernel headers installed and are immediately ready to build Kernel modules. (Such as the Quadrino GPS driver.)

← Same

← Same

← Same

Other Embedded Boards

For boards other than Raspberry PI or Beagle boards you should first consult documentation for your board on compiling the kernel. You may get away with just the headers if you consult building modules on your board. If you have to you may need to go to Vanilla Linux sources, see:

https://kernelnewbies.org/KernelBuild

Retrieving the current kernel configuration

In the RPi or BBB build steps you used the default kernel configuration. However, if you want to grab the current kernel configuration you can load the configs.ko kernel module to provide the config on the /proc interface:

sudo insmod /lib/modules/`uname -r`/kernel/kernel/configs.ko

The config is then found here: zcat /proc/config.gz

Compiling the QuadrinoGPS I2C client driver This step requires that you have already installed the kernel sources (or headers) for your kernel. The kernel sources should also have already been either compiled or at least prepared for out-of-tree module builds. If you used the premade SD card image, then you already have everything you need and the QuadrinoGPS driver source is already in ~/src/gps-driver. Download the QuadrinoGPS driver source code, or checkout the source code via GitHub: git clone https://github.com/flyingeinstein/quadrino-gps-driver.git OPTIONAL The Makefile will auto detect Kernel source in ~/src/linux and headers installed in /usr/src/linux-headers-x.y.z, but if you have them in a different location you can specify the location by setting the KERNEL_DIR environment variable:

The RaspberryPi image has the full kernel source installed in /home/pi/src/linux. export KERNEL_DIR=/home/pi/src/linux

Compile the kernel module:

make Install the kernel module:

sudo make install Or, if you plan to make changes to the driver and want to install only a link to the module in the build directory so you don’t have to keep installing the driver after every recompile, use:

sudo make install_link You will still need to unload/load the driver after each compile using rmmod/insmod as well as remove the driver from the i2c bus and reattach it using the /sys interface (see next chapter). Load the module:

sudo modprobe gps_quadrino

Configuring the QuadrinoGPS client driver on the I2C bus Loading the QuadrinoGPS i2c client driver using either insmod or modprobe does not automatically configure the GPS driver on the i2c bus. To do this we can either configure the driver to load on the i2c bus on reboot (persistent) or use the /sys interface to configure the driver on-demand. The pre-made SD card images already load and configure the driver at boot time using Device Tree Overlay.

Using the /sys interface

After inserting the module into the kernel using insmod or modprobe, we need to tell the i2c system to attach the driver to the given i2c address. In the directory for i2c bus #1, we wire the gps_quadrino driver to i2c bus address 0x20: RaspberryPi

cd /sys/devices/platform/soc/3f804000.i2c/i2c-1 sudo sh -c "echo 'gps_quadrino 0x20' > new_device"

Beagle Bone Black

cd /sys/devices/platform/soc/subsystem/devices/4819c000.i2c/i2c-2 sudo sh -c "echo 'gps_quadrino 0x20' > new_device"

We have to use "sudo sh -c" here so that the redirection to new_device file happens while under root, otherwise we get a permission denied. You could also just become root and execute echo 'gps_quadrino 0x20' > new_device.

If you even need to remove the device from i2c bus, this command will instruct the i2c sub-system to disconnect any attached driver from address 0x20:

echo 0x20 > delete_device

Configuring the driver to load at boot time

To load the gps_quadrino module at boot, add “gps_quadrino” as a line on it’s own in /etc/modules.

Testing the QuadrinoGPS client driver Once the driver is loaded and linked via the i2c bus to the address (as above), there will be a /dev/ttyGPS0 device link created. It will have a major/minor number of 4/96. There will also be more information on this driver in /sys/class/tty/ttyGPS0.

ls -l /dev/ttyGPS* Returns: crw-rw---- 1 root dialout 4, 96 Jul 28 03:59 /dev/ttyGPS0

We can read data from the GPS by cat’ing the ttyGPS0 device:

cat /dev/ttyGPS0

Returns a stream of GPS updates: $GPZDA,053239.1,15,8,2016,00,00*60 $GPGGA,053239,2748.096148,N,08247.062969,W,2,5,0.9,35.0,M,0.0,M,,,*4b $GPZDA,053240.1,15,8,2016,00,00*6e $GPGGA,053240,2748.096120,N,08247.062936,W,2,5,0.9,35.0,M,0.0,M,,,*41 $GPZDA,053241.1,15,8,2016,00,00*6f $GPGGA,053241,2748.096141,N,08247.062854,W,2,5,0.9,35.0,M,0.0,M,,,*42

Installing the GPSD tools If you used the pre-made SD card image then you already have these tools installed. Otherwise, on Debian/Raspbian installs use the following command to install the GPS tools:

sudo apt-get install gpsd gpsd-clients python-gps Test GPSD GPSD listens on port 2947. If you connect to this port with telnet or putty (in raw mode) you will get some JSON text. GPSD with it’s JSON interface is easily accessible by a variety of programming languages including the web. See http://catb.org/gpsd/gpsd_json.html for full list of GPSD commands, but to start we can tell GPSD to start monitoring the GPS device by initiating WATCH mode, type this into the telnet window:

?WATCH={"enable":true,"json":true}

GPSD Clients

● From Gnome/x-windows run xgps ● From ssh, run gpsmon ● From ssh, cat /dev/ttyGPS0

Configuring GPSD (GPS device & listen on all interfaces)

By default, GPSD listens on port 2947 but only listens on the localhost interface. This means you can only connect to GPSD on the RPi or BBB itself which may not be that useful. To be able to connect to GPSD from an external computer you need to add -G to the GPSD_OPTIONS setting in the config file /etc/default/gpsd then restart gpsd via sudo /etc/init.d/gpsd restart /etc/default/gpsd # 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="/dev/ttyGPS0" ← GPS device is at /dev/ttyGPS0 # Other options you want to pass to gpsd GPSD_OPTIONS="-G" ← listen on all interfaces

Appendix A Command Log for preparing RaspberryPi image This command log shows the steps I went through to create the SD card image. This is here just for reference. install i2c tools: sudo apt-get install i2c-tools libi2c-dev Enable I2C bus and chipset drivers: sudo raspi-config Make sure the GPS device is connected correctly. We are probing i2c bus 1 here. sudo i2cdetect -y 1 Note the current Kernel version: uname -a Compile the kernel: (from RaspberryPi KERNEL BUILDING) mkdir ~/src; cd ~/src git clone --depth=1 https://github.com/raspberrypi/linux KERNEL=kernel7 make bcm2709_defconfig make -j4 zImage modules dtbs sudo apt-get install bc make -j4 zImage modules dtbs sudo make modules_install sudo cp arch/arm/boot/dts/*.dtb /boot/ sudo cp arch/arm/boot/dts/overlays/*.dtb* /boot/overlays/ sudo cp arch/arm/boot/dts/overlays/README /boot/overlays/ sudo scripts/mkknlimg arch/arm/boot/zImage /boot/$KERNEL.img sudo reboot Compile the driver: cd ~/src/ git clone https://github.com/flyingeinstein/quadrino-gps-driver.git cd quadrino-gps-driver/ export KERNEL_DIR=/home/pi/src/linux/ make sudo make install sudo modprobe gps_quadrino Enable i2c driver: cd /sys/devices/platform/soc/3f804000.i2c/i2c-1/ sudo sh -c "echo 'gps_quadrino 0x20' > new_device" Stream GPS data: cat /dev/ttyGPS0

Appendix B Command Log for preparing BeagleBone Black image This command log shows the steps I went through to create the SD card image. This is here just for reference. Make sure the GPS device is connected correctly. Luckily the i2cdetect tool is installed by default on BBB: Notice we are probing i2c port 2. (P9 header, pins 19 & 20) i2cdetect -y -r 2 One unfortunate thing is the default BBB image contains no disk space left! I am able to finish this process if I first clean up some apt-get files. You'll eventually want to grow the disk if you have more room on the SD-card. sudo apt-get update sudo apt-get autoremove We can check if we have linux headers available, and what the package name is. You shouldn't need to do this step because linux kernel headers are installed by default in BBB. (See BBB is so easy!) sudo apt-get install linux-headers-$(uname -r) compile the quadrino gps driver: mkdir src cd src/ git clone https://github.com/flyingeinstein/quadrino-gps-driver.git cd quadrino-gps-driver/ export KERNEL_DIR=/usr/src/linux-headers-$(uname -r)/ make sudo make install The i2c subsystem is already enabled on the BBB, so we can simply cd into the device control directory. If you installed on one of BBB's other i2c busses than i2c-2 you may need to change the bolded number to 4802a000 (i2c-1) or 44e0b000 (i2c-0). cd /sys/devices/platform/soc/subsystem/devices/4819c000.i2c/i2c-2 sudo sh -c "echo 'gps_quadrino 0x20' > new_device" We should now see address 0x20 turn to UU indicating the GPS device was attached to the gps_quadrino driver: i2cdetect -y -r 2 stream GPS data: cat /dev/ttyGPS0

Appendix C Updating the Firmware on the QuadrinoGPS If you are familiar with Arduino it's easy to update the firmware on the GPS. You will need a USB-UART adapter and to ensure pin-out compatibility we recommend Sparkfun’s FT232R USB-Serial breakout (shown at right) but any adapter with RX/TX and DTR pins will work if you ensure the proper pin-pin wiring. First step is to solder a pin header onto the FIRMWARE FLASH PORT as indicated in this picture below (1) then place the USB-Serial adapter into the new header (2). If you don’t want to permanently solder pins onto the GPS you can just put the pin header into the USB-UART adapter’s female pin header and hold the pins onto the GPS while flashing.

(1) Solder a pin header to the FIRMWARE FLASH PORT

(2) Now you can attach the USB-Serial adapter and you are ready to flash the new firmware using the

Arduino IDE

Flashing Firmware

With the USB-Serial adapter in place and connected to the computer via a USB cable open the Arduino IDE, now:

1. Open the GPS firmware project (download link) 2. Select the Board Type via Tools | Board | Arduino Nano. 3. Select the Serial port (depends on your system)

4. Click Upload button in the top menu of the Arduino IDE 5. When the upload completes the GPS will begin it’s normal startup LED animation