mz25key Interface Developer's Guide

mz25key Developer's Guide

Prerequisites

• ESP-IDF v4.4: The Espressif IoT Development Framework, version 4.4 specifically. Later versions (v5.x) are not compatible due to Arduino component API changes. Install natively or use the official Docker image espressif/idf:v4.4.
• Python 3.8+: Required by the ESP-IDF build system scripts and menuconfig. Use update-alternatives on Linux to ensure python3 points to a recent version.
• Git: For cloning the repository and the two required component libraries. Note: unlike SharpKey, the mz25key repository does not use git submodules.
• USB-to-TTL UART adapter: For flashing firmware and serial debug output. Must support 3.3V logic levels with RTS and DTR signals for automated bootstrap/programming mode entry.
• Docker (optional): As an alternative to installing ESP-IDF natively. The espressif/idf:v4.4 Docker image contains the complete toolchain.
• Component versions: arduino-esp32 at tag 2.0.3 and esp_littlefs at tag v1.3.1 (with submodules initialised).

Repository Structure

mz25key/
├── main/
│   ├── SharpKey.cpp              — Entry point (same source as SharpKey)
│   ├── MZ2528.cpp                — MZ-2500/2800 host interface (Core 1)
│   ├── MZ5665.cpp                — MZ-5500/5600/6500 (compiled but unused in mz25key build)
│   ├── X1.cpp                    — Sharp X1 interface (compiled but unused)
│   ├── X68K.cpp                  — Sharp X68000 interface (compiled but unused)
│   ├── PC9801.cpp                — NEC PC-9801 interface (compiled but unused)
│   ├── Mouse.cpp                 — Mouse support
│   ├── HID.cpp                   — HID device manager / input aggregator
│   ├── BTHID.cpp                 — Bluetooth HID report translation
│   ├── BT.cpp                    — Bluetooth GAP/GATT discovery and pairing
│   ├── WiFi.cpp                  — WiFi AP/client, HTTP server, OTA, LittleFS
│   ├── PS2KeyAdvanced.cpp        — PS/2 keyboard protocol (interrupt-driven)
│   ├── PS2Mouse.cpp              — PS/2 mouse protocol
│   ├── KeyInterface.cpp          — Virtual base class for host interfaces
│   ├── LED.cpp                   — Status LED control
│   ├── NVS.cpp                   — Non-volatile storage wrapper
│   ├── SWITCH.cpp                — Timed button handler
│   ├── esp_efuse_custom_table.c  — eFuse field accessors (generated)
│   ├── esp_efuse_custom_table.csv — eFuse field definitions (source)
│   ├── Kconfig.projbuild         — Build configuration menu
│   └── include/                  — Headers with key mapping tables
│       ├── MZ2528.h              — MZ-2500/2800 mapping table (165 entries)
│       ├── X1.h, X68K.h, ...    — Other host mapping tables
│       └── ...
├── webserver/                    — HTML/CSS/JS web interface
│   ├── version.txt               — Release version (NOTE: not in project root)
│   └── html/                     — Web page source files
├── components/                   — EMPTY after clone! Must populate manually
│   ├── arduino-esp32/            — Clone from GitHub at tag 2.0.3
│   └── esp_littlefs/             — Clone from GitHub at tag v1.3.1 + submodules
├── build_webfs.sh                — Web filesystem builder script
├── sharpkey_partition_table.csv  — Flash partition layout (same as SharpKey)
├── sdkconfig                     — Default build configuration (MZ25KEY target)
├── CMakeLists.txt                — CMake project file
└── version.txt                   — (May exist — see webserver/version.txt for CI)

# Clone the mz25key repository
git clone https://git.eaw.app/eaw/mz25key.git
cd mz25key

# Clone required components manually (NOT submodules!)
mkdir -p components

# Arduino-ESP32 compatibility layer — must be v2.0.3
git clone https://github.com/espressif/arduino-esp32.git components/arduino-esp32
cd components/arduino-esp32 && git checkout 2.0.3 && cd ../..

# LittleFS filesystem support — must be v1.3.1 WITH submodules
git clone https://github.com/joltwallet/esp_littlefs.git components/esp_littlefs
cd components/esp_littlefs && git checkout v1.3.1 && git submodule update --init --recursive && cd ../..

Differences from SharpKey

