mz25key Interfaccia Guida per Sviluppatori

Guida per Sviluppatori mz25key

Il mz25key e un'interfaccia tastiera dedicata per i computer Sharp MZ-2500 e MZ-2800, basata sul microcontrollore ESP32 dual-core. Condivide il codice sorgente con il progetto SharpKey ma e compilato con una configurazione semplificata.
Nota: Questa guida contiene codice sorgente e dettagli tecnici in inglese. Consultare la versione inglese per il contenuto completo.

Prerequisiti

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

Struttura del repository

Repository: https://git.eaw.app/eaw/mz25key. Nessun submodule git.

Contenuto tecnico completo nella versione inglese.

Setup e build automatizzati (consigliato)

Il modo piu semplice per compilare il firmware mz25key e lo script di setup automatizzato per la propria piattaforma. Ogni script e autonomo: copiate il singolo file relativo alla vostra piattaforma ed eseguitelo. Installa la toolchain ESP-IDF v4.4, clona il repository (recuperando le due librerie di componenti richieste in components/) e puo compilare il firmware — il tutto in modo interattivo, con valori predefiniti ragionevoli che potete accettare premendo Invio. I passaggi manuali nativi, Docker e menuconfig restano disponibili per utenti avanzati e ricostruzioni parziali.

macOS / Linux / WSL — setup_mz25key.sh

chmod +x setup_mz25key.sh
./setup_mz25key.sh
Lo script rileva automaticamente il sistema operativo. Preferisce Docker (l'immagine ufficiale espressif/idf:v4.4, un download una tantum di ~3 GB) e ripiega su un'installazione ESP-IDF v4.4 nativa (Python 3.8–3.11, CMake, Ninja e gli altri prerequisiti tramite apt, dnf, pacman o Homebrew) quando Docker non e disponibile. Su Linux e WSL puo installare Docker Engine per voi.

Windows 10 / 11 — setup_mz25key_windows.ps1 (nativo, senza WSL o Docker)

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup_mz25key_windows.ps1
Lo script Windows usa winget per installare Git e (se non gia presente) Python 3.10 in un ambiente virtuale isolato, quindi installa la toolchain ESP-IDF v4.4 nativa per Windows di Espressif e compila il firmware. Richiede il Microsoft App Installer (che fornisce winget) — installatelo dal Microsoft Store se winget non viene trovato.

Domande poste dal setup
Ogni richiesta ha un valore predefinito sicuro tra parentesi — la lettera maiuscola e il valore predefinito, quindi premendo Invio lo si accetta.

macOS / Linux / WSL (setup_mz25key.sh):

Richiesta Predefinito Cosa fare
Install Docker Engine now? [Y/n] (Linux / WSL, se Docker manca) Si Invio per installare Docker e compilare nel container, oppure n per ripiegare su un’installazione ESP-IDF nativa.
Install now? [Y/n] (pacchetti OS / ESP-IDF nativo) Si Invio — installa i pacchetti OS mancanti ed ESP-IDF v4.4; potrebbe richiedere sudo.
Repo URL [https://git.eaw.app/eaw/mz25key.git] repo pubblico Invio per il repo pubblico, oppure incollare un URL diverso (ad es. il repo di sviluppo privato).
Install directory [~/mz25key] ~/mz25key Invio per ~/mz25key, oppure digitare un percorso.
Remove <dir> and re-clone? [y/N] (se quella directory contiene un repo diverso) No y solo se siete sicuri; altrimenti N e scegliere un’altra directory.
Build the mz25key firmware now? [Y/n] Si Invio per compilare subito (verifica l’ambiente).

Windows (setup_mz25key_windows.ps1):

Richiesta Predefinito Cosa fare
Repo URL [https://git.eaw.app/eaw/mz25key.git] repo pubblico Invio per il repo pubblico, oppure incollare un URL diverso.
mz25key checkout directory [%USERPROFILE%\mz25key] %USERPROFILE%\mz25key Invio per il valore predefinito, oppure digitare un percorso.
Build the mz25key firmware now? [Y/n] Si Invio per compilare subito.
Per esecuzioni non interattive, entrambi gli script rispettano le variabili d'ambiente: MZ25KEY_REPO_URL imposta l'URL del repository, e MZ25KEY_BUILD forza il metodo di build (docker o native).

Output e ricompilazione
Dopo un'esecuzione riuscita l'immagine del firmware si trova in build/main.bin e l'immagine del file system web in build/filesys.bin — gli stessi artefatti prodotti dalla build manuale. Per ricompilare in seguito senza rieseguire lo script di setup: 
# Docker (macOS / Linux / WSL)
docker run --rm -it -v "$PWD":/project -w /project espressif/idf:v4.4 idf.py build

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

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

Licenze

Sotto GNU Public Licence v3.

Avviso normative wireless

Modulo ESP32-S pre-certificato nella banda ISM 2,4 GHz. Responsabilita del costruttore.