TCP/IP - GPS Bricklet

Dies ist die Beschreibung des TCP/IP Protokolls für das GPS Bricklet. Allgemeine Informationen über die Funktionen und technischen Spezifikationen des GPS Bricklet sind in dessen Hardware Beschreibung zusammengefasst.

API

Eine allgemeine Beschreibung der TCP/IP Protokollstruktur findet sich hier.

Grundfunktionen

BrickletGPS.get_coordinates
Funktions-ID:
  • 1
Anfrage:
  • keine Nutzdaten
Antwort:
  • latitude – Typ: uint32, Einheit: 1/1000000 °, Wertebereich: [0 bis 90000000]
  • ns – Typ: char, Wertebereich: ['N', 'S']
  • longitude – Typ: uint32, Einheit: 1/1000000 °, Wertebereich: [0 bis 180000000]
  • ew – Typ: char, Wertebereich: ['E', 'W']
  • pdop – Typ: uint16, Einheit: 1/100, Wertebereich: [0 bis 216 - 1]
  • hdop – Typ: uint16, Einheit: 1/100, Wertebereich: [0 bis 216 - 1]
  • vdop – Typ: uint16, Einheit: 1/100, Wertebereich: [0 bis 216 - 1]
  • epe – Typ: uint16, Einheit: 1 cm, Wertebereich: [0 bis 216 - 1]

Gibt die GPS Koordinaten zurück. Breitengrad und Längengrad werden im Format DD.dddddd° angegeben, der Wert 57123468 bedeutet 57,123468°. Die Parameter ns und ew sind Himmelsrichtungen für Breiten- und Längengrad. Mögliche Werte für ns und ew sind 'N', 'S', 'E' und 'W' (Nord, Süd, Ost, West).

PDOP, HDOP und VDOP sind die "Dilution Of Precision" (DOP) Werte. Sie spezifizieren die zusätzlichen multiplikativen Effekte von der GPS Satellitengeometrie auf die GPS-Präzision. hier gibt es mehr Informationen dazu. Die Werte werden in Hundertstel gegeben.

EPE ist der "Estimated Position Error". Dies ist nicht der absolut maximale Fehler, es ist der Fehler mit einer spezifischen Konfidenz. Siehe hier für mehr Informationen.

Diese Daten sind nur gültig wenn ein Fix vorhanden ist (siehe get_status).

BrickletGPS.get_status
Funktions-ID:
  • 2
Anfrage:
  • keine Nutzdaten
Antwort:
  • fix – Typ: uint8, Wertebereich: Siehe Bedeutungen
  • satellites_view – Typ: uint8, Wertebereich: [0 bis 255]
  • satellites_used – Typ: uint8, Wertebereich: [0 bis 255]

Gibt den aktuellen Fix-Status, die Anzahl der sichtbaren Satelliten und die Anzahl der im Moment benutzten Satelliten zurück.

Mögliche Fix-Status Werte sind:

Wert Beschreibung
1 Kein Fix, get_coordinates, get_altitude und get_motion geben ungültige Daten zurück
2 2D Fix, nur get_coordinates und get_motion geben gültige Daten zurück
3 3D Fix, get_coordinates, get_altitude und get_motion geben gültige Daten zurück

Auf dem Bricklet ist eine blaue LED, die den Fix-Status anzeigt.

Die folgenden Bedeutungen sind für die Elemente dieser Funktion definiert:

Für fix:

  • 1 = No Fix
  • 2 = 2D Fix
  • 3 = 3D Fix
BrickletGPS.get_altitude
Funktions-ID:
  • 3
Anfrage:
  • keine Nutzdaten
Antwort:
  • altitude – Typ: int32, Einheit: 1 cm, Wertebereich: [-231 bis 231 - 1]
  • geoidal_separation – Typ: int32, Einheit: 1 cm, Wertebereich: [-231 bis 231 - 1]

Gibt die aktuelle Höhe und die dazu gehörige "Geoidal Separation" zurück.

Diese Daten sind nur gültig wenn ein Fix vorhanden ist (siehe get_status).

BrickletGPS.get_motion
Funktions-ID:
  • 4
Anfrage:
  • keine Nutzdaten
