diff --git a/.gitignore b/Firmware/.gitignore similarity index 100% rename from .gitignore rename to Firmware/.gitignore diff --git a/Firmware/README.md b/Firmware/README.md new file mode 100644 index 0000000..aee4836 --- /dev/null +++ b/Firmware/README.md @@ -0,0 +1,112 @@ +# DMM Demo + +Beispielprojekt zur Demonstration der wesentlichen Funktionen des DMM-Boards. +Wird auch zur Installation des Bootloaders und Test nach der Inbetriebnahme +eingesetzt. + +## Anleitung + +### Build-System und Entwicklungsumgebung + +Als plattformübergreifendes Build-System Dient das +[PlatformIO](https://platformio.org/). Diese steht sowohl als +Kommandozeilen-Tool, als auch als [Erweiterung](https://marketplace.visualstudio.com/items?itemName=platformio.platformio-ide) +zum [Visual Studio Code](https://code.visualstudio.com/). +(auch unter Linux und MacOS verfügbar!) + +Nutzt man das VSCode, so können nach der Installation der Erweiterung die unten +aufgeführten Befehle auch *ohne Installation der PIO im Betriebssystem* in den +Terminals innerhalb der IDE genutzt werden. Für die Betriebssystemweite Installation +siehe Anleitung unter [PlatformIO Core (CLI)](https://docs.platformio.org/en/latest/core/installation.html). + +*Nur Linux:* zur Programmierung des Bootloaders mit JTAGICE muss dieser +für nicht-root Nutzer per udev-Regel freigegeben werden. Erstelle dazu Datei +`/etc/udev/rules.d/99-jtagice3.rules` mit: +``` +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2140", MODE="0666" +``` + +### Auschecken und bauen +Es sollte sichergestellt sein, dass [Git](https://git-scm.com/) installiert und +der [eigene SSH-Schlüssel im GitLab-Profil hinterlegt](https://docs.gitlab.com/ee/ssh/) +ist. Für Git-Anfänger finden sich im Internet zahlreiche Anleitungen, zum Beispiel +[diese](https://www.freecodecamp.org/news/learn-the-basics-of-git-in-under-10-minutes-da548267cc91/). + +*GUI:* VSCode unterstützt Git direkt und kann nach der Einrichtung als GUI +genutzt werden. + +Auschecken: +``` +$ git clone git@teach.emg.ing.tu-bs.de:dmm/dmm-demo.git +$ cd dmm-demo +``` + +Es sind zwei PlatformIO-Environments definiert. `release` wird standardmäßig +genutzt und ist auf die Programmierung per Bootloader ausgelegt. `debug` wird +für das Aufspielen des Bootloaders oder Debugging mittels JTAGICE3 genutzt. + +Bauen von `release`: +``` +$ pio run +``` + +Bauen von `debug`: +``` +$ pio run -e debug + +``` + +Dabei werden neben der Toolchain automatisch die für DMM-Projekte vorgesehenen +[Bibliotheken](https://teach.emg.ing.tu-bs.de/git/dmm/dmm-libs) in den Ordner +`dmm-demo/depends` heruntergeladen. + +### Programmierung & Nutzung + +*GUI*: die aufgeführten Befehle können auch aus dem PlatformIO-Toolbar des +VSCode per Mausklick ausgeführt werden. + +#### Aufspielen des Bootloaders + +Auf einem neuen Board muss zunächst mittels JTAGICE3 ein Bootloader aufgespielt +werden. Dazu wird es mit dem JTAG-Header verbunden (Polung beachten!). +``` +$ pio run -t bootloader -e debug +``` + +#### Aufspielen des Programms + +Das Board muss per USB verbunden und Bootloader gestarted werden. +*Zum Start des Bootloaders den Joystick in Richtung unten halten, Reset-Taste +drücken und den Joystick loslassen. Die Aktivierung des Bootloaders erkennt man +an zwei leuchtenden roten LEDs auf dem Board* +``` +$ pio run -t upload +``` +Anschließend Reset-Taste drücken um das Programm zu starten. + +#### UART-Kommunikation + +Ein Teil des Demos beschäftigt sich mit Kommunikation über einen virtuellen +SerialPort via USB. Der `COMx` (Windows) oder `/dev/ttyUSBx` (Linux) Port wird +von PlattformIO automatisch erkannt. Dies geschieht anhand des `hwid` Parameters +unter `boards/emgdmm_v3.json`, der den VID/PID des FTDI-Chips des DMM-Boards +angibt. Ein Terminal kann somit einfach geöffnet werden: +``` +pio device monitor +``` + +Beim Drücken des Joystick im entsprechenden Teil des Demos wird nun eine Meldung +angezeigt. + +### Unit-Test + +Die Demo enthält im Ordner `tests` einen Beispiel zur Ausführung von Unit-Tests +auf dem Mikrocontroller. Dazu muss wie oben beschrieben der Bootloader aktiviert +werden. +``` +$ pio test +``` +Nach dem Befehl wird eine Firmware auf das Board heruntergeladen, die bei der +Ausführung per UART (wie auch bei `pio device monitor`) die Ergebnisse der +Tests im Terminal ausgibt. + diff --git a/boards/emgdmm_v3.json b/Firmware/boards/emgdmm_v3.json similarity index 100% rename from boards/emgdmm_v3.json rename to Firmware/boards/emgdmm_v3.json diff --git a/boards/stk500boot.hex b/Firmware/boards/stk500boot.hex similarity index 100% rename from boards/stk500boot.hex rename to Firmware/boards/stk500boot.hex diff --git a/include/README b/Firmware/include/README similarity index 100% rename from include/README rename to Firmware/include/README diff --git a/include/music.h b/Firmware/include/music.h similarity index 100% rename from include/music.h rename to Firmware/include/music.h diff --git a/lib/README b/Firmware/lib/README similarity index 100% rename from lib/README rename to Firmware/lib/README diff --git a/platformio.ini b/Firmware/platformio.ini similarity index 100% rename from platformio.ini rename to Firmware/platformio.ini diff --git a/src/main.c b/Firmware/src/main.c similarity index 100% rename from src/main.c rename to Firmware/src/main.c diff --git a/src/music.c b/Firmware/src/music.c similarity index 100% rename from src/music.c rename to Firmware/src/music.c diff --git a/test/README b/Firmware/test/README similarity index 100% rename from test/README rename to Firmware/test/README diff --git a/test/test_demo.c b/Firmware/test/test_demo.c similarity index 100% rename from test/test_demo.c rename to Firmware/test/test_demo.c diff --git a/test/unittest_transport.h b/Firmware/test/unittest_transport.h similarity index 100% rename from test/unittest_transport.h rename to Firmware/test/unittest_transport.h diff --git a/Hardware/.gitignore b/Hardware/.gitignore new file mode 100644 index 0000000..03d24da --- /dev/null +++ b/Hardware/.gitignore @@ -0,0 +1,26 @@ +# For PCBs designed using KiCad: http://www.kicad-pcb.org/ +# Format documentation: http://kicad-pcb.org/help/file-formats/ + +# Temporary files +*.000 +*.bak +*.bck +*.kicad_pcb-bak +*.sch-bak +*~ +_autosave-* +*.tmp +*-save.pro +*-save.kicad_pcb +fp-info-cache + +# Netlist files (exported from Eeschema) +*.net + +# Autorouter files (exported from Pcbnew) +*.dsn +*.ses + +# Exported BOM files +#*.xml +#*.csv diff --git a/Hardware/README.md b/Hardware/README.md new file mode 100644 index 0000000..f9cf8ea --- /dev/null +++ b/Hardware/README.md @@ -0,0 +1,5 @@ +# Projektspezifische Hardware + +Die EDA/CAD-Dateien und BOM von Erweiterungsplatinen. Dokumentation ist in der Repository-Wiki zu hinterlegen. + +Präferierte EDA-Software: [KiCad](https://kicad-pcb.org/). diff --git a/README.md b/README.md index aee4836..49b72f1 100644 --- a/README.md +++ b/README.md @@ -1,112 +1,9 @@ -# DMM Demo +# DMM-Demo -Beispielprojekt zur Demonstration der wesentlichen Funktionen des DMM-Boards. -Wird auch zur Installation des Bootloaders und Test nach der Inbetriebnahme -eingesetzt. +Zum Flashen des Bootloaders und des Demonstrationsprojektes siehe 'Firmware/README.md' -## Anleitung +## Erstellen eines DMM-Projektes -### Build-System und Entwicklungsumgebung - -Als plattformübergreifendes Build-System Dient das -[PlatformIO](https://platformio.org/). Diese steht sowohl als -Kommandozeilen-Tool, als auch als [Erweiterung](https://marketplace.visualstudio.com/items?itemName=platformio.platformio-ide) -zum [Visual Studio Code](https://code.visualstudio.com/). -(auch unter Linux und MacOS verfügbar!) - -Nutzt man das VSCode, so können nach der Installation der Erweiterung die unten -aufgeführten Befehle auch *ohne Installation der PIO im Betriebssystem* in den -Terminals innerhalb der IDE genutzt werden. Für die Betriebssystemweite Installation -siehe Anleitung unter [PlatformIO Core (CLI)](https://docs.platformio.org/en/latest/core/installation.html). - -*Nur Linux:* zur Programmierung des Bootloaders mit JTAGICE muss dieser -für nicht-root Nutzer per udev-Regel freigegeben werden. Erstelle dazu Datei -`/etc/udev/rules.d/99-jtagice3.rules` mit: -``` -SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2140", MODE="0666" -``` - -### Auschecken und bauen -Es sollte sichergestellt sein, dass [Git](https://git-scm.com/) installiert und -der [eigene SSH-Schlüssel im GitLab-Profil hinterlegt](https://docs.gitlab.com/ee/ssh/) -ist. Für Git-Anfänger finden sich im Internet zahlreiche Anleitungen, zum Beispiel -[diese](https://www.freecodecamp.org/news/learn-the-basics-of-git-in-under-10-minutes-da548267cc91/). - -*GUI:* VSCode unterstützt Git direkt und kann nach der Einrichtung als GUI -genutzt werden. - -Auschecken: -``` -$ git clone git@teach.emg.ing.tu-bs.de:dmm/dmm-demo.git -$ cd dmm-demo -``` - -Es sind zwei PlatformIO-Environments definiert. `release` wird standardmäßig -genutzt und ist auf die Programmierung per Bootloader ausgelegt. `debug` wird -für das Aufspielen des Bootloaders oder Debugging mittels JTAGICE3 genutzt. - -Bauen von `release`: -``` -$ pio run -``` - -Bauen von `debug`: -``` -$ pio run -e debug - -``` - -Dabei werden neben der Toolchain automatisch die für DMM-Projekte vorgesehenen -[Bibliotheken](https://teach.emg.ing.tu-bs.de/git/dmm/dmm-libs) in den Ordner -`dmm-demo/depends` heruntergeladen. - -### Programmierung & Nutzung - -*GUI*: die aufgeführten Befehle können auch aus dem PlatformIO-Toolbar des -VSCode per Mausklick ausgeführt werden. - -#### Aufspielen des Bootloaders - -Auf einem neuen Board muss zunächst mittels JTAGICE3 ein Bootloader aufgespielt -werden. Dazu wird es mit dem JTAG-Header verbunden (Polung beachten!). -``` -$ pio run -t bootloader -e debug -``` - -#### Aufspielen des Programms - -Das Board muss per USB verbunden und Bootloader gestarted werden. -*Zum Start des Bootloaders den Joystick in Richtung unten halten, Reset-Taste -drücken und den Joystick loslassen. Die Aktivierung des Bootloaders erkennt man -an zwei leuchtenden roten LEDs auf dem Board* -``` -$ pio run -t upload -``` -Anschließend Reset-Taste drücken um das Programm zu starten. - -#### UART-Kommunikation - -Ein Teil des Demos beschäftigt sich mit Kommunikation über einen virtuellen -SerialPort via USB. Der `COMx` (Windows) oder `/dev/ttyUSBx` (Linux) Port wird -von PlattformIO automatisch erkannt. Dies geschieht anhand des `hwid` Parameters -unter `boards/emgdmm_v3.json`, der den VID/PID des FTDI-Chips des DMM-Boards -angibt. Ein Terminal kann somit einfach geöffnet werden: -``` -pio device monitor -``` - -Beim Drücken des Joystick im entsprechenden Teil des Demos wird nun eine Meldung -angezeigt. - -### Unit-Test - -Die Demo enthält im Ordner `tests` einen Beispiel zur Ausführung von Unit-Tests -auf dem Mikrocontroller. Dazu muss wie oben beschrieben der Bootloader aktiviert -werden. -``` -$ pio test -``` -Nach dem Befehl wird eine Firmware auf das Board heruntergeladen, die bei der -Ausführung per UART (wie auch bei `pio device monitor`) die Ergebnisse der -Tests im Terminal ausgibt. +Jede Gruppe bestimmt einen Maintainer, der ein gemeinsames Projekt erstellt. +TODO