1. Build target: mz25key uses CONFIG_MZ25KEY_MZ2500 or CONFIG_MZ25KEY_MZ2800 in Kconfig, not CONFIG_SHARPKEY. This selects only the MZ-2500 or MZ-2800 host interface path and disables the runtime GPIO-based host auto-detection used by SharpKey.
2. No git submodules: The mz25key repository has no .gitmodules file. The components/ directory is empty after a fresh clone. You must manually clone arduino-esp32 (v2.0.3) and esp_littlefs (v1.3.1 with submodules) into components/. SharpKey uses git clone --recursive to fetch these automatically.
3. Single host interface: Only the MZ-2500 or MZ-2800 interface path is active at runtime. SharpKey detects the connected host via GPIO pin patterns and selects the appropriate interface dynamically.
4. Simplified configuration: Fewer Kconfig options are exposed. The multi-host GPIO detection pins, X1/X68K/PC9801/MZ5665 specific settings, and the universal build target are not relevant.
5. Separate repository: https://git.eaw.app/eaw/mz25key (SharpKey is at https://git.eaw.app/eaw/SharpKey).
6. CI/CD pipeline: Has an additional "Fetch Components" stage that clones the two component libraries. SharpKey's pipeline uses git submodule update --init --recursive instead.
7. Version file location: The CI pipeline reads the version from webserver/version.txt, not version.txt in the project root as SharpKey does.
8. Release artifact naming: Uses the mz25key- prefix (e.g. mz25key-FW-v1.00.bin.gz) instead of SharpKey-.

Software Architecture

Architecture Overview

 ┌───────────────────────────────────────────────────────────────────────────┐
 │                        ESP-32S (Dual Core 240MHz)                        │
 │                                                                         │
 │  ┌─────────────────────────────┐  ┌──────────────────────────────────┐   │
 │  │       CORE 0 (PRO)         │  │        CORE 1 (APP)              │   │
 │  │   FreeRTOS Scheduled       │  │   Spinlocked (no FreeRTOS)       │   │
 │  │                            │  │                                  │   │
 │  │  ┌──────────────────────┐  │  │  ┌────────────────────────────┐  │   │
 │  │  │ PS/2 Keyboard Input  │  │  │  │  MZ-2500/2800 Interface   │  │   │
 │  │  │  (PS2KeyAdvanced)    │  │  │  │  (MZ2528 class)           │  │   │
 │  │  └─────────┬────────────┘  │  │  │                            │  │   │
 │  │            │               │  │  │  - Monitor RTSN strobe     │  │   │
 │  │  ┌─────────▼────────────┐  │  │  │  - Read row from KDB[3:0] │  │   │
 │  │  │ Bluetooth Keyboard   │  │  │  │  - Output column data      │  │   │
 │  │  │  (BTHID class)       │  │  │  │    via KDO[7:0]           │  │   │
 │  │  └─────────┬────────────┘  │  │  │  - Handle KD4/MPX timing  │  │   │
 │  │            │               │  │  └────────────┬───────────────┘  │   │
 │  │  ┌─────────▼────────────┐  │  │               │                  │   │
 │  │  │ HID Processing       │  │  │               │                  │   │
 │  │  │  PS/2 → internal     │  │  │  ┌────────────▼───────────────┐  │   │
 │  │  │  scan code           │  │  │  │  Virtual Scan Matrix       │  │   │
 │  │  └─────────┬────────────┘  │  │  │  14 rows × 8 columns      │  │   │
 │  │            │               │  │  │  (15 rows for MZ-2800)     │  │   │
 │  │  ┌─────────▼────────────┐  │  │  └────────────────────────────┘  │   │
 │  │  │ MZ2528::mapKey()     │──┼──┤                                  │   │
 │  │  │  internal → matrix   │  │  │                                  │   │
 │  │  └──────────────────────┘  │  │                                  │   │
 │  │                            │  │                                  │   │
 │  │  ┌──────────────────────┐  │  │                                  │   │
 │  │  │ WiFi / Web Server    │  │  │                                  │   │
 │  │  │ OTA / NVS / LED      │  │  │                                  │   │
 │  │  └──────────────────────┘  │  │                                  │   │
 │  └─────────────────────────────┘  └──────────────────────────────────┘   │
 └───────────────────────────────────────────────────────────────────────────┘

         PS/2 Keyboard                       MZ-2500 / MZ-2800
         ┌─────────┐                         ┌───────────────┐
         │ CLK/DAT │◄────── GPIO ──────────►│ RTSN/KDB/KDO  │
         └─────────┘                         │ KD4/MPX       │
                                             └───────────────┘

FreeRTOS Task Model

