..
 #############################################################
 # This file was automatically generated on 2015-05-08.      #
 #                                                           #
 # If you have a bugfix for this file and want to commit it, #
 # please fix the bug in the generator. You can find a link  #
 # to the generators git repository on tinkerforge.com       #
 #############################################################


:breadcrumbs: <a href="../../index.html">Home</a> / <a href="../../index.html#software-tcpip">Software</a> / TCP/IP - GPS Bricklet

.. |device_identifier_constant| unicode:: 0xA0
   :trim:

.. _gps_bricklet_tcpip:

TCP/IP - GPS Bricklet
=====================

This is the description of the :ref:`TCP/IP protocol <llproto_tcpip>` for the :ref:`GPS Bricklet <gps_bricklet>`. General information and technical
specifications for the GPS Bricklet are summarized in its :ref:`hardware description
<gps_bricklet_description>`.

.. _gps_bricklet_tcpip_api:

API
---

A general description of the TCP/IP protocol structure can be found
:ref:`here <llproto_tcpip>`.




Basic Functions
^^^^^^^^^^^^^^^



.. tcpip:function:: BrickletGPS.get_coordinates

 :functionid: 1
 :emptyrequest: empty payload

 :response latitude: uint32
 :response ns: char
 :response longitude: uint32
 :response ew: char
 :response pdop: uint16
 :response hdop: uint16
 :response vdop: uint16
 :response epe: uint16

 Returns the GPS coordinates. Latitude and longitude are given in the
 ``DD.dddddd°`` format, the value 57123468 means 57.123468°.
 The parameter ``ns`` and ``ew`` are the cardinal directions for
 latitude and longitude. Possible values for ``ns`` and ``ew`` are 'N', 'S', 'E'
 and 'W' (north, south, east and west).
 
 PDOP, HDOP and VDOP are the dilution of precision (DOP) values. They specify
 the additional multiplicative effect of GPS satellite geometry on GPS 
 precision. See 
 `here <http://en.wikipedia.org/wiki/Dilution_of_precision_(GPS)>`__
 for more information. The values are give in hundredths.
 
 EPE is the "Estimated Position Error". The EPE is given in cm. This is not the
 absolute maximum error, it is the error with a specific confidence. See
 `here <http://www.nps.gov/gis/gps/WhatisEPE.html>`__ for more information.
 
 This data is only valid if there is currently a fix as indicated by
 :tcpip:func:`get_status <BrickletGPS.get_status>`.
 
.. tcpip:function:: BrickletGPS.get_status

 :functionid: 2
 :emptyrequest: empty payload

 :response fix: uint8
 :response satellites_view: uint8
 :response satellites_used: uint8

 Returns the current fix status, the number of satellites that are in view and
 the number of satellites that are currently used.
 
 Possible fix status values can be:
 
 .. csv-table::
  :header: "Value", "Description"
  :widths: 10, 100
 
  "1", "No Fix, :tcpip:func:`get_coordinates <BrickletGPS.get_coordinates>` and :tcpip:func:`get_altitude <BrickletGPS.get_altitude>` return invalid data"
  "2", "2D Fix, only :tcpip:func:`get_coordinates <BrickletGPS.get_coordinates>` returns valid data"
  "3", "3D Fix, :tcpip:func:`get_coordinates <BrickletGPS.get_coordinates>` and :tcpip:func:`get_altitude <BrickletGPS.get_altitude>` return valid data"
 
 There is also a :ref:`blue LED <gps_bricklet_fix_led>` on the Bricklet that
 indicates the fix status.
 
.. tcpip:function:: BrickletGPS.get_altitude

 :functionid: 3
 :emptyrequest: empty payload

 :response altitude: uint32
 :response geoidal_separation: uint32

 Returns the current altitude and corresponding geoidal separation.
 
 Both values are given in cm.
 
 This data is only valid if there is currently a fix as indicated by
 :tcpip:func:`get_status <BrickletGPS.get_status>`.
 
.. tcpip:function:: BrickletGPS.get_motion

 :functionid: 4
 :emptyrequest: empty payload

 :response course: uint32
 :response speed: uint32

 Returns the current course and speed. Course is given in hundredths degree
 and speed is given in hundredths km/h. A course of 0° means the Bricklet is
 traveling north bound and 90° means it is traveling east bound.
 
 Please note that this only returns useful values if an actual movement
 is present.
 
 This data is only valid if there is currently a fix as indicated by
 :tcpip:func:`get_status <BrickletGPS.get_status>`.
 
