223 lines
4.6 KiB
Markdown
223 lines
4.6 KiB
Markdown
# QMK Flash Tools - Quick Reference
|
|
|
|
## 🚀 Common Commands
|
|
|
|
### Flash Both Keyboard Sides
|
|
```bash
|
|
cd qmk_flash_tools
|
|
./autoflash_modular.sh
|
|
```
|
|
|
|
### Test Individual Components
|
|
```bash
|
|
# 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
|
|
```bash
|
|
cd qmk_flash_tools
|
|
cat device_mappings.json
|
|
# or
|
|
jq '.' device_mappings.json
|
|
```
|
|
|
|
### Reset Mappings
|
|
```bash
|
|
# 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
|
|
```bash
|
|
source lib/device_detection.sh
|
|
mount_point="/media/$USER/RPI-RP2" # Adjust path
|
|
print_device_info "$mount_point"
|
|
```
|
|
|
|
### Manually Test Detection
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
source lib/side_mapping.sh
|
|
save_side_mapping "serial:ABC123XYZ" "left"
|
|
save_side_mapping "serial:DEF456RST" "right"
|
|
```
|
|
|
|
### Check Specific Device
|
|
```bash
|
|
source lib/side_mapping.sh
|
|
side=$(get_saved_side "serial:ABC123XYZ")
|
|
echo "Device is: $side"
|
|
```
|
|
|
|
### List All Mappings
|
|
```bash
|
|
source lib/side_mapping.sh
|
|
list_all_mappings
|
|
```
|
|
|
|
## 📝 Environment Variables
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Clear and re-learn
|
|
source lib/side_mapping.sh
|
|
clear_mapping "serial:YOUR_DEVICE_ID"
|
|
# Then run autoflash again
|
|
```
|
|
|
|
### Build fails
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|