43d55f35b0
The pipeline was pasted into the Jenkins job, so it could not follow this repository. It is here now, and the job points at this file. It also fixes the build. The ESP-IDF container was run as root, so everything it produced was owned by root: packaging failed with "cp: cannot create regular file 'release/SharpKey-FW-vX.bin': Permission denied", and Jenkins could not wipe the workspace afterwards either. It now runs as the build user, with HOME set to the workspace so the toolchain has somewhere writable for its cache. The Gitea token is no longer a literal anywhere; it is bound from the Jenkins credential 'gitea-token', which also masks it in the build log. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
SharpKey
Website: engineers@work | Repository: git.eaw.app/eaw/SharpKey
Summary
The SharpKey is an IoT Multi-HID (Human Interface Device) to Multi-Host Interface with on-board web configuration and Over The Air update facilities. It enables more modern keyboard and mice
devices to be used with vintage computers where these devices are no longer obtainable or working.
The device is plug and play, it automatically detects connected input and host device types, self-configures and is ready for instant on useability. Bluetooth devices require the SharpKey and HID device to be set to pairing
mode for first time use and once paired operate exactly as wired equivalents.
At its heart, the SharpKey uses a dual-core WiFi/BT enabled SoC from Espressif with C++ based Object Oriented firmware. The on-board IoT web interface, operating in Station or Access Point mode, is based on venerable Javascript/JQuery/Bootstrap technologies
and supports most modern web browsers.
The SharpKey currently supports:
<style>
table {
border-collapse: collapse;
}
tr td {
padding-top: 0em;
}
tr:nth-child(4) td {
padding-top: 0;
}
</style>
| Input Devices | Host Computers | |||
|---|---|---|---|---|
| PS/2 Keyboards | Sharp X1 | Sharp MZ-56001. | ||
| PS/2 Mice | Sharp X68000 | Sharp MZ-65001. | ||
| PS/2 KVM Switch | Sharp MZ-2500 | NEC PC-98012. | ||
| Bluetooth HID | Sharp MZ-2800 |
Overview
Following on from the successful mz25key interface, the SharpKey advances the design in terms of hardware and software to provide an all in one expandable solution to interfacing keyboards and mice to venerable Sharp and NEC computers.
The mz25key supports adding a PS/2 keyboard to a Sharp MZ-2500 or MZ-2800 computer whereas the SharpKey is more versatile in connecting both keyboards and mice, via PS/2 or Bluetooth, to a host console.
PS/2 mode supports one device at a time, device type being determined by the connected host port type using host specific cables. A mouse cable connected to the mouse port of an X68000 will require a PS/2 mouse connected to the SharpKey
and a keyboard cable connected to the keyboard port of an X68000 will require a PS/2 keyboard connected to the SharpKey.
In PS/2 mode, it is possible to connect multiple host consoles, each with its own SharpKey device, to one Keyboard, Mouse and Monitor via a PS/2 KVM Switch such as the Apex EL-80DT.
Bluetooth mode supports simultaneous use of keyboard and mouse where the host supports it and the correct host specific cable is used. ie. an X68000 uses a single cable to transmit both keyboard and mouse data allowing simultaneous use of keyboard and mouse via Bluetooth, whereas
an MZ-2500 is restricted to keyboard or mouse per SharpKey (ie. to connect both a keyboard and mouse to an MZ-2500 requires 2 SharpKey devices).
This site aims to provide all the information, both technical and user guides for the SharpKey, please click on required link in the left panel. The schematics, layout and firmware are available on Gitea. Please follow or star a project
if you download and make use of it, either for creating your own SharpKey or basing another project on its design. Please note, the GNU license has a restriction that no commercial use can be made without prior written permission.
For more in depth detail, please click on a sidebar link to view the User Manual or Technical Guide.
1, 2.Waiting on testing, not yet released.
Building the Firmware
The SharpKey firmware is an ESP-IDF v4.4 (ESP32) project. Automated, self-contained setup scripts build it on Windows, macOS and Linux - you only need to copy the one script for your platform and run it. Each script installs any missing prerequisites, clones the repository (with submodules), prepares the ESP-IDF v4.4 toolchain and builds the firmware. A first run downloads roughly 1-2 GB (toolchain + submodules) and takes 15-40 minutes depending on your machine and connection; subsequent builds are far quicker.
Quick start
macOS / Linux:
./setup_SharpKey.sh
Windows 10 / 11 (native - no WSL, no Docker - from a PowerShell prompt):
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup_SharpKey_windows.ps1
You can run the script from any working directory - it does not need to be run from inside a SharpKey checkout, because it clones a fresh copy itself. A normal (non-admin) prompt is fine; the installers may request elevation when needed.
What the script does
Each run is idempotent and safe to re-run - it detects and reuses anything already in place. In order it will:
- Install prerequisites it can't find - Git and a compatible Python (via
wingeton Windows, or your system package manager / Homebrew on Linux/macOS). ESP-IDF v4.4 requires Python 3.8-3.11; if your default Python is 3.12+, the Windows script quietly builds inside a dedicated Python 3.10 virtual environment and leaves your own Python untouched. - Clone the SharpKey repository (with submodules - the
arduino-esp32submodule is large). An existing checkout is fast-forwarded rather than re-cloned. - Install the ESP-IDF v4.4 toolchain - on Windows via Espressif's
install.ps1; on macOS/Linux via the pinnedespressif/idf:v4.4Docker image (preferred) or a native ESP-IDF install. - Build the firmware - produces
build/main.bin(andbuild/filesys.bin).
Questions you will be asked
The scripts are interactive. You can accept every default by pressing Enter, or preset the answers with environment variables (below) for a fully unattended run. You may be prompted for:
| Prompt | Default | Notes |
|---|---|---|
| Repository URL | public repo https://git.eaw.app/eaw/SharpKey.git |
Paste a different URL (e.g. a private fork) to build that instead. |
| Checkout / install directory | ~/SharpKey (%USERPROFILE%\SharpKey on Windows) |
Where the repository is cloned and built. |
| Remove and re-clone? | (asked only if the target directory already exists but holds a different/incomplete repo) | Answer N to keep it; the script then uses it as-is. |
| Install Docker Engine now? (Linux/WSL only) | Y | Declining falls back to a native ESP-IDF install. |
| Install missing OS packages / ESP-IDF now? | Y | Decline to install them yourself; the build may fail without them. |
| Build the SharpKey firmware now? | Y | Answer N to only prepare the environment and build later by hand. |
Environment variable overrides (optional, for unattended builds)
| Variable | Effect |
|---|---|
SHARPKEY_REPO_URL |
Repository to clone/build (skips the repo-URL prompt). |
SHARPKEY_BUILD |
(macOS/Linux) Force the build method: docker or native. |
Example (build a private fork with Docker, no prompts for the repo/method):
SHARPKEY_REPO_URL="https://git.eaw.app/eaw/SharpKey.git" SHARPKEY_BUILD=docker ./setup_SharpKey.sh
Build methods per platform
| Platform | Method |
|---|---|
| Windows | Native ESP-IDF v4.4 Windows toolchain (installed by the PowerShell script via winget + Espressif's install.ps1). No WSL or Docker. The LittleFS image tool is shipped prebuilt as tools\mklittlefs.exe (the upstream component would otherwise build it with make, which Windows lacks); a host gcc/g++, if present, is used to rebuild it from source automatically. The bash/perl maintainer post-build scripts are skipped on Windows; the firmware (build\main.bin) and build\filesys.bin are still produced. |
| macOS / Linux | setup_SharpKey.sh builds via the pinned espressif/idf:v4.4 Docker image (recommended; identical everywhere) or a native ESP-IDF v4.4 install if Docker is unavailable. |
Output and flashing
The compiled firmware is written to build/main.bin (on macOS/Linux a versioned copy is also placed in release/sharpkey_fw_v<version>.bin). Flash it with the SharpKey web OTA updater, or with esptool / idf.py -p <PORT> flash.
To rebuild later without re-running the whole setup, activate the ESP-IDF environment and run idf.py build in your checkout (the script prints the exact commands for your install when it finishes).
Credits
Espressif IDF development environment and use of the ESP-32S reference material was used in the design of this Multi-HID interface.
Licenses
This design, hardware and software, is licensed under the GNU Public Licence v3.
No commercial use to be made of this design or any hardware/firmware component without express permission from the author. This condition overrides any rights afforded by the GNU GPL 3 license.
No commercial use to be made of this design or any hardware/firmware component without express permission from the author. This condition overrides any rights afforded by the GNU GPL 3 license.
The Gnu Public License v3
The source and binary files in this project marked as GPL v3 are free software: you can redistribute it and-or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
The source files are distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.