• Core 0 (PRO_CPU): Runs the standard FreeRTOS scheduler with WiFi/BT stack tasks, the PS/2 keyboard interrupt handler, the HID polling task, LED blinking, switch monitoring, and the WiFi HTTP server. All non-timing-critical work happens here.
• Core 1 (APP_CPU): Detached from FreeRTOS using a spinlock. It runs a bare-metal tight loop that monitors the host machine's RTSN strobe signal and responds within the required timing window (~600ns for MZ-2500, ~1.78us for MZ-2800). This core does not participate in FreeRTOS scheduling while the host interface is active.

1. Physical key press: The PS/2 keyboard generates a scan code (set 2) and clocks it out over the PS/2 DATA and CLK lines, or a Bluetooth HID device sends an HID report.
2. Input driver: PS2KeyAdvanced captures the scan code via GPIO interrupt and assembles it into a 16-bit internal code (upper byte = modifier flags, lower byte = keycode). For Bluetooth, BTHID translates the HID report into the same 16-bit format using a 179-entry lookup table.
3. HID aggregator: The HID class polls both input sources and presents a unified stream of key events.
4. Key mapping: MZ2528::mapKey() receives the 16-bit key code and looks it up in the 165-entry mapping table. The table maps PS/2 key codes to host-specific row/column pairs in the virtual key matrix.
5. Virtual scan matrix: A 14-element (or 15-element for MZ-2800) array in memory is updated — the relevant bit in the row byte is set (key pressed) or cleared (key released).
6. GPIO output: Core 1 continuously monitors RTSN. When the host requests a row, Core 1 reads the row index from KDB[3:0] and outputs the corresponding byte via KDO[7:0] through the 74HCT257 multiplexer. All done with IRAM_ATTR functions, spinlock, and direct register access.

MZ-2500 Keyboard Protocol

1. RTSN rising edge: The host signals it is sending a row address. The ESP32 begins monitoring.
2. Read KDB[3:0]: After ~160ns, the 4-bit row number (0-13) is valid on GPIO_IN_REG. The ESP32 reads it via direct register access.
3. Set KDO[7:0] HIGH: All 8 output bits are initially set to 0xFF (inactive / no keys pressed).
4. Check KDI4 (KD4): If KD4 is HIGH, the host wants the column data for the specific requested row. If KD4 is LOW, the host wants the STROBEALL value — the logical AND of all rows (used for idle key detection).
5. Clear active key bits: For the requested row, the active key bits are cleared via GPIO.out_w1tc (atomic clear operation).
6. RTSN falling edge: The host latches the data from the 74HCT257 multiplexer. The ESP32 waits for this edge before processing the next row.

  MZ-2500 Key Data Retrieval Protocol (one row scan cycle):

                 ┌────────── 660ns ──────────┐┌────────── 680ns ──────────┐
                 │                            ││                           │
        ┌────────┘                            └┘                           └────────┐
  RTSN  │   HIGH (row address phase)          │    LOW (data return phase)          │
        │                                     │                                     │
        │  ┌─ 160ns ─┐                        │                                     │
        │  │         │                        │                                     │
  KDB   │  │  ROW VALID                      │ ┌── nibble hi ──┐┌── nibble lo ──┐  │
  [3:0] │  │  (row 0-13)                     │ │   KDO[7:4]    ││   KDO[3:0]    │  │
        │  │                                  │ │               ││               │  │
        │                                     │                                     │
  KD4   ──── HIGH (row data mode) ──────────── HIGH ────────────────────────────────
        │                                     │                                     │
  MPX   ──────────────────────────────────────┘ ┌── 320ns ──┐┌── 320ns ──┐          │
        │                                       │   HIGH    ││   LOW     │          │
        │                                       │ upper nib ││ lower nib │          │
        └───────────────────────────────────────────────────────────────────────────┘

// In app_main(), after all Core 0 tasks are created:
portMUX_TYPE mux = portMUX_INITIALIZER_UNLOCKED;
portENTER_CRITICAL(&mux);      // Disables interrupts, prevents scheduling
hostInterface->run();           // Never returns — tight RTSN polling loop
portEXIT_CRITICAL(&mux);       // Never reached

MZ-2800 Keyboard Protocol

