63991df09d
- Created CONFIG_HIERARCHY.md to explain configuration file hierarchy and settings placement. - Added FLASH_HANDEDNESS.md detailing the flashing process for split keyboard handedness using Liatris controllers. - Introduced LIATRIS_QUICK_START.txt as a quick reference for handedness setup and flashing steps. - Included LICENSE file for GNU General Public License v2. - Added Makefile for building QMK firmware with user-specific configurations. - Updated README.md with instructions for configuring and building QMK userspace. - Created build_all.sh script to automate the building of regular and handedness initialization firmware. - Added qmk.json to define userspace version and build targets.
163 lines
7.2 KiB
Markdown
163 lines
7.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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
|