ZMK-Tastatur-Firmware auf SF32¶

Was ist ZMK auf SF32?¶

ZMK Firmware ist eine unter MIT-Lizenz stehende Tastatur-Firmware auf Basis von Zephyr. Das Upstream-Projekt ZMK stellt das Anwendungsmodell bereit, das viele kabelgebundene, drahtlose und geteilte Tastaturen nutzen: Matrixabtastung, Tastenbelegungen und Ebenen, Tastenverhalten, USB- und Bluetooth-HID, persistente Einstellungen sowie erweiterbare Board- und Shield-Definitionen.

OpenSiFli/zmk ist ein von OpenSiFli gepflegter Fork des Projekts. Der geprüfte Fork ergänzt:

• eine Board-Variante sf32lb52_devkit_lcd/sf32lb525uc6/zmk;
• die Integration des SF32LB52-SoC im ZMK-Anwendungsbaum;
• Konfigurationen für Einzel-Board, geteilte Tastatur, ZMK Studio und das Shield urchin_sf32lb52;
• ein auf SF32 ausgerichtetes CherryUSB-Backend;
• eine NVS-Einstellungspartition mit 256 KB und Unterstützung für Bluetooth-Einstellungen;
• eine Tastenbelegung für die geteilte Urchin-Tastatur mit drei Ebenen, Bluetooth-Profilsteuerung und Bindungen zum Entsperren von ZMK Studio.

Dies ist eine Entwicklungsportierung und kein getaggtes SF32-ZMK-Produkt-Release. Das README im Stammverzeichnis des Forks ist weiterhin das allgemeine Upstream-README von ZMK und enthält keinen SF32-spezifischen Schnellstart. Betrachten Sie Board, Shield, Manifest, Quellcode und Commit als ausführbare Referenz und verlangen Sie vor einer Anpassung eigene Nachweise zu sauberem Build, Flashen, Funktion und Wiederherstellung.

Warum die SF32-Implementierung?¶

Die SF32-Portierung zeigt, wie das Tastaturmodell von ZMK auf SF32LB52 laufen kann, während die Konventionen von Zephyr für Devicetree, Kconfig, west, Tastenbelegung, Shield und geteilte Tastaturen erhalten bleiben. Die Referenz urchin_sf32lb52 verteilt ein 38-Tasten-Layout auf zwei Hälften. Die linke Konfiguration ist die zentrale Seite (Central) der geteilten Tastatur, aktiviert CherryUSB und ZMK Studio und kann einem Host USB-HID anbieten; die rechte Konfiguration ist die periphere Seite (Peripheral). Beide Hälften aktivieren ZMK BLE.

Damit eignet sich der Fork zur Evaluierung einer drahtlosen geteilten Tastatur, eines USB-/Bluetooth-Desktop-Eingabegeräts, eines programmierbaren Makro-Pads oder eines eigenen Mensch-Maschine-Produkts auf SF32. Der Kompromiss liegt in der Reife der Abhängigkeiten: Das west-Manifest des Forks legt einen angepassten Zephyr-Branch (v4.3+sf32-zmk_fixes), eine feste SiFli-HAL-Revision und einen angepassten CherryUSB-Branch zephyr-adapt fest. Sie gehören zur Kompatibilitätsgrenze der Portierung und lassen sich ohne vollständige Migration und Regressionsdurchlauf nicht durch aktuelle Upstream-Revisionen ersetzen.

Ergebnis, Umfang und Eintrittskriterien¶

Ergebnis: versionsgebundene linke und rechte Urchin-Images bauen und flashen, die vollständige Tastenmatrix, die Ebenen, USB-HID, die BLE-Pfade für Split und Host, die Persistenz der Einstellungen, die Grenze zu ZMK Studio und die Wiederherstellung validieren und dann eine kontrollierte Änderung an Tastenbelegung oder Hardware mit wiederholbaren Nachweisen durchführen.

Diese Seite behauptet weder volle Funktionsparität mit Upstream-ZMK noch Kompatibilität mit beliebigen ZMK-Shields noch serienreife Akkulaufzeit noch validierte Funkleistung noch eine unterstützte Migration auf eine andere Zephyr-/ZMK-Revision. Sie definiert auch keine Tastatur-Leiterplatte für die Serie: Die Urchin-Konfiguration des Repositorys ordnet eine Referenz-Tastenmatrix den Pins des SF32LB52-DevKit-LCD zu und muss für eigene Hardware gezielt übersetzt werden.

