********************
GPS
********************

.. index:: devices; GPS

Overview
====================

Extracts and channelises information from an NMEA-0183 compatible
serially attached GPS.  This driver will currently run on Digi devices
and other Python platforms which provide the ``termios`` module. This
means that it does not currently run on a Windows PC.

Configuration
====================

A typical GPS configuration block looks like this::

    - name: gps0
      driver: devices.gps.gps:GPS
      settings:
        serial_device: /com/0
        serial_baud: 4800

Settings
--------------------

serial_device (optional, default: /gps/0)
    Device path where the NMEA data stream can be accessed.  The
    default ``/gps/0`` is applicable most of the time when the Digi
    device can determine that it has GPS functionality through a
    cellular module or installed GPS expansion.  

    If the GPS is attached to an external serial port, the device
    names are of the form ``/com/<port>`` where ``port`` is a
    zero-based index of the external serial ports of the unit.  

serial_baud (optional, default: 4800)
    The baud rate to communicate to the serial GPS

sample_rate_sec (optional, default: 60.0, *ConnectPort X3 only*) 
    The rate, in seconds, in which the GPS should be queried and have
    the resulting data be parsed.  On platforms other than ConnectPort
    X3, data is reported as it arrives.

    .. note:: 
        Due to hardware limitations, it is HIGHLY recommended keeping
        this value at or above 60 seconds.

Channels
====================
This driver directly extracts channel data from NMEA sentences.  The
channels provided are as follows:

fix_time (Get, type: string)
    A string of the form ``hh:mm:ss`` with the time of the last RMC
    message as reported by the GPS receiver

fix_good (Get, type: Boolean)
    A string: ``Valid`` or ``Invalid`` 

latitude_degrees (Get, type: float)
    The latitude of the reported fix in degrees

latitude_hemisphere (Get, type: string)
    ``N`` or ``S`` reporting the hemisphere of the fix

longitude_degrees (Get, type: float)
     The longitude of the reported fix in degrees

longitude_hemisphere (Get, type: string)
    ``E`` or ``W`` reporting the hemisphere of the fix

speed_over_ground (Get, type: float)
    Speed in knots

course_over_ground (Get, type: float)
    Direction of travel in degrees

fix_date (Get, type: string)
    A string of the form ``MM/DD/YY`` with the date of the last RMC
    message as reported by the GPS receiver

num_satellites (Get, type: integer)
    Number of satellites being tracked by the receiver

altitude (Get, type: float)
    Altitude component of reported fix

hdop (Get, type: float)
    Horizontal dilution of precision for reported fix


