Dokumentation nachträglich erstellen

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
http://download.nicai-systems.com/nibo/maroon_shield_1_03_schematic.pdf

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
https://learn.adafruit.com/downloads/pdf/rgb-lcd-shield.pdf

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
https://www.adafruit.com/datasheets/HD44780.pdf

Veröffentlicht von

Jürgen

Ich bin Software Ingenieur und habe meine Schwerpunkte in allen Aktivitäten, die zur Software Entwicklung gehören. Am längsten bin ich als Software Entwickler von Embedded Software in C tätig.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.