uConsole QMK Keyboard Firmware

This repository provides a streamlined, standalone QMK firmware distribution specifically optimized for the ClockworkPi uConsole.

Unlike the standard QMK repository, this project isolates the uConsole keyboard logic. By removing unrelated drivers and keyboard definitions, provide a lightweight environment dedicated to perfecting the uConsole typing experience.

🎯 Project Goals

• Clean Workspace: Only contains code relevant to the uConsole keyboard.
• Minimal Context: Makes it easy to identify specific hardware changes and logic.
• Rapid Development: Faster compile times and easier testing of experimental QMK features.
• Streamlined CI/CD: Simple workflows for rebuilding and releasing binaries.
• Low Barrier to Entry: Easier for community members to contribute layouts without learning the entire QMK ecosystem.

🧪 Keyboard Tester

Test your uConsole keyboard layout and functionality with our interactive keyboard tester:

https://j1n6.github.io/qmk-uconsole/

This web-based tool provides:

• Visual Feedback: See which keys are being pressed in real-time
• Layer Detection: Shows Layer 2 (Fn) key combinations
• D-Pad & Gamepad Testing: Test arrow keys, joystick buttons (X, Y, A, B), and mouse buttons (L, R, Middle)
• Scroll & Cursor Tracking: Visualize trackball movement and scroll events

Perfect for verifying your firmware installation and familiarizing yourself with the uConsole's unique keyboard layout!

🎹 Special Key Behaviors

Important

Keyboard Locale / OS Layout: This firmware expects the host operating system's keyboard layout to be set to US English (ANSI). If your OS is configured with a different layout, some key outputs—specifically special characters and tap-hold keys—might not display correctly or map to different symbols.

• Remapped A/B/X/Y in keyboard mode:

Game mode can be activited & toggled by Fn+G. Gamepad function is mapped to the following table:

Key	Gamepad mode	Keyboard mode
A	JS_0 (A)	Execute (KC_EXECUTE)
B	JS_1 (B)	Stop (KC_STOP)
X	JS_2 (X)	System Request (KC_SYSTEM_REQUEST)
Y	JS_3 (Y)	Menu (KC_MENU)
Select	JS_4 (Select)	Select (KC_SELECT)
Start	JS_5 (Start)	Super (KC_LEFT_GUI)

Tap-Hold Keys

Most alphabetic keys, numbers, and special character keys support tap-hold functionality. Modifier and Fn combinations bypass tap-hold (e.g. Ctrl+A behaves normally). Note: Game keys and the D-pad do not have tap-hold behavior to preserve their responsiveness.

