qmk_userspace/FLASH_HANDEDNESS.md

Flashing Split Keyboard Handedness (EE_HANDS)

Your fingerpunch/sweeeeep keyboard with Liatris controllers uses EE_HANDS for split keyboard handedness detection. This means each half needs to be flashed with its handedness information stored in EEPROM.

Note: The Liatris is an RP2040-based Pro Micro replacement controller. It uses .uf2 files and bootloader mode for flashing.

Visual Guide

┌─────────────────────────────────────────────────────────┐
│  STEP 1: Build handedness firmware files                │
│  $ ./build_handedness.sh                                │
│    → Creates _LEFT.uf2 and _RIGHT.uf2                   │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│  STEP 2: Flash LEFT half                                │
│  1. Unplug both halves                                  │
│  2. Plug in LEFT half                                   │
│  3. Double-tap RESET button on Liatris                  │
│  4. Drag _LEFT.uf2 to RPI-RP2 drive                     │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│  STEP 3: Flash RIGHT half                               │
│  1. Unplug both halves                                  │
│  2. Plug in RIGHT half                                  │
│  3. Double-tap RESET button on Liatris                  │
│  4. Drag _RIGHT.uf2 to RPI-RP2 drive                    │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│  STEP 4: Test                                           │
│  • Test each half independently (plug in solo)          │
│  • Both halves should work when connected               │
│  • If one acts wrong, re-flash that specific half       │
└─────────────────────────────────────────────────────────┘

Quick Reference

Build Commands

# Build LEFT hand firmware with EEPROM handedness
qmk compile -kb fingerpunch/sweeeeep -km smathev -e INIT_EE_HANDS_LEFT=yes

# Build RIGHT hand firmware with EEPROM handedness  
qmk compile -kb fingerpunch/sweeeeep -km smathev -e INIT_EE_HANDS_RIGHT=yes

Generated Files

After building, you'll have:

• fingerpunch_sweeeeep_smathev.uf2 - The most recent build (left OR right)
• Copy this immediately after building to preserve it!

Recommended Workflow

cd /home/smathev/git_dev/keyboards/qmk_userspace

# Build and save LEFT hand
qmk compile -kb fingerpunch/sweeeeep -km smathev -e INIT_EE_HANDS_LEFT=yes
cp fingerpunch_sweeeeep_smathev.uf2 fingerpunch_sweeeeep_smathev_LEFT.uf2

# Build and save RIGHT hand
qmk compile -kb fingerpunch/sweeeeep -km smathev -e INIT_EE_HANDS_RIGHT=yes
cp fingerpunch_sweeeeep_smathev.uf2 fingerpunch_sweeeeep_smathev_RIGHT.uf2

# Now you have both files ready to flash
ls -lh fingerpunch_sweeeeep_smathev_*.uf2

Flashing Instructions

For Liatris Controllers (RP2040-based):

The Liatris has a RESET button (small button on the controller). To enter bootloader mode:

Method 1: Double-tap Reset (Recommended)

1. Left Half:

   • Unplug both halves
   • Plug in LEFT half
   • Quickly double-tap the RESET button on the Liatris controller
   • The controller will appear as a USB drive named RPI-RP2
   • Copy/drag fingerpunch_sweeeeep_smathev_LEFT.uf2 to the RPI-RP2 drive
   • The board will reboot automatically and disappear

2. Right Half:

   • Unplug both halves
   • Plug in RIGHT half
   • Quickly double-tap the RESET button on the Liatris controller
   • The controller will appear as a USB drive named RPI-RP2
   • Copy/drag fingerpunch_sweeeeep_smathev_RIGHT.uf2 to the RPI-RP2 drive
   • The board will reboot automatically and disappear

Method 2: Hold Boot + Plug In

1. If double-tap doesn't work, you can hold the BOOT button while plugging in the USB cable
2. The Liatris has a small BOOT button - check the controller PCB for its location

💡 Tip: If the RPI-RP2 drive doesn't appear, try:

• Double-tapping faster or slower
• Using a different USB cable/port
• Checking that the Liatris is properly seated in the sockets

3. Test:
   • Plug in ONLY the left half → keyboard should work
   • Plug in ONLY the right half → keyboard should work
   • If either half doesn't work solo, re-flash that half

After Initial Handedness Setup

Once each half has been flashed with its handedness, you can flash regular firmware to BOTH halves:

# Normal build (no handedness parameter)
qmk compile -kb fingerpunch/sweeeeep -km smathev

# Flash this to BOTH halves - handedness is preserved in EEPROM

The handedness information persists in EEPROM through normal firmware updates!

Troubleshooting

"Wrong half detected"

• Re-flash the problematic half with the handedness firmware
• Make sure you're copying the correct file (LEFT vs RIGHT)
• Verify you're flashing the correct physical half

"Both halves act as the same side"

• You need to flash different files to each half
• *_LEFT.uf2 → left physical half (usually has the TRRS jack on the left side)
• *_RIGHT.uf2 → right physical half (usually has the TRRS jack on the right side)

"RPI-RP2 drive doesn't appear"

• Liatris-specific: Try double-tapping the RESET button faster or slower
• The timing can be finicky - practice a few times
• Make sure you're using a data USB cable (not charge-only)
• Try a different USB port
• Check that the Liatris is properly installed in the Pro Micro sockets

"Keyboard not detected as USB device"

• Check USB cable (must be a data cable, not charge-only)
• Try a different USB port
• Verify the Liatris is correctly inserted (orientation matters!)
• Check for bent pins on the Liatris controller

"Compile fails with 'converter not found'"

• Your keymap should have "converter": "liatris" in keymap.json
• This tells QMK to build for the Liatris controller

File Naming Convention

To avoid confusion, use this naming:

• *_LEFT.uf2 - For the left physical half
• *_RIGHT.uf2 - For the right physical half
• *.uf2 (no suffix) - Regular firmware (both halves)

Build Script

Created: build_handedness.sh for easier building