Antwort:
  • course – Typ: uint32, Einheit: 1/100 °, Wertebereich: [0 bis 36000]
  • speed – Typ: uint32, Einheit: 1/100 km/h, Wertebereich: [0 bis 232 - 1]

Gibt die aktuelle Richtung und Geschwindigkeit zurück. Eine Richtung von 0° bedeutet eine Bewegung des Bricklets nach Norden und 90° einer Bewegung nach Osten.

Dabei ist zu beachten: Diese Funktion liefert nur nützlich Werte wenn auch tatsächlich eine Bewegung stattfindet.

Diese Daten sind nur gültig wenn ein Fix vorhanden ist (siehe get_status).

BrickletGPS.get_date_time
Funktions-ID:
  • 5
Anfrage:
  • keine Nutzdaten
Antwort:
  • date – Typ: uint32, Wertebereich: [10100 bis 311299]
  • time – Typ: uint32, Wertebereich: [0 bis 235959999]

Gibt das aktuelle Datum und die aktuelle Zeit zurück. Das Datum ist im Format ddmmyy und die Zeit im Format hhmmss.sss angegeben. Zum Beispiel, 140713 bedeutet 14.07.13 als Datum und 195923568 bedeutet 19:59:23.568 als Zeit.

Fortgeschrittene Funktionen

BrickletGPS.restart
Funktions-ID:
  • 6
Anfrage:
  • restart_type – Typ: uint8, Wertebereich: Siehe Bedeutungen
Antwort:
  • keine Antwort

Startet das GPS Bricklet neu. Die folgenden Neustart-Typen stehen zur Verfügung:

Wert Beschreibung
0 Hot Start (alle verfügbaren Daten im NV-Speicher werden weiter genutzt)
1 Warm Start (Ephemerisdaten werden verworfen)
2 Cold Start (Zeit-, Position-, Almanach- und Ephemerisdaten werden verworfen)
3 Factory Reset (Alle System/User Einstellungen werden verworfen)

Die folgenden Bedeutungen sind für die Elemente dieser Funktion definiert:

Für restart_type:

  • 0 = Hot Start
  • 1 = Warm Start
  • 2 = Cold Start
  • 3 = Factory Reset
BrickletGPS.get_identity
Funktions-ID:
  • 255
Anfrage:
  • keine Nutzdaten
Antwort:
  • uid – Typ: char[8]
  • connected_uid – Typ: char[8]
  • position – Typ: char, Wertebereich: ['a' bis 'h', 'i', 'z']
  • hardware_version – Typ: uint8[3]
    • 0: major – Typ: uint8, Wertebereich: [0 bis 255]
    • 1: minor – Typ: uint8, Wertebereich: [0 bis 255]
    • 2: revision – Typ: uint8, Wertebereich: [0 bis 255]
  • firmware_version – Typ: uint8[3]
    • 0: major – Typ: uint8, Wertebereich: [0 bis 255]
    • 1: minor – Typ: uint8, Wertebereich: [0 bis 255]
    • 2: revision – Typ: uint8, Wertebereich: [0 bis 255]
  • device_identifier – Typ: uint16, Wertebereich: [0 bis 216 - 1]

Gibt die UID, die UID zu der das Bricklet verbunden ist, die Position, die Hard- und Firmware Version sowie den Device Identifier zurück.

Die Position 'a', 'b', 'c', 'd', 'e', 'f', 'g' oder 'h' (Bricklet Anschluss) sein. Der Raspberry Pi HAT (Zero) Brick ist immer an Position 'i' und das Bricklet hinter einem Isolator Bricklet ist immer an Position 'z'.

Eine Liste der Device Identifier Werte ist hier zu finden. 

Konfigurationsfunktionen für Callbacks

BrickletGPS.set_coordinates_callback_period
Funktions-ID:
  • 7
Anfrage:
  • period – Typ: uint32, Einheit: 1 ms, Wertebereich: [0 bis 232 - 1], Standardwert: 0
Antwort:
  • keine Antwort

Setzt die Periode mit welcher der CALLBACK_COORDINATES Callback ausgelöst wird. Ein Wert von 0 deaktiviert den Callback.

