Deutsch
English
Menu
Software / API Bindings / openHAB / API Reference and Examples / Bricklets (Discontinued) / GPS Bricklet

openHAB - GPS Bricklet

Warning

The openHAB bindings are still in beta, but the development was stopped.

This is the description of the openHAB API bindings for the GPS Bricklet. General information and technical specifications for the GPS Bricklet are summarized in its hardware description.

An installation guide for the openHAB API bindings is part of their general description.

Thing

UID:
  • tinkerforge:brickletgps:[UID]
Required firmware version:
  • 2.0.0
Firmware update supported:
  • yes
Channels:
Actions:
Parameters:
  • Status Update Interval – Type: integer, Default: 1000, Unit: ms, Min: 0, Max: 4294967295
  • Specifies the update interval for the status in milliseconds. A value of 0 disables automatic updates.

  • Altitude Update Interval – Type: integer, Default: 1000, Unit: ms, Min: 0, Max: 4294967295
  • Specifies the update interval for the altitude and geodial separation in milliseconds. A value of 0 disables automatic updates.

  • Motion Update Interval – Type: integer, Default: 1000, Unit: ms, Min: 0, Max: 4294967295
  • Specifies the update interval for the course and speed in milliseconds. A value of 0 disables automatic updates.

Channels

Location

The location as determined by the bricklet.

Type:
  • Location
UID:
  • tinkerforge:brickletgps:[UID]:BrickletGPSLocation
Read only:
  • No
Parameters:
  • Update Interval – Type: integer, Default: 1000, Unit: ms, Min: 0, Max: 4294967295
  • Specifies the update interval in milliseconds. A value of 0 disables automatic updates.
Fix

The current fix status

Type:
  • Contact
UID:
  • tinkerforge:brickletgps:[UID]:BrickletGPSFix
Read only:
  • No
Satellites In View

The number of satellites that are in view.

Type:
  • Number:Dimensionless
UID:
  • tinkerforge:brickletgps:[UID]:BrickletGPSSatellitesInView
Read only:
  • Yes
Satellites Used

The number of satellites that are currently used.

Type:
  • Number:Dimensionless
UID:
  • tinkerforge:brickletgps:[UID]:BrickletGPSSatellitesUsed
Read only:
  • Yes
Altitude

The measured altitude

Type:
  • Number:Length
UID:
  • tinkerforge:brickletgps:[UID]:BrickletGPSAltitude
Read only:
  • Yes
Unit:
  • Meter
Geoidal Separation

The geoidal separation corresponding to the current altitude

Type:
  • Number:Length
UID:
  • tinkerforge:brickletgps:[UID]:BrickletGPSGeoidalSeparation
Read only:
  • Yes
Unit:
  • Meter
Course

The current course. 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.

Type:
  • Number:Angle
UID:
  • tinkerforge:brickletgps:[UID]:BrickletGPSCourse
Read only:
  • Yes
Unit:
  • Degree Angle
Range:
  • 0 Degree Angle to 360 Degree Angle (Step 0.01 Degree Angle)
Speed

The current speed. Please note that this only returns useful values if an actual movement is present.

Type:
  • Number:Speed
UID:
  • tinkerforge:brickletgps:[UID]:BrickletGPSSpeed
Read only:
  • Yes
Unit:
  • Kilometre Per Hour
Date Time

The current date and time.

Type:
  • DateTime
UID:
  • tinkerforge:brickletgps:[UID]:BrickletGPSDateTime
Read only:
  • No
Parameters:
  • Update Interval – Type: integer, Default: 1000, Unit: ms, Min: 0, Max: 4294967295
  • Specifies the update interval in milliseconds. A value of 0 disables automatic updates.
Restart

