SuperKey Multifunktions-Makrotastatur¶

Was ist SuperKey?¶

SiFliSparks/SuperKey ist eine Referenzimplementierung einer multifunktionalen Makrotastatur mit Displays auf Basis von SF32LB52. Die Open-Source-Firmware läuft mit RT-Thread und LVGL v9, steuert drei LCDs des Typs GC9107 mit 128 × 128 Pixeln, drei RGB-LEDs, vier physische Tasten, einen Drehencoder und den Temperatur- und Feuchtesensor SHT30 an und verbindet sich als zusammengesetztes USB-HID/CDC-Gerät mit einem Computer.

SuperKey ist mehr als ein Tastenfeld für Tastenkürzel. Die funktionsfähige Referenz vereint folgende Produktpfade:

• USB-HID-Ausgabe für Tastatur und Mediensteuerung;
• Leistungsdaten des Computers, Wetterdaten, Konfiguration und Energiezustand über USB CDC oder UART mit 1 Mbit/s;
• Seiten auf drei Displays für Leistungsüberwachung, Wetter, Uhr, Dienstprogramme, Musik und benutzerdefinierte Tastenbelegungen;
• das Begleitprogramm SuperKeyHub, das Hostdaten erfasst, Funktionen konfiguriert und Firmwareupdates anstößt;
• reproduzierbare Hardware anhand des offenen Hardwaredesigns sf32-keyboard.

Warum die SF32-Implementierung?¶

SuperKey benötigt Grafik, mehrere Displays, ein zusammengesetztes USB-Gerät, Tasten und Encoder, Sensoren, RGB-Effekte, ein Dateisystem und optional Audio. SF32LB52 führt diese Echtzeitaufgaben auf dem MCU aus. Dadurch kann das Gerät seine Oberfläche starten und grundlegende HID-Funktionen bereitstellen, auch wenn das Begleitprogramm nicht läuft. Das Hostprogramm übernimmt Rechner-Telemetrie und Internetdaten, die besser vom Desktopbetriebssystem verarbeitet werden.

Diese Aufgabenteilung eignet sich für Desktop-Controller, Tastaturen für wiederkehrende Arbeitsabläufe, Statusanzeigen und kompakte HMIs, bringt aber klar definierte Abhängigkeiten mit sich. Erweiterte Datenanzeigen benötigen das Begleitprogramm, Treiber und externe APIs. Firmware- und Hostversionen müssen kompatibel bleiben; USB-Verbindungsverlust, der Schlafmodus des Hosts und beschädigte Konfigurationen erfordern eigene Wiederherstellungstests.

Ergebnis, Umfang und Eintrittskriterien¶

Ergebnis: Eine versionsgebundene SuperKey-Referenz reproduzieren, HID, CDC, Oberfläche auf drei Displays, Eingaben, Sensorik und Wiederherstellung nach dem Schlafmodus validieren und anschließend jeweils nur eine Verhaltenskategorie ändern. Build-, Kommunikations- und Regressionstests sind als Nachweise für die Produktbewertung aufzubewahren.

Diese Seite belegt weder die Serienreife der Open-Source-Platine noch die Kompatibilität mit jeder PC-Telemetriequelle, jedem Wetterdienst, jeder seriellen Bridge, jedem USB-Host oder jeder Betriebssystemversion. Börsenkurse sowie Wetter- und Leistungsdaten können von der SuperKeyHub-Version, APIs Dritter, Systemberechtigungen und der Hosthardware abhängen.

Halten Sie vor dem Start Folgendes bereit:

• SuperKey-Hardware gemäß offenem Design, einschließlich drei LCDs des Typs GC9107, Tasten, Encoder und USB-Datenverbindung;
• einen Rechner mit Windows 10/11 für den hauptsächlich dokumentierten Weg. Das SuperKeyHub-Repository nennt Windows- und macOS-Unterstützung; prüfen Sie Programmierung, CDC-Kommunikation und Wiederherstellung dennoch auf dem gewählten Hostbetriebssystem;
• eine zur Firmware passende SuperKeyHub-Version;
• eine SiFli-SDK-Umgebung mit rekursiv ausgechecktem SDK-Submodul und funktionierendem Programmier-/Wiederherstellungsanschluss;
• falls Wetterfunktionen geprüft werden: einen gültigen QWeather-API-Key, API-Host und eine Stadtkonfiguration;
• ein Testprotokoll für USB-Enumeration, serielle Logs, Tastenverhalten, Displayzustand und Wiederherstellung aus dem Schlafmodus.