Halten Sie vor dem Start bereit:

• zwei SF32LB52-DevKit-LCD-Boards, die zur Variante sf32lb525uc6/zmk des Forks passen;
• einen geteilten 38-Tasten-Testaufbau, der genau gemäß den Overlays urchin_sf32lb52_left und urchin_sf32lb52_right verdrahtet ist, oder ein kleineres dokumentiertes Test-Shield für erste Prüfungen der Portierung;
• einen Host mit funktionierender Zephyr-/ZMK-west-Umgebung und ausreichend Speicherplatz für die festgelegten Module des Forks;
• bekannte Verbindungen zum Flashen, für die serielle Konsole und für die Wiederherstellung jeder Hälfte, bevor das Split-Verhalten getestet wird;
• ein USB-Datenkabel für die linke/zentrale Hälfte und eine unabhängige Möglichkeit, die rechte/periphere Hälfte zu versorgen und wiederherzustellen;
• einen Bluetooth-Host, einen Host mit ZMK-Studio-Unterstützung, falls Studio im Umfang liegt, und eine Möglichkeit, den Strom jeder Hälfte zu messen;
• ein Protokoll für Fork-Commit, Manifest-Revisionen, Board-/Shield-Bezeichner, Build- und Flash-Logs, Tastentestergebnisse, Bonds, Einstellungszustand und Strommessungen.

Hardware- und Software-Spezifikationen¶

Hardware-Spezifikation¶

Software-Spezifikation¶

Unterstützte Referenzkonfiguration auswählen¶

Die geprüfte OpenSiFli-Basis ist der Commit fd4d5843065f vom 27.05.2026. Er enthält das Urchin-Shield und die zu diesem Commit verfügbare Aktualisierung der Board-Konfiguration, ist aber kein getaggtes SF32-ZMK-Release. Legen Sie diesen Commit für die erste Reproduktion fest oder erfassen und prüfen Sie ausdrücklich einen neueren Commit.

Die folgenden Befehle kombinieren die Form des eigenen west-Workflows des Forks mit seinen genauen Bezeichnern für das SF32-Board und das Urchin-Shield. Bewahren Sie die beiden Build-Verzeichnisse getrennt auf, damit die Images nicht verwechselt werden:

git clone https://github.com/OpenSiFli/zmk.git
cd zmk
git checkout fd4d5843065f

west init -l app
west update --fetch-opt=--filter=tree:0
west zephyr-export

west build -s app -p always -d build-left \
  -b sf32lb52_devkit_lcd/sf32lb525uc6/zmk -- \
  -DSHIELD=urchin_sf32lb52_left

west build -s app -p always -d build-right \
  -b sf32lb52_devkit_lcd/sf32lb525uc6/zmk -- \
  -DSHIELD=urchin_sf32lb52_right

Erfassen Sie das finale west list, die erzeugte Kconfig- und Devicetree-Ausgabe, Artefakt-Hashes, die Zuordnung von Image zu Hälfte und das tatsächliche Flash-Verfahren. Beginnen Sie erst mit dem Split-Test, wenn sich jedes Board unabhängig wiederherstellen lässt.

Projektphasen und Entscheidungspunkte¶

Systemarchitektur und Abhängigkeiten¶

flowchart LR
    KL["Linke Tastenmatrix\n19 Positionen"] --> L["Linker SF32LB52\nZMK Central"]
    KR["Rechte Tastenmatrix\n19 Positionen"] --> R["Rechter SF32LB52\nZMK Peripheral"]
    R -->|"ZMK-BLE-Split-Verbindung"| L
    L -->|"USB-HID\nCherryUSB"| H["Host-Rechner"]
    L -->|"Bluetooth-HID"| H
    H <-->|"ZMK Studio\nnur Firmware-Image der linken Seite"| L
    NL["NVS-Einstellungen\nBonds und Konfiguration"] --> L
    NR["NVS-Einstellungen\npersistenter Zustand"] --> R
    M["OpenSiFli-West-Manifest\nangepasstes Zephyr + HAL + CherryUSB"] --> L
    M --> R

