oder: Wie hänge ich mein AddOn in BiDiB ein?

Die Basissoftware des BiDiBOne enthält neben den Funktionen zur Kommunikation mit dem BiDi-Bus auch das Tasksystem Cortos und einige andere Grundfunktionen sowie die Debug-Schnittstelle.

Darauf sollen die verschiedenen AddOns mit möglichst einfachen Mitteln aufbauen können.

Für eine bessere Übersicht und Wartung sind die Quellen für Basis und AddOn(s) in verschiedenen Projekten unter einer Solution organisiert.

Es gibt eine Solution: BiDiBOne mit dem Projekt Basis und weiteren AddOn-Projekten (Details siehe unten).

Das Zusammenspiel der einzelnen Projekte wird in den Properties der Solution geregelt.

Dazu ist im Solution-Explorer die Solution-Zeile anzuwählen und im Kontextmenü (z.B. Rechtsklick) der Menüpunkt Properties zu wählen.

Im Atmel Studio 6 hat man die Auswahl zwischen einem einzelnen oder mehreren Startup Projekten. In jedem Falle kann man aber beim BiDiBOne nur einen Startpunkt wählen. Das sollte das AddOn-Projekt sein:

Die Abhängigkeiten unter den einzelnen Projekten sind im Absatz Project Dependencies einzustellen (dazu jedes Projekt einzeln in der Drop-Down-Box aufrufen): Die Abhängigkeiten regeln die Reihenfolge, in der die einzelnen Projekte gebaut werden. Die zeigt Atmel Studio 6 u.A. im Punkt Startup Projects.

Die Basis enthält alle zum Betrieb notwendigen Funktionen. Zusätzlich werden viel gebrauchte Hilfsfunktionen zur Verfügung gestellt.

Die Quellen im Basis-Projekt sollten in keinem Falle direkt geändert werden. Sollten dennoch Anpassungen notwendig sein, die nicht allgemeingültig sind das unter AddOn-Basisersatz-Projekt beschriebene Verfahren zu verwenden.

Dieses Vorgehen dient der klaren Trennung und leichteren Wartbarkeit der Software.

Das AddOn-Projekt enthält die eigentliche Funktionalität für die Zusatzhardware.

Um die vordefinierten Funktionen dem Basis-Projekt zugänglich zu machen, ist in den Properties des AddOn-Projektes im Kapitel: ToolChain - AVR/GNU C Compiler bei Symbols das Symbol ADDON_IMPLEMENTED einzutragen:

Das AddOn-Projekt liegt parallel zum Basis-Projekt. Es enthält unterhalb des Verzeichnisses src mindestens die Verzeichnisse addon und core. Soll die main-Funktion angepasst werden, muss sie direkt in das src-Verzeichnis kopiert werden.

Das AddOn-Projekt im Solution-Explorer am Beispiel OneControl:

Im addon-Verzeichnis befinden sich die Quellen, die die Anbindung an das Basis-System ermöglichen. Sie werden direkt durch „Add“ eingebunden. Details finden sich weiter unten.

Im core-Verzeichnis befinden sich alle notwendigen Dateien aus dem Basis-Projekt. Sie werden als „Add As Link“ eingebunden und werden so nicht physisch kopiert sondern verbleiben ausschließlich im Basis-Projekt. Die Quellen werden mit einem Verknüpfungssymbol angezeigt.

Alle für das AddOn-Projekt notwendigen Verzeichnisse und Quellen können jetzt nach Bedarf ergänzt werden. Es empfiehlt sich aber aus Gründen der klaren Abgrenzung eigene Quellen in Verzeichnisse unterhalb des addon-Verzeichnisses zu legen.

Es kann Fälle geben, in denen man Quellen aus dem Basis-Projekt zeitweilig oder auch dauerhaft für sein AddOn anpassen muss. Und die Anpassungen sollen nicht allgemeingültig sein.

Diese Maßnahme sollte aber die Ausnahme sein, da die in den eigenen AddOns angepassten Quellen nicht bei einem Update des Basis-Projektes nachgeführt werden!

