Hantek Protokoll
Einleitung
Hantek/Tekway verwenden ein proprietäres USB-Protokoll zur Kommunikation mit DSO5xxxB DSOs (bDeviceClass = 255, Vendor Specific Class). Es gibt für das Protokoll kein Windows-SDK, obwohl seit Jahren von Hantek versprochen. Für Linux sollte man von Hantek absolut gar nichts erwarten. Hantek hat prinzipiell nie für ihre Produkte ein Linux-SDK bereitgestellt. Obwohl zum Beispiel die DSO5xxxxB DSOs Linux als Betriebssystem verwenden[1].
Die USB- und Protokoll-Implementierung sind ziemlich vermurkst. DSOs sind alleine über die USB VID:PID 049f:505a[2] und die Bus- und Deviceadresse auf dem USB-Bus identifizierbar. Beim Betrieb mehrerer DSO5xxxBs an einem PC kann man diese nicht neben der VID_PID über ihre Seriennummer identifizieren, da Hantek die nicht im USB-Descriptor angibt (iSerial ist 0). Und zu guter Letzt meldet sich das DSO beim Booten kurz mit einer anderen VID:PID am Bus (vermutlich einer von Rigol ...).
Das Protokoll verwendet USB Bulk-Transfers, Bulk-Out Endpunkt 0x01, Bulk-In Endpunkt 0x82, maximal 64 Bytes pro USB Bulk-Package.
Über den USB Bulk-Paketen liegt direkt Hanteks DSO-Protokoll. Es ist Anfrage/Antwort orientiert. Das heißt, der USB Host (PC) sendet eine Anfrage und erhält eine oder mehrere Antworten. Das Protokoll kann daher synchron, in einem einzigen Thread, implementiert werden, obwohl Hantek angeblich in TTScope separate Sende- und Empfangsthreads verwendet. Meldungen des Hantek DSO-Protokolls können länger als 64 Bytes sein. Sie werden entsprechend auf mehrere Bulk-Pakete aufgeteilt[3].
Grundsätzlicher Aufbau
| Markierung 0x43 oder 0x53 |
Länge | Kommando | Datenbytes | Checksumme | ||
| LSB | MSB | |||||
| Markierung 0x43 oder 0x53 |
Länge | Kommando | Subkommando | Datenbytes | Checksumme | |
| LSB | MSB | |||||
| Markierung 0x43 oder 0x53 |
Länge | Kommando | Checksumme | |||
| LSB | MSB | |||||
Das Meldungsformat ist identisch für Anfragen und Antworten. Jede Meldung beginnt mit einem Markierungsbyte. Es gibt zwei unterschiedliche Markierungen:
0x53: Normale Meldung 0x43: Debugging Meldung
Dem Markierungsbyte folgen zwei Bytes mit einer Längenangabe, LSB zuerst. Das Längenwort enthält die Gesamtlänge minus 3.
Dem Längenwort folgt das Kommando-Byte. Es bezeichnet das gewünschte Kommando. siehe 0x53 Normale Meldungen. Ein gesetztes 7. Bit bedeutet es handelt sich um eine Antwort. Somit gibt es in Richtung PC --> DSO nur Kommando-Bytes < 0x80, in Richtung DSO --> PC nur Kommando-Bytes >= 0x80.
Dem Kommando-Byte folgen kommando-spezifische Datenbytes. Manche Kommandos verwenden das erste Datenbyte als ein Unterkommando-Byte. Die Anzahl der Datenbytes kann Null sein.
Den Datenbytes folgt eine primitives Checksummen-Byte. Es ist die dümmster Art eine Checksumme zu berechnen. Es werden alle Bytes der Meldung aufsummiert und das LSB der Summe als Checksumme verwendet.
0x53 Normale Meldungen
0x00 Echo
Alle Datenbytes in der Anfrage werden einfach unverändert zurückgesendet.
0x01 DSO Einstellungen lesen
Man erhält einen langen Datensatz, in dem die aktuellen Einstellungen des DSO binär-kodiert sind.
0x02 Sample-Daten lesen
0x10 Datei lesen
Liest eine beliebige Datei auf dem DSO. Die Anfrage enthält den vollständigen Dateipfad.
Die Antwort verwendet zwei Unterkommando-Bytes
0x01: Daten 0x02: Checksumme über alle Daten
Da eine Antwort nur knapp 64KB enthalten kann, werden eventuell mehrere Antworten mit dem Unterkommando-Byte 0x01 gesendet. Ein Unterkommando-Byte 0x02 markiert das Ende der Dateiübertragung und enthält gleichzeitig eine Checksumme über alle Bytes der Datei.
0x11 DSO Einstellungen schreiben
Man muss einen Datensatz mit den binärkodierten Einstellungen senden, entsprechend 0x01 DSO Einstellungen lesen
0x12 Bedienfeld sperren/freischalten
Erlaubt es, das DSO-Bedienfeld zu sperren oder zu entsperren. Folgende Datenbytes sind bekannt:
0x01 0x00: Entsperren 0x01 0x01: Sperren
Ist dass Bedienfeld gesperrt, erscheint ein roter Schlüssel in der oberen Statusleiste auf dem DSO-Bildschirm und die Bedienelemente haben keine Funktion mehr.
In der Antwort enthält man jeweils die gesendeten Datenbytes zurück. Man erhält leider nicht den vorherigen Zustand zurück.
0x13 Tastendruck auslösen
Erlaubt es das Drücken fast aller DSO-Tasten zu simulieren. Die gewünschte Taste wird durch jeweils zwei Datenbytes ausgewählt:
0x00 0x01 - F0 Taste 0x01 0x01 - F1 Taste 0x02 0x01 - F2 Taste 0x03 0x01 - F3 Taste 0x04 0x01 - F4 Taste 0x05 0x01 - F5 Taste 0x06 0x01 - F6 Taste 0x07 0x01 - F7 Taste 0x08 0x01 - V0 links drehen 0x09 0x01 - V0 rechts drehen 0x0A 0x01 - V0 drücken 0x0B 0x01 - Save/Recall Taste 0x0C 0x01 - Measure Taste 0x0D 0x01 - Acquire Taste 0x0E 0x01 - Utility Taste 0x0F 0x01 - Cursor Taste 0x10 0x01 - Display Taste 0x11 0x01 - Autoset Taste 0x12 0x01 - Single Seq Taste 0x13 0x01 - Run/Stop Taste 0x14 0x01 - Help Taste 0x15 0x01 - Default Setup Taste 0x16 0x01 - Save to USB Taste 0x17 0x01 - Math Menu Taste 0x18 0x01 - CH1 Menu Taste 0x19 0x01 - CH1 Position links drehen 0x1A 0x01 - CH1 Position rechts drehen 0x1B 0x01 - CH1 Position drücken 0x1C 0x01 - CH1 Volts/Div links drehen 0x1D 0x01 - Ch1 Volts/Div rechts drehen 0x1E 0x01 - CH2 Menu Taste 0x1F 0x01 - CH2 Position links drehen 0x20 0x01 - CH2 Position rechts drehen 0x21 0x01 - CH2 Position drücken 0x22 0x01 - CH2 Volts/Div links drehen 0x23 0x01 - Ch2 Volts/Div rechts drehen 0x24 0x01 - Horz Menu Taste 0x25 0x01 - Horizontal Position rechts drehen 0x26 0x01 - Horizontal Position links drehen 0x27 0x01 - Horizontal Position drücken 0x28 0x01 - Horizontal Sec/Div links drehen 0x29 0x01 - Horizontal Sec/Div rechts drehen 0x2A 0x01 - Trig Menu Taste 0x2B 0x01 - Trigger Level links drehen 0x2C 0x01 - Trigger Level rechts drehen 0x2D 0x01 - Trigger Level drücken 0x2E 0x01 - Set to 50% Taste 0x2F 0x01 - Force Trig Taste 0x30 0x01 - Probe Check Taste
Die Antwort zu einem Tastenkomando enthält ein Datenbyte, dass das selektierte Menü bezeichnet, bevor der Tastendruck simuliert wurde. Das Menü muss nicht notwendigerweise angezeigt sein. Auch wenn es ausgeblendet ist, enthält die Antwort ein entsprechendes Datenbyte, dass des Menüs das angezeigt worden wäre, wenn es nicht ausgeblendet wäre.
0x14 Systemzeit setzen
Erlaubt es Datum und Zeit des DSOs zu setzen. Die Anfrage enthält sieben Datenbytes:
Byte 0: Jahr (LSB) \_ Nicht kleiner als 2009 Byte 1: Jahr (MSB) / Byte 2: Monat (1 ... 12) Byte 3: Tag (1 ... 31) Byte 4: Stunde (0 ... 23) Byte 5: Minute (0 ... 59) Byte 6: Sekunde (0 ... 59)
Die Antwort ist leer. D.h. sie enthält kein Datenbyte.
0x20 Bildschirm-Snapshot
0x21 Systemzeit lesen
Erlaubt es die Systemzeit zu lesen. Die Anfrage ist leer, d.h. enthält kein Datenbyte. Die Antwort enthält sieben Datenbytes, siehe 0x14 Systemzeit setzen.