• Longer setup times: KDB[3:0] row data trails RTSN by at least 650ns (compared to 160ns on the MZ-2500). The ESP32 must insert a longer delay before reading the row number.
• Higher RTSN frequency: The RTSN period is approximately 1.78us.
• Higher task priority: The MZ-2800 interface task runs at MAX_PRIORITIES-1 instead of priority 25.
• Row 14: In native 80286 mode, the MZ-2800 scans a 15th row (row 14) containing keys specific to the 80286 operating system. In MZ-2500 compatibility mode, only rows 0-13 are scanned.
• Shorter debounce: ~100us initial, ~300us repeat (compared to ~600us on the MZ-2500).
• Different connector: The MZ-2800 uses an AMP 9-pin D-Sub connector (3M 10120-6000L/10220-5212PL compatible replacement). The MZ-2500 uses an 8-pin mini-DIN.
• STROBEALL row: The MZ-2800 sends row 0 during STROBEALL mode; the MZ-2500 sends row 4. In both cases the row value is ignored.

Key Matrix Structure

  Row 0:  F1, F2, F3, F4, F5, NUM, GRAPH, KANA
  Row 1:  F6, F7, F8, F9, F10, HOME/CLR, semicolons, colon
  Row 2:  1, 2, 3, 4, 5, 6, 7, 8
  Row 3:  9, 0, -, ^, YEN, TAB, Q, W
  Row 4:  E, R, T, Y, U, I, O, P
  Row 5:  @, [, RETURN, A, S, D, F, G
  Row 6:  H, J, K, L, ;, :, ], SPACE
  Row 7:  Z, X, C, V, B, N, M, ,
  Row 8:  ., /, _, cursor down, cursor left, cursor right, cursor up, DEL/BS
  Row 9:  ROLLUP, ROLLDOWN, INS, CLR, cursor keys (alternate)
  Row 10: Tenkey 0, 1, 2, 3, 4, 5, 6, 7
  Row 11: Tenkey 8, 9, *, +, -, /, ., =
  Row 12: CTRL, SHIFT, LOCK, KANA_LOCK, GRAPH_LOCK
  Row 13: Japanese transform keys (HENKAN, MUHENKAN, etc.)
  Row 14: MZ-2800 specific keys (80286 mode only — not scanned on MZ-2500)

Source Modules

Key Mapping System

Scan Code Pipeline

  PS/2 Scan Code Set 2    Internal 16-bit Code      MZ Matrix Position
  ┌──────────────────┐    ┌──────────────────┐      ┌──────────────────┐
  │ Make: 0x1C       │    │ Upper: modifiers │      │ Row: 5           │
  │ Break: 0xF0 0x1C │──►│ Lower: 0x41 (A)  │──►  │ Col bit: 0x08    │
  │ (PS/2 protocol)  │    │ (PS2KeyAdvanced) │      │ (MZ2528::mapKey) │
  └──────────────────┘    └──────────────────┘      └──────────────────┘

  Stage 1: PS2KeyAdvanced     Stage 2: HID class     Stage 3: MZ2528::mapKey()
  (interrupt-driven,          (normalisation,         (165-entry table lookup,
   scan code set 2)            modifier tracking)      row/column output)

  Bit 15    Bit 14    Bit 13    Bit 12    Bit 11    Bit 10    Bit 9     Bit 8
┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐
│  BREAK  │  SHIFT  │  CTRL   │  CAPS   │  ALT    │ ALT_GR  │  GUI    │FUNCTION │
└─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘
  Bits 7-0: Key code (unique identifier for each physical key)

Mapping Table

  Column          Type      Description
  ──────────────  ────────  ──────────────────────────────────────────────────
  PS2 Keycode     uint8_t   Lower byte of the 16-bit internal key code
  Ctrl Key        uint8_t   Modifier key requirements (PS2CTRL_NONE, SHIFT, etc.)
  Keyboard Model  uint8_t   PS/2 keyboard model filter (0 = all models)
  Host Model      uint8_t   Target machine (MZ_ALL, MZ_80B, MZ_2000, MZ_2500, MZ_2800)
  Make Row1       uint8_t   Row in virtual matrix to activate on key press
  Make Key1       uint8_t   Column bit mask to set in that row
  Make Row2       uint8_t   Second row (for SHIFT+key combos; 0xFF = unused)
  Make Key2       uint8_t   Second column bit mask
  Break Row1      uint8_t   Row to deactivate on key release
  Break Key1      uint8_t   Column to clear on release
  Break Row2      uint8_t   Second row to deactivate on release
  Break Key2      uint8_t   Second column bit mask on release

Updating Key Mappings

