Slots & Variants

The LYNXcat uses a slot-based modular architecture. Each keyboard half has 3 physical slots. Each slot supports multiple hardware variants selected at compile time via Cargo feature flags.

Slot Architecture

Slot	Position	Always Present	Interface
Finger (0)	Top	Yes	13-pin GPIO matrix + encoder
Thumb (1)	Middle	Yes	12-pin GPIO + ADC + LED
Bottom (2)	Bottom	No (one half only)	6-pin SPI or 4-pin I2C

Key Terms:

Slot = Physical position + electrical interface
Variant = Specific hardware configuration for that slot
Module Variation = Interchangeable hardware for the same slot

Slot Variants

Finger Slot (0)

Variant	Feature Flag	Hardware	Description
Keys	`fk`	4×6 key matrix	Keys only
KeysWheel	`fkw`	4×6 matrix + rotary encoder	Keys + scroll wheel

Interface: 13-pin GPIO (4 rows × 6 cols + encoder pins)

Thumb Slot (1)

Variant	Feature Flag	Hardware	Description
Keys	`tk`	4×3 key matrix	Keys only
KeysJoystick	`tkj`	4×3 matrix + analog joystick + LED	Keys + joystick

Interface: 12-pin GPIO (4 rows × 3 cols) + 2 ADC (joystick X/Y) + 1 GPIO (LED)

Bottom Slot (2)

Variant	Feature Flag	Hardware	Description
None	`bn`	Empty	No hardware
Mouse-ADNS5050	`bm-adns5050`	ADNS-5050 optical sensor	Budget mouse sensor (implemented)
Mouse-PMW3360	`bm-pmw3360`	PMW3360 optical sensor	Mid-range sensor (placeholder)
Mouse-ADNS9800	`bm-adns9800`	ADNS-9800 laser sensor	High-end sensor (placeholder)
Gyro	`bg`	MPU-6050	6-axis gyroscope (placeholder)

Interface: 6-pin SPI (mouse sensors) or 4-pin I2C (gyro) — polymorphic based on variant

Feature Flag System

Side Selection

Flag	Full	Side
`l`	`left`	Left keyboard half
`r`	`right`	Right keyboard half

Build Command Format

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

The <port_num> is a number, not a full path. The script resolves it per platform.

Examples:

# Left half: keys + wheel, keys + joystick, gyro
./f cat-l fkw tkj bg 0

# Right half: keys only, keys only, mouse sensor (ADNS5050)
./f cat-r fk tk bm-adns5050 1

# Left half: keys + wheel, keys only, no bottom module
./f cat-l fkw tk bn 2

Platform-Specific Port Resolution

Platform	Port Num	Resolves To
Linux	`0`	`/dev/ttyACM0`
Linux	`2`	`/dev/ttyACM2` (or `/dev/ttyUSB2`)
macOS	`0`	First `/dev/cu.usbmodem*` device
macOS	`1`	Second `/dev/cu.usbmodem*` device
Windows	-	Use WSL with Linux port resolution

Tip: Run ./f without arguments to see available ports on your system.

Feature Flag Resolution

The ./f script translates slot arguments to Cargo features:

./f cat-l fkw tkj bg 0

Becomes (on Linux):

cargo build -p cat --release --no-default-features --features l,fkw,tkj,bg
espflash flash --port /dev/ttyACM0 --chip esp32s3 ...

Compile-Time Configuration

All slot variants are configured at compile time. No runtime detection. This ensures:

Zero runtime overhead
Dead code elimination for unused variants
Type-safe hardware access
Explicit build-per-configuration

Consequence: Changing hardware requires reflashing with different feature flags.

Matrix Scanning Convention

Matrix dimensions follow software scanning convention:

Rows = Inputs (scanned sequentially)
Cols = Outputs (driven high/low)

Slot	Rows	Cols	Total Pins
Finger	4	6	10 (+ 3 encoder)
Thumb	4	3	7 (+ 2 ADC + 1 LED)

Slot-to-Action Mapping

Each slot generates specific InputAction types:

Slot	Variants	InputActions
Finger	fk	KeyPress, KeyRelease
Finger	fkw	KeyPress, KeyRelease, ScrollIncrement
Thumb	tk	KeyPress, KeyRelease
Thumb	tkj	KeyPress, KeyRelease, JoystickPosition
Bottom	bm-*	MouseMotion
Bottom	bg	GyroscopeMotion
Bottom	bn	(none)

Input Actions: /home/ad/dev/lynx-v4/docs/architecture/input-actions.md
LYNXcat Firmware: /home/ad/dev/lynx-v4/docs/firmware/cat.md
Hardware Modules: /home/ad/dev/lynx-v4/hardware/docs/modules/
Pin Connections: /home/ad/dev/lynx-v4/hardware/docs/pins-connections.md