The plain build

Device	Finger module	Thumb module	Bottom module	Battery
Left cat	`left-F21`	`left-T11`	none	none
Right cat	`right-F20W`	`right-T11`	none	none
Tower	LILYGO T-Dongle-S3

Revision dev@e21e4f5 · 2026-11-01 · not a release

Flash firmware

Once your keyboard runs: flash it again for a newer firmware, other modules, another Coordinator or a new device. Its settings come after. None of it opens the case.

Flashing for the first time is part of the build: Build, flash and pair.

When to flash again

You want to	Done with	How
Take a newer LYNX	A reflash service mode	Update the firmware
Fit other modules to a cat	A reflash service mode	Update the firmware
Make another device the Coordinator	Build, flash and pair service mode	Build, flash and pair
Add, replace or pair a device again	Build, flash and pair service mode	Build, flash and pair

A reflash: The Coordinator's: SVC, or BOOT held, shows its port. A cat is no keyboard and shows its port as it is.
Build, flash and pair: Every device of the setup plugged in: the Coordinator through SVC, or BOOT held, if it already runs LYNX.

Update the firmware

draft instructions

For each cat the tower

A fresh build (the first after a container or RMK update) resets the Coordinator's Vial keymap once, at its first start: save your keymap in Vial before you update.

To take a newer LYNX, update your copy with git pull and start the setup page. Hold the Coordinator's SVC key for 2 s, then click step 4's Reflash the Coordinator: it builds and flashes the Coordinator alone, which keeps its pairing and its settings. Flash each cat the same way from the terminal, with the setup file you saved, its side and its port. Devices on different firmware may not understand each other, so update all of them together.

git pull
./lx setup ui
./lx setup flash <setup file> <left or right> <cat's port>

How you know it worked: Each cat pairs again (no LED 1 solid red), and the Coordinator types.

Something doesn't match

The cats stay unpaired after an update: the update may have changed how the devices talk: flash every device, or run step 4's Build, flash and pair, which also pairs them again.

The setup page at step 4, Build, flash and pair, with the job done: every board flashed and paired.

Change its settings

You want to	Done with	Keys	How
Change the keymap and bindings	Vial		Set up your keys in Vial
Change the mouse or scroll speed	The keyboard's Vial keys The setup page in service mode service mode	`MS+` `MS-` `SC+` `SC-`	Change the settings
Change the layer LED colours	The keyboard's Vial keys The setup page in service mode service mode	`LC>` `LC<`	Change the settings
Trim a hand's pointer direction	The keyboard's Vial keys The setup page in service mode service mode	`YL>` `YL<` `YR>` `YR<`	Change the settings
Change a gyro's mode or speed	The setup page in service mode service mode		Change the settings
Get the keyboard back after holding SVC	no tool		Leave service mode without changing anything

Change the settings

draft instructions

For each cat the tower

In service mode the Coordinator is no keyboard. Without a Read or a Save it restarts by itself after 2 minutes; after a Read it waits until you Save.

The speeds, directions and LED colours can change any time, without a rebuild and without opening the case. On the keyboard, the Vial keys (MS±, SC±, LC>/LC<, YL/YR) change them directly; a gyro's mode and speed only the setup page changes. On the setup page: hold the Coordinator's SVC key for 2 s; every cat blinks blue and the page shows the Coordinator's port. Click Read from the Coordinator: step 2 then shows what it stores, and it waits for you. Change what you want, then click Save: only what you changed is written, and the Coordinator restarts as your keyboard.

./lx setup ui

How you know it worked: After the save, the Coordinator types again and the LEDs show the new layer colours.

Why this matters

Service mode hands the Coordinator's USB port from the keyboard back to the computer, so no BOOT button is needed inside a closed case.

Something doesn't match

Nothing happens when you press SVC: hold it for the full 2 s; a tap does nothing, so a stray press does not drop the keyboard. On LYNXgram, hold the layer-1 key first, then SVC.

You entered service mode but want to change nothing: see the next step, Leave service mode.

The page shows no port after holding SVC: your keymap has no SVC key yet (one stored before it existed): bind it in Vial once. Or plug the Coordinator in with BOOT held instead.

The Coordinator does not come back as a keyboard after the save: press its reset button (RST), or unplug it and plug it in again.

The save says the Coordinator runs older firmware: it would not read what the page writes, and would lose its radio channel and trims. Reflash it first (see Update the firmware), let it start once as your keyboard, then hold SVC and save again.

The setup page at step 2, Sensors and LEDs, after Read from the Coordinator: the settings the tower stores.

Leave service mode without changing anything

draft instructions

For each cat the tower

Held for 2 s, SVC stops the keyboard: every cat blinks blue and the Coordinator waits for the setup page. To get your keyboard back without changing anything, do one of these:

wait 2 minutes: the Coordinator restarts as your keyboard by itself;
on the setup page, click Restart the Coordinator: nothing to save in step 2;
unplug the Coordinator and plug it in again (a cat with a battery: press its reset button, RST).

After Read from the Coordinator it no longer restarts by itself: it waits in its bootloader until you Save, Restart or replug it.

How you know it worked: The Coordinator types again, and no cat blinks blue.

Why this matters

Anyone who holds `SVC` by mistake loses the keyboard until the Coordinator restarts; nothing is lost, and settings changed on the keyboard before were saved as service mode began.

Something doesn't match

Pressing SVC again does nothing: in service mode the keyboard is stopped, so no key works. Use one of the three ways above.

It does not come back after 2 minutes: the page read it, so it waits for a save. Click Restart the Coordinator: nothing to save, or unplug it and plug it in again.