mz25key Schnittstelle Entwicklerhandbuch

mz25key Entwicklerhandbuch

Das mz25key ist ein dediziertes Tastaturinterface fuer die Sharp MZ-2500 und MZ-2800 Computer, basierend auf dem Espressif ESP32 Dual-Core-Mikrocontroller. Es uebersetzt moderne PS/2- und Bluetooth-HID-Tastaturen in das native MZ-2500/MZ-2800-Tastaturmatrix-Protokoll. Das mz25key teilt die gesamte Codebasis mit dem SharpKey Multi-Host-Interface-Projekt, wird aber mit einer vereinfachten Konfiguration erstellt.
Dieses Handbuch ist die primaere Entwicklerreferenz fuer die mz25key-Firmware. Es behandelt die vollstaendige Software-Architektur, jedes Quellmodul, das MZ-2500/MZ-2800-Tastaturprotokoll, das Tastenzuordnungssystem, die Web-Oberflaeche, die Bluetooth-Integration, die Build-Umgebung, die CI/CD-Pipeline und Debugging-Techniken.
Hauptunterschied zu SharpKey: Das mz25key ist derselbe Quellcode wie SharpKey, wird aber mit dem Kconfig-Ziel MZ25KEY_MZ2500 oder MZ25KEY_MZ2800 anstelle von SHARPKEY erstellt. Der kritische Unterschied ist, dass das mz25key-Git-Repository keine Git-Submodule verwendet -- die erforderlichen Komponentenbibliotheken muessen manuell geklont werden.
Hinweis: Dieses Entwicklerhandbuch enthaelt umfangreichen Quellcode, API-Dokumentation und technische Details, die in englischer Sprache verbleiben. Bitte lesen Sie die englische Version fuer den vollstaendigen Inhalt, einschliesslich:
  • Voraussetzungen (ESP-IDF v4.4, Python 3.8+, Git, UART-Adapter)
  • Repository-Struktur und Quellmodule
  • Software-Architektur und Kern-Trennung
  • MZ-2500/MZ-2800-Tastaturprotokoll-Implementierung
  • Tastenzuordnungssystem
  • Web-Interface (WiFi Manager, OTA, KeyMap Editor)
  • Bluetooth-HID-Integration
  • Build-Anleitung (nativ und Docker)
  • CI/CD-Pipeline (Jenkins)
  • Debugging-Techniken

Voraussetzungen

Bevor Sie die mz25key-Firmware bauen und flashen koennen, benoetigen Sie eine funktionierende Entwicklungsumgebung:
  • ESP-IDF v4.4: Das Espressif IoT Development Framework, Version 4.4 spezifisch.
  • Python 3.8+: Erforderlich fuer die Build-System-Skripte.
  • Git: Zum Klonen des Repositories und der Komponentenbibliotheken.
  • USB-zu-TTL UART-Adapter: Zum Flashen der Firmware.
  • Docker (optional): Als Alternative zur nativen ESP-IDF-Installation.
  • Komponentenversionen: arduino-esp32 bei Tag 2.0.3 und esp_littlefs bei Tag v1.3.1.

Repository-Struktur

Das mz25key-Repository ist unter https://git.eaw.app/eaw/mz25key gehostet. Es teilt dieselben Quelldateien wie das SharpKey-Projekt, lebt aber in einem separaten Repository ohne .gitmodules-Datei. 
mz25key/
├── main/
│   ├── SharpKey.cpp              — Entry point
│   ├── MZ2528.cpp                — MZ-2500/2800 host interface (Core 1)
│   ├── PS2KeyAdvanced.cpp        — PS/2 protocol driver
│   ├── HID.cpp                   — Bluetooth HID
│   ├── WiFi.cpp                  — WiFi web interface
│   └── LED.cpp                   — Activity LED
├── components/                   — Manually cloned libraries
├── data/                         — Web filesystem source
├── sdkconfig                     — Kconfig build settings
└── build_webfs.sh                — Web filesystem build script

Weiterer technischer Inhalt (Architektur, Modulbeschreibungen, CI/CD) finden Sie in der englischen Version.

Automatisiertes Setup und Build (empfohlen)

Der einfachste Weg, die mz25key-Firmware zu bauen, ist das automatisierte Setup-Skript fuer Ihre Plattform. Jedes Skript ist in sich geschlossen: Kopieren Sie einfach die einzelne Datei fuer Ihre Plattform und fuehren Sie sie aus. Es installiert die ESP-IDF v4.4-Toolchain, klont das Repository (und holt die beiden erforderlichen Komponentenbibliotheken nach components/) und kann die Firmware bauen — alles interaktiv, mit sinnvollen Standardwerten, die Sie durch Druecken von Enter uebernehmen koennen. Die manuellen nativen, Docker- und menuconfig-Schritte bleiben fuer fortgeschrittene Benutzer und Teil-Builds verfuegbar.