Die anzupassenden Quellen müssen dann in ein eigenes Projekt kopiert werden. Dort können sie angepasst werden ohne Einfluß auf das Basis-Projekt selber oder gar andere AddOns zu nehmen. Hierbei sind die im Folgenden beschriebenen Besonderheiten des Atmel Studio 6 zu beachten.

Das Atmel Studio erstellt aus den Quellen für jedes Projekt einer Solution ein makefile. Quellen, die in anderen Projekten liegen und über eine Verknüpfung referenziert werden, bindet Atmel Studio ebenso ein. Das entsprechende makefile wird aber abhängig von der alphabetischer Reihenfolge der internen Projektnamen aufgebaut. Da unsere angepasste Quellen anstatt der eigentlichen aus dem Basis-Projekt eingebunden werden sollen, müssen sie in einem Projekt mit einem günstigen Namen angelegt werden; hier empfiehlt sich der Name A_<AddOn-Projektname>.

Die Verknüpfung („Add As Link“) im AddOn-Projekt bezieht sich jetzt auf dieses Hilfsprojekt anstatt auf das Basis-Projekt.

Das funktioniert sicher mit C-Quellen. Bei Header-Dateien kann man auf die speziellen Header hinweisen. Allerdings beziehen sich Quellen aus dem Basisverzeichnis immer noch auf ihre Header dort. Bei ungeschickter Konstellation kann das aber zu Inkonsistenzen führen.

Zum korrekten Bauen muss das Hilfsprojekt eine Datei mit einer main-Funktion haben (im Beispiel: mainDummy.c).

(Dieses Verhalten von Atmel Studio lässt sich im makefile überprüfen.)

Die Basissoftware enthält definierte „Hooks“, um die Software der AddOns einzubinden.

Für die eindeutige Erkennung am BiDi-Bus sind die folgenden Angaben (in addon.h) zu machen: Hier am Beispiel einer Eigenbaugruppe (BIDIB_VENDOR_ID=13) und der Produkt-ID 116.