Der CALLBACK_COORDINATES Callback wird nur ausgelöst, wenn sich die Koordinaten seit der letzten Auslösung geändert haben.

BrickletGPS.get_coordinates_callback_period
Funktions-ID:
  • 8
Anfrage:
  • keine Nutzdaten
Antwort:
  • period – Typ: uint32, Einheit: 1 ms, Wertebereich: [0 bis 232 - 1], Standardwert: 0

Gibt die Periode zurück, wie von set_coordinates_callback_period gesetzt.

BrickletGPS.set_status_callback_period
Funktions-ID:
  • 9
Anfrage:
  • period – Typ: uint32, Einheit: 1 ms, Wertebereich: [0 bis 232 - 1], Standardwert: 0
Antwort:
  • keine Antwort

Setzt die Periode mit welcher der CALLBACK_STATUS Callback ausgelöst wird. Ein Wert von 0 deaktiviert den Callback.

Der CALLBACK_STATUS Callback wird nur ausgelöst, wenn sich der Status seit der letzten Auslösung geändert hat.

BrickletGPS.get_status_callback_period
Funktions-ID:
  • 10
Anfrage:
  • keine Nutzdaten
Antwort:
  • period – Typ: uint32, Einheit: 1 ms, Wertebereich: [0 bis 232 - 1], Standardwert: 0

Gibt die Periode zurück, wie von set_status_callback_period gesetzt.

BrickletGPS.set_altitude_callback_period
Funktions-ID:
  • 11
Anfrage:
  • period – Typ: uint32, Einheit: 1 ms, Wertebereich: [0 bis 232 - 1], Standardwert: 0
Antwort:
  • keine Antwort

Setzt die Periode mit welcher der CALLBACK_ALTITUDE Callback ausgelöst wird. Ein Wert von 0 deaktiviert den Callback.

Der CALLBACK_ALTITUDE Callback wird nur ausgelöst, wenn sich die Höhe seit der letzten Auslösung geändert hat.

BrickletGPS.get_altitude_callback_period
Funktions-ID:
  • 12
Anfrage:
  • keine Nutzdaten
Antwort:
  • period – Typ: uint32, Einheit: 1 ms, Wertebereich: [0 bis 232 - 1], Standardwert: 0

Gibt die Periode zurück, wie von set_altitude_callback_period gesetzt.

BrickletGPS.set_motion_callback_period
Funktions-ID:
  • 13
Anfrage:
  • period – Typ: uint32, Einheit: 1 ms, Wertebereich: [0 bis 232 - 1], Standardwert: 0
Antwort:
  • keine Antwort

Setzt die Periode mit welcher der CALLBACK_MOTION Callback ausgelöst wird. Ein Wert von 0 deaktiviert den Callback.

Der CALLBACK_MOTION Callback wird nur ausgelöst, wenn sich die Bewegung seit der letzten Auslösung geändert hat.

BrickletGPS.get_motion_callback_period
Funktions-ID:
  • 14
Anfrage:
  • keine Nutzdaten
Antwort:
  • period – Typ: uint32, Einheit: 1 ms, Wertebereich: [0 bis 232 - 1], Standardwert: 0

Gibt die Periode zurück, wie von set_motion_callback_period gesetzt.

BrickletGPS.set_date_time_callback_period
Funktions-ID:
  • 15
Anfrage:
  • period – Typ: uint32, Einheit: 1 ms, Wertebereich: [0 bis 232 - 1], Standardwert: 0
Antwort:
  • keine Antwort

Setzt die Periode mit welcher der CALLBACK_DATE_TIME Callback ausgelöst wird. Ein Wert von 0 deaktiviert den Callback.

Der CALLBACK_DATE_TIME Callback wird nur ausgelöst, wenn sich das Datum oder die Zeit seit der letzten Auslösung geändert haben.

BrickletGPS.get_date_time_callback_period
Funktions-ID:
  • 16
Anfrage:
  • keine Nutzdaten
Antwort:
  • period – Typ: uint32, Einheit: 1 ms, Wertebereich: [0 bis 232 - 1], Standardwert: 0