Behandeln Sie Fehler als getrennte Domänen: physische Matrix/Verdrahtung, die Split-Verbindung von rechts nach links, USB auf der linken Seite, Host-Bluetooth, gespeicherte Bonds/Einstellungen, ZMK Studio, Flashen und Wiederherstellung des Boards sowie der festgelegte Abhängigkeits-Stack. Eine Taste, die den Host nicht erreicht, kann vor dem Scan, beim Split-Transport, in der zentralen Tastenbelegung oder am gewählten HID-Endpunkt ausfallen; diagnostizieren Sie den Pfad in dieser Reihenfolge.

Phase 1 — Die unveränderte Portierungsbasis herstellen¶

Ziel: Die genaue OpenSiFli-Referenz nachweisen, bevor Tastenbelegung, Overlay oder Abhängigkeit geändert werden.

1. Erfassen Sie beide Board-Revisionen und verdrahten Sie die beiden Aufbauten genau gemäß den linken und rechten Urchin-Overlays. Beschriften Sie Boards sowie USB-/Flash-Kabel nach Rolle.
2. Bauen Sie beide Images beim festgelegten Commit, speichern Sie west list und prüfen Sie die erzeugte Konfiguration, um das erwartete Board, Shield, die Split-Rolle, BLE, CherryUSB, ZMK Studio und die NVS-Einstellungen zu bestätigen.
3. Flashen Sie jedes Image über seinen unabhängig verifizierten Wiederherstellungspfad. Erfassen Sie Kaltstart- und Konsolenverhalten, bevor Sie die Hälften oder den Host koppeln.
4. Stellen Sie die BLE-Split-Verbindung her und verifizieren Sie dann alle 38 Positionen gegen die Ebenen default, lower und raise. Prüfen Sie Bluetooth-Profilauswahl/-Löschen und die Studio-Entsperr-Bindungen bewusst, damit sie bei den Tipptests nicht versehentlich ausgelöst werden.
5. Validieren Sie USB-HID und ZMK Studio auf der linken Hälfte und dann Bluetooth-HID zum gewählten Host. Wiederholen Sie dies nach einem Kaltstart.

Aufzubewahrende Nachweise: Aufzeichnungen zu Board und Verdrahtung, Revisionen von Fork und Manifest, erzeugte Konfigurationen, Image-Hashes, Flash- und Boot-Logs, vollständige Matrix der Tastenpositionen, Ebenenergebnisse, Endpunktauswahl sowie Host-/Studio-Versionen.

Abnahmekriterium für Kontrollpunkt 1: Zwei Kaltstarts reproduzieren die vollständige 38-Positionen-Belegung, alle drei Ebenen, die Split-Verbindung von rechts nach links und mindestens einen gewählten Host-Endpunkt; beide Hälften bleiben unabhängig wiederherstellbar.

Phase 2 — Eingabe, Transport, Einstellungen und Wiederherstellung validieren¶

Ziel: Nachweisen, dass realistische Tastaturfehler sichtbar und behebbar sind, ohne aus einem unbekannten Zustand neu bauen zu müssen.

Abnahmekriterium für Kontrollpunkt 2: Für jeden zutreffenden Fehler liegt ein wiederholbares Ergebnis zu Erkennung und Wiederherstellung vor, kein Test hinterlässt einen hängenden HID-Zustand, und Einstellungen oder Bonds lassen sich ohne Ersetzen unversionierter Dateien auf die erfasste Basis zurücksetzen.

Phase 3 — Eine reproduzierbare Quellbasis aufbauen¶

Ziel: Einem zweiten Ingenieur ermöglichen, beide Images neu zu erzeugen und Phase 2 aus sauberen Quellen zu wiederholen.

1. Beginnen Sie mit einem sauberen Fork-Checkout beim erfassten Commit und führen Sie west init, west update und west zephyr-export ohne lokale Modulersetzung aus.
2. Speichern Sie west list, Compiler-/Werkzeugversionen, die erzeugte .config, den erzeugten Devicetree, die Speicherausgabe, Build-Logs und beide Artefakte mit Hashes.
3. Flashen Sie die beschrifteten linken und rechten Images auf die richtigen Hälften und wiederholen Sie den vollständigen Testsatz aus Phase 2.
4. Vergleichen Sie Artefakte und Konfiguration mit der ursprünglichen Aufzeichnung; erklären Sie jeden nicht reproduzierbaren Unterschied, bevor Sie fortfahren.

