PAIR Commands für RYS352A

Hier werden einzelne Projekte mit MicroPython vorgestellt
Antworten
Heinrichs
Beiträge: 178
Registriert: Do 21. Okt 2010, 18:31

PAIR Commands für RYS352A

Beitrag von Heinrichs » Sa 18. Mai 2024, 15:16

Was versteht man unter PAIR Commands?

In dem Dokument https://cdn.sparkfun.com/assets/e/5/e/8 ... -506N5.pdf habe ich folgende Beschreibung gefunden:

PAIR command is an AIROHA proprietary GNSS data transfer protocol. This protocol is used to configure the GNSS module's parameters, aiding information and to receive notifications from the GNSS module. The PAIR aligns with the NMEA sentence format to process data more efficiently.

Auf deutsch: PAIR Command ist ein AIROHA-eigenes GNSS-Datenübertragungsprotokoll. Dieses Protokoll wird verwendet zum Konfigurieren der Parameter des GNSS-Moduls, Informationen unterstützend, und um Benachrichtigungen vom GNSS-Modul zu erhalten. Das PAIR [-Protokoll] folgt dem NMEA-[Daten-]Satz-Format, um Daten effizienter zu verarbeiten.

Das PAIR-Protokoll wurde von der Firma AIROHA entwickelt; vielleicht leitet sich die Bezeichnung PAIR aus einer Zusammenziehung von “Protocol” und “AIROHA” ab.

Die obige Beschreibung deckt m. E. nicht das ganze Leistungsspektrum der PAIR Commands ab. Schaut man sich die Beschreibungen der PAIR Commands an, findet man am Ende einer solchen Beschreibung jeweils eine Typ-Angabe. Es lassen sich (im Wesentlichen) drei Typen finden:
  • Command-Typ: Kommandos von diesem Typ lösen einen Prozess beim GNSS-Modul aus. Dies kann z. B. ein Kalt-Start des Moduls ($PAIR007) sein oder das Speichern der aktuellen Navigations-Daten aus dem RAM in den Flash ($PAIR511).
  • Set-Typ: Durch Kommandos von diesem Typ kann man Parameter des GNSS ändern. Damit kann man z. B. das Aktualisierungsintervall einstellen (Das ist das Intervall, nach dem das GNSS-Modul aus den empfangenen Satellitensignalen jeweils eine Positionsbestimmung durchführt.); das zugehörige PAIR Command ist $PAIR050. Mit dem Kommando $PAIR066 kann man festlegen, mit welchen Satellitensystemen gearbeitet werden soll.
  • Get-Typ: Mit Kommandos von diesem Typ kann man die Werte von Parametern abfragen, mit denen das Modul arbeitet. Z. B. Kann man mit dem Kommando $PAIR051 den Wert des Aktualisierungsintervalls abfragen.

Arbeiten mit PAIR Commands

Als erstes wollen wir die Grundsätze der Verfahrensweise verdeutlichen. Hierzu benutzen wir als Beispiel das Kommando $PAIR051. Ganz bewusst greifen wir hier auf ein Kommando vom Get-Typ zurück: Hier bleiben nämlich Fehleingaben folgenlos.

Als Grundlage benutzen wir das Datenblatt RYS352x_PAIR_Command_Guide.pdf vom 18.12.2023 (s. Anhang). Hier finden wir im Abschnitt 2.3.10 folgende Informationen zur Ermittlung des Aktualisierungsintervalls (position fix interval):

Message$PAIR051
DescriptionGets the position fix interval
TypeGet

Code: Alles auswählen

Message Structure
$PAIR051*<Checksum><CR><LF>
Ein Parameter muss hier nicht mit auf den Weg gegeben werden. Allerdings müssen wir noch die Prüfsumme (Checksum) bestimmen. Diese ergibt sich aus einer XOR-Verknüpfung der einzelnen Bytes des PAIR-Kommandos. Wir benutzen hierzu der Einfachheit halber das Programm checksum.py (s. Anlage Materialien): Nach dem Start dieses Programms geben wir wie angefordert PAIR051 (ohne das $-Zeichen) ein. In unserem Fall liefert das Programm den Hex-Wert 0x3e.

Die zu sendende Message ist demnach $PAIR051*3E. Das geben wir in dem Programm RYS352A_PAIR_CMD.py (s. Anlage Materialien) als PAIR Command ein. Als Antwort erhalten wir die beiden Zeilen:

Code: Alles auswählen