.. tcpip:function:: BrickletGPS.get_date_time

 :functionid: 5
 :emptyrequest: empty payload

 :response date: uint32
 :response time: uint32

 Returns the current date and time. The date is
 given in the format ``ddmmyy`` and the time is given
 in the format ``hhmmss.sss``. For example, 140713 means
 14.05.13 as date and 195923568 means 19:59:23.568 as time.
 


Advanced Functions
^^^^^^^^^^^^^^^^^^

.. tcpip:function:: BrickletGPS.restart

 :functionid: 6
 :request restart_type: uint8

 :noresponse: no response

 Restarts the GPS Bricklet, the following restart types are available:
 
 .. csv-table::
  :header: "Value", "Description"
  :widths: 10, 100
 
  "0", "Hot start (use all available data in the NV store)"
  "1", "Warm start (don't use ephemeris at restart)"
  "2", "Cold start (don't use time, position, almanacs and ephemeris at restart)"
  "3", "Factory reset (clear all system/user configurations at restart)"
 
.. tcpip:function:: BrickletGPS.get_identity

 :functionid: 255
 :emptyrequest: empty payload

 :response uid: char[8]
 :response connected_uid: char[8]
 :response position: char
 :response hardware_version: uint8[3]
 :response firmware_version: uint8[3]
 :response device_identifier: uint16

 Returns the UID, the UID where the Bricklet is connected to, 
 the position, the hardware and firmware version as well as the
 device identifier.
 
 The position can be 'a', 'b', 'c' or 'd'.
 
 The device identifier numbers can be found :ref:`here <device_identifier>`.
 |device_identifier_constant|
 


Callback Configuration Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



.. tcpip:function:: BrickletGPS.set_coordinates_callback_period

 :functionid: 7
 :request period: uint32

 :noresponse: no response

 Sets the period in ms with which the :tcpip:func:`CALLBACK_COORDINATES <BrickletGPS.CALLBACK_COORDINATES>` callback is triggered
 periodically. A value of 0 turns the callback off.
 
 :tcpip:func:`CALLBACK_COORDINATES <BrickletGPS.CALLBACK_COORDINATES>` is only triggered if the coordinates changed since the
 last triggering.
 
 The default value is 0.
 
.. tcpip:function:: BrickletGPS.get_coordinates_callback_period

 :functionid: 8
 :emptyrequest: empty payload

 :response period: uint32

 Returns the period as set by :tcpip:func:`set_coordinates_callback_period <BrickletGPS.set_coordinates_callback_period>`.
 
.. tcpip:function:: BrickletGPS.set_status_callback_period

 :functionid: 9
 :request period: uint32

 :noresponse: no response

 Sets the period in ms with which the :tcpip:func:`CALLBACK_STATUS <BrickletGPS.CALLBACK_STATUS>` callback is triggered
 periodically. A value of 0 turns the callback off.
 
 :tcpip:func:`CALLBACK_STATUS <BrickletGPS.CALLBACK_STATUS>` is only triggered if the status changed since the
 last triggering.
 
 The default value is 0.
 
.. tcpip:function:: BrickletGPS.get_status_callback_period

 :functionid: 10
 :emptyrequest: empty payload

 :response period: uint32

 Returns the period as set by :tcpip:func:`set_status_callback_period <BrickletGPS.set_status_callback_period>`.
 
.. tcpip:function:: BrickletGPS.set_altitude_callback_period

 :functionid: 11
 :request period: uint32

 :noresponse: no response

 Sets the period in ms with which the :tcpip:func:`CALLBACK_ALTITUDE <BrickletGPS.CALLBACK_ALTITUDE>` callback is triggered
 periodically. A value of 0 turns the callback off.
 
 :tcpip:func:`CALLBACK_ALTITUDE <BrickletGPS.CALLBACK_ALTITUDE>` is only triggered if the altitude changed since the
 last triggering.
 
 The default value is 0.
 
.. tcpip:function:: BrickletGPS.get_altitude_callback_period

 :functionid: 12
 :emptyrequest: empty payload

 :response period: uint32

 Returns the period as set by :tcpip:func:`set_altitude_callback_period <BrickletGPS.set_altitude_callback_period>`.
 
.. tcpip:function:: BrickletGPS.set_motion_callback_period

 :functionid: 13
 :request period: uint32

 :noresponse: no response

 Sets the period in ms with which the :tcpip:func:`CALLBACK_MOTION <BrickletGPS.CALLBACK_MOTION>` callback is triggered
 periodically. A value of 0 turns the callback off.
 
 :tcpip:func:`CALLBACK_MOTION <BrickletGPS.CALLBACK_MOTION>` is only triggered if the motion changed since the
 last triggering.
 
 The default value is 0.
 
