Flashing Guide

Quick reference for flashing LYNXcat and LYNXtower firmware.

Quick Start

# Flash tower (production)
./f tower 2

# Flash left cat (default: basic keys)
./f cat-l fk tk bn 2

# Flash right cat
./f cat-r fk tk bn 3

Cat Configuration

LYNXcat firmware requires specifying side and module configuration:

./f cat-{l|r} <finger> <thumb> <bottom> <port>

Command Structure

./f  cat-l   fk      tk      bn      2
│    │       │       │       │       │
│    │       │       │       │       └─ Port number (/dev/ttyACM2)
│    │       │       │       └───────── Bottom: bn/bm/bm-*/bg
│    │       │       └───────────────── Thumb: tk/tkj
│    │       └───────────────────────── Finger: fk/fkw
│    └───────────────────────────────── Target: cat-l or cat-r
└────────────────────────────────────── Flash script

Options

Argument	Option	Description
Target	`cat-l`, `cat-r`	Left or right keyboard half
Finger	`fk`	4x6 key matrix only
	`fkw`	4x6 key matrix + scroll wheel
Thumb	`tk`	4x3 key matrix only
	`tkj`	4x3 key matrix + joystick
Bottom	`bn`	No bottom module
	`bm`	Mouse sensor (alias for bm-adns5050)
	`bm-adns5050`	ADNS-5050 optical sensor (500kHz bit-bang SPI)
	`bm-pmw3360`	PMW-3360 gaming sensor (placeholder)
	`bm-adns9800`	ADNS-9800 laser sensor (placeholder)
	`bg`	Gyro (MPU-6050)

Examples

# MVP setup (both halves, keys only)
./f cat-l fk tk bn 2
./f cat-r fk tk bn 3

# Right with scroll wheel + mouse sensor (default ADNS-5050)
./f cat-r fkw tk bm 3

# Right with explicit mouse sensor variant
./f cat-r fkw tk bm-adns5050 3
./f cat-r fkw tk bm-pmw3360 3   # (placeholder)
./f cat-r fkw tk bm-adns9800 3  # (placeholder)

# Left with joystick + gyro
./f cat-l fk tkj bg 2

# Full featured right half
./f cat-r fkw tkj bm 3

Tower Modes

./f tower 2        # Production: RMK + USB HID (default, board selection only)
./f tower-test 2   # Test mode: ESP-NOW + logging (adds test feature)

Direct Cargo Commands

Build without flashing (inside container):

# Cat builds
cargo build -p cat --release --features "l,fk,tk,bn"
cargo build -p cat --release --features "r,fkw,tk,bm-adns5050"

# Tower builds
cargo build -p tower --release                        # Production (BPI-Leaf)
cargo build -p tower --release --features test        # Test mode (BPI-Leaf)

Port Detection

Find connected boards:

ls /dev/ttyACM*

The ./f script accepts port number only (e.g., 2 for /dev/ttyACM2).

Verify Correct Firmware

After flashing, connect to serial monitor to verify config:

# Monitor serial output (Ctrl+C to exit)
espmonitor /dev/ttyACM2

Look for startup banner with config:

✋ LYNXcat firmware starting...
🐱 Config: side=left, finger=fk, thumb=tk, bottom=bn

If config doesn't match expectation, reflash with correct features.

Troubleshooting

Issue	Solution
`Permission denied`	Run on host: `sudo usermod -aG dialout $USER`, re-login
Device not in container	Add `--device=/dev/ttyACMX` to podman command
Wrong config flashed	Check serial output, reflash with correct features
`compile_error! "Must specify side"`	Use `cat-l` or `cat-r` (not just `cat`)
`compile_error! "Cannot specify both"`	Remove conflicting features (e.g., don't use `l,r`)
Multiple mouse sensors specified	Use only one: `bm`, `bm-adns5050`, `bm-pmw3360`, or `bm-adns9800`
Forgot which cat is which port	Unplug one, check which `/dev/ttyACM*` disappears

Configuration Matrix

Valid combinations: 2 sides × 2 finger × 2 thumb × 5 bottom = 40 configs

Bottom options: bn (none), bm/bm-adns5050, bm-pmw3360, bm-adns9800, bg (gyro)

Common setups:

Setup	Left	Right
MVP	`cat-l fk tk bn`	`cat-r fk tk bn`
Standard	`cat-l fk tkj bg`	`cat-r fkw tk bm`
Full	`cat-l fkw tkj bg`	`cat-r fkw tkj bm-adns5050`