$PAIR001,051,0*3F
$PAIR051,1000*13
In der ersten Zeile bestätigt das Modul mit dem PAIR Command $PAIR001, dass es eine Message erhalten hat (PAIR_ACK, Acknowledge = Bestätigung). Hierbei wird mit dem Parameter 051 die Nummer des Kommandos angegeben. Der zweite Parameter (hier 0) zeigt an, dass das Kommando erfolgreich ausgeführt wurde. Die hinter dem * angegebene Prüfsumme 3F könnte man zur Absicherung nutzen; darauf wollen wir aber hier verzichten. (In seltenen Fällen kann hier der zweite Parameterwert auch 1 (NACK = Not acknowledged) sein, dann ist das Kommando noch nicht vollständig bearbeitet und man muss auf das nächste $PAIR001-Kommando warten, welches dann hoffentlich mit einem Parameterwert 0 (ACK = acknowledged) aufwartet.) In der nächsten Zeile erhalten wir (als einzigen Parameter) das Ergebnis 1000. Dieser gibt an, dass aktuell jede 1000 ms eine Aktualisierung (neue Ermittlung der Position aus den empfangenen Satellitensignalen) erfolgt.

Die Antworten bestehen in der Regel aus 1 bis 3 PAIR-Commands. Bei allen drei Typen besteht die Antwort mindestens aus einem $PAIR001-Kommando; sollte hier der ACK-Wert nicht 0 sein, wird man noch auf eine weitere Antwort (in Form eines PAIR-Commands mit dem ACK-Wert 0) warten müssen. Beim Get-Typ erhält man darüber hinaus noch ein PAIR-Kommando mit den angeforderten Daten. In dem Datenblatt RYS352x_PAIR_Command_Guide.pdf können Sie an Hand der Beispiele sehen, wie viele Antworten es im Einzelfall gibt. Im Folgenden betrachten wir nur Fälle, bei denen eine NACK-Antwort nicht erscheinen sollte. Das im nächsten Abschnitt vorgestellte Programm erwartet dementsprechend nur ein einziges $PAIR001 Command (mit dem ACK-Parameter 0) und bei Get-Kommandos zusätzlich die gewünschten Informationen.

Wer es mit einem Fall zu tun hat, bei dem ein NACK auftaucht, sollte das Programm RS352A_PAIR_CMD_1.py (s. Anhang Materialien) benutzen. Es greift auf dieselben Ideen zurück wie das einfachere Programm RS352A_PAIR_CMD.py, welches im Folgenden vorgestellt und benutzt wird.


Das Programm RYS352A_PAIR_CMD.py

Nach den schon aus Kapitel 3 bekannten Importen und Instanziierungen erfolgt zunächst die Eingabe des PAIR-Kommandos (inkl. $). Anschließend muss man den Typ des PAIR-Kommandos angeben: Beim PAIR-Kommandos vom Typ “Get” ist das “g”, sonst “c” oder “s”.

Code: Alles auswählen

# Importe
from machine import UART
from utime import ticks_ms
from rys352a import RYS352A

# Instanziierungen/Initialisierungen:
	uart = UART(1, baudrate=115_200, bits=8, parity=None, stop=1, tx=12, rx=13, rts=-1, cts=-1, txbuf=256, rxbuf=256, timeout=5000, timeout_char=2)
gnss = RYS352A(uart, ticks_ms)

######################### Hauptprogramm ###########################

# Eingaben...
while True:
    cmd = input('PAIR Command mit checksum: ')
    if cmd[0] != '$':
        print('PAIR Command muss mit $ beginnen!')
    else:
        break
	PAIR_type = input('PAIR-TYP (c, s, g): ') # g bei get
print()

# Bearbeitung...
gnss.uart.readline()         # Lesepuffer leeren
gnss.send_cmd(cmd)           # PAIRCommand senden
weiter = True
while weiter:                # auf Antwort $PAIR001 warten...
    PAIR001_list = gnss.get_data('$PAIR001')
    if PAIR001_list != []:
        print('PAIR001: ', PAIR001_list[0], ',', PAIR001_list[1][0])
        if nr_of_PAIR == ‘g’:
            print(gnss.read_item())
        weiter = False
    else:
        print('Keine Rückmeldung erhalten...')
        weiter = input('PAIR Command noch einmal senden? j/n ')
        print()
        weiter = (weiter == 'j')        
        gnss.send_cmd(cmd)   # PAIR Command noch einmal senden              
Nach dem Entleeren des Lesepuffers wird das PAIR-Kommando an das RYS352A-Modul gesendet. In der folgenden Endlos-Schleife wird zunächst mit Hilfe der get_data-Methode von gnss nach dem ACK-PAIR-Kommando “$PAIR001" gesucht. Wird dieses innerhalb der Timeout-Zeit von 2000 ms (vgl. Kapitel 3) gefunden, dann ist der in PAIR001_list gespeicherte Rückgabewert keine leere Liste; in diesem Fall werden die beiden Parameter von $PAIR001 auf dem Terminal ausgegeben. Gegebenenfalls wird direkt im Anschluss daran auch weitere PAIR-Kommandos vom RYS352A-Modul empfangen und ebenfalls auf dem Terminal ausgegeben.

