| name | reprogram-foot-pedal |
| description | Reprogram a PCsensor-compatible USB foot pedal (KEGOL/iKKEGOL, VID:PID 3553:b001 and similar) using the rgerganov/footswitch CLI so each pedal sends a chosen key or modifier combo (e.g. Ctrl+Shift+Alt+A). Covers native Linux, macOS, and Windows+WSL2 (usbipd bind/attach). Use when the user wants to remap, reprogram, or configure a foot pedal or footswitch, mentions "foot pedal", "footswitch", "PCsensor", "KEGOL", "3553:b001", "usbipd", pedal keybindings, or reports a pedal sending wrong keys or not being detected in WSL.
|
| user-invocable | true |
| version | 1.0.0 |
| license | MIT |
| metadata | {"author":"dan","tags":["hardware","usb","hid","wsl2"]} |
Reprogram Foot Pedal
Reprogram a PCsensor-compatible USB foot pedal so each pedal sends the key
combination the user wants. The configuration is written into the pedal's own
firmware, so it persists across reboots and computers.
Success artifact: footswitch -r reads back the desired mapping, and the
pedal produces the new keys when pressed.
Inputs
- ``: (Optional) Desired mapping, e.g. "left=ctrl+shift+alt+a center=ctrl+shift+alt+b right=ctrl+shift+alt+c". If absent, ask the user in Step 2.
Steps
1. Locate the pedal repo
Resolve $PEDAL_REPO in this order:
$PEDAL_REPO env var, if set~/code/pedal, if it exists- Otherwise ask the user for the path, or offer to clone the repo
The footswitch tool will be built at $PEDAL_REPO/footswitch/ (cloned in
Step 4 if missing).
Success criteria: $PEDAL_REPO resolved to an existing directory.
2. Confirm the desired mapping
Ask the user (if not given via arguments) what each pedal should send:
- Which pedals to change (1=left, 2=center, 3=right)
- For each: modifiers (any of
ctrl, shift, alt, win) plus a key
(e.g. a, F5, media keys), a typed string (-s), or a mouse button (-b)
Success criteria: A concrete target mapping confirmed by the user.
3. Identify the device and OS path
Detect the OS, then read ONE matching companion file for the detailed procedure:
| Environment | How to detect | Companion file |
|---|
| WSL2 | uname -r contains microsoft | ${SKILL_DIR}/windows-wsl2.md |
| Native Linux | uname -s = Linux, not WSL | ${SKILL_DIR}/linux.md |
| macOS | uname -s = Darwin | ${SKILL_DIR}/macos.md |
Verify the pedal is a supported device (see the table in $PEDAL_REPO/README.md).
The tested KEGOL/iKKEGOL triple pedal is 3553:b001. On Linux/macOS use lsusb
(or system_profiler SPUSBDataType); on WSL2 use usbipd.exe list from the
Windows side.
Success criteria: Device VID:PID confirmed in the supported table; companion
file loaded.
Rules: If the VID:PID is NOT in the supported table, STOP and tell the user —
do not attempt to program an unknown device.
4. Get device access and build footswitch
Follow the loaded companion file. It covers:
- Getting the device reachable (WSL2: usbipd bind/attach — requires a UAC
prompt; native Linux/macOS: direct access)
- Installing the hidapi dependency and building
rgerganov/footswitch
Human checkpoint: On WSL2, warn the user before triggering the UAC prompt
for usbipd bind (first time only).
Success criteria: footswitch -r (with appropriate privileges) prints the
current pedal configuration.
5. Read, program, verify
-
Read current config first and show it to the user: footswitch -r
-
Program the confirmed mapping, e.g.:
footswitch -1 -m ctrl -m shift -m alt -k a \
-2 -m ctrl -m shift -m alt -k b \
-3 -m ctrl -m shift -m alt -k c
-m is repeatable per pedal; each -1/-2/-3 section takes its own
modifiers and key.
-
Read back and confirm it matches the target: footswitch -r
Success criteria: Readback shows the desired mapping (modifiers appear as
l_ctrl+l_shift+l_alt+<key>).
6. Clean up and test
- WSL2 only: detach the pedal back to Windows
(
usbipd.exe detach --busid <BUSID>) — the companion file has details.
- Ask the user to press each pedal in a text editor or shortcut recorder and
confirm the new keys arrive.
- If anything is off, consult
${SKILL_DIR}/troubleshooting.md.
Success criteria: User confirms pedals produce the new key combos.