Die Produkt-IDs werden an der angegebenen Adresse (http://www.opendcc.de/elektronik/bidib/opendcc_bidib.html) vergeben.

Zur Initialisierung ruft das Basissystem Funktionen des AddOns an drei Stellen im Modul addon.c auf:

• Nach Abschluss der Basisinitialisierung und vor Freigabe der Interrupts die Funktion addon_init()
• Nach Abschluss der gesamten Initialisierung sowie nach Freigabe der Interrupts und innerhalb einer Task die Funktion addon_power_up()
• Beim Herunterfahren die Funktion addon_close()

Die Funktionen sind din der Quelle addon.c vorbereitet.

Von dort aus können alle weiteren Initialsierungen und „Shutdowns“ aufgerufen werden.

Hier am Beispiel OneControl in einer frühen Version.

Besondere Beachtung ist der power_up_addon-Funktion zu zollen. Sie wird zu Beginn der Taskverwaltung aufgerufen und ist wie eine „normale“ Task zu programmieren. Beendet wird sie erst, wenn die Anwendung -1 zurückliefert.

Während die Power-Up-Tasks noch laufen, startet das Tasksystem alle angemeldeten Tasks, die als ready gekennzeichnet wurden! Um Initialisierungskonflikte zu vermeiden, dürfen die vom AddOn abhängigen Taks erst zum Schluss der Power-Up-Task freigegeben werden!

Zur Einbindung in die Taskverwaltung cortos sind in der Headerdatei: addon_tasklist.h die folgenden Einträge erforderlich:

• Prototypdefinition ADDON_PROTOTYPES
• Task-ID ADDON_TASKENUMS
• Taskdefinition ADDON_TASKLIST
• FIFO-Definitionen ADDON_FIFOS

Alle Teile werden an den betreffenden Stellen in der Taskverwaltung eingebunden. Hier am Beispiel OneControl in einer frühen Entwicklungsphase. (Die FIFO-Definitionen schließen sich entsprechend an.)

Anmerkung: Es ist zu überlegen, ob das Basis-System verschiedene Prioritätsgruppen unterstützen sollte. Dann würden die einzelnen Blöcke entsprechend in die Taskliste der Basis eingefügt.

Nach Erhalt einer MSG_ACCESSORY_SET-Nachricht vom BiDiBus wird die Funktion bidib_msg_accessory_set_addon im Modul addon.c aufgerufen.

Die Argumente sind:

• unsigned char acc_num = Nummer des Accessorys, beginnend mit 0, maximal NUM_OF_ACCESSORY-1
• unsigned char aspect = Nummer des Aspekts, beginnend mit 0, maximal NUM_OF_ASPECTS_PER_ACCESSORY-1

Da diese Aktionen während des Betriebs innerhalb einer Task laufen, gilt auch hier, dass bei komplexeren Funktionen die folgende Bearbeitung lediglich initiiert werden sollte. Die eigentliche Funktionalität sollte in einer entsprechenden Task durchgeführt werden.

… wird fortgesetzt …

Nach Erkennen eines Accessory-Set-Befehls wird aus der Makro-Task heraus die Funktion performAddOnMacro im Modul addon.c aufgerufen:

Hier am Beispiel der Standardmakro-Implementierung. Die Argumente sind:

• lstate ⇒ Schaltbefehl
• lvalue ⇒ Wert des Makropunktes

Die Unterscheidung des Accessory-Typs kann am Beispiel abgelesen werden.

Da diese Aktionen während des Betriebs innerhalb einer Task laufen, gilt auch hier, dass bei komplexeren Funktionen die folgende Bearbeitung lediglich initiiert werden sollte. Die eigentliche Funktionalität sollte in einer entsprechenden Task durchgeführt werden.

Auch das debug_if-Modul enthält „Hooks“ zur Unterstützung der AddOns.

• Aufruftabelle ASCII_PARSE_TAB_ADDON
• Überschrift PA_info_addon()
• Zusammenfassung PA_help_addon()

Diese Teile werden ebenso an den entsprechenden Stellen im Basis-Projekt eingebunden.

Die Aufruftabelle muss in der vorbereiteten Headerdatei: addon_debug_if.h definiert werden.

Hier am Beispiel OneControl mit DMX-Vorgabe:

Zusätzlich müssen hier auch die Prototypen für die eigentlichen Debug-Funktionen definiert werden.

Die Texte für Überschrift und Zusammenfassung werden in der vorbereiteten Quelle addon_debug_if.c formuliert:

Anschließend werden die eigentlichen Debug-Funktionen programmiert.

1. AddOn-Projekt mit vorgegebener Verzeichnisstruktur erstellen
2. Projektattribute anpassen (i.e. ADDON_IMPLEMENTED)
3. In der Solution Projektreihenfolge und -abhängigkeiten festlegen
4. Benötigte Basis-Projekt-Dateien über „Add As Link“ in das core-Verzeichnis einbinden
5. In addon.h Versionsinformationen definieren
6. In addon.c/h Initialisierung und „Shutdown“ veranlassen
7. In addon_tasklist.h Tasks definieren
8. In addon.c Makrofunktionen initiieren
9. In addon_debug.c/h Debugfunktionen einbauen

• BIDIB_VENDOR_ID vendor ID = 13
• BIDIB_PRODUCT_ID product ID see http://www.opendcc.de/elektronik/bidib/opendcc_bidib.html
• CLASS_ACCESSORY occurence of accessory messages (0/1=no/yes)
• CLASS_OCCUPANCY occurence of occupancy messages (0/1=no/yes)
• CLASS_SWITCH occurence of switch messages (0/1=no/yes)

• ADDON_PROTOTYPES Prototypdefinitionen
• ADDON_TASKENUMS Task-IDs
• ADDON_TASKLIST Taskdefinitionen
• ADDON_FIFOS FIFO-Definitionen

• addon_init() Funktionsaufruf zur Initialisierung vor Freigabe de Interrupts
• addon_power_up() ask zur weiteren Initialsierung nach Freigabe der Interrupts
• addon_close() Funktion zum Schließen des AddOns insbesondere der Interrupts

• performAddOnMacro() Ausführen der Makros eines AddoOns

• ASCII_PARSE_TAB_ADDON Aufruftabelle der einzelenen Debug-Befehle
• PA_info_addon() Überschrift
• PA_help_addon() Zusammenfassung