Handregler - PC Schnittstelle

Anschluß

    Der PC kann über eine USB-Schnittstelle angeschlossen werden. Dabei wird ein virtueller COM-Port initialisiert. (USB-IF OpenDCC Throttle V1.0, VID=0x0403, PID=0xBFDA). Diese USB-Schnittstelle dient zum einen für den Firmware-Update sowie als Interface für die Konfiguration.
    Eine gleichzeitige Verbindung von Xpressnet und USB ist möglich, jedoch entsteht hierbei eine Masseverbindung vom PC zum Xpressnet. Diese kann die VDE-gerechte Schutztrennung der Modellbahn aufheben und ist daher offiziell nicht erlaubt.

Firmware-Update

    Wenn beim Einschalten des Handreglers die Shifttaste gedrückt ist, dann wird der Bootloader aktiv und es kann ein Firmware-Update durchgeführt werden. Das Display ist aus, es leuchten Softkey A (grün) und Softkey (D) rot. Der Bootloader kommuniziert im standard-AVROSP Protokoll mit 19200 Baud. 8N1. Nähere Informationen finden sich in der Bauanleitung.

Konfigurationsschnittstelle

    Vorab ein wichtiger Hinweis: das XBEE Modul und USB benutzen den gleichen Anschluß am Prozessor, ein gleichzeitiger Betrieb von USB und XBEE-Modul ist daher nicht möglich. Wenn ein Modul installiert ist, so erhält dieses automatisch den Vorrang. Man muß daher das XBEE-Modul manuell über das Setup-Menu deaktivieren, um die USB-Schnittstelle benutzen zu können.
    Im regulärem Betrieb ist auf dem USB-Port ein Kommando-Interface (API) implementiert, mit dem man Befehle an den Handregler absenden kann. Die API arbeiten mit einem seriellen Protokoll, eingestellt sind 115200 Baud, 8 Bit, keine Parity, 1 Stopbit (8N1). Übertragen werden 8-Bit ASCII, die API unterscheidet bei Befehlen nicht nach Groß-Kleinschreibung. Gesendete Befehle werden mit <cr> oder <cr-lf> terminiert, die Antwort enthält <cr-lf> als Endemarkierung.
    Unbekannte Befehl werden mit 'unknown command' beantwortet.

