# QMK Flash Tools - Modular Edition

Automated flashing tools for QMK split keyboards with RP2040 controllers (like Liatris).

## 📁 Structure

```
qmk_flash_tools/
├── autoflash_modular.sh       # Main flashing script
├── lib/                        # Reusable library modules
│   ├── device_detection.sh     # USB device detection functions
│   ├── side_mapping.sh         # Device-to-side mapping storage
│   └── qmk_helpers.sh          # QMK build/flash wrappers
├── test/                       # Standalone test scripts
│   ├── test_device_detection.sh
│   ├── test_side_mapping.sh
│   └── test_qmk_helpers.sh
└── README.md                   # This file
```

## 🚀 Quick Start

### 1. Flash Both Sides

```bash
cd qmk_flash_tools
chmod +x autoflash_modular.sh
./autoflash_modular.sh
```

The script will:
1. Build firmware once
2. **First time only:** Ask which side you'll flash (left/right)
3. **Subsequent runs:** Auto-detect which side is plugged in
4. Wait for you to enter bootloader
5. Verify and flash with correct handedness
6. Repeat for the other side

### 2. Test Individual Components

```bash
# Test device detection
cd test
chmod +x test_device_detection.sh
./test_device_detection.sh

# Test side mapping
chmod +x test_side_mapping.sh
./test_side_mapping.sh

# Test QMK helpers
chmod +x test_qmk_helpers.sh
./test_qmk_helpers.sh
```

## 🔧 Configuration

Edit the top of `autoflash_modular.sh`:

```bash
KEYBOARD="fingerpunch/sweeeeep"  # Your keyboard
KEYMAP="smathev"                 # Your keymap
USB_MOUNT_PATHS=(...)            # Where USB drives mount
SIDE_MAPPING_FILE="..."          # Device mappings (defaults to ./device_mappings.json)
```

## 📚 Library Documentation

### device_detection.sh

Functions for detecting RP2040 devices via host USB information.

**Key Functions:**
- `wait_for_rp2040()` - Wait for device to enter bootloader
- `get_usb_serial_from_host(mount_point)` - Get USB serial from host
- `get_usb_device_path(mount_point)` - Get USB port location
- `get_device_identifier(mount_point)` - Get best available ID
- `print_device_info(mount_point)` - Debug info

**Example:**
```bash
source lib/device_detection.sh
mount_point=$(wait_for_rp2040)
device_id=$(get_device_identifier "$mount_point")
echo "Device: $device_id"
```

### side_mapping.sh

Functions for storing and retrieving which device is left/right.

**Key Functions:**
- `init_mapping_file()` - Create mapping file if needed
- `save_side_mapping(device_id, side)` - Save mapping
- `get_saved_side(device_id)` - Retrieve saved side
- `detect_side(device_id)` - Get side (prompts if unknown)
- `list_all_mappings()` - Show all saved mappings
- `clear_mapping(device_id)` - Remove a mapping
- `clear_all_mappings()` - Reset all mappings

**Example:**
```bash
source lib/side_mapping.sh
export SIDE_MAPPING_FILE="./device_mappings.json"

save_side_mapping "serial:ABC123" "left"
side=$(get_saved_side "serial:ABC123")
echo "Side: $side"
```

### qmk_helpers.sh

Wrapper functions for QMK CLI commands.

**Key Functions:**
- `check_qmk_installed()` - Verify QMK is available
- `build_firmware(keyboard, keymap)` - Compile firmware
- `flash_side(keyboard, keymap, side)` - Flash with handedness
- `flash_with_bootloader(keyboard, keymap, bootloader)` - Flash with specific bootloader
- `verify_keyboard_exists(keyboard)` - Check keyboard definition
- `clean_build()` - Clean build artifacts

**Example:**
```bash
source lib/qmk_helpers.sh

check_qmk_installed || exit 1
build_firmware "fingerpunch/sweeeeep" "smathev"
flash_side "fingerpunch/sweeeeep" "smathev" "left"
```

## 🧪 Testing Workflow

### Test Device Detection

1. **Without device:**
```bash
./test/test_device_detection.sh
# Shows "no device found", good for baseline
```

2. **With device:**
```bash
# Enter bootloader mode on keyboard
./test/test_device_detection.sh
# Shows USB serial, path, and identifier
```

### Test Side Mapping

```bash
./test/test_side_mapping.sh
# Runs comprehensive tests:
# - Create mapping file
# - Save/retrieve mappings
# - Clear mappings
# - Interactive prompt (optional)
```

### Test QMK Helpers

```bash
./test/test_qmk_helpers.sh
# Tests:
# - QMK installation check
# - Keyboard verification
# - Build (optional)
# - Function signatures
```