// Map PS/2 F11 to MZ row 3, bit 7 (HELP key)
// { PS2Code, CtrlKey, KbdModel, HostModel, MkRow1, MkKey1, MkRow2, MkKey2,
//   BkRow1, BkKey1, BkRow2, BkKey2 }
{PS2_KEY_F11, PS2CTRL_NONE, 0, MZ_ALL, {3, 0x80, 0, 0, 0, 0}, {3, 0x80, 0, 0}},

// Map PS/2 Backslash to MZ row 6, bit 2 (single-position mapping)
// 0xFF in Row2 means no second matrix position needed
{0x5D, 0x00, 0x00, 0x00, 6, 0x04, 0xFF, 0x00, 6, 0x04, 0xFF, 0x00},

• ALT+F1: MZ-2500 layout (default) — the standard 14-row matrix.
• ALT+F2: MZ-2000 layout — adjusts the matrix to match MZ-2000 key positions.
• ALT+F3: MZ-80B layout — reconfigures for the MZ-80B keyboard matrix arrangement.

Supported Keyboards

• Wyse KB-3926 (PS/2, compact layout)
• OADG 109 Japanese keyboard (PS/2)
• Sanwa SKBL1 (PS/2, backlit)
• Periboard 810 (Bluetooth, compact)
• Omoton K8508 (Bluetooth, slim)
• Standard IBM Model M (PS/2, via DIN-to-PS/2 adapter)
• Cherry G80 series (PS/2)
• Logitech K380 (Bluetooth multi-device)

Binary Keymap Files

  MZ2528_KeyMap.BIN     — custom keymap for MZ-2500/MZ-2800

GPIO Configuration

• RTSNI on GPIO 35: This is an input-only pin on the ESP32. It is read via the GPIO_IN1_REG bank (GPIOs 32-39), not GPIO_IN_REG (GPIOs 0-31). The firmware uses a pre-computed bit mask for direct register access.
• KDO0-7 output: These 8 pins drive the 74HCT257 quad 2:1 multiplexer. The MPX signal from the host directly controls the multiplexer to select the upper or lower nibble, eliminating the need for the ESP32 to respond to MPX timing.
• ADC2/WiFi GPIO conflict: GPIOs 0, 2, 4, 12-15, 25-27 are shared with ADC2, which cannot be used while WiFi is active. The PCB design uses these pins for digital GPIO only, avoiding the conflict.

Bluetooth Integration

• Protocols: Bluetooth Classic + BLE HID support.
• Bonded devices: Up to 5 devices can be stored in NVS.
• Pairing window: 60 seconds after initiating scan via the button (hold 10-14 seconds).
• PIN: "1234" for devices that require legacy pairing. Most modern devices use SSP (no PIN).
• Priority: PS/2 keyboard input has priority over Bluetooth when both are connected. Events from both sources are merged by the HID aggregator.

1. Press and hold the mz25key button for 10-14 seconds. The LED enters fast-blink mode.
2. Put the Bluetooth keyboard into pairing mode (usually by holding its pairing button).
3. The mz25key scans for BT HID devices for approximately 60 seconds.
4. When a device is found, pairing initiates automatically (SSP, no PIN required for most devices).
5. On success, the LED returns to normal blink. The device address is saved to NVS for automatic reconnection on subsequent power-ups.

WiFi and Web Interface

• AP mode: The mz25key creates its own WiFi network (default SSID: sharpkey). Connect a device to this network and access the web interface at http://192.168.4.1.
• Client mode: The mz25key connects to an existing WiFi network using credentials stored in NVS. The web interface is accessible at the DHCP-assigned IP address.
• Mode switching: Hold the button 2-4 seconds for client mode, 5-9 seconds for AP mode. A reboot is required to switch between WiFi and Bluetooth.

Building the Web Filesystem (build_webfs.sh)

1. Copies all HTML files from webserver/html/ into the webfs/ staging directory.
2. Compresses CSS and JavaScript files with gzip (the HTTP server serves them with Content-Encoding: gzip to save flash space).
3. Copies any binary assets (default keymap files, favicon) into webfs/.
4. The ESP-IDF build system then packages the webfs/ directory into a LittleFS filesystem image (build/filesys.bin) that is flashed to the filesys partition.

# Build the web filesystem before building firmware
chmod +x build_webfs.sh
./build_webfs.sh

# The output is used automatically by the ESP-IDF build

OTA Updates

