Clockworkpi Uconsole

Disclaimer & Purpose

This document serves as a personal repository for hacking and optimizing the ClockworkPi uConsole. I created this because official guides and community instructions are often fragmented across various forums, making it difficult to track the current status of specific mods or fixes.

While the information here has been personally validated, the uConsole is a DIY-oriented device. Please be aware that any modifications are performed at your own risk.

Operating Systems

The community member Rex maintains a list of OS distributions for uConsole, the latest images can be found in Shared Google Drive.

The best way to prepare the OS disk/SD card is using Raspberryy PI Imager.

Keyboard Firmware

The keyboard contains a Aurdurino microchip, the firmware can be upgraded or custmoized via QMK. There are a number of things to check first.

If Fn+trackball does not scroll, you need up grade to the lastest stock firmware.

• Github Wiki Link
• Orignal Stock Binary

Making sure you first download the orignal stock firmware, it contains a maple_upload script that help with both flashing stock firmware or flashing the QMK firmware.

To upgrade to the latest stock firmware:

1. Install DFU Tools: sudo apt install -y dfu-util
2. Unpack the compressed files: tar zxvf uconsole_keyboard_flash.tar.gz
3. Execute upgrade command: cd uconsole_keyboard_flash && ./flash

Alternatively, the community has kindly developed an alternative QMK firmware.

• The orignal contributors repository: https://github.com/oesmith/qmk_firmware
• 20240922 version is found to be reletively stable for me: Download clockworkpi_uconsole_default.20240922.bin on your uconsole

To install the QMK firmware:

1. Ensure the DFU Tools is installed: sudo apt install -y dfu-util
2. Download the orignal stock firmware packages Unpack the compressed files: tar zxvf uconsole_keyboard_flash.tar.gz
3. Edit the maple_upload, change all the default 750 to 1500 millionsecond dealy, othewires you might see the serial port isn’t ready or not found errors.
4. Flash the QMK firmware by the following command sudo ./maple_upload ttyACM0 2 1EAF:0003 clockworkpi_uconsole_default.20240922.bin
5. To upgrade QMK firmware from existing QMK: $ sudo dfu-util -w -d 1eaf:0003 -a 2 -D clockworkpi_uconsole_default.20240922.bin -R

The 20240922 Firmware Contain the following features:

• It tries to match the stock keymapping as much it can be, don’t be suprised if some does not map to the orignal stock firmware behaviours.
• Gamepad Mode: Toggled by Fn+G, it re-binds the arrow keys to d-pad buttons
• Trigger Booloader: LeftAlt + RightAlt + Start

Any customization requires modification to the QMK repository, you can fork the contributors repository to build an alternative keyboard layout.

To restore the orignal firmware with the stock packages provided by ClockworkPi, simply run sudo ./flash.sh.