Kommt es bei der Suche nach dem ACK-PAIR-Kommando zu einem Timeout (was recht häufig geschehen kann), dann ist PAIR001_list gleich []; in diesem Fall verzweigt das Programm in den else-Teil. Hier hat man dann die Möglichkeit, einen weiteren Versuch zu starten...


Anwendungen

Nun ist es an der Zeit, das RYS352A_PAIR_CMD-Programm einzusetzen. Beginnen wir mit PAIR-Commands vom Typ Get:

Beispiel 1: Aktualisierungsrate lesen ($PAIR051)

Dieses Beispiel haben wir oben schon beschrieben. Wenn Sie es noch nicht getestet haben, sollten Sie dies jetzt nachholen.


Beispiel 2: Geschwindigkeitsschwelle lesen ($PAIR071)

Damit ruft man den Schwellenwert für die statische Navigationsgeschwindigkeit ab. Liegt die tatsächliche Geschwindigkeit unterhalb der Schwelle, bleibt die Ausgangsposition unverändert und die Ausgangsgeschwindigkeit beträgt 0. Wird der Schwellenwert auf 0 gesetzt, ist diese Funktion deaktiviert.

In unserem Programm machen wir folgende Eingaben:

Code: Alles auswählen

PAIR Command mit checksum: $PAIR071*3C
Anzahl der zu empfangenden PAIR Commands: 2
Als Antwort erhalten wir:

Code: Alles auswählen

PAIR001:  071 , 0
$PAIR071,0.0*3E
Der zweiten Zeile entnehmen wir, dass die Geschwindigkeitsschwellen-Funktion deaktiviert ist. Wäre hingegen der Schwellenwert z. B. 1,4 m/s, so würde bei einer Geschwindigkeit von 0,8 m/s der nächste Positionswert nicht verändert und als Geschwindigkeit 0 angezeigt werden.


Beispiel 3: GNSS-Suchmodus lesen ($PAIR067)

Mit diesem PAIR-Kommando können wir ermitteln, welche Satelliten-Systeme benutzt werden sollen. In unserem Programm geben wir $PAIR067*3B (mit 2 Antworten) ein. Wir erhalten als Ergebnis:

Code: Alles auswählen

$PAIR067,1,1,1,1,1,0*3A
Wie sind die angegebenen Parameter 1,1,1,1,1,0 zu deuten? Die Einsen und Nullen geben den Zustand der einzelnen Satelitten-Systeme an: Eine 1 steht für aktiviert, eine 0 für deaktiviert. Dabei gilt die Reihenfolge GPS, GLONASS, Galileo, BDS, QZSS, Reserved (=0). In diesem Fall hält unser Modul also Ausschau nach allen Satellitensystemen und wertet die Daten von allen Satelliten aus, die “sichtbar” sind. In Abb. 1 von Kapitel 3 sind das 19 Satelliten. Die relativ niedrige Zahl ergibt sich daraus, dass bei dieser Aufnahme sich das Modul im Haus etwa zwei Meter vom Fenster entfernt befand. Wenn wir nur einen Teil der Satellitensysteme aktivieren, wird diese Zahl sinken. Das werden wir gleich sehen, wenn wir uns den PAIR Commands vom Typ Set widmen.


Beispiel 4: GNSS-Suchmodus setzen ($PAIR066)

Wir wollen jetzt nur mit GPS- und GLONASS-Satelliten arbeiten. Das zugehörige PAIR-Kommando lautet:

Code: Alles auswählen

$PAIR066,1,1,0,0,0,0*3A
Die Prüfsumme haben wir wieder mit dem Programm checksum.py ermittelt.

Starten wir nun das Programm RYS352A_Position_Datetime_more_Display.py (welches zur Aufnahme von Abb. 1 in dem Beitrag Ein RYS352A-Micropython-Modul benutzt worden war), so werden jetzt weniger Satelliten (bei mir 12) angezeigt.

Wenn wir unser RYS352A-Modul jetzt für einige Zeit von der elektrischen Quelle trennen, arbeitet es nach einem Neustart wieder mit allen Satelliten; offensichtlich werden die von uns vorgenommenen Einstellungen nicht dauerhaft gespeichert. (Bemerkung: Vermutlich liegt hier ein Problem mit dem RTC-Akku vor; dessen Spannung ist - wie eine Messung zeigt - viel zu niedrig. Normalerweise sollte der Akku dafür sorgen, dass die Daten im RAM für einige Tage erhalten bleiben.)


Beispiel 5: PPS konfigurieren ($PAIR752)