## 🐛 Troubleshooting

### Device not detected

```bash
# Check if device appears
ls /media/$USER/
# Should see RPI-RP2 or similar

# Run device detection test
./test/test_device_detection.sh
```

### Can't identify device

The script uses these methods in order:
1. USB serial number (most reliable)
2. USB physical port path
3. Mount point name (fallback)

Check which method worked:
```bash
source lib/device_detection.sh
mount_point="/media/$USER/RPI-RP2"
print_device_info "$mount_point"
```

### Side mismatch detected

If you see a mismatch warning:

**Option 1: Exit and plug in correct side (safest)**
- Choose `[e]` to exit
- Unplug the keyboard
- Plug in the correct side
- Run the script again

**Option 2: Update the mapping**
- Choose `[c]` to clear old mapping and save new one
- Use this if you know the old mapping was wrong

**Option 3: Force flash (dangerous!)**
- Choose `[f]` to flash anyway
- Only use if you're absolutely certain
- May result in swapped left/right behavior

Or manually reset mappings:
```bash
source lib/side_mapping.sh
clear_mapping "serial:ABC123"  # Use your device ID
```

Or reset all mappings:
```bash
cd qmk_flash_tools
rm device_mappings.json
```

### Build fails

```bash
# Test QMK directly
qmk compile -kb fingerpunch/sweeeeep -km smathev

# Check keyboard exists
qmk list-keymaps -kb fingerpunch/sweeeeep
```

## 💡 Advanced Usage

### Use in other scripts

```bash
#!/usr/bin/env bash
source /path/to/qmk_flash_tools/lib/device_detection.sh
source /path/to/qmk_flash_tools/lib/side_mapping.sh

# Your custom logic here
mount_point=$(wait_for_rp2040)
device_id=$(get_device_identifier "$mount_point")
side=$(detect_side "$device_id")
echo "Detected $side side"
```

### Custom keyboard configuration

```bash
# Set environment variables before running
export KEYBOARD="your/keyboard"
export KEYMAP="your_keymap"
./autoflash_modular.sh
```

### Different mapping file

```bash
export SIDE_MAPPING_FILE="/tmp/my_test_mappings.json"
./autoflash_modular.sh
```

## 📋 Requirements

- **bash** - Shell interpreter
- **qmk** - QMK CLI (`python3 -m pip install qmk`)
- **jq** - JSON processor (`sudo apt-get install jq`)
- **findmnt** - Usually included with util-linux
- **udevadm** - Usually included with systemd

## 🔒 File Permissions

Make scripts executable:
```bash
chmod +x autoflash_modular.sh
chmod +x test/*.sh
chmod +x lib/*.sh
```

## 📝 How Device Mapping Works

The script intelligently handles three states:

### 🟢 Empty Mapping (First Time)
- **No devices mapped yet**
- **Asks:** "Which side will you flash first?"
- Script learns both sides as you flash them
- First device = saved as what you specify (left/right)
- Second device = saved as the other side
- Result: Complete mapping of both sides

### 🟡 Partial Mapping (One Side Known)
- **One device mapped, one unknown**
- **Auto-detects:** No asking needed!
- If you plug in the known device → "Detected: left side"
- If you plug in unknown device → "Detected: right side (inferred)"
- Result: Completes mapping automatically

### 🔴 Complete Mapping (Both Sides Known)
- **Both devices are mapped**
- **Auto-detects:** Fully automatic!
- Plug in any side → "Detected: left side" or "Detected: right side"
- Only the two known devices are allowed
- Unknown device → **Rejected immediately** (safety feature)
- Result: Fast, automatic flashing with full protection

### Why This Matters
- **First run**: Asks which side (one-time setup) ✅
- **Normal use**: Fully automatic - just plug and flash! ✅
- **Protection**: Unknown devices rejected - can't flash wrong keyboard ✅
- **Smart**: Knows when to ask vs. when to auto-detect 🧠

## 📝 Additional Notes

- **Input timing**: You're asked which side BEFORE entering bootloader (so you can still type!)
- **EEPROM wipe**: Liatris overwrites EEPROM on flash, so we use HOST USB info
- **Board-ID**: INFO_UF2.TXT is NOT unique per device, don't rely on it
- **USB serial**: Burned into RP2040 chip, persists even when EEPROM wiped

## 🆘 Support

Issues? Check:
1. Run test scripts to isolate the problem
2. Check device detection with `print_device_info()`
3. Verify mappings with `list_all_mappings()`
4. Test QMK commands directly: `qmk compile -kb ... -km ...`

## 📄 License

Same as your QMK userspace configuration.