Partition Scheme

  Name            Type    SubType   Offset     Size       Description
  ──────────────  ──────  ────────  ─────────  ─────────  ────────────────────────────
  nvs             data    nvs       0x9000     0x5000     Non-volatile storage
  otadata         data    ota       0xE000     0x2000     OTA boot selection data
  ota_0           app     ota_0     0x10000    0x1A0000   Firmware bank 0 (1664 KB)
  ota_1           app     ota_1     0x1B0000   0x1A0000   Firmware bank 1 (1664 KB)
  filesys         data    0x80     0x350000   0xA0000    LittleFS web filesystem (640 KB)
  coredump        data    coredump  0x3F0000   0x10000    Core dump storage (64 KB)

1. Connect to the mz25key web interface (AP or client mode).
2. Navigate to /ota.html.
3. Select "Firmware Update" (uploads main.bin) or "Filesystem Update" (uploads filesys.bin).
4. Choose the binary file and click Upload. A progress bar shows transfer status.
5. After upload, the device verifies image integrity (SHA-256 hash check).
6. If verification passes, the device reboots into the new firmware. Version validation prevents downgrade.

eFuse Custom Fields

# Read all eFuse values
espefuse.py --port /dev/ttyUSB0 summary

# Write the hardware revision (WARNING: one-time-programmable, cannot be undone!)
espefuse.py --port /dev/ttyUSB0 burn_efuse BLOCK3 0x12 --offset 0 --size 8

# Write the serial number
espefuse.py --port /dev/ttyUSB0 burn_efuse BLOCK3 0x0042 --offset 8 --size 16

Build Environment

Native Build Setup

# Install ESP-IDF v4.4
mkdir -p ~/esp
cd ~/esp
git clone -b v4.4 --recursive https://github.com/espressif/esp-idf.git esp-idf-v4.4
cd esp-idf-v4.4
./install.sh

# Activate the environment (needed in every new terminal session)
. ~/esp/esp-idf-v4.4/export.sh

Clone and Build

# Clone the mz25key repository (no --recursive needed)
git clone https://git.eaw.app/eaw/mz25key.git
cd mz25key

# Clone required components manually (NOT submodules!)
mkdir -p components

# Arduino-ESP32 compatibility layer — must be exactly v2.0.3
git clone https://github.com/espressif/arduino-esp32.git components/arduino-esp32
cd components/arduino-esp32 && git checkout 2.0.3 && cd ../..

# LittleFS filesystem support — must be v1.3.1 WITH submodules initialised
git clone https://github.com/joltwallet/esp_littlefs.git components/esp_littlefs
cd components/esp_littlefs && git checkout v1.3.1 && git submodule update --init --recursive && cd ../..

# Configure the build target (select MZ25KEY_MZ2500 or MZ25KEY_MZ2800)
idf.py menuconfig

# Build the web filesystem (required before first firmware build)
chmod +x build_webfs.sh && ./build_webfs.sh

# Build the firmware
idf.py build

# Flash to the device
idf.py -p /dev/ttyUSB0 flash

# Flash and monitor in one command
idf.py -p /dev/ttyUSB0 flash monitor

  build/main.bin                           — Firmware binary (for OTA update)
  build/filesys.bin                        — Web filesystem image (for OTA update)
  build/bootloader/bootloader.bin          — Bootloader
  build/partition_table/partition-table.bin — Partition table
  build/ota_data_initial.bin               — OTA data partition

Menuconfig Options

• Build Target: Select mz25key - MZ2500 or mz25key - MZ2800. This sets the Kconfig symbol MZ25KEY_MZ2500 or MZ25KEY_MZ2800 and determines the protocol timing, row count, and task priority.
• PS/2 Keyboard GPIO: Configure the DATA and CLK pins for the PS/2 keyboard interface.
• Host Interface GPIO: Pin assignments for RTSN, KDB[3:0], KDO[7:0], KD4, MPX.
• WiFi Settings: Default SSID, password, AP mode channel.
• Bluetooth: Enable/disable Bluetooth HID stack.
• Debug Options: Enable serial debug output (CONFIG_DEBUG_SERIAL), disable individual GPIO groups for testing.

Docker Build

# Clone and prepare (same manual component cloning required)
git clone https://git.eaw.app/eaw/mz25key.git
cd mz25key
mkdir -p components
git clone https://github.com/espressif/arduino-esp32.git components/arduino-esp32
cd components/arduino-esp32 && git checkout 2.0.3 && cd ../..
git clone https://github.com/joltwallet/esp_littlefs.git components/esp_littlefs
cd components/esp_littlefs && git checkout v1.3.1 && git submodule update --init --recursive && cd ../..

# Build web filesystem
chmod +x build_webfs.sh && ./build_webfs.sh

