squarectl

Use your Elite SQUARE cycling controller with indoor cycling apps that don't support it natively: Rouvy, Zwift, MyWhoosh, and any other app that takes keyboard input.

squarectl runs in the background, listens to the SQUARE over Bluetooth, and translates each button press into a keystroke for the app currently in focus. You ride normally; the SQUARE buttons just work.

Why

The Elite SQUARE talks Bluetooth, but most indoor cycling apps don't pair with it directly. squarectl bridges the gap by impersonating a keyboard, so any app that responds to keys (which is essentially all of them) can be controlled from the handlebars.

Requirements

• An Elite SQUARE controller
• Windows 10 or 11 (WebView2 runtime: preinstalled on Win11, auto-installed by the installer on Win10), or macOS 11+ on Apple Silicon
• Bluetooth
• A cycling app you already use

Linux is supported by the codebase but not packaged as a release yet. See Build from source.

Install

Windows

Grab the latest .exe installer from the Releases page and run it.

Windows SmartScreen warning: the installer is not code-signed (signing certificates aren't free, and squarectl is a side project). On first launch you'll see a blue "Windows protected your PC" screen. Click More info → Run anyway. You only need to do this once.

macOS (Apple Silicon)

Grab the latest .dmg from the Releases page, open it, and drag squarectl into the Applications folder.

macOS Gatekeeper warning: the app isn't code-signed (an Apple Developer account is required, and squarectl is a side project). On first launch macOS will show "squarectl is damaged and can't be opened" — this message is misleading, the app is fine. Open Terminal and run:

xattr -cr /Applications/squarectl.app

Then double-click the app. You only need to do this once.

The first time squarectl runs, macOS will ask for Bluetooth permission (to talk to the SQUARE) and Accessibility permission (to simulate keystrokes). Both are required.

Usage

1. Power on the SQUARE.
2. Launch squarectl. It stays open in the background.
3. Pick the profile matching your cycling app from the dropdown (Rouvy, Zwift, MyWhoosh, or any custom profile).
4. Launch your cycling app and bring its window to the front.
5. Ride. The SQUARE buttons now drive the app via the keyboard mapping.

Zwift on Windows: Zwift ignores keystrokes from squarectl unless squarectl is launched with admin rights. Right-click squarectl → Run as administrator.

Profiles

Each profile is a small TOML file mapping SQUARE buttons to keys. Three are bundled out of the box (Rouvy, Zwift, MyWhoosh) and you can drop in your own.

Where they live:

• Windows: %APPDATA%\org.kochka.squarectl\profiles\
• macOS: ~/Library/Application Support/org.kochka.squarectl/profiles/

What a profile looks like:

[profile]
name = "Rouvy"
description = "Default mapping for Rouvy"

[buttons]
# D-pad
Up              = "up"
Down            = "down"
Left            = "left"
Right           = "right"

# Face buttons
A               = "return"
B               = "escape"
Triangle        = "space"
Square          = "h"

# Left shifter
LeftCampagnolo  = "left"
LeftBrake       = ["1", "6"]   # toggle: alternates "1" and "6" each press
LeftShift1      = ""           # unmapped

Mapping forms:

Form	Effect
Button = "key"	A single key tap.
Button = ["k1", "k2"]	Toggle: alternates k1 and k2 on every press. Useful for things like switching between two gear groups.
Button = ""	Button is intentionally unmapped, no key sent.

Available key names: up, down, left, right, return, escape, space, tab, backspace, single letters (a–z) and digits (0–9).

Mouse wheel: scroll_up, scroll_down, scroll_left, scroll_right (one press scrolls roughly one physical wheel notch).

SQUARE buttons: Up, Down, Left, Right, A, B, Triangle, Square, Circle, X, Y, Z, LeftCampagnolo, LeftBrake, LeftShift1, LeftShift2, RightCampagnolo, RightBrake, RightShift1, RightShift2.

Add or edit a profile

1. Copy an existing .toml in the profiles folder, or create a new one. The filename should be lowercase / snake_case (e.g. my_setup.toml); the user-facing profile name comes from the name field inside.
2. Edit the [buttons] section.
3. Restart squarectl. The new profile appears in the dropdown.

Build from source

Only needed if you're on Linux or want to tweak the code. Requires Rust, Node.js and pnpm.

pnpm install
pnpm tauri build

The bundled app lands in src-tauri/target/release/bundle/.

License

MIT — do whatever you want with it.

Disclaimer

squarectl is an independent project. It is not affiliated with or endorsed by Elite, Rouvy, Zwift, or MyWhoosh.