Greg's Speedcube Companion

Greg's Speedcube Companion is standalone firmware for a touchscreen speedcubing timer built on the RAKWireless WisBlock platform. It connects directly to supported Bluetooth smart cubes, displays their state in 2D and 3D, generates scrambles, times solves, and keeps statistics for four named profiles.

This repository is a fork of WisBlock Smart Cube Companion, created by Xose Pérez. Greg Helding maintains this fork with a focus on completing the UI, improving Bluetooth reliability, and making the firmware reproducible and maintainable.

Project status

The firmware is under active development. Development and production builds pass, protocol behavior is covered by host-side tests, and Rubik's Connected has been verified on hardware for discovery, reconnection, battery reporting, move notifications, and live cube-state rendering. A complete release acceptance pass is still in progress.

Features

• Direct BLE connection without a phone or cloud service.
• Protocol support for GAN v2, Giiker/Xiaomi, and GoCube-compatible cubes, including Rubik's Connected.
• Live 2D and 3D cube views for supported 2x2 and 3x3 smart cubes.
• WCA-style generated scrambles: 20 moves for 3x3 and 9 for 2x2.
• Automatic timing from the first post-scramble move through the solved state.
• BLE GAN Smart Timer, wired StackMat-compatible timer, and manual timing modes.
• Four editable profiles with persistent names, PB, Ao5, Ao12, and last-12 solve history per puzzle.
• Persistent brightness, active profile, active puzzle, and preferred cube.
• Visible BACK, NEXT, DONE, and SAVE controls; swipe gestures remain shortcuts.
• Versioned, checksummed settings with migration and interrupted-write recovery.

Hardware

The reference build uses:

• RAK19007 WisBlock Base Board
• RAK4631 nRF52840 Core
• RAK14014 240x320 touch display
• RAK18001 buzzer module
• A suitable 3.7 V LiPo battery; the reference unit uses 1000 mAh

Install the buzzer in WisBlock slot A. The optional StackMat input connects to the secondary hardware serial pins on header J10 and requires a stereo audio connection and soldering. Hardware photos are available in images/.

Using the companion

For a smart-cube solve:

1. Wake the cube by turning a face, then select SMART CUBE. Do not pair it through the operating system; the Companion scans and connects directly.
2. Select a profile. Tap the selected profile again to rename it, or press NEXT to continue.
3. Confirm that the 2D and 3D views match the physical cube, using NEXT to move between screens.
4. Follow the displayed scramble moves. Inspection begins when the scramble is complete.
5. Make the first solving move to start the timer. Solving the cube stops it.
6. Press SAVE to record the solve, or use the trash button to discard it.

Four consecutive U turns jump from a cube view to scrambling; repeating the shortcut during scrambling skips to inspection.

Scrambles use standard cube notation. U, D, L, R, F, and B mean Up, Down, Left, Right, Front, and Back. Look directly at the named face: a bare letter is a clockwise quarter-turn, ' is counterclockwise, and 2 is a half-turn.

Development setup

The repository includes a Nix flake and direnv configuration. It also carries the RAK4631 PlatformIO board definition and variant in rakwireless/, so ~/.platformio must not be patched.

direnv allow                         # enter the Nix development shell
pio run                              # build development firmware (DEBUG=2)
pio run -e production                # build production firmware (DEBUG=1)
tests/run_host_tests.sh              # run protocol and policy tests
pio run -t upload                    # flash a connected RAK4631
pio device monitor -b 115200         # view development logs
pio run -t clean                     # remove build artifacts

The first PlatformIO build downloads the Nordic platform, toolchain, Arduino framework, and libraries. On Linux, USB upload and monitoring require access to /dev/ttyACM*, normally through dialout membership and PlatformIO udev rules.

Firmware sources are in code/; smart-cube protocols are in code/cubes/ and timer protocols in code/timers/. Editable artwork lives in assets/, compiled bitmap headers in code/assets/, documentation in docs/, and host tests in tests/.

Troubleshooting

• If a cube is not found, charge and wake it, move it close to the Companion, and ensure no other device currently holds its BLE connection.
• If the first connection attempt times out, leave the pairing screen open; scanning resumes automatically and retries supported devices.
• CUBE xx% confirms battery communication. The 2D and 3D views should also show all six colors and update after every turn.
• Use the development build and serial monitor when reporting BLE or protocol problems. Include the cube model and the relevant [BLE], [GOC], [GAN], or [GII] lines.

License and attribution

Copyright (C) 2023 Xose Pérez

Copyright (C) 2026 Greg Helding, for subsequent modifications

This project is free software licensed under the GNU General Public License version 3 or later (GPL-3.0-or-later), matching the upstream project's licensing terms. It is provided without warranty; see the license for redistribution and modification terms.