8.1.8. Nachbauen und Weiterentwickeln

Für einen eigenen Aufbau werden die Referenzhardware, ein USB-Datenkabel und die Quellen von Firmware, Java-Client und NeitzelLib benötigt. Die folgenden Schritte setzen voraus, dass diese Checkouts bereits vorliegen. Die Befehle werden jeweils im genannten Projektverzeichnis ausgeführt.

Die Firmware verwendet ESP-IDF 5.5.2 für das Ziel esp32s3. Das Komponentenmanifest legt außerdem LVGL 8.4.0, den GT911-Treiber und esp_tinyusb 2.2.0 fest. Eine passende ESP-IDF-Umgebung muss installiert und in der verwendeten Shell aktiviert sein. Die Einrichtung hängt vom Betriebssystem und dem gewählten Installationsweg ab. Espressif ESP-IDF 5.5.2 Getting Started

Im Verzeichnis waveshare-device wird die Firmware gebaut und anschließend der native Testlauf gestartet.

idf.py build
sh tests/run.sh

Der Testlauf benötigt einen C-Compiler und die aktivierte ESP-IDF-Umgebung mit IDF_PATH. Er prüft unter anderem Konfigurationsvalidierung, Profilverwaltung, App-Befehle, Rastermigration und Displaytransformation. Dabei verwendet er AddressSanitizer und UndefinedBehaviorSanitizer.

Das Gerät wird über USB angeschlossen. Für den Flashbefehl muss der tatsächlich erkannte Geräteport eingesetzt werden. Die folgende Variable ist ein Platzhalter für diesen Port.

DEVICE_PORT='<Geräteport>'
idf.py -p "$DEVICE_PORT" flash

Das Projekt verwendet eine eigene Partitionstabelle mit 280 KiB NVS und einer 2-MiB-Anwendungspartition. Deshalb wird der vollständige Build einschließlich Partitionstabelle übertragen. Der aktuelle Anwendungsbereich beginnt an einem anderen Offset als beim frühen Prototyp.

Falls das Gerät nicht in den Bootloader wechselt, BOOT gedrückt halten, RESET betätigen und BOOT anschließend loslassen. Die Desktop-Anwendung enthält derzeit keinen automatisierten Firmware-Updater. Nach dem Neustart stellt die native USB-Verbindung HID und CDC bereit. Laufzeitlogs sind auf UART konfiguriert.

Für den vollständigen Java-Build werden JDK 21 und Maven benötigt. Das JDK muss jpackage und jlink enthalten, weil der Build standardmäßig ein natives Anwendungsabbild erzeugt. JAVA_HOME und der in der Shell verwendete Java-Befehl müssen auf das passende JDK zeigen. Mit den folgenden Befehlen lässt sich prüfen, welche Werkzeuge Maven tatsächlich verwendet.

java -version
mvn -version

Zunächst werden im NeitzelLib-Checkout das FX-Modul und seine benötigten Module in das lokale Maven-Repository installiert. Maven muss dabei ebenfalls JDK 21 verwenden.

mvn -pl fx -am install

Dieser Schritt stellt die vom Editor benötigten NeitzelLib-Abhängigkeiten für den anschließenden Build bereit. Voraussetzung ist ein NeitzelLib-Stand, dessen Versionen zu den Abhängigkeiten des Java-Clients passen.

Danach wird im Verzeichnis java-client der gesamte Reaktor gebaut und geprüft.

mvn verify

Das Anwendungsabbild liegt anschließend unter ActiveSideDeviceFX/target/app-image/. Es enthält eine Java-Laufzeit. Für seine Nutzung ist daher keine gesonderte Java-Installation erforderlich.

Das Abbild wird jeweils für Betriebssystem und Architektur des Buildrechners erstellt. Windows-, Linux- und macOS-Pakete benötigen daher eigene Builds. Der vorhandene Ablauf erzeugt ein Anwendungsabbild. Installer, Signierung und macOS-Notarisierung sind zusätzliche Aufgaben. Linux benötigt eine grafische Umgebung und die nativen JavaFX-/GTK-Abhängigkeiten.

Für einen Testlauf ohne erneutes Erzeugen des Anwendungsabbilds steht die Skip-Option bereit.

mvn verify -Djpackage.skip=true

Zum direkten Entwicklungsstart wird das Editor-Modul mit seinen Abhängigkeiten installiert und anschließend über das JavaFX-Maven-Plugin gestartet.

mvn -pl ActiveSideDeviceFX -am install -Djpackage.skip=true
mvn -pl ActiveSideDeviceFX javafx:run

Die CLI kann zum Prüfen der sichtbaren Ports verwendet werden. Nach dem vollständigen Build wird sie im Java-Client-Verzeichnis so aufgerufen.

java -jar waveshare-client/target/waveshare-client-1.0-SNAPSHOT.jar ports

Firmware und Client müssen denselben Protokollstand unterstützen. Der hier beschriebene Quellstand verwendet Protokollversion 4 und Konfigurationsschema 3. Ältere Kombinationen können deshalb eine Inkompatibilitätsmeldung auslösen.

In der Desktop-Anwendung werden die Ports mit Refresh ports aktualisiert. Anschließend den passenden Port wählen und Connect ausführen. Soll die bestehende Gerätekonfiguration den Ausgangspunkt bilden, wird sie mit Load from device übernommen. Send to device überträgt umgekehrt den Desktop-Entwurf und ersetzt damit die Konfiguration auf dem Gerät. Eine mit Save gespeicherte Datei ist eine eigenständige Sicherung.

Für den ersten praktischen Test eignet sich eine einzelne Schaltfläche. Bei einer IntelliJ-Taste muss die zugehörige Aktion in der verwendeten Keymap eingerichtet sein. Danach lassen sich schrittweise weitere Eigenschaften prüfen.

1. Tastatur- und Medienaktionen am angeschlossenen Computer auslösen.
2. Seitenwechsel, Scrollen und langes Drücken auf dem Touchdisplay ausprobieren.
3. Gedrehte Seiten auf Darstellung, Treffgenauigkeit und Wischrichtungen prüfen.
4. Eine Konfiguration speichern, das Gerät neu starten und den gespeicherten Stand kontrollieren.
5. Displaytimeout und Aufwecken testen. Die erste Berührung soll das Display aktivieren, ohne eine Aktion auszulösen.
6. Profile manuell wechseln und anschließend die automatische Zuordnung zur aktiven Anwendung prüfen.

Für einen früheren Projektstand sind automatisierte Tests, ein macOS-Anwendungsbuild sowie Firmware-Flash, USB-Erkennung, Protokoll-Handshake und Konfigurationsabfrage am Gerät dokumentiert. Die später hinzugekommenen Raster- und Rotationsfunktionen benötigen eine eigene Prüfung am Gerät. Ein erfolgreicher Build allein belegt weder die Touchqualität noch die korrekte Funktion jeder Betriebssystemkombination.

Für die automatische Profilauswahl sind macOS, Windows und Linux/X11 vorgesehen. Wayland wird derzeit nicht unterstützt. Unter macOS können zusätzliche Berechtigungen für Fensterinformationen nötig sein. Die noch offenen Plattform-, Berechtigungs- und Hardwareprüfungen gehören deshalb zu den nächsten Entwicklungsschritten.

Bei eigenen Erweiterungen sollten Geräteprotokoll, Java-Bibliothek, CLI und Editor gemeinsam betrachtet werden. Eine neue Gerätefunktion braucht eine passende Darstellung und Validierung auf beiden Seiten. Für andere Hardware kommen zusätzlich Displaytreiber, Pinbelegung, Speicherbedarf und USB-Anbindung hinzu.