API Befehle

  • Backup
    Parameter: keine
    Aktion: Es wird eine Liste mit zwei Datensätzen je Lok ausgegeben. Der Inhalt ist wie folgt:
             LocADD Lok#, SPEEDSTEPS, FORMAT, NAME
         LocPic Lok#, <Picture-ID>
    Diese Liste kann einfach auf PC abgespeichert werden und für ein Wiedereinpielen zurück an den Handregler übertragen werden.
  • Help
    Parameter: keine
    Antwort: ein Hilfetext, der die API-Befehle kurz erläutert.
  • Info
    Parameter: keine
    Antwort: MFT_G 1.0 version 00.08 api 01 xbee 1 (Beipiel)
    Die Antwort besteht aus einem String, beginnend mit dem Hardware Identifier (MFT_G (für Graphikdisplay) oder MFT_C (für Char-Display)) und der Versionnummer. Es folgen weitere Schlüsselworte, jeweils gefolgt von einem Zahlenwert.
    MFT_<X>Das bezeichnet die Geräteart, <X> bezeichnet das Display; C=char 20 x 4, G=Graphik 128x64
    versionDie geladene Softwareversion wird angezeigt, bestehen aus [Hauptversion].[Unterversion]
    api Dies ist die Versionnummer des Parsers, anhand dieser kann unterschieden werden, welcher Befehlsvorrat unterstützt wird.
    xbee Gibt an, ob ein Funkmodul installiert ist.
  • LocADD Lok#, SPEEDSTEPS, FORMAT, NAME
    Parameter:
    Lok#Lokadresse (1 .. 10239)
    SPEEDSTEPSAnzahl der Fahrstufen, mögliche Auswahl: 14, 28, 126
    FORMATLokformat, mögliche Auswahl: hier nur DCC
    NAMEmax. 10 Zeichen (ASCII);
    Antwort: Ein String wie bei LocQuery oder ERROR:11 (=data base full, last entry was not stored)
    Aktion: Die Lok wird in die interne Datenbank aufgenommen und permanent gespeichert. Wenn eine Lok mit gleicher Adresse in der Datenbank bereits vorhanden ist, dann wird diese mit der neuen Lok ersetzt und ein eventuell vorhandener Bildverweis gelöst. (Dieser ist dann mit LocPic neu zu setzen.)
  • LocDel [Lok#]
    Parameter:
    Lok#Lokadresse (1 .. 10239); wenn keine Lokdrasse angegeben ist, werden alle Datensätze gelöscht.
    Antwort: OK Es werden eine (oder alle) Loks aus der Datenbank des Handreglers gelöscht.
  • LocDump
    Aktion: Es wird eine Liste mit einem Datensatz pro Zeile ausgegeben. Der Aufbau jeder Zeile ist wie folgt:

    Lok#, SPEEDSTEPS, FORMAT, NAME
    Die Liste wird mit einer Zeile "*END*" abgeschlossen.
  • LocFree
    Parameter: keine
    Antwort: Integerzahl
    Die Anzahl noch freier Lokdatenspeicher wird zurückgemeldet.
  • LocPic Lok#, [<Picture-ID>]
    Parameter:
    Lok#Lokadresse (1 .. 10239)
    Picture-IDKennziffer des der Lok zuzuordnenden Bildes.
    Antwort: OK oder Error: Locaddr
    Aktion: Wenn eine Lok mit dieser Adresse in der Datenbank vorhanden ist, dann wird der Bildverweis mit der Picture-ID ersetzt. Wenn keine Pict-ID angegeben wurde, wird die Pict-ID der angefragten Lok angezeigt. Wenn die Lok noch nicht vorhanden ist, so wird die Fehlermeldung Error: Locaddr ausgegeben.
  • LocQuery Lok#
    Parameter:
    Lok#Lokadresse (1 .. 10239)
    Antwort: Zeile mit Lokinformationen oder Error: Locaddr
    Aktion: Wenn eine Lok mit dieser Adresse in der Datenbank vorhanden ist, dann werden die Informationen zu dieser Lok ausgegeben. Wenn die Lok noch nicht vorhanden ist, so wird die Fehlermeldung Error: Locaddr ausgegeben.
  • PicADD <Picture-ID>
    Parameter:
    Picture-IDKennziffer, unter welcher das neue Bild gespeichert wird.
    Das im Speicher aufgebaute Bild wird mit PicADD unter einer ID gespeichert und kann fortan für Lokomotiven verwendet werden. (ab api 02)
  • PICDEL <Picture-ID>
    Parameter:
    Picture-IDKennziffer des zulöschendes Bildes.
    Bild im Handregler löschen. Bilder im internen Flash können nicht gelöscht werden. (ab api 02)
  • PicFree
    Parameter: keine
    Antwort: Integerzahl
    Die Anzahl noch freier Bildspeicherplätze wird zurückgemeldet.
    (Hinweis: hier wird bis zur Implementierung eines EEPROM Speichers immer 0 zurückgemeldet)
  • PicList <Picture-ID>
    Parameter: keine
    Gibt eine Liste aller verfügbare Bilder aus. (ab api 02)
  • PicPix ADDR BYTE
    Parameter:
    ADDRPageadresse des Bytes (0 ... 191)
    BYTE8 Pixel, welche an dieser Pageadresse liegen.
    Antwort: OK
    Bilder sind als binäre Abbilder der Pixels gespeichert. Ein Bild besteht aus 24 Zeilen und 64 Spalten, Zählung von oben links beginnend. Je 8 Zeilen werden zu einer Page zusammengefasst, Adressierung beginnt oben links und geht dann zuerst durch die Spalten, dann durch die bereits pageweise zusammengefassten Zeilen. 'PicPix 65 255' bedeutet also ein senkrechten Strich über 8 Pixel mitte links, zweite Spalte.
    (Hinweis: enthalten ab api 02)
    • Die folgenden Befehle sind nur für Debugzwecke gedacht, es erfolgt keine Parameterprüfung - bitte vorsichtig benutzen :-)
  • XER ADDR
    Lese von der EEPROM Adresse (z.B. XER 0x34)
  • XEW ADDR DATA
    Schreibe auf EEPROM Adresse (z.B. XEW 0x34 0x45)
  • XFR ADDR
    Lese von der FLASH Adresse (externes SPI Flash) (z.B. XFR 0x34)
  • XFW ADDR DATA
    Schreibe auf FLASH Adresse (z.B. XFW 0x34 0x45)
    Hinweis: Flash kann nur von 1 auf 0 geschrieben werden. Was mal auf 0 ist, kann nur mit Sector-Erase wieder auf 1 gesetzt werden.
  • XFERA
    Löscht das komplette FLASH (dauert 20s), wenn fertig, kommt 'done'.

Anwendung: Bilder einspielen

    Ein Lokbild muß zuerst auf die richtige Größe (64 x 24 Pixel) gebracht werden. Dann wird es als monochromes Bitmap abgespeichert. Diese monochrome Bitmap wird nun bmp2glcd auf ein Format konvertiert, welches für die pageweise Adressierung der LCD besonders geeignet ist. Dieses Bild wird nun mit einer Folge von 192 Befehlen PicPix im Speicher aufgebaut und anschließend mit PicAdd zur Bilddatenbank hinzugefügt.