Hardware- und Software-Spezifikationen¶

Hardware-Spezifikation¶

Software-Spezifikation¶

Unterstützte Referenzkonfiguration auswählen¶

Die Upstream-Releaseliste führt Firmware v1.4.2 als festen Ausgangspunkt. Das zitierte Material legt keine konkrete kompatible SuperKeyHub-Version fest. Wählen und fixieren Sie einen Hub-Release oder Commit, prüfen Sie damit Telemetrie, Konfiguration und DFU mit v1.4.2 und dokumentieren Sie die getestete Kombination, statt Kompatibilität aus Versionsnummern abzuleiten.

Die Upstream-CI verwendet folgendes Ziel. Installieren und exportieren Sie die SiFli-SDK-Umgebung, bevor Sie den Befehl lokal ausführen:

git clone --recursive https://github.com/SiFliSparks/SuperKey.git
cd SuperKey/SiFli-SDK
./install.sh
. ./export.sh
cd ../app/project
scons --board=sf32lb52-superkey --board_search_path="../boards" -j8

Verwenden Sie unter Windows die entsprechenden PowerShell-Installations- und Umgebungs-Skripte von SiFli-SDK. Die Parallelität kann variieren; Boardname, Board-Suchpfad und Submodulrevisionen müssen jedoch im Build-Protokoll stehen.

Projektphasen und Entscheidungspunkte¶

Systemarchitektur und Abhängigkeiten¶

flowchart LR
    U["Nutzer\nTasten und Drehencoder"] --> F["SF32LB52-Firmware\nRT-Thread + LVGL v9"]
    F --> D["Drei LCDs des Typs GC9107\nRGB-LEDs, SHT30, optional Audio"]
    F -->|"USB HID\nTastatur- und Medienereignisse"| P["Windows-/macOS-Host"]
    P -->|"USB CDC oder UART mit 1 Mbit/s\nTelemetrie, Wetter, Konfiguration, Energiemodus"| F
    H["SuperKeyHub\nErfassung, Konfiguration, Update"] <--> P
    H <--> A["Wetter-API und Host-Telemetriequellen"]
    H -->|"CDC-DFU"| F

Ordnen Sie Fehler fünf Bereichen zu: Gerätehardware/Display, HID-Eingabe, CDC-/UART-Datenkanal, Begleitprogramm/Systemberechtigungen und externe Datendienste. Eine leere Wetteranzeige ist nicht automatisch ein Firmwarefehler; Ursache können API-Key, API-Host, Stadtkonfiguration oder Datenübertragung sein.

Phase 1 — Die unveränderte Referenzbasis einrichten¶

Ziel: Den vollständigen Referenzpfad nachweisen, bevor der Code geändert wird.

1. Prüfen Sie anhand der Upstream-Montageunterlagen die Ausrichtung der LCD-Kabel sowie Schalter, Encoder, Gehäuse und USB-Buchse; dokumentieren Sie Platinen- und Firmwarerevision.
2. Installieren Sie die passende SuperKeyHub-Version. Prüfen Sie zunächst die Geräte-Enumeration und anschließend HID und CDC getrennt.
3. Konfigurieren Sie Wetterzugangsdaten, Port und seriellen Betrieb mit 1 Mbit/s. Dokumentieren Sie das Verhalten ohne Begleitprogramm; verbinden Sie es anschließend und aktivieren Sie die Datenübertragung.
4. Prüfen Sie die Navigation auf drei Displays, Tastenbelegung, Mediensteuerung, Encoder, Daten vom Sensor SHT30, LED-Effekte und einen vollständigen Telemetrie-Aktualisierungszyklus.
5. Führen Sie einen Kaltstart durch und wiederholen Sie den Test. Sichern Sie UI-Fotos, Protokolle des Begleitprogramms und Geräts sowie das Ergebnis der Versionsabfrage.

Aufzubewahrende Nachweise: Hardwarerevision, Firmware-Tag/Commit, SDK-Commit, Version des Begleitprogramms, Betriebssystem, Port- und API-Konfiguration, USB-Enumeration, Protokolle, Displayzustände und Eingabeprotokoll.

Abnahmekriterium für Kontrollpunkt 1: Bei zwei Kaltstarts funktionieren HID-Eingabe, CDC-Datenaktualisierung und Interaktion mit allen drei Displays. Jeder Fehlerbereich lässt sich anhand von Protokollen oder beobachtbarem Zustand unterscheiden.

Phase 2 — Fehler- und Wiederherstellungsgrenzen validieren¶