Restarts the GPS Bricklet, the following restart types are available:

  • Hot start (use all available data in the NV store)
  • Warm start (don't use ephemeris at restart)
  • Cold start (don't use time, position, almanacs and ephemeris at restart)
  • Factory reset (clear all system/user configurations at restart)
Type:
  • Commands (String)
UID:
  • tinkerforge:brickletgps:[UID]:BrickletGPSRestart
Read only:
  • No
Commands:
  • Hot Start
  • Warm Start
  • Cold Start
  • Factory reset

Actions

Actions can be used in rules by creating an action object. All actions return a Map<String, Object>. Returned values can be accessed by name, sometimes the type deduction needs some hints, as shown below:

val actions = getActions("tinkerforge", "tinkerforge:brickletgps:[UID]")
val hwVersion = actions.brickletGPSGetIdentity().get("hardwareVersion") as short[]
logInfo("Example", "Hardware version: " + hwVersion.get(0) + "." + hwVersion.get(1) + "." + hwVersion.get(2))

Basic Actions

brickletGPSGetCoordinates()
Return Map:
  • latitude – Type: long, Unit: 1/1000000 °, Range: [0 to 90000000]
  • ns – Type: char, Range: ['N', 'S']
  • longitude – Type: long, Unit: 1/1000000 °, Range: [0 to 180000000]
  • ew – Type: char, Range: ['E', 'W']
  • pdop – Type: int, Unit: 1/100, Range: [0 to 216 - 1]
  • hdop – Type: int, Unit: 1/100, Range: [0 to 216 - 1]
  • vdop – Type: int, Unit: 1/100, Range: [0 to 216 - 1]
  • epe – Type: int, Unit: 1 cm, Range: [0 to 216 - 1]

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 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 for more information.

This data is only valid if there is currently a fix as indicated by Fix.

brickletGPSGetStatus()
Return Map:
  • fix – Type: short, Range: See constants
  • satellitesView – Type: short, Range: [0 to 255]
  • satellitesUsed – Type: short, Range: [0 to 255]

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:

Value Description
1 No Fix, GetCoordinates(), Altitude and Course return invalid data
2 2D Fix, only GetCoordinates() and Course return valid data
3 3D Fix, GetCoordinates(), Altitude and Course return valid data

There is also a blue LED on the Bricklet that indicates the fix status.

The following constants are available for this function:

For fix:

  • val FIX_NO_FIX = 1
  • val FIX_2D_FIX = 2
  • val FIX_3D_FIX = 3
brickletGPSGetAltitude()
Return Map:
  • altitude – Type: int, Unit: 1 cm, Range: [-231 to 231 - 1]
  • geoidalSeparation – Type: int, Unit: 1 cm, Range: [-231 to 231 - 1]

Returns the current altitude and corresponding geoidal separation.

This data is only valid if there is currently a fix as indicated by Fix.

brickletGPSGetMotion()
Return Map:
  • course – Type: long, Unit: 1/100 °, Range: [0 to 36000]
  • speed – Type: long, Unit: 1/100 km/h, Range: [0 to 232 - 1]

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 Fix.

brickletGPSGetDateTime()
Return Map:
  • date – Type: long, Range: [10100 to 311299]
  • time – Type: long, Range: [0 to 235959999]

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.

Advanced Actions

brickletGPSRestart(short restartType)
Parameters:
  • restartType – Type: short, Range: See constants

Restarts the GPS Bricklet, the following restart types are available:

Value Description
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)

The following constants are available for this function:

For restartType:

  • val RESTART_TYPE_HOT_START = 0
  • val RESTART_TYPE_WARM_START = 1
  • val RESTART_TYPE_COLD_START = 2
  • val RESTART_TYPE_FACTORY_RESET = 3
brickletGPSGetIdentity()
Return Map:
  • uid – Type: String, Length: up to 8
  • connectedUid – Type: String, Length: up to 8
  • position – Type: char, Range: ['a' to 'h', 'z']
  • hardwareVersion – Type: short[], Length: 3
    • 0: major – Type: short, Range: [0 to 255]
    • 1: minor – Type: short, Range: [0 to 255]
    • 2: revision – Type: short, Range: [0 to 255]
  • firmwareVersion – Type: short[], Length: 3
    • 0: major – Type: short, Range: [0 to 255]
    • 1: minor – Type: short, Range: [0 to 255]
    • 2: revision – Type: short, Range: [0 to 255]
  • deviceIdentifier – Type: int, Range: [0 to 216 - 1]

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). A Bricklet connected to an Isolator Bricklet is always at position 'z'.

The device identifier numbers can be found here.