Das Ziel für eine nachträgliche Dokumentation ist eine möglichst ausführliche Beschreibung aus allen (noch) vorhandenen Quellen zusammenzustellen. Damit wird die weitere Arbeit mit der Software deutlich vereinfacht, da man nicht mehr jedesmal sich die benötigten Informationen zusammen suchen muss.
Am Beispiel Maroon Shield
Zu diesem Shield liegen bereits einige Informationen verteilt vor. Vom Zusammenlöten und aus dem Stromlaufplan ist klar, das es zwei Taster gibt. Es muss also eine Möglichkeit geben, den Zustand dieser Tasten festzustellen. In der Firmware (-> Software Analyse, Modul process.c) sehe ich dann die Bestätigung. Es werden je nach Zustand der Tasten unterschiedliche ASCII Zeichen über die serielle Schnittstelle zurückgeschickt.
Im Kommunikationsprotokoll sind dann verschiedene Kommandos beschrieben, die das Shield kann oder später können soll. Für diese Firmware (Software Analyse, Modul process.c) sind eigentlich nur die Kommandos interessant, die bereits existieren. Es ist ein recht einfaches Protokoll aus lauter Escape (0x1b) Sequenzen, das sind bestimmte Werte, die als Steuerzeichen im Datenstrom herausgefiltert werden und mit den zusätzlichen Parametern die Steuerung des Displays erledigen. In der Firmware (-> Software Analyse, Modul unicode.c) sehe ich dann die Bereiche für die unicode (16 bit) Zeichen (dezimal):
0x00 bis 0x1F : Steuerzeichen
0x20 bis 0x7F : Basis Zeichensatz
0x80 bis 0x9F : Steuerzeichen
0xA0 bis 0xFF : Erweiterter Zeichensatz
0x0100 bis 0x206F : nichts
0x2070 bis 0x207F : Superscript Zeichen
0x2080 bis 0x208F : Subscript Zeichen
0x2591, 0x2592, 0x2593, 0x2639,
0x2680 bis 0x2685, 0x263A, 0x20AC : Sonderzeichen
Aus einer Unicode Zeichentabelle und in font.c kann ich die darstellbaren Zeichen nachlesen.
Mit diesen Informationen kann ich eine Dokumentation erstellen:
0. Zeichenerklärung
1. Serielle Parameter
2. Stream Kommandos (mit der nächsten Ausgabe)
3. Zeichensatz Kommandos
4. sofort Kommandos (ohne Verzögerung)
5. Rückgabewerte der beiden Tasten
und erhalte eine Arbeitsbasis, die mir den Umgang mit dem Maroon Shield erheblich vereinfacht.
Am Beispiel LCD Shield
Für das LCD Shield sind schon weniger Informationen verfügbar. So bleibt die Firmware auf dem Prozessor, der das LCD Shield steuert, unsichtbar. Was vorhanden ist, ist eine ausführliche Beschreibung, wie das Shield zusammengelötet wird und wie man es in der Arduino Software benutzt. Schaltpläne sind ebenfalls vorhanden, allerdings ohne Hinweis, mit welcher Software die lesbar sind, ich vermute allerdings, das es das program Eagle, ein Layoutprogramm, ist. Im Dokument ‚using-the-rgb-lcd-shield‘ ist der Abschnitt ‚Writing your own Sketches‘ und der Abschnitt ‚Detached Usage‘ die Hauptquelle an Informationen. Auch aus diesen Informationen lässt sich eine gute Dokumentation erstellen:
0. Kontrasteinstellung
1. Sonderfunktionen
2. Standardfunktionen aus der Liquid Crystal Bibliothek
3. verfügbarer Zeichensatz
Allgemein
1. Welche Quellen sind vorhanden?
1.1 Schaltpläne / Stromlaufpläne
1.2 eingebettete Software / Firmware, Sourcen oder Beschreibung
1.3 Dokumentation von Komponenten (Datenblatt oder Datasheet) mit Informationen zur Ansteuerung, Kennlinien, usw.
1.4 Beschreibungen zur Funktion (Anforderungen)
1.5 Kommunikationsprotokolle
2. Was brauche ich in welcher Reihenfolge, um das Shield / die Komponente zu betreiben?
Daraus lässt sich immer eine gute Übersicht und Dokumentation für das jeweilige Shield, die Komponente etc. erstellen. Hat man erst einmal ein solches Dokument, ist die Arbeit damit viel einfacher, ohne lange zu Suchen.
Links
Maroon Shield – Stromlaufplan
Klicke, um auf maroon_shield_1_03_schematic.pdf zuzugreifen
Maroon Shield – Kommunikationsprotokoll
http://www.nibo-roboter.de/wiki/Maroon_Shield/Protokoll
Maroon Shield Firmware
https://sourceforge.net/p/maroon-shield/code/HEAD/tree/trunk/ -> Download Snapshot
Unicode
https://de.wikipedia.org/wiki/Unicode
ASCII Tabelle
https://de.wikipedia.org/wiki/American_Standard_Code_for_Information_Interchange#ASCII-Tabelle
Bauanleitung LCD Shield
Klicke, um auf rgb-lcd-shield.pdf zuzugreifen
Software Bibliothek LCD Shield benutzen
https://learn.adafruit.com/rgb-lcd-shield/using-the-rgb-lcd-shield
LCD Shield Library
https://github.com/adafruit/Adafruit-RGB-LCD-Shield-Library
LCD Shield Schematics and Layout (Eagle 6 format)
https://github.com/adafruit/Adafruit-RGB-LCD-shield
Datenblatt LCD Display
