Make your Zwift Click V2 act as a computer keyboard to shift gears & steer in any cycling apps.
Zwift locks the Click V2 to its own app. zwiftboard frees it: connect over Bluetooth, press a button, and it types the keys your app already understands. Gear up, gear down, steer, pause, change view.
- One pod or two - Both controllers or right only works out of the box.
- No Unlock Tricks - No need to start Zwift App to unlock controllers. Everything is done for you automatically.
- Free and open source - no subscription, no paid tier.
- Starts your app for you - each profile can launch its cycling app once Bluetooth is up, so one double-click on
zwiftboard.exeopens the whole setup. See Start a program with a profile. - Clicks land in the right window - optionally bring your app to the front before every key, so a press never goes to the wrong window.
- Ready for your app - profiles for MyWhoosh, Zwift, TrainerRoad, Rouvy, TrainingPeaks Virtual, Biketerra, Tacx Training and Wahoo SYSTM. Or map any program yourself.
- Windows, Zwift Click V2 - the pair this tool is built for.
Download the latest version from the release page.
Windows users can install with Scoop straight from this repository — it is its own bucket:
scoop bucket add zwiftboard https://github.com/thomaschampagne/zwiftboard
scoop install zwiftboard/zwiftboardThe manifest in bucket/ is regenerated by CI on every release, and
scoop update zwiftboard picks up each new release. The package is also
submitted to the community extras
bucket — once that PR is merged, scoop install extras/zwiftboard works too.
Manual downloads remain available on the Releases page.
-
Download the latest release: grab
zwiftboard.exefrom the Releases page. The config file is created on first run at%LocalAppData%\zwiftboard\config.yml. -
Close Zwift / the Companion app — each controller accepts only one BLE connection at a time.
-
Sign in when the LEFT pod needs it. The status screen (
ctrl+z) asks for your Zwift email and password so it can renew the LEFT controller's time-limited unlock (the app uses Zwift's own sign-in once; nothing is stored but a session token besideconfig.yml). PressEscto close the form — only the RIGHT controller works normally then, and the warning stays on the screen. The prompt comes back on the next launch until you sign in. -
Run it and press a button on each controller while it scans to wake them. Double mode (both pods) is the startup mode; press
ctrl+mto switch to single mode (RIGHT pod only):zwiftboard.exe # startup profile: `defaultProfile:` from the config (ships as notepad) zwiftboard.exe -p trainerroad # pick another profile zwiftboard.exe -v # debug logging (raw frames, services)time=... level=INFO msg="profile loaded" profile=notepad bindings=5 time=... level=INFO msg="key mapping" button=PLUS key=k time=... level=INFO msg=button controller=zwift/86:04 button=PLUS state=pressed key=k
If the profile sets startProgram, zwiftboard also launches that app once Bluetooth is up (see Start a program with a profile).
Press a button during a scan burst to wake a controller. Scanning never gives up: a controller switched on 10 minutes later still gets picked up.
The config lives at %LocalAppData%\zwiftboard\config.yml (or pass -config;
an explicit path must already exist). The default file is created on first run,
and a config from the old location next to the exe is migrated there. One file:
loglevel:, an optional defaultProfile:, and a profiles: map.
loglevel: info # debug | info | warn | error
defaultProfile: notepad # profile used when -p is not passed; must exist
profiles:
mywhoosh: # pick with -p mywhoosh
single: # right controller only
PLUS: i # gear down
A: right # steer right
B: k # gear up
Y: u # U-turn / minimal UI
Z: left # steer left
double: # both controllers (press m to switch)
LEFT: left # left controller: steer left
RIGHT: right # left controller: steer right
UP: up # left controller: arrow up
DOWN: down # left controller: arrow down
MIN: k # left controller: gear up
PLUS: i
A: right
B: k
Y: u
Z: left
my-zwift-setup: # add your own — any name works
focusProgramNamePrefixOnClick: ZwiftApp # per profile, beside single/double
single:
A: space
B: esc
double:
A: space
B: escKey tokens: a-z, 0-9, f1–f12, named keys
(up down left right enter space tab esc backspace delete insert home end pageup pagedown shift ctrl alt capslock), and single punctuation
- = , . / ; ' [ ] ` \ (quote punctuation that is also YAML syntax, as
above).
If the default config can't be created or read, zwiftboard still runs and logs
every press — you just don't get keystrokes. An explicit -config is the
exception: it must already exist and is a fatal error if it doesn't.
Each profile has two button maps:
single:— the right controller only (Y Z A B PLUS).double:— both controllers: the left pod'sLEFT UP RIGHT DOWN MINplus the right pod's buttons.
Press ctrl+m on the status screen to switch between them. The mode is shown in the
header (Mode: SINGLE / Mode: DOUBLE, in its own magenta chip), and the Keys Bindings panel lists only the buttons of
the active mode. The mode stays the same when you switch profile. A button that
is not in the active map is ignored, so in single mode the left pod does nothing.
In double mode the gear keys follow one rule in every program that has a gear
key: the right pod's PLUS shifts down (easier), and the left pod's MIN shifts
up (harder). Programs without a keyboard gear key use their closest effort or
resistance key, listed in config.yaml.
Both maps are required in every profile. A profile written in the old format (its
buttons directly under the profile name, with no single:/double:) still loads:
it is read as single with only its right-pod buttons, the left-pod buttons go to double, zwiftboard logs a warning, and double holds every button.
To migrate, move the buttons under single: and add a double: map. A left-pod
button under single: is an error.
By default keys go to whichever window has focus, like a real keyboard. To make every click land in the cycling app even if another window stole focus, tell zwiftboard which program to bring forward first — per profile, since each game window is different:
profiles:
mywhoosh:
focusProgramNamePrefixOnClick: MyWhoosh # window title contains "MyWhoosh" (or .exe prefix: MyWhooshHD.exe)
trainerroad:
focusProgramNamePrefixOnClick: null # disabled (default): keys → focused windowThe value matches the window title (case-insensitive contains) or the start of
the program .exe name (case-insensitive prefix) — so MyWhoosh matches
MyWhooshHD.exe. On each button press the matching window is restored (if
minimized) and brought to the foreground, then the key is tapped into it. If
no window matches, the tap is dropped and a warning logged — zwiftboard
never types into an unrelated app. Windows remembers the focused window, so
the game stays in front for the whole ride.
Launch your cycling app automatically once Bluetooth is up — per profile, so each
setup starts its own program. The startProgram value accepts:
- an
.exepath (C:\Zwift\ZwiftApp.exe); - a bare
.exename (MyWhooshHD.exe), resolved viaPATH/ App Paths; - a
.bator.cmdscript; - a
.ps1PowerShell script; - an MS Store AUMID (
PackageFamilyName!AppId), e.g.MyWhoosh.MyWhoosh_abc!App.
profiles:
mywhoosh:
startProgram: MyWhooshHD.exe
my-zwift-setup:
startProgram: MyWhoosh.MyWhoosh_abc!App # MS Store app (AUMID)null (or absent) disables it. It starts once Bluetooth is up. A missing path
logs a warning and is skipped; an already-running program is left alone.
To find a Store app's AUMID, open PowerShell and copy the AppID column of:
Get-StartApps | Sort-Object Name | Format-Table -AutoSize
# or filter: Get-StartApps | Where-Object Name -like '*whoosh*'The app must be installed for the current user.
While the status screen is running, move through the profiles without a restart or a BLE reconnect:
ctrl+left/ctrl+right— previous / next profile;ctrl+n/ctrl+p— same, for terminals that do not report modified keys.
The config file is re-read on every switch, so a profile you just edited is
picked up: the button map, focusProgramNamePrefixOnClick and startProgram
apply immediately (loglevel: still needs a restart). A held key is released
first, so nothing sticks across a switch; if the config no longer parses, the
screen shows the error and the current profile stays active. Neither the
controllers nor their connection are touched.
ctrl+left / ctrl+right need a terminal that reports keyboard-enhancement
sequences (kitty/CSI-u); the ctrl+n / ctrl+p fallbacks work everywhere.
ctrl+r— reloadconfig.yamland apply it to the current profile live (no restart, no BLE reconnect;loglevel:still needs a restart);ctrl+m— Toggle mode: switch the current profile betweensingleanddouble;ctrl+s— start the current profile'sstartProgramagain (e.g. after you closed it); hidden when the profile has nostartProgram;ctrl+l— show/hide the log panel (k/jor the mouse wheel scroll it);ctrl+e— open the config file in your editor;ctrl+c— quit.
zwiftboard [flags]
| Flag | Default | Meaning |
|---|---|---|
-p |
config defaultProfile:, else mywhoosh |
Startup profile (must exist in the config; unknown name errors with the list). Ships as notepad |
-config |
%LocalAppData%\zwiftboard\config.yml |
Config file path; must already exist when passed explicitly (default path is created on first run) |
-v |
false |
Force debug log level (raw frames, service list) |
-log |
(none) | Also write log lines to this file (truncated at startup; TUI mode defaults to zwiftboard.log) |
-plain |
false |
Plain log output on stderr instead of the TUI status screen |
-demo |
false |
TUI with mock toggle keys, no Bluetooth (try the screen anywhere) |
-version |
false |
Print version and exit |
| Profile | Click becomes… | Source |
|---|---|---|
mywhoosh |
+ gear down, B gear up, A/Z steer right/left, Y U-turn / minimal UI |
MyWhoosh shortcuts |
mywhoosh-hd |
same mapping as mywhoosh |
MyWhoosh (HD build) — focuses MyWhooshHD.exe, auto-starts the MS Store app |
trainerroad |
A space play/pause, B t mode, Y h heart-rate, Z w workout |
TrainerRoad shortcuts |
systm |
A space pause, B ` ERG, Y m mute, Z esc close settings |
SYSTM shortcuts |
zwift |
+/B FTP bias down/up, A/Z turn right/left, Y power-up |
Zwift shortcuts |
trainingpeaks |
-/= resistance down/up, A/Z turn right/left, Y graph toggle |
TrainingPeaks Virtual controls |
biketerra |
S/W gear down/up, A/Z menu right/left, Y UI toggle |
Biketerra virtual shifting |
rouvy |
,/. gear down/up, A/Z turn right/left, Y hide interface |
Rouvy remote controllers |
tacx |
+/B difficulty down/up, A/Z next/previous screen, Y pause |
Tacx keyboard shortcuts |
notepad |
+ p, A a, B b, Y y, Z z, plus the left pod's LEFT l, UP u, RIGHT r, DOWN d, MIN m |
focuses Notepad and starts it — the shipped default |
Every shipped profile has a double: map that adds the LEFT pod's arrows (LEFT UP RIGHT DOWN) and its MIN shift-up key. In single mode the profile keeps only the right pod's buttons. notepad maps all five left-pod buttons.
┌────────────────────────────┐ ┌───────────────────────────────────────────┐
│ Zwift Click V2 pair │ │ Windows PC │
│ │ │ │
│ LEFT RIGHT │ BLE │ zwiftboard.exe │
│ [arrows -] [Y Z A B +] │◄──────►│ 1. scan bursts (Zwift vendor filter) │
│ │ GATT │ 2. connect + handshake, keepalive 3s │
│ frame 0x23: │ notify │ 3. decode protobuf bitmap (0=pressed) │
│ protobuf bitmap, │ write │ 4. edge-triggered diff (pair MIRRORS │
│ 0 = pressed │ indic. │ every press on both units) │
│ │ │ 5. keys.Down/Up → focus target window, │
│ │ │ then user32 keybd_event │
└────────────────────────────┘ └───────────────────┬───────────────────────┘
│ simulated keystroke
┌─────────────────▼───────────────────────┐
│ foreground app: MyWhoosh, Zwift, │
│ Rouvy, TrainerRoad, SYSTM, ... │
└─────────────────────────────────────────┘
- Scan — endless 10s bursts (3s gap), filtered by Zwift's manufacturer ID
0x094Aor azwift*name. - Connect — WinRT GATT, with a retry loop because Windows returns a
partial service list right after connect. Characteristics are matched by
UUID across all services: Async
…0002(notify), SyncRX…0003(write), SyncTX…0004(indicate) of service00000001-19ca-4651-86e5-fa29dcdd09d1. - Handshake & keepalive — the activation trio (
RideOn 02 03,00 08 00,00 08 10), then aRideOnwrite every 3s. The keepalive is the liveness probe: a successful write proves the session is up, a failed one is the only disconnect signal — idle button silence is normal and never ends a session. After ~55s of button silence a single pod reset (0x18) reboots the pod on our schedule, and the scan-gated reconnect picks it back up within seconds; any received frame restarts the idle clock. - Decode — button frames start with
0x23; protobuf field 1 is a bitmap where 0 = pressed. Bits:LEFT 0x1 UP 0x2 RIGHT 0x4 DOWN 0x8 A 0x10 B 0x20 Y 0x40 Z 0x80 MIN 0x100 PLUS 0x1000. - Hold — a mapped key goes down on the pressed transition and
up on the released one, so holding a button holds the key (steering
in MyWhoosh needs the left/right hold). While held, the key auto-repeats
like a real keyboard (250ms delay, ~33ms interval — a synthetic press is
otherwise a single event, so letters would not repeat in text apps).
The mirroring is asymmetric: the RIGHT pod's presses arrive on both
units' streams, the LEFT pod's own presses only on the left unit's.
Dedup is edge-triggered: a handler only acts on bits that changed since
the previous frame, and an identical mirrored bitmap changes nothing. If
focusProgramNamePrefixOnClickis set, the configured window is brought to the foreground before the key goes out via Windowskeybd_event.
Both pods connected, both mappable. The Click V2 ships as two pods
that work as a pair: the LEFT pod is the pair's BLE anchor and the RIGHT pod
mirrors its state to the LEFT over a private RF link. This build connects both
pods — keeping the LEFT anchor connected is what keeps the RIGHT pod's link
alive. Single mode maps the RIGHT pod's buttons (Y Z A B PLUS);
double mode adds the LEFT pod's (LEFT UP RIGHT DOWN MIN).
Scanning never gives up, so a pod turned on minutes later still joins.
The LEFT pod's time-limited Zwift unlock. The LEFT pod's button engine only
streams while a time-limited unlock granted by Zwift's servers is valid. The pod sends
a FF 03 challenge when it connects; the game app forwards it to Zwift's
d-lock service and writes the signed reply back as ff 04 00 <reply>.
zwiftboard does the same once you are signed in — the challenge, the HTTP
request and the response are logged at debug level with credentials redacted —
so a single sign-in keeps the LEFT pod working without opening Zwift. With no
sign-in, or when the API is unreachable, the session falls back to the plain
ff 04 00 ack and the RIGHT pod is unaffected.
Each controller gets its own reconnecting session goroutine (5s backoff); connects are serialized so they never overlap an active scan.
| Symptom | Fix |
|---|---|
Right pod drops, logs session ended |
The link ended (a keepalive write failed — a real disconnect), so zwiftboard reconnects after 5s. Idle button silence never ends a session, so sitting on one virtual gear for a long time is fine — shifting still works when you press again. |
| LEFT pod stops typing after ~1 min | Its time-limited Zwift unlock expired. Press ctrl+z to sign in (the form appears when no session is stored or the stored one was rejected) (it only appears when no session is stored or the stored one was rejected); the new challenge is then answered with the signed reply. With no sign-in only the RIGHT controller works. |
| Right pod's LED keeps blinking | The pair's LEFT anchor is not connected. Switch the LEFT controller on too (both pods must be on); a lone RIGHT pod's blinking LED is cosmetic but its link drops ~65s after its last button. |
| One press holds the key down | Normal: keys follow the button — held while pressed, released on release (steering needs the hold). |
found controller name=… addr=D4:06:0F:… |
Normal — the advertisement may carry no name; address is what matters. |
| Controller not found | Press any button to wake it during the scan burst; keep it awake. |
| Keys land in the wrong window | Set focusProgramNamePrefixOnClick: to the game's window title or .exe — zwiftboard brings it to the front and taps only into it. |
| App quits / stops responding after a while | zwiftboard never exits on a runtime fault — a glitchy BLE event logs recovered from panic (a WARN with stack) and the session retry / scan loop keeps it alive. Switching Windows Bluetooth off mid-run also survives: sessions end, scanning retries every 3s, and it reconnects when Bluetooth comes back. If buttons go silent instead, check the session ended lines: that is a lost connection recovering after 5s, not a crash. |
| Nothing works with Zwift open | Close Zwift / Companion first: one BLE connection per controller. |
| LEFT pod does nothing | It is off in single mode. Press ctrl+m on the status screen to switch to DOUBLE (the header shows the mode). |
| Log warns "legacy flat format" | The profile uses the old layout (buttons directly under the profile name). It still works; move its buttons under single: and double: to silence the warning (see Controller modes). |
Not a HID keyboard: Zwift itself won't see the Click as a Bluetooth keyboard here — only the Windows foreground app receives the simulated keys.
Requires Go ≥ 1.27 (see go.mod). No BLE hardware needed to develop: tests
run on any OS, real scanning needs Windows.
Tasks run through just (required — install it
first):
| Recipe | Does |
|---|---|
just test |
unit tests (run anywhere) |
just vet |
go vet for the host and GOOS=windows |
just fmt |
gofmt -w . |
just build |
build the Windows amd64 exe (plus the icon resource) |
just sanity |
local: fmt then test vet build |
just ci |
check-only fmt-check vet test build, no source rewrites |
just run |
run from source (Windows host); go run . -v for raw frames |
just demo |
TUI with mock toggle keys, no Bluetooth |
just release VERSION |
build the release assets into dist/ (POSIX; used by CI) |
just scoop-manifest VERSION SHA256 |
render the Scoop extras manifest to stdout |
just scoop-release VERSION |
release + dist/zwiftboard.json (local end-to-end) |
just update-deps |
blanket go get -u ./... + go mod tidy (BLE libs included) |
just --list shows every recipe.
Releases are cut automatically from main by
semantic-release. A push to main runs
.github/workflows/release.yml:
checksrunsjust ci(the same check-only guards as pull requests).releaseruns semantic-release, which callsjust release <version>to builddist/zwiftboard.exe,dist/zwiftboard.zipanddist/checksums.txt.bucketruns only when semantic-release published a new release. It downloads that release'schecksums.txt, rendersbucket/zwiftboard.jsonwithjust scoop-manifest <tag> <sha256>, and commits it straight back tomain— this repo is its own scoop bucket, so no PAT or PR is needed.scoopruns only when semantic-release published a new release. It downloads that release'schecksums.txt, rendersextras/bucket/zwiftboard.jsonwithjust scoop-manifest <tag> <sha256>, and opens (or updates) a PR against ScoopInstaller/Extrasmasterfrom theSCOOP_EXTRAS_PATowner's fork. Nothing is pushed to Extras directly — a human reviews and merges the PR. The job then posts the/verifycomment the contribution guide asks for; because the PR comes from a fork, that comment (not the PR-open event) is what triggers the manifest verifier. The very first manifest is a new package, which Extras wants backed by an approved package-request issue before the initial PR.
Emulate the build + manifest steps locally before pushing (Linux/WSL; macOS
needs coreutils for sha256sum, plus zip):
just ci # the guards CI runs
just scoop-release 0.0.0-test # dist/zwiftboard.exe, .zip, checksums.txt, zwiftboard.json
cat dist/zwiftboard.json # inspect the Extras manifestjust scoop-release <version> builds the release assets and renders the
manifest from the freshly computed sha256 — the same two steps CI splits across
the release and bucket/scoop jobs, so a green local run proves the release
job will find dist/zwiftboard.exe and the scoop job will render a valid
manifest. Use a throwaway version (semantic-release assigns the real one) and
push to main only after just ci is green.
Layout — a single binary, entry point at the repo root:
main.go flags, logger setup, target registry, wiring
internal/zwift/ protocol facts: GATT UUIDs, button bits, frame decode
internal/ble/ scan (Watch), connect (Session), decode, hold + cross-session dedup
internal/keys/ config token → VK code; Down/Up/ReleaseVK (keybd_event on Windows)
internal/config/ config.yaml: loglevel + profiles (returns errors)
- Add an option to start a program (exe, script, msstore app) linked to a profile (e.g. Start MyWhoosh if exists). Update documentation.
- Convert local scripts and CI execution with just. Update documentation.
- Add just update-deps task. Update documentation.
- Profile switching with ctrl+left/right. Update documentation.
-
sshortcut to start the profile's program manually;rto reload config. Widen the status panel. Update documentation. - Double-click to single key feature? Update documentation.