macOS / Linux / WSL — setup_mz25key.sh

chmod +x setup_mz25key.sh
./setup_mz25key.sh
Das Skript erkennt Ihr Betriebssystem automatisch. Es bevorzugt Docker (das offizielle espressif/idf:v4.4-Image, ein einmaliger Download von ~3 GB) und faellt auf eine native ESP-IDF v4.4-Installation zurueck (Python 3.8–3.11, CMake, Ninja und die anderen Voraussetzungen ueber apt, dnf, pacman oder Homebrew), wenn Docker nicht verfuegbar ist. Unter Linux und WSL kann es Docker Engine fuer Sie installieren.

Windows 10 / 11 — setup_mz25key_windows.ps1 (nativ, kein WSL oder Docker erforderlich)

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup_mz25key_windows.ps1
Das Windows-Skript verwendet winget, um Git und (falls noch nicht vorhanden) Python 3.10 in einer isolierten virtuellen Umgebung zu installieren, installiert dann Espressifs native ESP-IDF v4.4-Windows-Toolchain und baut die Firmware. Es erfordert den Microsoft App Installer (der winget bereitstellt) — installieren Sie ihn aus dem Microsoft Store, falls winget nicht gefunden wird.

Fragen, die das Setup stellt
Jede Eingabeaufforderung hat einen sicheren Standardwert in Klammern — der Grossbuchstabe ist der Standard, sodass Druecken von Enter ihn uebernimmt.

macOS / Linux / WSL (setup_mz25key.sh):

Eingabeaufforderung Standard Was zu tun ist
Install Docker Engine now? [Y/n] (Linux / WSL, falls Docker fehlt) Ja Enter, um Docker zu installieren und im Container zu bauen, oder n, um auf eine native ESP-IDF-Installation zurueckzufallen.
Install now? [Y/n] (OS-Pakete / natives ESP-IDF) Ja Enter — installiert die fehlenden OS-Pakete und ESP-IDF v4.4; fragt evtl. nach sudo.
Repo URL [https://git.eaw.app/eaw/mz25key.git] oeffentliches Repo Enter fuer das oeffentliche Repo oder eine andere URL einfuegen (z. B. das private Entwicklungs-Repo).
Install directory [~/mz25key] ~/mz25key Enter fuer ~/mz25key oder einen Pfad eingeben.
Remove <dir> and re-clone? [y/N] (falls dieses Verzeichnis ein anderes Repo enthaelt) Nein y nur, wenn Sie sicher sind; andernfalls N und ein anderes Verzeichnis waehlen.
Build the mz25key firmware now? [Y/n] Ja Enter, um sofort zu bauen (verifiziert die Umgebung).

Windows (setup_mz25key_windows.ps1):

Eingabeaufforderung Standard Was zu tun ist
Repo URL [https://git.eaw.app/eaw/mz25key.git] oeffentliches Repo Enter fuer das oeffentliche Repo oder eine andere URL einfuegen.
mz25key checkout directory [%USERPROFILE%\mz25key] %USERPROFILE%\mz25key Enter fuer den Standard oder einen Pfad eingeben.
Build the mz25key firmware now? [Y/n] Ja Enter, um sofort zu bauen.
Fuer unbeaufsichtigte (nicht-interaktive) Laeufe respektieren beide Skripte Umgebungsvariablen-Ueberschreibungen: MZ25KEY_REPO_URL legt die Repository-URL fest und MZ25KEY_BUILD erzwingt die Build-Methode (docker oder native).

Ausgabe und Neu-Bauen
Nach einem erfolgreichen Lauf befindet sich das Firmware-Image unter build/main.bin und das Web-Dateisystem-Image unter build/filesys.bin — dieselben Artefakte, die der manuelle Build erzeugt. Um spaeter neu zu bauen, ohne das Setup-Skript erneut auszufuehren: 
# Docker (macOS / Linux / WSL)
docker run --rm -it -v "$PWD":/project -w /project espressif/idf:v4.4 idf.py build

# Native ESP-IDF (macOS / Linux / WSL)
. ~/esp/esp-idf-v4.4/export.sh && idf.py build

# Native ESP-IDF (Windows PowerShell)
& "$HOME\esp\esp-idf-v4.4\export.ps1"; idf.py build

Danksagungen

Die Espressif IDF-Entwicklungsumgebung und ESP-32S-Referenzmaterialien wurden verwendet.

Lizenzen

Unter GNU Public Licence v3 lizenziert. Keine kommerzielle Nutzung ohne Genehmigung.

Hinweis zur Funkregulierung

Dieses Geraet enthaelt ein vorzertifiziertes ESP32-S Funkmodul im 2,4 GHz ISM-Band. Verantwortung des Erbauers.