qmk_userspace/qmk_flash_tools/QUICK_REFERENCE.md

QMK Flash Tools - Quick Reference

🚀 Common Commands

Flash Both Keyboard Sides

cd qmk_flash_tools
./autoflash_modular.sh

Test Individual Components

# Test side mapping (no hardware needed)
./test/test_side_mapping.sh

# Test device detection (needs keyboard in bootloader)
./test/test_device_detection.sh

# Test QMK functions
./test/test_qmk_helpers.sh

# Run all tests
./test/run_all_tests.sh

View Saved Mappings

cd qmk_flash_tools
cat device_mappings.json
# or
jq '.' device_mappings.json

Reset Mappings

# Reset all
cd qmk_flash_tools
rm device_mappings.json

# Or use the library
source lib/side_mapping.sh
clear_all_mappings

🔍 Debug Commands

Check Device Info

source lib/device_detection.sh
mount_point="/media/$USER/RPI-RP2"  # Adjust path
print_device_info "$mount_point"

Manually Test Detection

source lib/device_detection.sh
source lib/side_mapping.sh

# Wait for device
mount_point=$(wait_for_rp2040)

# Get identifier
device_id=$(get_device_identifier "$mount_point")
echo "Device ID: $device_id"

# Detect side
side=$(detect_side "$device_id")
echo "Side: $side"

Test QMK Commands

# Check QMK version
qmk --version

# List keymaps
qmk list-keymaps -kb fingerpunch/sweeeeep

# Compile only (no flash)
qmk compile -kb fingerpunch/sweeeeep -km smathev

# Flash with specific bootloader
qmk flash -kb fingerpunch/sweeeeep -km smathev -bl uf2-split-left

🛠️ Manual Side Mapping

Add Mapping Manually

source lib/side_mapping.sh
save_side_mapping "serial:ABC123XYZ" "left"
save_side_mapping "serial:DEF456RST" "right"

Check Specific Device

source lib/side_mapping.sh
side=$(get_saved_side "serial:ABC123XYZ")
echo "Device is: $side"

List All Mappings

source lib/side_mapping.sh
list_all_mappings

📝 Environment Variables

# Keyboard configuration
export KEYBOARD="fingerpunch/sweeeeep"
export KEYMAP="smathev"

# Device detection
export USB_MOUNT_PATHS=("/media/$USER" "/run/media/$USER" "/mnt")
export RP2040_PATTERN="*RP2040*"
export USB_WAIT_INTERVAL=0.5

# Side mapping file (relative to qmk_flash_tools/)
export SIDE_MAPPING_FILE="./device_mappings.json"

🐛 Troubleshooting One-Liners

# Check if RP2040 is mounted
ls /media/$USER/ | grep -i rp2040

# Find all USB devices
lsusb

# Check USB device info
udevadm info --query=property /dev/sdb1  # Adjust device

# Monitor USB events (run in separate terminal)
udevadm monitor

# Check QMK firmware location
qmk config user.qmk_home

# Force clean and rebuild
qmk clean && qmk compile -kb fingerpunch/sweeeeep -km smathev

# Check if jq is installed
jq --version

📂 File Locations

Main script:        qmk_flash_tools/autoflash_modular.sh
Libraries:          qmk_flash_tools/lib/*.sh
Tests:              qmk_flash_tools/test/*.sh
Mapping file:       qmk_flash_tools/device_mappings.json
QMK firmware:       ~/qmk_firmware/ (or user.qmk_home)
Build output:       ~/qmk_firmware/.build/

🔧 Common Fixes

Device not appearing

# Check dmesg for USB events
dmesg | tail -n 20

# Try different USB port
# Try different USB cable (must be data cable, not charge-only)

Wrong side detected

# Clear and re-learn
source lib/side_mapping.sh
clear_mapping "serial:YOUR_DEVICE_ID"
# Then run autoflash again

Build fails

# Update QMK
python3 -m pip install --upgrade qmk

# Pull latest QMK firmware
cd ~/qmk_firmware
git pull

# Clean and try again
qmk clean

Permission denied

# Make scripts executable
chmod +x qmk_flash_tools/*.sh
chmod +x qmk_flash_tools/lib/*.sh
chmod +x qmk_flash_tools/test/*.sh

📚 Function Quick Reference

device_detection.sh

• wait_for_rp2040() - Wait for device
• get_usb_serial_from_host(mount) - Get serial
• get_usb_device_path(mount) - Get USB path
• get_device_identifier(mount) - Get ID
• print_device_info(mount) - Debug info

side_mapping.sh

• init_mapping_file() - Create file
• save_side_mapping(id, side) - Save
• get_saved_side(id) - Retrieve
• detect_side(id) - Auto-detect/prompt
• list_all_mappings() - Show all
• clear_mapping(id) - Remove one
• clear_all_mappings() - Reset

qmk_helpers.sh

• build_firmware(kb, km) - Compile
• flash_side(kb, km, side) - Flash with handedness
• check_qmk_installed() - Verify QMK
• verify_keyboard_exists(kb) - Check KB
• clean_build() - Clean