qmk_userspace/qmk_flash_tools/SOLUTION_SUMMARY.md

Solution Summary: Ask BEFORE Bootloader

The Problem You Identified 🎯

"Once I enter the bootloader I can't use the device - so I need to input the device-side beforehand."

Absolutely correct! This is a critical UX issue that the original design missed.

The Solution ✅

New Workflow Order:

1. ASK which side (while keyboard still works!)
2. WAIT for bootloader (user enters bootloader mode)
3. DETECT device (get USB serial from host)
4. VERIFY match (does device match expected side?)
5. FLASH (with correct handedness)

Code Changes Made:

1. New Function: detect_side_with_expected()

Location: lib/side_mapping.sh

detect_side_with_expected(device_id, expected_side)

This function:

• Takes the expected side (what user said)
• Checks if device is in mappings
• First time: Saves device as expected side ✅
• Matches: Continues automatically ✅
• Mismatch: Gives user options ⚠️

2. Mismatch Handling

When device doesn't match expected:

⚠️  WARNING: SIDE MISMATCH DETECTED

Expected: left side
Saved mapping says: right side

What would you like to do?
  [e] Exit safely (recommended)
  [c] Clear this mapping and save as left
  [f] Force flash as left anyway (DANGEROUS)

3. Updated Main Script

Location: autoflash_modular.sh

New function:

flash_side_with_verification(expected_side)

Changes to workflow:

# OLD: Asked AFTER device detected
flash_side_auto()  # User can't type in bootloader!

# NEW: Ask BEFORE device connected
read -p "Which side will you flash first? [left/right]:"
flash_side_with_verification("left")  # ✅ Can type!

Complete Flow Example 📋

First Run:

$ ./autoflash_modular.sh

Which side will you flash first? [left/right]: left  ← Can type!

Please enter bootloader on the left half:
Press Enter when ready...
[User enters bootloader, presses Enter]

Waiting for device...
Found device: serial:ABC123
New device detected (first time setup)
✅ Saving as left side

Flashing: left side
✅ left side flashed successfully!

Flash the right side now? [y/n]: y

Please enter bootloader on the right half:
Press Enter when ready...
[User enters bootloader, presses Enter]

Waiting for device...
Found device: serial:XYZ789
New device detected (first time setup)
✅ Saving as right side

Flashing: right side
✅ right side flashed successfully!

🎉 Flashing complete!

Subsequent Runs (Auto-verified):

$ ./autoflash_modular.sh

Which side will you flash first? [left/right]: left

Please enter bootloader on the left half:
[User enters bootloader]

Found device: serial:ABC123
✅ Confirmed: This is the left side (matches saved mapping)

Flashing: left side
✅ Done!

Mismatch Scenario:

Which side will you flash first? [left/right]: left

[User accidentally plugs in RIGHT keyboard]

Found device: serial:XYZ789
⚠️  WARNING: SIDE MISMATCH DETECTED

Expected: left side
Saved mapping says: right side

Your choice [e/c/f]: e

❌ Exiting safely. Please plug in the correct keyboard half.

Why This Works 🎯

✅ User can type - Asked before bootloader
✅ Safety first - Verifies device matches
✅ Clear errors - Obvious when wrong side plugged in
✅ Flexible - Can update mappings if needed
✅ Persistent - Remembers devices forever

Files Modified

• lib/side_mapping.sh - Added detect_side_with_expected()
• autoflash_modular.sh - Changed to ask first, then verify
• README.md - Updated workflow documentation
• WORKFLOW.md - New visual flow diagrams

Testing

Test the new flow:

# Test mismatch handling
./test/test_side_mapping.sh

# Test full workflow (needs hardware)
./autoflash_modular.sh

Your insight was absolutely correct - asking before bootloader is the only way to make this work! 🎉