Key Category	Tap (< 200ms)	Hold (≥ 200ms)	Examples
Letters	Lowercase	Uppercase	a ↔ A
Numbers	Number	Shifted Symbol	1 ↔ !
Special Chars	Base Character	Shifted Symbol	` ↔ ~, [ ↔ {, - ↔ _

D-Pad & Directional Keys

The physical directional keys change functions based on the active mode:

Active Mode	Modifier Held	D-Pad Function
Keyboard (Layer 0)	None	Standard arrow keys (Up, Down, Left, Right)
Keyboard (Layer 0)	Y or B Button	Mouse cursor movement (quick trackball alternative)
Gamepad (Layer 2)	None	Virtual joystick axes (X and Y axes)

Trackball & Cursor Settings

Advanced trackball features are accessed by holding the Select key:

Action	Function	Description
Hold Select + Move Trackball	Trackball Scrolling	Move Up/Down for vertical, Left/Right for horizontal scroll
Hold Select + Click Trackball	Precision Cursor Mode	Toggles between normal and precision (reduced) cursor speeds

System & Feature Toggles

Use the following shortcuts to toggle hardware modes and special features:

Shortcut / Key Combo	Function	Description
Fn + G	Gamepad Mode	Toggles Layer 2 (maps A/B/X/Y and D-Pad for gaming)
Fn + T + H	Tap-Hold Toggle	Turns tap-hold on/off (Default: disabled, saves to EEPROM) *
Double-Tap Letter	Quick Duplication	Quickly produces two lowercase characters (e.g. aa)
LAlt+RAlt+Start	DFU Mode	Enters bootloader mode for firmware flashing

* Note: In the clockworkpi_uconsole_no_tap_hold.bin build, the tap-hold feature is completely compiled out, so Fn+T+H does nothing.

🎯 Installation Guide

⚠️ WARNING: Don't install a firmware image without another input method, like an external keyboard or SSH connection, or you won't have any way to fix it if it fails. The uConsole keyboard is an independent USB device, so even if it has issues the rest of the unit is unaffected.

Prerequisites

Before starting, ensure you have the necessary tools installed on your uConsole:

1. Install DFU utilities:

   sudo apt install -y dfu-util

On musl libc Linux systems, you have to install gcompat first for the upload script to work. On Alpine or postmarketOS, this can be done via sudo apk add gcompat.

2. Download the original stock firmware package:

   wget https://github.com/clockworkpi/uConsole/raw/master/Bin/uconsole_keyboard_flash.tar.gz
   tar zxvf uconsole_keyboard_flash.tar.gz
   cd uconsole_keyboard_flash

3. Download the latest QMK firmware:

   • Go to Releases
   • Download the firmware binary file of your choice:
     • clockworkpi_uconsole_default.bin: Standard full-featured firmware (includes the tap-hold toggle feature).
     • clockworkpi_uconsole_no_tap_hold.bin: Simplified firmware with the tap-hold feature completely disabled/compiled out.
   • Move the downloaded .bin file to the uconsole_keyboard_flash folder. (Note: If you download the no_tap_hold build, replace clockworkpi_uconsole_default.bin with clockworkpi_uconsole_no_tap_hold.bin in the flashing commands below.)

---

Option 1: First-Time Flash from Stock Firmware

If you're upgrading from the original ClockworkPi firmware:

1. Edit the upload script for better reliability:

   Open maple_upload and change all delay values from 750 to 1500 milliseconds. This prevents "serial port not ready" errors.

2. Flash the firmware:

   sudo ./maple_upload ttyACM0 2 1EAF:0003 clockworkpi_uconsole_default.bin

---

Option 2: Upgrade from Existing QMK Firmware

If you already have QMK installed and want to update:

1. Run the DFU utility:

   sudo dfu-util -w -d 1eaf:0003 -a 2 -D clockworkpi_uconsole_default.bin -R

2. Enter bootloader mode:

When dfu-util says waiting for device, exit with ctrl-C, press Left Alt, Right Alt, and Start, all simultaneously.

After installing the QMK firmware, the bootloader has a 2-3 second window for uploading firmware. Otherwise it will verify the existing firmware and continue to function normally.

---

🆘 Recovery: Unbricking Your Keyboard

In some rare cases, the keyboard will have entered the DFU mode, but the firmware won't have flashed and the keyboard won't respond to input. If this happens, try rebooting the operating system and repeating the flashing steps.

If the keyboard remains non-functional, don't panic! Follow these steps:

1. Connect the micro-USB cable from your uConsole to the keyboard

2. Enter bootloader mode:

   • Locate the S1 pin on the keyboard PCB
   • Short the S1 pin (you'll see a green LED flash)

3. Flash the stock firmware:

   cd uconsole_keyboard_flash
   sudo ./flash

   Note: You may need to try this several or many times.

4. Verify: Once successful, your keyboard should be responsive again. You can then re-flash QMK if needed.

Other Resources

Improving Keypress & Backlight

A custom keyboard diffuser design is available to improve the keypress responsiveness & lighting, details can be found here. Most importantly, you are able to fast type on the small keyboard!

Improving Fit and Reducing Noise

If the trackball does not sit flush beneath the uConsole cover or exhibits slight mechanical "play," you can install a custom shim to tighten the fit. This modification eliminates internal gaps and significantly dampens the vibration noise generated when rolling the trackball against the metal chassis.

• Download: Trackball Shim STL

• Material Recommendation: I highly recommend printing this part using TPU or another flexible filament. The elasticity of TPU provides the necessary grip to hold the module in place while acting as a shock absorber for a quieter user experience.

☕ Support My Work

If you like my work, please consider Buy me a Coffee. Thank you.

📜 License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

You are free to use, modify, and distribute this software under the terms of the GPL-3.0 license. Any derivative works must also be distributed under the same license terms.

For the full license text, see the LICENSE file in this repository or visit https://www.gnu.org/licenses/gpl-3.0.html.

Note: This firmware is provided "as is" without warranty of any kind. Use at your own risk.

🤝 Acknowledgments

Special thanks to oesmith for the initial groundwork and porting the base layout to the uConsole hardware.