# Build firmware using Docker
docker run --rm -v $(pwd):/project -w /project espressif/idf:v4.4 idf.py build

# Flash via Docker (requires USB device access)
docker run --rm --privileged \
    --volume /dev:/dev --volume /sys:/sys:ro --volume /dev/bus/usb:/dev/bus/usb \
    -v $(pwd):/project -w /project \
    espressif/idf:v4.4 \
    idf.py -p /dev/ttyUSB0 build flash monitor

# Add to ~/.bashrc or ~/.zshrc
alias idf44='docker run --rm --privileged --volume /dev:/dev --volume /sys:/sys:ro \
    --volume /dev/bus/usb:/dev/bus/usb -v $PWD:/project -w /project -it \
    espressif/idf:v4.4 idf.py "$@"'

# Then use:
idf44 build
idf44 menuconfig
idf44 -p /dev/ttyUSB0 flash monitor

Continuous Integration (Jenkins)

Pipeline Overview

1. Checkout: Clean workspace, clone repository from Gitea. Note: NO submodule init is performed (there are no submodules).
2. Fetch Components: Clone arduino-esp32 at tag 2.0.3 and esp_littlefs at tag v1.3.1 (with submodules) into components/. This stage is unique to mz25key — SharpKey uses git submodule update --init --recursive instead.
3. Determine Version: Auto-increment from the latest Gitea release tag, or read from webserver/version.txt.
4. Build Web Filesystem: Run build_webfs.sh to package HTML, CSS, and JavaScript into the LittleFS image.
5. Generate eFuse Table: Run efuse_table_gen.py inside the IDF Docker container to generate the eFuse C source from the CSV definition.
6. Build Firmware: Launch the espressif/idf:v4.4 Docker container and run idf.py build.
7. Package Release: Create versioned FW, FilePack, and FlashPack archives.
8. Create Gitea Release: Upload artifacts to Gitea as a tagged release.

Fetch Components Stage

stage('Fetch Components') {
    steps {
        sh """
            mkdir -p components

            git clone https://github.com/espressif/arduino-esp32.git components/arduino-esp32
            cd components/arduino-esp32 && git checkout 2.0.3 && cd ../..

            git clone https://github.com/joltwallet/esp_littlefs.git components/esp_littlefs
            cd components/esp_littlefs && git checkout v1.3.1 \
                && git submodule update --init --recursive && cd ../..
        """
    }
}

Webhook Configuration

• Target URL: http://your-server:8080/generic-webhook-trigger/invoke?token=mz25key-build-trigger
• Content Type: application/json
• Trigger On: Push Events
• Branch Filter: refs/heads/(main|master)

Version Management

Release Artifacts

• mz25key-FW-vX.XX.bin.gz — Gzip-compressed firmware binary for OTA update via the web interface. Upload to the device through /ota.html as a "Firmware" update.
• mz25key-FilePack-vX.XX.bin.gz — Gzip-compressed LittleFS filesystem image for OTA update. Upload as a "Filesystem" update to update web pages, keymaps, and other web-served content.
• mz25key-FlashPack-vX.XX.tar.gz — Complete flash image archive containing bootloader, partition table, firmware, filesystem, and OTA data. Used for initial programming via esptool.py or for factory recovery.

Pipeline Configuration

volumes:
  - /srv/jenkins/data:/var/jenkins_home
  - /var/run/docker.sock:/var/run/docker.sock    # Required for ESP-IDF sibling container

eFuse Table Generation

Differences from SharpKey CI Pipeline

• Fetch Components stage: mz25key explicitly clones arduino-esp32 and esp_littlefs into components/. SharpKey uses git submodule update --init --recursive during the Checkout stage instead.
• Generate eFuse Table stage: mz25key includes an additional pipeline stage that generates the eFuse configuration table from the CSV definition. The SharpKey pipeline handles this within the Build stage.
• Version file location: mz25key reads its version from webserver/version.txt, whereas SharpKey reads from version.txt in the project root.
• Artifact naming: Release artifacts use the mz25key- prefix (e.g. mz25key-FW-v1.00.bin.gz) instead of SharpKey-.
• Webhook token: Uses mz25key-build-trigger (not sharpkey-build-trigger).
• No submodule init: The Checkout stage does not run any submodule commands because there are no submodules. SharpKey's Checkout stage runs git submodule update --init --recursive.

Debugging

Serial Monitor

idf.py -p /dev/ttyUSB0 monitor

