NAME

Tinkerforge::BrickletGPS - Determine position, velocity and altitude using GPS

CONSTANTS

DEVICE_IDENTIFIER

This constant is used to identify a GPS Bricklet.

The get_identity() subroutine and the CALLBACK_ENUMERATE callback of the IP Connection have a device_identifier parameter to specify the Brick's or Bricklet's type.

DEVICE_DISPLAY_NAME

This constant represents the display name of a GPS Bricklet.

CALLBACK_COORDINATES

This constant is used with the register_callback() subroutine to specify the CALLBACK_COORDINATES callback.

CALLBACK_STATUS

This constant is used with the register_callback() subroutine to specify the CALLBACK_STATUS callback.

CALLBACK_ALTITUDE

This constant is used with the register_callback() subroutine to specify the CALLBACK_ALTITUDE callback.

CALLBACK_MOTION

This constant is used with the register_callback() subroutine to specify the CALLBACK_MOTION callback.

CALLBACK_DATE_TIME

This constant is used with the register_callback() subroutine to specify the CALLBACK_DATE_TIME callback.

FUNCTION_GET_COORDINATES

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_STATUS

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_ALTITUDE

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_MOTION

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_DATE_TIME

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_RESTART

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_SET_COORDINATES_CALLBACK_PERIOD

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_COORDINATES_CALLBACK_PERIOD

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_SET_STATUS_CALLBACK_PERIOD

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_STATUS_CALLBACK_PERIOD

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_SET_ALTITUDE_CALLBACK_PERIOD

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_ALTITUDE_CALLBACK_PERIOD

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_SET_MOTION_CALLBACK_PERIOD

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_MOTION_CALLBACK_PERIOD

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_SET_DATE_TIME_CALLBACK_PERIOD

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_DATE_TIME_CALLBACK_PERIOD

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_IDENTITY

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTIONS

new()

Creates an object with the unique device ID *uid* and adds it to the IP Connection *ipcon*.

get_coordinates()

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 <https://en.wikipedia.org/wiki/Dilution_of_precision_(GPS)>`__ for more information.

EPE is the "Estimated Position Error". This is not the absolute maximum error, it is the error with a specific confidence. See `here <https://www.nps.gov/gis/gps/WhatisEPE.html>`__ for more information.

This data is only valid if there is currently a fix as indicated by :func:`Get Status`.

get_status()

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, :func:`Get Coordinates`, :func:`Get Altitude` and :func:`Get Motion` return invalid data"
"2", "2D Fix, only :func:`Get Coordinates` and :func:`Get Motion` return valid data"
"3", "3D Fix, :func:`Get Coordinates`, :func:`Get Altitude` and :func:`Get Motion` return valid data"

There is also a :ref:`blue LED <gps_bricklet_fix_led>` on the Bricklet that indicates the fix status.

get_altitude()

Returns the current altitude and corresponding geoidal separation.

This data is only valid if there is currently a fix as indicated by :func:`Get Status`.

get_motion()

Returns the current course and speed. 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 :func:`Get Status`.

get_date_time()

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.07.13 as date and 195923568 means 19:59:23.568 as time.

restart()

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)"

set_coordinates_callback_period()

Sets the period with which the :cb:`Coordinates` callback is triggered periodically. A value of 0 turns the callback off.

The :cb:`Coordinates` callback is only triggered if the coordinates changed since the last triggering.

get_coordinates_callback_period()

Returns the period as set by :func:`Set Coordinates Callback Period`.

set_status_callback_period()

Sets the period with which the :cb:`Status` callback is triggered periodically. A value of 0 turns the callback off.

The :cb:`Status` callback is only triggered if the status changed since the last triggering.

get_status_callback_period()

Returns the period as set by :func:`Set Status Callback Period`.

set_altitude_callback_period()

Sets the period with which the :cb:`Altitude` callback is triggered periodically. A value of 0 turns the callback off.

The :cb:`Altitude` callback is only triggered if the altitude changed since the last triggering.

get_altitude_callback_period()

Returns the period as set by :func:`Set Altitude Callback Period`.

set_motion_callback_period()

Sets the period with which the :cb:`Motion` callback is triggered periodically. A value of 0 turns the callback off.

The :cb:`Motion` callback is only triggered if the motion changed since the last triggering.

get_motion_callback_period()

Returns the period as set by :func:`Set Motion Callback Period`.

set_date_time_callback_period()

Sets the period with which the :cb:`Date Time` callback is triggered periodically. A value of 0 turns the callback off.

The :cb:`Date Time` callback is only triggered if the date or time changed since the last triggering.

get_date_time_callback_period()

Returns the period as set by :func:`Set Date Time Callback Period`.

get_identity()

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', 'd', 'e', 'f', 'g' or 'h' (Bricklet Port). The Raspberry Pi HAT (Zero) Brick is always at position 'i' and the Bricklet connected to an :ref:`Isolator Bricklet <isolator_bricklet>` is always as position 'z'.

The device identifier numbers can be found :ref:`here <device_identifier>`. |device_identifier_constant|