Gibt die Periode zurück, wie von set_date_time_callback_period gesetzt.

Callbacks

BrickletGPS.CALLBACK_COORDINATES
Funktions-ID:
  • 17
Antwort:
  • latitude – Typ: uint32, Einheit: 1/1000000 °, Wertebereich: [0 bis 90000000]
  • ns – Typ: char, Wertebereich: ['N', 'S']
  • longitude – Typ: uint32, Einheit: 1/1000000 °, Wertebereich: [0 bis 180000000]
  • ew – Typ: char, Wertebereich: ['E', 'W']
  • pdop – Typ: uint16, Einheit: 1/100, Wertebereich: [0 bis 216 - 1]
  • hdop – Typ: uint16, Einheit: 1/100, Wertebereich: [0 bis 216 - 1]
  • vdop – Typ: uint16, Einheit: 1/100, Wertebereich: [0 bis 216 - 1]
  • epe – Typ: uint16, Einheit: 1 cm, Wertebereich: [0 bis 216 - 1]

Dieser Callback wird mit der Periode, wie gesetzt mit set_coordinates_callback_period, ausgelöst. Die Parameter sind die gleichen wie die von get_coordinates.

Der CALLBACK_COORDINATES Callback wird nur ausgelöst, wenn sich die Koordinaten seit der letzten Auslösung geändert haben und ein Fix vorhanden ist (siehe get_status).

BrickletGPS.CALLBACK_STATUS
Funktions-ID:
  • 18
Antwort:
  • fix – Typ: uint8, Wertebereich: Siehe Bedeutungen
  • satellites_view – Typ: uint8, Wertebereich: [0 bis 255]
  • satellites_used – Typ: uint8, Wertebereich: [0 bis 255]

Dieser Callback wird mit der Periode, wie gesetzt mit set_status_callback_period, ausgelöst. Die Parameter sind die gleichen wie die von get_status.

Der CALLBACK_STATUS Callback wird nur ausgelöst, wenn sich der Status seit der letzten Auslösung geändert hat.

Die folgenden Bedeutungen sind für die Elemente dieser Funktion definiert:

Für fix:

  • 1 = No Fix
  • 2 = 2D Fix
  • 3 = 3D Fix
BrickletGPS.CALLBACK_ALTITUDE
Funktions-ID:
  • 19
Antwort:
  • altitude – Typ: int32, Einheit: 1 cm, Wertebereich: [-231 bis 231 - 1]
  • geoidal_separation – Typ: int32, Einheit: 1 cm, Wertebereich: [-231 bis 231 - 1]

Dieser Callback wird mit der Periode, wie gesetzt mit set_altitude_callback_period, ausgelöst. Die Parameter sind die gleichen wie die von get_altitude.

Der CALLBACK_ALTITUDE Callback wird nur ausgelöst, wenn sich die Höhe seit der letzten Auslösung geändert hat und ein Fix vorhanden ist (siehe get_status).

BrickletGPS.CALLBACK_MOTION
Funktions-ID:
  • 20
Antwort:
  • course – Typ: uint32, Einheit: 1/100 °, Wertebereich: [0 bis 36000]
  • speed – Typ: uint32, Einheit: 1/100 km/h, Wertebereich: [0 bis 232 - 1]

Dieser Callback wird mit der Periode, wie gesetzt mit set_motion_callback_period, ausgelöst. Die Parameter sind die gleichen wie die von get_motion.

Der CALLBACK_MOTION Callback wird nur ausgelöst, wenn sich die Bewegung seit der letzten Auslösung geändert hat und ein Fix vorhanden ist (siehe get_status).

BrickletGPS.CALLBACK_DATE_TIME
Funktions-ID:
  • 21
Antwort:
  • date – Typ: uint32, Wertebereich: [10100 bis 311299]
  • time – Typ: uint32, Wertebereich: [0 bis 235959999]

Dieser Callback wird mit der Periode, wie gesetzt mit set_date_time_callback_period, ausgelöst. Die Parameter sind die gleichen wie die von get_date_time.

Der CALLBACK_DATE_TIME Callback wird nur ausgelöst, wenn sich das Datum oder die Zeit seit der letzten Auslösung geändert haben.