Abnahmekriterium für Kontrollpunkt 3: Eine zweite Umgebung erzeugt korrekt beschriftete Images, die Phase 2 ohne unversionierte Overlays, veraltete Build-Ausgaben oder nicht fixierte Abhängigkeitsrevisionen bestehen.

Phase 4 — Jeweils eine Tastatur-Grenze anpassen¶

Ziel: Eine Produktänderung vornehmen und dabei die bewährte Portierung und unabhängige Wiederherstellungspfade erhalten.

Abnahmekriterium für Kontrollpunkt 4: Die Änderung ist geprüft, ursprüngliche Images und Einstellungen lassen sich wiederherstellen, und alle zutreffenden Tests zu Matrix, Ebenen, Split, USB, BLE, Studio, Versorgung und Wiederherstellung bestehen.

Phase 5 — Prüfung der Produktreife¶

Beantworten Sie vor dem Entwurf einer eigenen Tastatur-Leiterplatte oder eines Akku-Prototyps:

• Wer verantwortet den OpenSiFli-ZMK-Fork, den angepassten Zephyr-Branch, die SiFli-HAL-Revision, die CherryUSB-Anpassung und künftige Sicherheits- oder Kompatibilitätsupdates?
• Welche Upstream-ZMK-Funktionen werden auf SF32 tatsächlich genutzt, und welche sind nur im geerbten Baum vorhanden?
• Wie werden Image-Identität links/rechts, Board-Revision, Tastenbelegung, Konfiguration, Bonds und Werksreset-Zustand in Fertigung und Service kontrolliert?
• Wie hoch sind die gemessenen Ströme jeder Hälfte im aktiven Betrieb, verbunden im Leerlauf, getrennt und im Schlaf, einschließlich Scan-Rate, Wiederverbindungsverhalten und Akkuschutz?
• Welche Hosts, Betriebssysteme, USB-Controller, Bluetooth-Stacks, Aufwachpfade, Rollover-Fälle und Störbedingungen wurden getestet?
• Lassen sich ein fehlgeschlagenes Abhängigkeitsupdate, eine Studio-Änderung, ein Schreibvorgang in die Einstellungen oder ein Update im Feld beheben, ohne das Produkt zu öffnen oder zu verschrotten?
• Sind die Lizenzen von ZMK/Zephyr, die Leiterplatten- und Gehäusedateien, die Tastenbelegungsinhalte, Logos, Schriften und mitgelieferten Konfigurationen für den Vertrieb geeignet?

Abnahmekriterium für Kontrollpunkt 5: Jedes Restrisiko hat einen Verantwortlichen, Nachweise und eine Disposition, und das Team hat ausdrücklich entschieden: fortfahren, zurückstellen oder stoppen.

Übergabe an das Produktdesign¶

Übernehmen Sie das genaue SF32-Bauteil und den Speicher, Split-Rollen und Transport, die Zuordnung von Zeilen/Spalten/direkten Eingängen, die Diodenrichtung, den USB-Anschluss, Annahmen zu Antenne und Gehäuse, die NVS-/Einstellungsrichtlinie, Flash- und Wiederherstellungsschnittstellen, das Energiebudget je Hälfte, Testaufbauten, die Image-Kennzeichnung und das festgelegte Manifest. Fahren Sie fort mit SF32LB52-DevKit-LCD, der Plattformgrenze von Zephyr, der Bluetooth-Architektur, dem Hardware-Design-Leitfaden SF32LB52x und Design for Production.

Maßgebliche Quellen¶

• OpenSiFli/zmk-SF32-Fork
• Geprüfter Commit von OpenSiFli/zmk
• ZMK-Board-Variante für SF32LB52 beim geprüften Commit
• Geteiltes Urchin-SF32LB52-Shield beim geprüften Commit
• West-Manifest des OpenSiFli-ZMK beim geprüften Commit
• Upstream zmkfirmware/zmk
• ZMK-Dokumentation
• Zephyr-Projektdokumentation

Zuletzt aktualisiert: 2026-10-21