Die grüne PPS-LED blinkt jede Sekunde einmal auf. Dabei ist sie für 100 ms ein- und 900 ms ausgeschaltet. Die Leuchtdauer können wir mit dem PAIR-Kommando 752 ändern. Soll die Leuchtdauer z. B. 500 ms betragen, lautet das zugehörige Kommando:

Code: Alles auswählen

$PAIR752,2,500*3D
Dabei gibt der Parameter 2 (Standard) an, dass das Blinksignal erfolgen soll, wenn 3D-Positions-Daten zur Verfügung stehen. Der zweite Parameter gibt die Leuchtdauer in ms an. Auch diese Einstellung ist nicht dauerhaft gespeichert (s. o.).


Beispiel 6: Navigationsmodus einstellen ($PAIR080)

Das GNSS-Modul muss aus den zahlreichen Satelliten-Signalen passende Werte für die Position berechnen. Dabei berücksichtigt es auch das Bewegungsverhalten des GNSS-Moduls. Um hierbei möglichst gute Werte zu erzielen, kann man dem RYS352A-Modul mit dem $PAIR080-Kommando Hinweise zur Bewegungsart geben. In der folgenden Tabelle sind die implementierten Bewegungstypen angegeben; zusätzlich wird erläutert, wie die speziellen Umstände bei der Positionsberechnung berücksichtigt werden.

Implementiert sind folgende Modi:

IndexBezeichnungErläuterung
0NormalmodusFür allgemeine Zwecke
1FitnessmodusWird zum Laufen und Gehen verwendet, wodurch Bewegungen mit niedriger Geschwindigkeit (< 5 m/s) einen größeren Einfluss auf die Positionsberechnung haben.
5DrohnenmodusWird für Drohnenanwendungen mit gleichwertigem Dynamikbereich und gleicher Vertikalbeschleunigung in verschiedenen Flugphasen verwendet. (Zum Beispiel Schweben, Cruisen)
7SchwimmmodusWird zum Schwimmen verwendet, um die Bahnkurve zu glätten und die Genauigkeit der Distanzberechnung zu verbessern

Das Kommando für den Fitnessmodus lautet z. B.:

Code: Alles auswählen

$PAIR080,1*2F
Auch diese Einstellung ist nicht dauerhaft gespeichert. Mit dem Kommando $PAIR081*33 kann man das überprüfen.


Beispiel 7: Aktuelle Konfiguration vom RTC-RAM im Flash speichern ($PAIR513)

Dieses PAIR-Kommando ist vom Typ Command (s. o.). Hier werden also keine Parameter gesetzt oder gelesen. Nach der Ausführung stehen die Konfigurationsdaten im Flash; bei einem Kalt-Start greift unser RYS352A auf diese Konfiguration zurück. Um dieses Kommando zu testen, sollten sie zuvor einen Standard-Parameter z. B. die Leuchtdauer der PPS-LED ändern.

Das Kommando lautet:

Code: Alles auswählen

$PAIR513*3D
Wenn Sie zuvor die PPS-Leuchtdauer auf 500 ms eingestellt haben, sollte dann bei einem Kalt-Start die Leuchtdauer wieder 500 ms betragen.

Auf ähnliche Weise kann man mit dem $PAIR511-Kommando die aktuellen Navigations-Daten vom RTC-RAM im Flash speichern.


Beispiel 8: Kalt-Start auslösen ($PAIR006)

Durch dieses Kommando wird ein Kaltstart durchgeführt, was bedeutet, dass keine Standortinformationen im Empfänger gespeichert sind, einschließlich Zeit, Position sowie Almanach- und Ephemeridendaten.

Das Kommando lautet:

Code: Alles auswählen

$PAIR006*3C
Das RYS352A-Modul wird dies mit den folgenden beiden ACK-Commands beantworten (Bei Benutzung des Programms RYS352A_PAIR_CMD.py wird nur die erste Zeile angezeigt!):

Code: Alles auswählen

$PAIR001,006,1*3C
$PAIR001,006,0*3D
Bei meinem Test war folgendes zu beobachten: Die PPS-LED hörte auf zu blinken, ein Zeichen dafür, dass keine GNSS-Daten vorliegen. Innerhalb einer Minute fing sie an zu blinken. Dann schaute ich mir mit dem Programm RYS352A_Position_Datetime_more_Display.py (s. Anhang Materialien) die ermittelten Daten an. Interessant war zu sehen, wie die Anzahl der Satelliten bei 12 beginnend stetig anstieg, bis sie nach etwa 10 Minuten auf Werte über 20 gekommen war.


.
Dateianhänge
RYS352A_PAIR.zip
Materialien
(7.07 KiB) 382-mal heruntergeladen
RYS352x_PAIR_Command_Guide.pdf
(1.32 MiB) 382-mal heruntergeladen

Antworten