mz25key Interfaz Guia del Desarrollador

Guia del Desarrollador mz25key

El mz25key es una interfaz de teclado dedicada para los ordenadores Sharp MZ-2500 y MZ-2800, basada en el microcontrolador ESP32 de doble nucleo. Comparte su codigo fuente con el proyecto SharpKey pero se compila con una configuracion simplificada.

Nota: Esta guia contiene codigo fuente y detalles tecnicos en ingles. Consulte la version inglesa para el contenido completo.

Requisitos previos

ESP-IDF v4.4

Python 3.8+

Git

Adaptador USB-TTL UART

Docker (opcional)

Estructura del repositorio

Repositorio: https://git.eaw.app/eaw/mz25key. Sin submodulos git.

Contenido tecnico completo en la version inglesa.

Instalacion y build automatizados (recomendado)

La forma mas sencilla de compilar el firmware mz25key es el script de instalacion automatizado para su plataforma. Cada script es autonomo: copie unicamente el archivo correspondiente a su plataforma y ejecutelo. Instala la cadena de herramientas ESP-IDF v4.4, clona el repositorio (obteniendo las dos bibliotecas de componentes requeridas en components/) y puede compilar el firmware, todo de forma interactiva, con valores por defecto sensatos que puede aceptar pulsando Enter. Los pasos manuales nativos, con Docker y de menuconfig descritos a continuacion siguen disponibles para usuarios avanzados y recompilaciones parciales.

macOS / Linux / WSL — setup_mz25key.sh

chmod +x setup_mz25key.sh
./setup_mz25key.sh

El script detecta automaticamente su sistema operativo. Prefiere Docker (la imagen oficial espressif/idf:v4.4, una descarga unica de ~3 GB) y recurre a una instalacion nativa de ESP-IDF v4.4 (Python 3.8-3.11, CMake, Ninja y los demas prerrequisitos mediante apt, dnf, pacman o Homebrew) cuando Docker no esta disponible. En Linux y WSL puede instalar Docker Engine por usted.

Windows 10 / 11 — setup_mz25key_windows.ps1 (nativo, sin WSL ni Docker)

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup_mz25key_windows.ps1

El script de Windows usa winget para instalar Git y (si no esta ya presente) Python 3.10 en un entorno virtual aislado, luego instala la cadena de herramientas nativa ESP-IDF v4.4 para Windows de Espressif y compila el firmware. Requiere el App Installer de Microsoft (que proporciona winget); instalelo desde la Microsoft Store si no se encuentra winget.

Preguntas que hace el instalador

Cada solicitud tiene un valor por defecto seguro entre corchetes; la letra en mayuscula es el valor por defecto, asi que pulsar Enter lo acepta.

macOS / Linux / WSL (setup_mz25key.sh):

Solicitud	Por defecto	Que hacer
`Install Docker Engine now? [Y/n]` (Linux / WSL, si falta Docker)	Si	Enter para instalar Docker y compilar en el contenedor, o n para recurrir a una instalacion nativa de ESP-IDF.
`Install now? [Y/n]` (paquetes del SO / ESP-IDF nativo)	Si	Enter: instala los paquetes del SO que faltan y ESP-IDF v4.4; puede pedir `sudo`.
`Repo URL [https://git.eaw.app/eaw/mz25key.git]`	repo publico	Enter para el repo publico, o pegue otra URL (p. ej. el repo de desarrollo privado).
`Install directory [~/mz25key]`	`~/mz25key`	Enter para `~/mz25key`, o escriba una ruta.
`Remove <dir> and re-clone? [y/N]` (si ese directorio contiene un repo distinto)	No	y solo si esta seguro; en caso contrario N y elija otro directorio.
`Build the mz25key firmware now? [Y/n]`	Si	Enter para compilar de inmediato (verifica el entorno).

Windows (setup_mz25key_windows.ps1):

Solicitud	Por defecto	Que hacer
`Repo URL [https://git.eaw.app/eaw/mz25key.git]`	repo publico	Enter para el repo publico, o pegue otra URL.
`mz25key checkout directory [%USERPROFILE%\mz25key]`	`%USERPROFILE%\mz25key`	Enter para el valor por defecto, o escriba una ruta.
`Build the mz25key firmware now? [Y/n]`	Si	Enter para compilar de inmediato.

Para ejecuciones desatendidas (no interactivas), ambos scripts respetan variables de entorno: MZ25KEY_REPO_URL define la URL del repositorio, y MZ25KEY_BUILD fuerza el metodo de build (docker o native).

Salida y recompilacion

Tras una ejecucion correcta, la imagen del firmware esta en build/main.bin y la imagen del sistema de archivos web en build/filesys.bin, los mismos artefactos que produce el build manual. Para recompilar mas tarde sin volver a ejecutar el script de instalacion:

# 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

Entorno de compilacion

Los pasos manuales de configuracion de la cadena de herramientas y compilacion (nativo, Docker y menuconfig) se documentan en la version inglesa, para usuarios avanzados y recompilaciones parciales. La mayoria de los usuarios deberian usar el script de instalacion automatizado anterior, que realiza todos esos pasos por usted.

Licencias

Bajo GNU Public Licence v3.

Aviso de regulacion inalambrica

Modulo ESP32-S pre-certificado en la banda ISM de 2,4 GHz. Responsabilidad del constructor.