.. tcpip:function:: BrickletGPS.get_motion_callback_period

 :functionid: 14
 :emptyrequest: empty payload

 :response period: uint32

 Returns the period as set by :tcpip:func:`set_motion_callback_period <BrickletGPS.set_motion_callback_period>`.
 
.. tcpip:function:: BrickletGPS.set_date_time_callback_period

 :functionid: 15
 :request period: uint32

 :noresponse: no response

 Sets the period in ms with which the :tcpip:func:`CALLBACK_DATE_TIME <BrickletGPS.CALLBACK_DATE_TIME>` callback is triggered
 periodically. A value of 0 turns the callback off.
 
 :tcpip:func:`CALLBACK_DATE_TIME <BrickletGPS.CALLBACK_DATE_TIME>` is only triggered if the date or time changed since the
 last triggering.
 
 The default value is 0.
 
.. tcpip:function:: BrickletGPS.get_date_time_callback_period

 :functionid: 16
 :emptyrequest: empty payload

 :response period: uint32

 Returns the period as set by :tcpip:func:`set_date_time_callback_period <BrickletGPS.set_date_time_callback_period>`.
 


.. _gps_bricklet_tcpip_callbacks:

Callbacks
^^^^^^^^^

.. tcpip:function:: BrickletGPS.CALLBACK_COORDINATES

 :functionid: 17

 :response latitude: uint32
 :response ns: char
 :response longitude: uint32
 :response ew: char
 :response pdop: uint16
 :response hdop: uint16
 :response vdop: uint16
 :response epe: uint16


 This callback is triggered periodically with the period that is set by
 :tcpip:func:`set_coordinates_callback_period <BrickletGPS.set_coordinates_callback_period>`. The parameters are the same
 as for :tcpip:func:`get_coordinates <BrickletGPS.get_coordinates>`.
 
 :tcpip:func:`CALLBACK_COORDINATES <BrickletGPS.CALLBACK_COORDINATES>` is only triggered if the coordinates changed since the
 last triggering and if there is currently a fix as indicated by
 :tcpip:func:`get_status <BrickletGPS.get_status>`.
 
.. tcpip:function:: BrickletGPS.CALLBACK_STATUS

 :functionid: 18

 :response fix: uint8
 :response satellites_view: uint8
 :response satellites_used: uint8


 This callback is triggered periodically with the period that is set by
 :tcpip:func:`set_status_callback_period <BrickletGPS.set_status_callback_period>`. The parameters are the same
 as for :tcpip:func:`get_status <BrickletGPS.get_status>`.
 
 :tcpip:func:`CALLBACK_STATUS <BrickletGPS.CALLBACK_STATUS>` is only triggered if the status changed since the
 last triggering.
 
.. tcpip:function:: BrickletGPS.CALLBACK_ALTITUDE

 :functionid: 19

 :response altitude: uint32
 :response geoidal_separation: uint32


 This callback is triggered periodically with the period that is set by
 :tcpip:func:`set_altitude_callback_period <BrickletGPS.set_altitude_callback_period>`. The parameters are the same
 as for :tcpip:func:`get_altitude <BrickletGPS.get_altitude>`.
 
 :tcpip:func:`CALLBACK_ALTITUDE <BrickletGPS.CALLBACK_ALTITUDE>` is only triggered if the altitude changed since the
 last triggering and if there is currently a fix as indicated by
 :tcpip:func:`get_status <BrickletGPS.get_status>`.
 
.. tcpip:function:: BrickletGPS.CALLBACK_MOTION

 :functionid: 20

 :response course: uint32
 :response speed: uint32


 This callback is triggered periodically with the period that is set by
 :tcpip:func:`set_motion_callback_period <BrickletGPS.set_motion_callback_period>`. The parameters are the same
 as for :tcpip:func:`get_motion <BrickletGPS.get_motion>`.
 
 :tcpip:func:`CALLBACK_MOTION <BrickletGPS.CALLBACK_MOTION>` is only triggered if the motion changed since the
 last triggering and if there is currently a fix as indicated by
 :tcpip:func:`get_status <BrickletGPS.get_status>`.
 
.. tcpip:function:: BrickletGPS.CALLBACK_DATE_TIME

 :functionid: 21

 :response date: uint32
 :response time: uint32


 This callback is triggered periodically with the period that is set by
 :tcpip:func:`set_date_time_callback_period <BrickletGPS.set_date_time_callback_period>`. The parameters are the same
 as for :tcpip:func:`get_date_time <BrickletGPS.get_date_time>`.
 
 :tcpip:func:`CALLBACK_DATE_TIME <BrickletGPS.CALLBACK_DATE_TIME>` is only triggered if the date or time changed since the
 last triggering.
 