Ziel: Nachweisen, dass typische Desktop-Unterbrechungen das Gerät nicht zu einer Demonstration machen, die ein erneutes Flashen erfordert.

Abnahmekriterium für Kontrollpunkt 2: Für jeden relevanten Fehlerfall sind Erkennung und Wiederherstellung reproduzierbar; eine undokumentierte manuelle Zustandskorrektur ist nicht erforderlich.

Phase 3 — Eine reproduzierbare Quellbasis erstellen¶

Ziel: Einem zweiten Entwickler ermöglichen, aus einem sauberen Checkout einen Build und die Programmierung des Firmware-Images durchzuführen und die Prüfungen aus Phase 2 zu wiederholen.

1. Klonen Sie rekursiv und dokumentieren Sie sowohl den SuperKey- als auch den SiFli-SDK-Commit.
2. Bauen Sie mit sf32lb52-superkey und dem Suchpfad ../boards in einer sauberen Umgebung.
3. Sichern Sie Build-Protokoll, Speicher-/Partitionsausgabe, Flash-Skript, erzeugte Images und serielles Protokoll.
4. Wiederholen Sie den Build auf einem zweiten Rechner oder nach dem Löschen des Build-Verzeichnisses, flashen Sie das Image auf dieselbe Hardware und führen Sie die wichtigsten Regressionstests erneut aus.

Abnahmekriterium für Kontrollpunkt 3: Zum Erzeugen eines Images, das Phase 2 besteht, sind weder nicht versionierte Dateien noch veraltete Build-Artefakte noch manuelles Austauschen von Binärdateien erforderlich.

Phase 4 — Jeweils eine Produktvariable anpassen¶

Ziel: Die Änderungsgrenzen prüfen und gleichzeitig die bestandene Referenz erhalten.

Abnahmekriterium für Kontrollpunkt 4: Die Änderung ist geprüft, das ursprüngliche Image wiederherstellbar und die Tests für HID, CDC, Display, Eingabe, Schlafmodus und Wiederherstellung sind bestanden.

Phase 5 — Produktreife-Überprüfung¶

Vor der Entwicklung eigener Hardware oder eines Pilotaufbaus muss das Team folgende Fragen beantworten:

• Wird das Produkt weiterhin von SuperKeyHub, Administratorrechten und einem Wetterdienst Dritter abhängen, und wer verantwortet diese Abhängigkeiten?
• Wie werden Firmware-, Begleitprogramm- und Protokollversionen verwaltet, und wie werden inkompatible Kombinationen verhindert?
• Welche Kombinationen aus Ziel-PCs, USB-Hubs, Kabeln, Energiesparrichtlinien und Sicherheitssoftware wurden getestet?
• Wie hoch sind Speicherbedarf, Temperatur und Stromaufnahme, wenn drei Displays, USB-Daten, LEDs, Sensorik und optionales Audio gleichzeitig aktiv sind?
• Wie lassen sich Konfiguration, Tastenbelegungen und Updatezustand nach Stromausfall oder beschädigtem Speicher wiederherstellen?
• Sind offene Platine, Gehäuse, Schriften, Symbole, Musik und APIs Dritter für die vorgesehene Verteilung lizenziert?

Abnahmekriterium für Kontrollpunkt 5: Für jedes verbleibende Risiko sind Verantwortliche, Nachweise und Maßnahmen festgelegt; das Team hat über Fortfahren, Zurückstellen oder Abbrechen entschieden.

Übergabe an das Produktdesign¶

Übernehmen Sie Auswahl von SF32 und Speicher, USB-HID/CDC-Deskriptoren, Anschlüsse für drei Displays und Hintergrundbeleuchtung, Schnittstellen für Eingaben und Sensoren, Stromversorgungs- und Schlafrichtlinie, Dateisystem- und Updatepartitionen, Protokoll des Begleitprogramms, Produktionstestpunkte und validierten Wiederherstellungspfad in die nächste Designphase. Fahren Sie mit SF32LB52x, dem SF32LB52x Hardware-Design-Leitfaden, SiFli-SDK: Bauen, Flashen und Überwachen und Design für die Produktion fort.

Maßgebliche Quellen¶

• SiFliSparks/SuperKey-Firmware-Repository
• Release v1.4.2 von SuperKey
• SiFliSparks/SuperKeyHub-Begleitprogramm-Repository
• SuperKey-Projektdokumentation
• Offene sf32-keyboard-Hardware
• OpenSiFli/SiFli-SDK

Zuletzt aktualisiert: 2026-10-21