mz25key Interface Guide du Developpeur

Guide du Developpeur mz25key

Le mz25key est une interface clavier dediee pour les ordinateurs Sharp MZ-2500 et MZ-2800, basee sur le microcontroleur ESP32 double coeur. Elle partage son code source avec le projet SharpKey mais est construite avec une configuration simplifiee.
Note : Ce guide contient du code source et des details techniques en anglais. Consultez la version anglaise pour le contenu complet incluant : prerequis, structure du depot, architecture, protocoles, systeme de correspondance, interface web, Bluetooth, build et CI/CD.

Prerequis

  • ESP-IDF v4.4
  • Python 3.8+
  • Git
  • Adaptateur USB-TTL UART
  • Docker (optionnel)

Structure du depot

Depot : https://git.eaw.app/eaw/mz25key. Pas de submodules git -- les composants doivent etre clones manuellement.

Contenu technique complet dans la version anglaise.

Configuration et build automatises (recommande)

La methode la plus simple pour compiler le firmware mz25key est le script de configuration automatise propre a votre plateforme. Chaque script est autonome : copiez uniquement le fichier correspondant a votre plateforme et executez-le. Il installe la chaine d'outils ESP-IDF v4.4, clone le depot (en recuperant les deux bibliotheques de composants requises dans components/) et peut compiler le firmware — le tout de maniere interactive, avec des valeurs par defaut sensees que vous pouvez accepter en appuyant sur Entree. Les etapes manuelles native, Docker et menuconfig ci-dessous restent disponibles pour les utilisateurs avances et les rebuilds partiels (voir la version anglaise pour la configuration manuelle detaillee de l'environnement de build).

macOS / Linux / WSL — setup_mz25key.sh

chmod +x setup_mz25key.sh
./setup_mz25key.sh
Le script detecte automatiquement votre systeme d'exploitation. Il prefere Docker (l'image officielle espressif/idf:v4.4, un telechargement unique de ~3 Go) et bascule vers une installation ESP-IDF v4.4 native (Python 3.8–3.11, CMake, Ninja et les autres prerequis via apt, dnf, pacman ou Homebrew) lorsque Docker n'est pas disponible. Sous Linux et WSL, il peut installer Docker Engine pour vous.

Windows 10 / 11 — setup_mz25key_windows.ps1 (natif, sans WSL ni Docker)

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup_mz25key_windows.ps1
Le script Windows utilise winget pour installer Git et (s'il n'est pas deja present) Python 3.10 dans un environnement virtuel isole, puis installe la chaine d'outils Windows ESP-IDF v4.4 native d'Espressif et compile le firmware. Il necessite le Microsoft App Installer (qui fournit winget) — installez-le depuis le Microsoft Store si winget est introuvable.

Questions posees par la configuration
Chaque invite a une valeur par defaut securisee entre crochets — la lettre majuscule est la valeur par defaut, donc appuyer sur Entree l'accepte.

macOS / Linux / WSL (setup_mz25key.sh) :

Invite Defaut Que faire
Install Docker Engine now? [Y/n] (Linux / WSL, si Docker absent) Oui Entree pour installer Docker et compiler dans le conteneur, ou n pour basculer vers une installation ESP-IDF native.
Install now? [Y/n] (paquets OS / ESP-IDF natif) Oui Entree — installe les paquets OS manquants et ESP-IDF v4.4 ; peut demander sudo.
Repo URL [https://git.eaw.app/eaw/mz25key.git] depot public Entree pour le depot public, ou collez une autre URL (par ex. le depot de dev prive).
Install directory [~/mz25key] ~/mz25key Entree pour ~/mz25key, ou saisissez un chemin.
Remove <dir> and re-clone? [y/N] (si ce repertoire contient un depot different) Non y uniquement si vous etes sur ; sinon N et choisissez un autre repertoire.
Build the mz25key firmware now? [Y/n] Oui Entree pour compiler immediatement (verifie l’environnement).

Windows (setup_mz25key_windows.ps1) :

Invite Defaut Que faire
Repo URL [https://git.eaw.app/eaw/mz25key.git] depot public Entree pour le depot public, ou collez une autre URL.
mz25key checkout directory [%USERPROFILE%\mz25key] %USERPROFILE%\mz25key Entree pour le defaut, ou saisissez un chemin.
Build the mz25key firmware now? [Y/n] Oui Entree pour compiler immediatement.
Pour les executions sans surveillance (non interactives), les deux scripts respectent des surcharges d'environnement : MZ25KEY_REPO_URL definit l'URL du depot, et MZ25KEY_BUILD force la methode de build (docker ou native).

Sortie et recompilation
Apres une execution reussie, l'image du firmware se trouve dans build/main.bin et l'image du systeme de fichiers web dans build/filesys.bin — les memes artefacts que ceux produits par le build manuel. Pour recompiler ensuite sans relancer le script de configuration : 
# Docker (macOS / Linux / WSL)
docker run --rm -it -v "$PWD":/project -w /project espressif/idf:v4.4 idf.py build

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

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

Licences

Sous GNU Public Licence v3.

Avis de reglementation sans fil

Module ESP32-S pre-certifie dans la bande ISM 2,4 GHz. Responsabilite du constructeur.