# Or with Docker:
docker run --rm --privileged --volume /dev:/dev --volume /sys:/sys:ro \
    -v $PWD:/project -w /project -it espressif/idf:v4.4 \
    idf.py -p /dev/ttyUSB0 monitor

  Tag         Source              Description
  ──────────  ──────────────────  ───────────────────────────────────────
  sharpkey    SharpKey.cpp        Application-level events (init, host detection)
  MZ2528      MZ2528.cpp          MZ-2500/MZ-2800 interface events
  HID         HID.cpp             Key event processing
  PS2         PS2KeyAdvanced.cpp  PS/2 scan code reception
  BT          BT.cpp              Bluetooth discovery and pairing
  BTHID       BTHID.cpp           Bluetooth HID report translation
  WiFi        WiFi.cpp            WiFi and HTTP server events
  NVS         NVS.cpp             Configuration storage
  LED         LED.cpp             LED state changes
  SWITCH      SWITCH.cpp          Button press events

esp_log_level_set("*", ESP_LOG_WARN);        // Default: warnings and errors only
esp_log_level_set("MZ2528", ESP_LOG_DEBUG);   // Verbose MZ2528 output

GPIO Debug Flags

• CONFIG_DEBUG_DISABLE_KDB: Disables the keyboard bidirectional data bus (KD[3:0]). Use when testing host strobe detection without driving data back.
• CONFIG_DEBUG_DISABLE_KDO: Disables the keyboard data output (scan data to multiplexer). Use when testing input-side logic only.
• CONFIG_DEBUG_DISABLE_RTSNI: Disables the RTSN input monitoring. Use to test passive matrix updates without host polling.
• CONFIG_DEBUG_DISABLE_MPXI: Disables the MPX input monitoring. Use when debugging row strobe detection independently of nibble multiplexing.
• CONFIG_DEBUG_DISABLE_KDI: Disables the KD4 input. Use when testing without the type strobe signal.

Common Issues

• Components not cloned — "component not found" errors:
  • The most common build failure. After cloning the mz25key repository, the components/ directory is empty. You must manually clone arduino-esp32 (v2.0.3) and esp_littlefs (v1.3.1) as described in the Clone and Build section.
• esp_littlefs submodules missing — mklittlefs build fails:
  • The esp_littlefs component has its own git submodules (including the mklittlefs tool). If you forget to run git submodule update --init --recursive inside components/esp_littlefs/, the web filesystem build will fail with "No rule to make target 'dist'".
• Timing issues — host not detecting keys:
  • Ensure the MZ2528 interface is pinned to Core 1 with the spinlock. Any FreeRTOS scheduling on Core 1 will cause missed RTSN strobes.
  • Verify all hot-path functions have IRAM_ATTR — flash cache misses add hundreds of nanoseconds of latency.
  • Use a logic analyser to verify the RTSN response time is within the required window.
• ADC2/WiFi GPIO conflict:
  • GPIOs 0, 2, 4, 12-15, 25-27 are shared with ADC2. Analog reads on these pins return garbage when WiFi is active. The mz25key PCB uses these pins for digital GPIO only.
• eFuse CSV not committed:
  • The .gitignore may exclude *.c files in the eFuse directory. Ensure the CSV definition file (esp_efuse_custom_table.csv) is committed. The generated C file is rebuilt during CI.
• MZ-2800 mode keys not working:
  • Ensure the build target is MZ25KEY_MZ2800 (not MZ25KEY_MZ2500). The MZ-2800 has longer setup times (650ns for KDB vs 160ns) and an additional 15th row.
• PS/2 keyboard not detected:
  • Check PS/2 DATA and CLK wiring. PS/2 uses open-collector signalling; 4.7K pull-up resistors to 5V are required.
  • Some keyboards require a power cycle after ESP32 reset.
• WiFi will not connect:
  • The ESP32 supports 2.4GHz only — it cannot connect to 5GHz networks.
  • WiFi and Bluetooth are mutually exclusive. Disable BT before enabling WiFi.
• Bluetooth keyboard not pairing:
  • Ensure WiFi is disabled (mutual exclusion).
  • Put the keyboard into pairing mode before initiating the scan from the mz25key.
  • Some keyboards require removing the existing pairing first.
• OTA update fails:
  • Ensure the correct file type — main.bin for firmware, filesys.bin for filesystem.
  • Version validation prevents downgrade — upload a newer version.
• ESP32 core panic / reboot loop:
  • Usually a stack overflow or null pointer. The UART monitor shows the panic register dump. Increase stack sizes in menuconfig if needed.

Reference Sites

Wireless Regulatory Notice