MagicKey63

English | 中文

A compact mechanical keyboard with an onboard screen, dual hidden encoders, and browser-based configuration.

MagicKey63 combines a practical 63-key layout with device-side macros, customizable controls, and open-source hardware and firmware. It is built for everyday use and made for engineers, makers, and firmware hackers to modify and extend.

Under the hood, its RP2040-based platform includes USB HID/RNDIS, a self-hosted Web configuration UI, LittleFS storage, an LVGL screen interface, WS2812 lighting, macro recording and playback, switch bounce diagnostics, and open hardware and mechanical design files.

Features

• Compact 63-key layout with arrow keys and practical editing keys.
• RP2040 firmware with matrix scanning, USB HID, USB networking, and device-side HTTP APIs.
• Self-hosted web configuration page for keymap editing, macro management, resource upload, and version display.
• The web settings page can be updated independently without reflashing the full firmware.
• LVGL onboard UI with status, layer, lighting, network, and bootloader pages.
• Hidden dual clickable encoders for layer switching, volume, menu control, or custom workflows.
• Device-side macro recording, storage, and playback without host-side macro software.
• PIO/DMA-based key scanning and WS2812 driving to reduce real-time CPU load.
• Switch bounce diagnostics for validating switches, debounce behavior, and scan timing.
• Typing Analytics / Input Quality Analytics estimates Typing Score, Estimated Accuracy, Corrections, and Streak locally on the RP2040. It does not store typed content, keep a full keycode history, or transmit input content.
• Firmware, web UI, hardware files, and mechanical files are open-sourced under separate licenses.

Build

Build from the repository root. A local Raspberry Pi Pico SDK checkout is required:

export PICO_SDK_PATH=/path/to/pico-sdk
cmake -S . -B build
cmake --build build

The generated UF2 is available at:

build/firmware.uf2

For release and debug builds, use the project script:

tool/build_firmware.sh --release --incremental -j 8
tool/build_firmware.sh --release --clean -j 8
tool/build_firmware.sh --debug --incremental -j 8

Local checks:

tool/check_ci.sh

Flash

When the device is connected to a Windows host through WSL2, use:

WINDOWS_DRIVE='E:\' TIMEOUT_SECONDS=120 ./tool/flash_uf2_wsl.sh

If the device IP has been changed, provide the matching bootloader URL:

BOOTLOADER_URL=http://172.23.63.1/api/rebootToUf2 ./tool/flash_uf2_wsl.sh

You can also enter UF2 mode manually and copy build/firmware.uf2 to the RPI-RP2 volume.

Web Configuration

Default USB network address:

http://10.63.27.1:80

The device can switch to alternate IP presets or a custom IP. Tool scripts accept DEVICE_URL and BOOTLOADER_URL:

DEVICE_URL=http://172.23.63.1:80 python3 tool/upload_html.py
BOOTLOADER_URL=http://172.23.63.1/api/rebootToUf2 ./tool/flash_uf2_wsl.sh

After editing web/webServer/index.html, index.css, or main.js, regenerate the tracked single-file page:

python3 tool/build_single_html.py
git diff --exit-code -- web/webServer/out/index.html

License Notes

Different parts of this repository use different licenses. See LICENSE and THIRD_PARTY_LICENSES.md.

• Firmware, web UI, and development tools: GPL-2.0-only.
• Hardware electronics design files: CERN-OHL-S-2.0.
• Case and mechanical 3D files: CC-BY-SA-4.0.
• Mongoose is licensed as GPL-2.0-only or commercial. This firmware project uses the GPL-2.0-only option. Closed-source or non-GPL commercial redistribution requires separate Mongoose commercial licensing.
• LVGL, littlefs, cJSON, TinyUSB, and Pico SDK components keep their own license notices.

VID/PID Status

The USB VID/PID has been updated to the Raspberry Pi provided assignment: 0x2E8A:0x113A. The assignment source is documented in firmware/usb/usb_descriptors.c, and the firmware no longer uses TinyUSB demo IDs or a temporary development PID.

Before release, run:

tool/check_ci.sh --strict-release

Repository Layout

• firmware/: RP2040 Pico SDK firmware source code and firmware-side third party libraries.
• web/: Web settings UI source files and generated single-file output.
• tool/: Development, upload, flashing, packaging, and Codex status sync scripts.
• case_3d/: Keyboard enclosure and mechanical structure 3D files.
• hardware/: Schematics and hardware manufacturing source/export files.
• tool/dist/: Generated tool package artifacts.
• build/: Local CMake build output.

Release Artifacts

tool/build_firmware.sh records the Pico SDK path and git commit, runs arm-none-eabi-size, and copies release artifacts to:

build/release/<BuildType>/firmware.uf2
build/release/<BuildType>/firmware.elf
build/release/<BuildType>/firmware.map
build/release/<BuildType>/firmware.size.txt
build/release/<BuildType>/build-info.txt