padctl

padctl maps gamepad HID reports to Linux uinput events using a declarative TOML device config.

Overview

• TOML device config — describe report layout, field offsets, button groups, and output capabilities without writing code.
• User mapping config (~/.config/padctl/) — personal button remaps, gyro mouse, layers, and macros; separate from device configs.
• XDG auto-discovery — daemon finds device and mapping configs across user, system, and builtin directories automatically.
• Runtime mapping switch — padctl switch <name> swaps the active mapping without restarting the daemon.
• Exclusive device grab — grabs the hidraw/evdev node so the original device is hidden from other processes (games, Steam, etc.) while padctl is running.
• padctl-capture — record HID traffic and generate a TOML skeleton automatically.
• padctl --validate — static config checker for CI and community contributions.
• padctl --doc-gen — generate device reference pages from TOML.

Source

https://github.com/BANANASJIM/padctl

Getting Started

Install via Package Manager

Arch Linux (AUR)

yay -S padctl-bin   # prebuilt binary
yay -S padctl-git   # build from source

If you previously installed from source with sudo padctl install, remove that manual install before switching to AUR so pacman can own the files:

sudo padctl uninstall --prefix /usr --no-immutable
yay -S padctl-bin   # or: yay -S padctl-git

Debian / Ubuntu

curl -fLO https://github.com/BANANASJIM/padctl/releases/latest/download/padctl_amd64.deb
sudo dpkg -i padctl_amd64.deb

For arm64:

curl -fLO https://github.com/BANANASJIM/padctl/releases/latest/download/padctl_arm64.deb
sudo dpkg -i padctl_arm64.deb

Package installs place the binary, udev rules, device configs, and system-wide user unit on disk. They do not run the live padctl install phase, so enable the service from your normal login session and reload udev rules:

systemctl --user daemon-reload
systemctl --user enable --now padctl.service
sudo udevadm control --reload-rules

If your controller config uses block_kernel_drivers (currently Flydigi Vader 5), the driver-block udev rules act on their own: they unbind the kernel driver only while a padctl daemon is running (its control socket exists under /run/user/<uid>/ or /run/padctl/). Unplug and replug the controller after starting the service. When the service is stopped or disabled, the rules leave the kernel driver alone and restore it on the next unplug.

Prerequisites

• Zig 0.15+ (build from source)
• Linux kernel ≥ 5.10 (uinput + hidraw support)
• libusb-1.0 (system package, optional — pass -Dlibusb=false to build without)
• A HID gamepad accessible via /dev/hidraw*

Build from Source

git clone https://github.com/BANANASJIM/padctl
cd padctl
zig build -Doptimize=ReleaseSafe

Optional build flags:

• -Dlibusb=false — disable libusb linkage (uses hidraw-only path)
• -Dwasm=false — disable WASM plugin runtime

GCC 15 build failure (issue #147): Arch Linux and similar distros with glibc 2.43+ may hit error: relocation R_X86_64_PC64 in .sframe section is unsupported — glibc 2.43 adds .sframe sections to crt1.o startup objects, which Zig 0.15.x's linker does not yet handle. This is an upstream Zig limitation, not a padctl bug. Build inside the canonical Docker image (./scripts/padctl-docker build, Debian bookworm + glibc 2.36) — see Build with Docker below — or install Zig 0.15.2 from the official tarball on a system with glibc ≤ 2.41 (Debian 12, Ubuntu 22.04/24.04 all work; Arch with glibc 2.43+ does NOT). Upstream fix: ziglang/zig#31272.

Build with Docker

If you do not have Zig installed — or hit the glibc 2.43+ linker error above — build inside the canonical Docker image. It pins the Zig version from .zigversion against Debian bookworm (glibc 2.36) and matches the CI build environment, so it needs only Docker:

./scripts/padctl-docker build      # zig build inside the image
./scripts/padctl-docker test       # zig build test inside the image
./scripts/padctl-docker shell      # interactive shell for debugging

The first run builds the image (padctl-build:<zig-version>) and later runs reuse it. The repository is bind-mounted at /src, so zig-out/ appears in your working tree as with a native build.

Install

sudo ./zig-out/bin/padctl install

This copies the binary, systemd service, device configs, and udev rules into /usr. It also runs systemctl daemon-reload and udevadm trigger automatically, and removes any legacy udev rules left by previous installs.

Custom prefix (e.g. for packaging):

sudo ./zig-out/bin/padctl install --prefix /usr --destdir "$DESTDIR"

Lifecycle scope override

PADCTL_INSTALL_PHASE=package forces the installer to act as if invoked by a package post-install script (no service start/enable, no XDG path creation, no UDEV reload). Useful for dpkg --configure, rpm --install, and AUR PKGBUILD package() functions. Scope is resolved in this priority order: --destdir flag > PADCTL_INSTALL_PHASE env > DESTDIR env > --scope flag > euid > --prefix.

Additional Services

padctl install also sets up the following on all systems:

• padctl-reconnect — A hotplug script triggered by udev when a controller is plugged in. It re-applies the active mapping through any running padctl daemon socket. It does not start or restart the daemon; padctl install enables/starts padctl.service unless you pass --no-enable or --no-start. After suspend/resume the kernel re-emits udev events for re-enumerated devices, so the same hook handles post-wake reconnect — no separate resume unit is needed.
• Driver conflict rules — Auto-generated udev rules that unbind conflicting kernel drivers (e.g., xpad) from devices that padctl manages. Configured per-device via block_kernel_drivers in device TOML configs. The udev rule only detaches a kernel driver while a padctl daemon is running (its control socket exists), so a plain package install never strips a controller before the service starts. When padctl install runs as root, it also walks /sys/bus/usb/drivers/<driver>/unbind for matching VID:PID pairs immediately, so already-bound devices are evicted without waiting for replug (issue #162).

Install a Mapping

To install a mapping config to /etc/padctl/mappings/ during install:

sudo ./zig-out/bin/padctl install --mapping vader5

The --mapping flag is repeatable. Use --force-mapping to overwrite existing mapping files.

When --mapping is given, the installer also writes a device-to-mapping binding in /etc/padctl/config.toml so the daemon auto-applies the mapping on every boot. Use --force-binding to overwrite an existing binding for the same device.

Bazzite / immutable distros: See the Bazzite / Immutable Distros guide for special installation steps.

Install problems? See Troubleshooting for daemon/socket checks, udev permission issues, missing device configs, and known build failures.

Verify

padctl status
padctl scan
padctl list-mappings

padctl status verifies the user service socket is reachable. padctl scan lists connected HID devices and shows whether a matching device config was found for each. padctl list-mappings verifies the mapping search paths are readable.

If padctl status fails, run padctl doctor — it checks the daemon, the systemd service state, and every supported device, and prints next-step hints.

Run as Service

If you built from source, run the installer first — zig build alone does not install the service file:

zig build
sudo ./zig-out/bin/padctl install    # installs binary, service, device configs, and udev rules

padctl install automatically runs daemon-reload, enables, and starts padctl.service via sudo -u $SUDO_USER systemctl --user. Driver-block udev rules activate on their own once the daemon is running. The systemctl --user enable --now padctl.service line is only needed if you used --no-enable or --no-start.

To auto-start at boot without an active login session (headless setups, Steam Deck game mode):

sudo loginctl enable-linger $USER

The service runs padctl in daemon mode, scanning all config directories (user, system, and builtin) with automatic hotplug support. udev rules grant access via uaccess — no sudo needed for the logged-in user.

Check the daemon is running:

$ padctl status
STATUS device=Flydigi Vader 5 Pro state=active mapping=fps

Each managed device prints one space-separated triple: device=<name>, state=<active|suspended>, mapping=<active mapping name|(none)>. Multiple devices appear on the same line. Exit code is 0 when the daemon answered and 1 when the response begins with ERR or the socket is unreachable.

Run Manually

Bare invocation — padctl auto-discovers configs via XDG paths:

padctl

Or target specific configs:

# Single config
padctl --config /usr/share/padctl/devices/sony/dualsense.toml

# All configs in a directory
padctl --config-dir /usr/share/padctl/devices/

Validate a Config

padctl --validate devices/sony/dualsense.toml      # device config
padctl --validate ~/.config/padctl/mappings/fps.toml  # mapping config

--validate auto-detects which schema to apply by scanning for a [device] section header — files containing [device], [device.*], or [[device.*]] are validated as device configs; everything else (including bare name = ... mapping files) is validated against the mapping schema.

Exit 0 = valid. Exit 1 = validation errors printed to stderr. Exit 2 = file not found or parse failure.

The flag is repeatable: padctl --validate a.toml --validate b.toml validates both files and exits with the worst code seen.

Adding a new device

padctl 的目标是「新设备 = 一个 .toml，零代码」。当 padctl scan 显示某个设备 unmatched（没有匹配的 device config）时，用 padctl-capture 录制它的 HID 报文并 生成一个起始 TOML 骨架：

padctl-capture --vid 0xVVVV --pid 0xPPPP --output mypad.toml

padctl-capture 会提示后续步骤。完整流程：

1. Capture — 运行上面的命令录制报文，得到 mypad.toml 骨架。
2. Refine — 检查并调整 [report] 字段的 offset / type，使按键和摇杆映射正确。
3. Install — 放到用户配置目录：mkdir -p ~/.config/padctl/devices && cp mypad.toml ~/.config/padctl/devices/
4. Validate — padctl --validate ~/.config/padctl/devices/mypad.toml
5. Test decode — padctl config test 实时预览解码出的具名按键/摇杆事件，确认字段正确。

Generate Device Docs

padctl --doc-gen --config devices/sony/dualsense.toml

User Config

padctl reads a config file to set per-device default mappings. The loader checks these paths in order (first found wins):

1. ~/.config/padctl/config.toml — user overrides (highest priority)
2. /etc/padctl/config.toml — system-wide defaults (written by padctl install --mapping)

version = 1

[[device]]
name = "Flydigi Vader 5 Pro"
default_mapping = "fps"

On daemon start, padctl matches the connected device name (case-insensitive) and loads the named mapping profile automatically. The system path is the fallback for environments where HOME is not set (e.g. systemd services).

padctl switch <name> automatically updates the user config, so the choice is remembered for bare padctl switch (re-apply without a name). Bare padctl switch (no argument) reads default_mapping from the connected device's entry in config.toml; if no entry exists, it prints error: no default_mapping in config.toml for device "<name>" and exits. To make the choice survive reboots, use padctl switch <name> --persist which copies the mapping and config to /etc/padctl/ via sudo.

CLI Reference

padctl switch [name] [--device <id>]       # switch mapping; omit name to fall back to default_mapping from config.toml
padctl switch <name> --persist             # switch + copy to /etc/padctl/ for reboot persistence (sudo)
padctl status [--socket <path>]            # show daemon status
padctl devices [--socket <path>]           # list connected devices
padctl list-mappings [--config-dir <dir>]  # list available mapping profiles
padctl reload [--pid <pid>]                # send SIGHUP to reload configs
padctl config list                         # show XDG config search paths
padctl config init [--device <name>]       # interactive mapping creator; templates: default, fps, racing, fighting
padctl config edit [name]                  # open mapping in $VISUAL/$EDITOR
padctl config test [--config] [--mapping]  # live input preview; prints decoded named events by default, --raw restores hex dump
padctl dump enable|disable                 # toggle diagnostic logging (persists)
padctl dump status                         # show dump state, log path, size, time span
padctl dump export --period Nm|Nh|Nd [-o file]  # export filtered log window
padctl dump clear                          # delete all log files

See the Diagnostic Logging guide for the full padctl dump workflow, log paths, and the [diagnostics] config section.

udev Permissions

padctl needs access to /dev/hidraw*, /dev/uinput, and /dev/uhid. The first two are standard for HID gamepad daemons; /dev/uhid is required for the SDL3-visible IMU pairing path (per ADR-015). padctl install writes the necessary udev rules (60-padctl.rules) automatically.

The padctl install command generates and installs udev rules automatically from device configs.

If you need to regenerate rules after adding custom device configs:

sudo padctl install

The udev rules use TAG+="uaccess" to grant the active graphical user access without requiring root. For SSH, headless, or test sessions without desktop ACLs, the rules also grant GROUP="input", MODE="0660"; add your user to the input group and log in again if those sessions need direct device access.

Installing padctl on Bazzite / Immutable Linux

This guide covers installing padctl on immutable Linux distributions where /usr is read-only (Bazzite, Fedora Atomic, Universal Blue, etc.).

Quick Install

Run the bootstrap script — it handles everything automatically:

curl -fsSL https://raw.githubusercontent.com/BANANASJIM/padctl/main/scripts/bazzite-setup.sh \
  | bash -s -- --mapping vader5

Replace vader5 with the mapping for your controller, or omit --mapping to install without a mapping. Available mappings are in the mappings/ directory.

When run locally (not via curl), the script prompts for mapping selection interactively if --mapping is not provided:

bash scripts/bazzite-setup.sh

What the script does:

1. Detects immutable OS (checks for ostree or read-only /usr)
2. Installs dependencies via Homebrew (Zig compiler, libusb) — no system reboot needed
3. Clones and builds padctl from source with ReleaseSafe optimization
4. Installs the daemon, systemd service, udev rules, and reconnect scripts
5. Persists the selected mapping as a device binding in /etc/padctl/config.toml (auto-applies on every boot)
6. Applies the mapping to the current session
7. Verifies the installation

Safe to re-run for updates — it rebuilds and reinstalls while preserving your mapping configs in ~/.config/padctl/mappings/.

Script Options

What the Install Does

Why /usr is a Problem

On immutable distros, /usr is a read-only filesystem overlay. The standard padctl install places systemd service files and udev rules under /usr/lib/, which works on regular Linux but fails silently on immutable systems — the files exist but systemd can't resolve them through symlinks during boot.

How --immutable Fixes It

The padctl install --immutable flag changes where system files are placed:

padctl-resume.service was removed (issue #131-B); udev hotplug handles post-suspend reconnect.

Files in /etc/ persist across system updates on immutable distros.

The immutable.conf Drop-in

The immutable install creates a systemd user-service drop-in override with these changes:

Security note on DeviceAllow=: The immutable drop-in does not grant file permissions by itself. Device access still comes from the installed udev rules, desktop uaccess ACLs, or input-group membership for headless sessions. Clearing the systemd device allowlist is needed so libusb can use USB bus nodes (/dev/bus/usb/) for vendor-specific control transfers once normal file permissions allow access.

Managing Mappings

Mapping configs can live in two places:

padctl switch <name> searches ~/.config/ first, so you can customize mappings without root:

# Edit your personal mapping
nano ~/.config/padctl/mappings/vader5.toml

# Apply changes immediately (no sudo needed)
padctl switch vader5

The /etc/padctl/mappings/ copy is used as a fallback by the hotplug reconnect script (which runs as root).

Auto-apply on boot

When you install with --mapping, the installer writes a device binding to /etc/padctl/config.toml:

version = 1

[[device]]
name = "Flydigi Vader 5 Pro"
default_mapping = "vader5"

The daemon reads this file at startup and auto-applies the mapping — no manual padctl switch needed after reboot. User-level overrides in ~/.config/padctl/config.toml take priority when available.

You can also persist a mapping change after switching at runtime:

padctl switch vader5 --persist

This copies your user mapping and config to /etc/padctl/ via sudo, so the change survives reboots without re-running the installer.

Uninstalling

sudo padctl uninstall --immutable --prefix /usr/local --mapping vader5

This removes all installed files including the /etc/systemd/user/ service files and the specified mapping. User configs in ~/.config/padctl/ are never touched.

Mapping Configuration Guide

Overview

A mapping config controls how padctl translates physical inputs to virtual outputs. It is separate from the device config:

• Device config (devices/*.toml) — describes the hardware HID protocol. Stable, community-maintained. You usually don't touch this.
• Mapping config (~/.config/padctl/mappings/*.toml) — your personal preferences: remapped buttons, gyro mouse, layers, macros.

Without a mapping config, padctl passes all inputs through unchanged as a standard gamepad.

Quick Start

Create a mapping

Use the interactive creator:

mkdir -p ~/.config/padctl/mappings/
padctl config init

Or, from a source checkout, copy the repository example and edit it:

cp config/example-mapping.toml ~/.config/padctl/mappings/my-config.toml
$EDITOR ~/.config/padctl/mappings/my-config.toml

XDG Search Paths

padctl searches for mapping profiles in this order (first match wins):

1. ~/.config/padctl/mappings/ — user overrides
2. /etc/padctl/mappings/ — system-wide profiles
3. /usr/share/padctl/mappings/ — builtin profiles

Apply a mapping

Switch the active mapping at runtime:

padctl switch fps

Every switch automatically saves your choice to ~/.config/padctl/config.toml, so you can restore it later with a bare switch:

padctl switch          # re-applies default_mapping from config.toml for the connected device

Bare padctl switch queries the running daemon for the connected device name, then looks up default_mapping in config.toml (user path first, then /etc/padctl/config.toml). If no entry is found it exits with error: no default_mapping in config.toml for device "<name>".

Persist across reboots (--persist)

By default, padctl switch only saves to your user config (~/.config/padctl/config.toml). The systemd daemon cannot read this at boot because HOME is not set in its service environment. To make the mapping survive reboots:

padctl switch fps --persist

This will:

1. Apply the mapping at runtime (same as without --persist)
2. Save to your user config (same as without --persist)
3. Prompt for confirmation, then ask for your sudo password
4. Copy the mapping file to /etc/padctl/mappings/
5. Copy your user config to /etc/padctl/config.toml

The daemon reads /etc/padctl/ at boot, so the mapping auto-applies on every reboot without manual intervention.

Limitations:

• --persist is not yet supported with --device (multi-controller setups). In multi-device sessions, auto-save and bare padctl switch resolve against the first connected device. Use padctl install --mapping <name> for explicit per-device persistence in multi-controller setups.
• A future version may persist by default, but this behavior is uncertain and subject to change.

Config file precedence

The daemon checks these paths in order when resolving default mappings:

1. ~/.config/padctl/config.toml — user overrides (highest priority, only available when HOME is set)
2. /etc/padctl/config.toml — system-wide defaults (written by padctl install --mapping or padctl switch --persist)

version = 1

[[device]]
name = "Flydigi Vader 5 Pro"
default_mapping = "fps"

If you installed with padctl install --mapping vader5, the system config is already written for you.

Manual run

Or pass a mapping directly when running padctl manually:

padctl --mapping ~/.config/padctl/mappings/my-config.toml

Validate

Mapping configs are validated at daemon startup. Errors are written to the journal:

journalctl --user -u padctl.service -n 30

Mapping configs can also be validated with padctl --validate; the flag auto-detects device vs mapping schema by scanning for a [device] table.

Configuration Sections

Button Remapping ([remap])

Keys are button names; values are the target action.

[remap]
A  = "B"              # swap A and B
M1 = "KEY_F13"        # back paddle → keyboard key
M2 = "mouse_left"     # grip button → mouse left click
M3 = "disabled"       # silence an unused button
M4 = "macro:dodge_roll"  # run a macro (defined below)
LM = "mouse_side"
RM = "RS"

Available target types:

For example, to fire the triggers from back buttons:

[remap]
M1 = "RT"   # full analog pull (255) while M1 is held
M2 = "LT"

Note: BTN_* values (e.g. "BTN_SOUTH") are routed to the virtual mouse device, not the gamepad. To remap to a gamepad button use a friendly ButtonId name ("A", "Select", etc.) instead.

Available button names: A, B, X, Y, LB, RB, LT, RT, Start, Select, Home, Capture, LS, RS, DPadUp, DPadDown, DPadLeft, DPadRight, M1, M2, M3, M4, Paddle1, Paddle2, Paddle3, Paddle4, TouchPad, Mic, C, Z, LM, RM, O

Tap / hold / double-press on one button

Bind separate actions to a short press, a long press, and a double press of the same button by using an inline table instead of a string:

[remap]
A  = { tap = "KEY_X", hold = "KEY_Y", double = "KEY_Z" }
B  = { tap = "B", hold = "KEY_LEFTSHIFT" }           # tap passes B through, hold = shift
RB = { tap = "RB", hold = "KEY_TAB", hold_ms = 400, double_ms = 200 }

• tap fires on release (short press), hold fires once held past hold_ms (default 300 ms), double fires on a second press within double_ms (default 250 ms) of the first release.
• At least one leg is required; absent legs do nothing. Legs are single targets only — macro:<name> and chord arrays are not allowed inside a gesture.
• Works the same in [layer.remap].
• Trade-off: when double is set, tap is delayed until the double-press window closes (the only way to tell a single press from the first of a double). Omit double to keep tap instant. Plain string and chord remaps are unchanged and never add latency.

Gyroscope ([gyro])

Translates gyroscope motion to mouse movement or a virtual stick. Off by default.

[gyro]
mode        = "mouse"
activate    = "LS"      # hold left stick click to enable gyro
sensitivity = 2.0
deadzone    = 300       # raw gyro units; filters small wobble
smoothing   = 0.4       # 0–1; higher = smoother but more latency
invert_y    = true

Omit activate to have gyro always active when mode is "mouse".

activate accepts a bare button name ("LS") or the hold_<BTN> form ("hold_RB") — both behave identically. For analog triggers (LT/RT) you must also declare trigger_threshold at the top level, otherwise the trigger axis is never converted to a button press and the gyro gate never fires.

Joystick mode

Set mode = "joystick" to route the gyro signal to a virtual stick axis instead of mouse events. Use target to choose which stick receives the output:

[gyro]
mode   = "joystick"
target = "right_stick"   # "right_stick" (default) or "left_stick"
deadzone    = 200
sensitivity = 100        # stick mode needs a much larger value than mouse
                         # mode — see the note below
smoothing   = 0.3

This is useful for games that read the right stick for camera control but do not natively support gyro input. In the default response = "rate" mode the same gyro fields (deadzone, smoothing, curve, invert_x, invert_y) behave as in mouse mode — but sensitivity does not scale the same way.

Mouse mode integrates the gyro rate into relative cursor motion frame by frame, so even small values keep moving the pointer. Joystick mode instead emits an absolute stick deflection: the raw gyro rate is normalized against max_val (default 32767, the full int16 range) before scaling. A normal hand motion produces a raw rate that is only a small fraction of max_val, so a mouse-style sensitivity = 1.5 yields a stick deflection of just a few percent — usually inside the game's own deadzone, so it feels as if gyro is off. Start around sensitivity = 100 and tune in the 50–150 range. Lowering max_val (for example max_val = 2000) raises the normalized signal and so increases the deflection for a given motion — it is an equivalent lever to sensitivity, useful if you would rather keep sensitivity small.

For racing games, response = "tilt" maps controller tilt to an absolute stick position instead of treating gyro motion like stick velocity. degrees_full controls how far the controller must be tilted for full stick deflection, and axis_x / axis_y choose which motion axis drives each virtual stick axis:

[gyro]
mode = "joystick"
response = "tilt"
target = "left_stick"
axis_x = "roll"          # steer by rolling the controller left/right
axis_y = "none"          # leave the Y stick axis unchanged
degrees_full = 35.0      # +/-35 degrees maps to full stick deflection
smoothing = 0.2

response = "tilt" uses the accelerometer to estimate roll and pitch, so it gives a stable absolute stick position without gyro integration drift. yaw does not have an absolute tilt estimate and resolves to neutral in tilt mode. When response = "tilt", the default X source is roll; in the default response = "rate" mode, X still uses yaw. If a device has not reported a non-zero accelerometer vector yet, tilt mode leaves the physical stick axes unchanged for that frame. In tilt mode, deadzone is applied after converting tilt to virtual stick output rather than to raw gyro units.

Blending gyro with the physical stick (blend_stick)

By default, gyro joystick output replaces the physical stick value while gyro is active. Set blend_stick = true to add the gyro signal on top of the physical stick instead:

[gyro]
mode        = "joystick"
target      = "right_stick"
activate    = "LS"
sensitivity = 1.5
deadzone    = 200
smoothing   = 0.3
blend_stick = true          # add gyro onto physical stick instead of replacing it

This lets the physical stick handle coarse movement while the gyro provides fine aim adjustment simultaneously — useful for aim-assist workflows. The combined value is clamped to the valid axis range (-32767..32767).

Note: when the physical stick is already at full deflection (±32767), the gyro contribution is clamped out entirely. blend_stick has no effect when mode = "mouse".

Escaping an in-game deadzone (minimum_output)

Some games apply their own deadzone to the right stick, so a small gyro deflection produces no in-game camera movement at all — slow, precise aiming simply does nothing until you move past the game's threshold. minimum_output raises the gyro output to a floor whenever gyro is active, so even a slight motion clears that deadzone:

[gyro]
mode           = "joystick"
target         = "right_stick"
activate       = "LS"
sensitivity    = 100
deadzone       = 200
smoothing      = 0.3
minimum_output = 0.15      # floor stick output at 15% of full scale while gyro moves

minimum_output is a fraction of full scale clamped to the 0.0–1.0 range (where 1.0 corresponds to roughly 20000 stick units). When the computed output magnitude is non-zero but below this floor, padctl scales it up to exactly minimum_output while preserving the aim direction — so a 5% deflection becomes a 15% deflection pointing the same way. The floor only kicks in for motion that already cleared the gyro deadzone: a perfectly still controller stays at zero, and any input absorbed by deadzone is never resurrected by minimum_output. Tune the value so the smallest deliberate motion just clears the game's own stick deadzone — start around 0.10–0.20 and raise it if slow aiming still produces no movement.

Note: minimum_output only applies in mode = "joystick". Mouse mode integrates motion frame by frame, so it has no deadzone to escape and ignores this field. The default minimum_output = 0.0 disables the floor entirely.

Sticks ([stick.left] / [stick.right])

Three modes:

• "gamepad" (default) — pass through as normal gamepad axes
• "mouse" — stick controls the cursor
• "scroll" — stick controls scroll wheel

[stick.right]
mode             = "mouse"
sensitivity      = 2.5
deadzone         = 100
suppress_gamepad = true   # prevent duplicate gamepad axis events

Use suppress_gamepad = true with "mouse" or "scroll" to avoid sending both gamepad axes and mouse/scroll events simultaneously.

D-pad ([dpad])

[dpad]
mode             = "arrows"  # emit arrow key events
suppress_gamepad = true

Default is "gamepad". Set to "arrows" to make the d-pad behave as arrow keys (useful for desktop navigation).

Layers ([[layer]])

Layers are the most powerful feature. A layer is a context-sensitive override: while active, its remap/gyro/stick/dpad settings replace the base config.

Three activation modes:

• "hold" — active while the trigger button is held
• "toggle" — press once to enter, press again to exit
• "hold_toggle" — short press fires tap; holding past hold_timeout toggles the layer on or off

The tap + hold_timeout combination lets a button do double duty: if released before hold_timeout ms, it fires tap instead of activating the layer.

The optional hold field emits a chosen output continuously while the layer is active — the trigger does double duty as both a layer switch and a passthrough button. It applies uniformly to all three activation modes, and fires only after the layer activates (a short press that resolves to tap emits no hold output). Released automatically on every exit path. hold takes a single ButtonId, KEY_*, mouse_*, or BTN_* target (not macro:<name>).

# Witcher-3 "Sense": hold LB to enter a layer AND still emit LB.
[[layer]]
name         = "sense"
trigger      = "LB"
activation   = "hold"
hold         = "LB"
hold_timeout = 200

[layer.remap]
A = "KEY_Q"

# Keyboard modifier held while a toggle layer is latched on.
[[layer]]
name       = "fn"
trigger    = "Select"
activation = "toggle"
hold       = "KEY_LEFTSHIFT"

[layer.remap]
A = "KEY_F1"

# "aim" layer: hold LM to enable gyro + mouse aim
[[layer]]
name         = "aim"
trigger      = "LM"
activation   = "hold"
hold_timeout = 200        # ms; short press fires tap action
tap          = "mouse_side"

[layer.gyro]
mode        = "mouse"
sensitivity = 2.0
smoothing   = 0.3

[layer.stick_right]
mode             = "mouse"
sensitivity      = 1.0
suppress_gamepad = true

[layer.remap]
RB = "mouse_left"
RT = "mouse_right"

Layer sub-configs can also be written inline (equivalent):

[[layer]]
name         = "aim"
trigger      = "LM"
activation   = "hold"
hold_timeout = 200
tap          = "mouse_side"
gyro         = { mode = "mouse", sensitivity = 2.0, smoothing = 0.3 }
stick_right  = { mode = "mouse", sensitivity = 1.0, suppress_gamepad = true }
remap        = { RB = "mouse_left", RT = "mouse_right" }

Toggle example — F-key row on Select:

[[layer]]
name       = "fn"
trigger    = "Select"
activation = "toggle"

[layer.remap]
A = "KEY_F1"
B = "KEY_F2"
X = "KEY_F3"
Y = "KEY_F4"

Hold-to-toggle example — hold LM to keep a racing layer enabled, hold it again to disable it. A short press still emits tap:

[[layer]]
name         = "race"
trigger      = "LM"
activation   = "hold_toggle"
hold_timeout = 300
tap          = "LM"

[layer.gyro]
mode = "joystick"
response = "tilt"
target = "left_stick"
axis_x = "roll"
axis_y = "none"
degrees_full = 35.0

Layers are evaluated in declaration order. Only one layer is active at a time.

Macros ([[macro]])

Named sequences bound via macro:<name> in remap values.

[[macro]]
name  = "dodge_roll"
steps = [
    { tap = "B" },
    { delay = 50 },
    { tap = "LEFT" },
]

[[macro]]
name  = "shift_hold"
steps = [
    { down = "KEY_LEFTSHIFT" },
    "pause_for_release",
    { up = "KEY_LEFTSHIFT" },
]

Bind in remap: M1 = "macro:dodge_roll"

Warning: hold_timeout belongs on the [[layer]] block, not [[macro]]. A hold_timeout value under [[macro]] is not recognized and the schema linter will warn about it; the layer continues to use the default 200 ms. To make a hold layer fire quickly, put hold_timeout = 50 (or your chosen value, 1–5000 ms) on the [[layer]] block itself.

Repeat-while-held — turbo / combo (repeat_delay_ms)

Add repeat_delay_ms = N to a [[macro]] block to make the macro restart while the trigger button is held. Releasing the trigger lets the current iteration finish naturally and stops further restarts. Omit the field for legacy single-shot behaviour.

# Spam A while RM held: tap, wait 50 ms, tap again, ...
[[macro]]
name = "spam_a"
repeat_delay_ms = 50
steps = [{ tap = "A" }]

[remap]
RM = "macro:spam_a"

Trigger Threshold — analog LT / RT as digital buttons

Warning: trigger_threshold must be at the top level of the mapping file. Placing it inside [[layer]] is silently ignored. To use LT / RT as remap source keys or layer triggers, set this field once at the top of your mapping file, outside any layer block.

LT / RT are analog axes by default and cannot be used directly as [remap] source keys. Once trigger_threshold is declared, padctl synthesizes digital button events from the axis values each frame, making them available for [remap] and layer triggers:

trigger_threshold = 100   # 0–255, shared by LT and RT

[remap]
LT = "KEY_LEFTSHIFT"      # axis > 100 → synthesize LT press → emit Shift
RT = "mouse_right"        # axis > 100 → synthesize RT press → emit right click

See Mapping Config Reference — trigger_threshold for the full field description.

LT / RT also work as down / up targets inside [[macro]] — press and release the virtual trigger from any macro step:

[remap]
M1 = "macro:aim_burst"

[[macro]]
name = "aim_burst"
steps = [
    { down = "LT" },
    { delay = 80 },
    { up = "LT" },
]

Adaptive Trigger ([adaptive_trigger]) — DualSense only

Configures the resistance profile of the DualSense L2/R2 triggers. See Mapping Config Reference for full field tables.

In-controller Chord Switch ([chord_switch])

Hold a set of modifier buttons, then tap a selector button to switch the active mapping without touching a CLI. This is configured in ~/.config/padctl/config.toml (not in a mapping file), and each selectable mapping file declares chord_index = N:

# ~/.config/padctl/config.toml
[chord_switch]
modifier  = ["LM", "RM"]
selectors = ["A", "B", "X", "Y"]
hold_ms   = 120

# ~/.config/padctl/mappings/desktop.toml
chord_index = 1   # LM+RM → tap A → switch to this mapping

See Mapping Config Reference — chord_switch for full field tables and a runnable example.

Full Example

A copy-paste-ready example covering every major feature is included in the repository at examples/mappings/comprehensive.toml. It covers base remaps, hold/toggle/hold-toggle layers, macros, stick modes, and gyro.

Reference

Full field tables and all accepted values: Mapping Config Reference

Diagnostic Logging

padctl ships with a general-purpose, togglable file logger. It is designed to be the single mechanism you reach for when diagnosing any class of bug — stuck rumble, input drops, mapping misses, hotplug oddities, daemon crashes — so that reports come with structured evidence instead of guesswork.

It is off by default and has no hot-path cost when disabled. The current build already emits a very detailed trace of the force-feedback pipeline; other subsystems (input routing, layer/remap decisions, hotplug, config reload, …) will be instrumented behind the same switch over time. The user-facing contract — enable, reproduce, export, attach — stays the same as more coverage is added.

Quick workflow

padctl dump enable                          # turn logging on (survives reboot)
# ... reproduce the issue by playing ...
padctl dump export --period 30m -o bug.log  # capture the last 30 minutes
padctl dump disable                         # turn it off again

Attach bug.log to your issue report.

Commands

Period syntax

--period accepts Nm (minutes), Nh (hours), or Nd (days). Examples: --period 15m, --period 2h, --period 7d.

Log file location

padctl picks the first entry whose env var is set / parent dir is reachable, going top-to-bottom:

On a default Bazzite install (user-service + StateDirectory=padctl in the unit file) the daemon and CLI both converge on ~/.local/state/padctl/padctl.log.

padctl dump status prints the path currently in use. If both the current-session path and a legacy location contain padctl.log, the command picks whichever file was most recently modified (mtime-based) so you always see the active one.

Config file

Diagnostic logging is driven by a dedicated section in config.toml:

[diagnostics]
dump = false          # master switch; padctl dump enable/disable flips this
max_log_size_mb = 100 # rotation threshold (default 100 MB)

padctl dump enable and padctl dump disable are just a convenience front-end for toggling dump and forwarding the change to the running daemon — you can also edit this section by hand and send SIGHUP (padctl reload) instead.

⚠️ Rewrite behavior. padctl dump enable/disable parses config.toml, rewrites it from the known schema, and atomically renames the result into place. Anything outside the documented schema — unknown sections, undocumented keys, hand-written comments — is not preserved. If you hand-edit config.toml with content that matters (e.g. a forward-looking [experimental] block, inline comments documenting a choice), keep it in a sibling file, or drive padctl via SIGHUP after the edit instead of using the dump subcommand. The current known schema is version, [diagnostics] (dump, max_log_size_mb), [supervisor] (suspend_grace_sec), [chord_switch] (modifier, selectors, hold_ms), and [[device]] entries (name, default_mapping).

Supervisor tunables

config.toml may also include a [supervisor] section to tune hot-plug suspend behavior:

The suspend_grace_sec value is preserved across padctl dump enable/disable and padctl switch; comments and unknown keys inside [supervisor] follow the same rewrite caveat as the rest of config.toml.

Chord switch (issue #183)

Set up an in-controller mapping switch so you can change profiles without leaving Big Picture mode. Add a [chord_switch] section to ~/.config/padctl/config.toml and a chord_index to each mapping you want to be selectable:

# ~/.config/padctl/config.toml
[chord_switch]
modifier  = ["LM", "RM"]      # held simultaneously to arm the chord
selectors = ["A", "B", "X", "Y"]  # each maps to chord_index 1..N by position
hold_ms   = 80                # debounce window — selector edges in this window are ignored

# ~/.config/padctl/mappings/fps.toml
name = "fps"
chord_index = 1   # press A while holding modifier → switch to this mapping

# ~/.config/padctl/mappings/racing.toml
name = "racing"
chord_index = 2   # press B while holding modifier → switch to this mapping

While the modifier is held, selector buttons are suppressed from the virtual gamepad output so the in-game UI does not see them. If no mapping declares a matching chord_index, the daemon logs a warning and does nothing. The standard padctl switch <name> CLI still works alongside the chord. [chord_switch] is preserved across padctl dump enable/disable's rewrite. Comments inside the section follow the same rewrite caveat as the rest of config.toml.

Rotation

On every daemon startup and on every fresh file-open, padctl stats the existing log. If it exceeds max_log_size_mb, the file is renamed to padctl.log.1 (overwriting any previous backup) and a new empty padctl.log is created. There is only ever one rotated backup.

This keeps disk usage bounded to roughly 2 * max_log_size_mb without needing logrotate or any external tooling.

What gets logged

When dump = false (the default), only warnings and errors are written, and only lazily on the first occurrence.

When dump = true, padctl adds verbose tracing on top. The coverage today is deepest in the force-feedback pipeline — that is the area where the logger was needed first — and is being expanded to other subsystems as issues surface. Current coverage:

• Session lifecycle — daemon start, config loaded, devices attached/detached
• FF_UPLOAD / FF_ERASE kernel requests with effect IDs, rumble magnitudes, and replay durations
• EV_FF PLAY / STOP events with scheduler decisions (forwarded, throttled, auto-stop timer armed, etc.)
• HID rumble frames written to the physical device, with the first 16 bytes hex-dumped so post-checksum data can be inspected
• Scheduler slot state (all 16 effect slots) before and after every mutation

Planned areas (no promised order): input-report parsing, layer/remap resolution, hotplug/netlink events, config reload, IPC commands. You can track progress on these in the repo issue tracker.

Reporting issues

When opening an issue that needs diagnostic data, the recommended flow is:

padctl dump enable
# reproduce the bug (play the game, press the button, wait for the glitch)
padctl dump export --period 1h -o issue.log
padctl dump disable

Attach issue.log. Sensitive information in the logs is limited to device names, USB identifiers, and input report bytes — there is no keystroke capture or payload from other applications.

Troubleshooting

Run padctl doctor first and paste its output in bug reports. It checks the daemon socket, the systemd service state, kernel driver bindings, and every supported device in one pass, and prints next-step hints. The manual flows below remain as fallback when doctor is unavailable or inconclusive.

Common runtime failures that have generated repeat issue reports, with diagnostics and workarounds.

padctl status says it cannot connect to the daemon

Symptoms:

• padctl status exits non-zero or reports that the daemon socket is unreachable.
• padctl switch <name> cannot apply a mapping.

Check the user service:

systemctl --user status padctl.service
journalctl --user -u padctl.service -n 80

Common causes:

• padctl install was run with --no-enable or --no-start.
• padctl install was run as root without SUDO_USER, so it could not locate the real user's systemd user manager.
• The user has not logged in since install, or headless boot needs linger.

Fix:

systemctl --user daemon-reload
systemctl --user enable --now padctl.service

For headless setups or boot-before-login:

sudo loginctl enable-linger $USER

Permission denied opening hidraw, uinput, or uhid

Symptoms:

• The daemon starts but logs PermissionDenied, AccessDenied, or open failures for /dev/hidraw*, /dev/uinput, or /dev/uhid.
• padctl scan sees the controller but the daemon cannot manage it.

Fix:

sudo udevadm control --reload-rules
sudo udevadm trigger
systemctl --user restart padctl.service

Then unplug and replug the controller. Graphical sessions normally receive access through TAG+="uaccess" ACLs. SSH/headless sessions may also need input-group membership:

sudo usermod -aG input $USER

Log out and back in after changing groups.

Controller is visible but no matching config is found

Symptoms:

• padctl scan lists the HID device but says no config matched.
• The daemon log says no devices were found in config dirs.

Check installed configs:

padctl doctor resolves the daemon's real device config directories and lists every device TOML it finds — prefer it over a hardcoded path, because the install prefix differs by platform (ostree/immutable distros install under /usr/local/share/padctl/devices, not /usr/share/padctl/devices):

padctl doctor

To inspect a specific config manually, validate it from the directory doctor reported, e.g.:

padctl --validate /usr/share/padctl/devices/sony/dualsense.toml

If doctor finds zero device TOMLs, reinstall the current package. If your device is not listed, capture it and open a device-config contribution.

Kernel driver or another mapper still owns the controller

Symptoms:

• The physical controller continues to appear directly in games while padctl is running.
• padctl cannot exclusively grab the device, or duplicate inputs appear.
• Xbox-compatible devices still bind to xpad even though their device TOML sets block_kernel_drivers.

Package-manager install fix:

systemctl --user daemon-reload
systemctl --user enable --now padctl.service
sudo udevadm control --reload-rules

Then unplug and replug the controller. The driver-block udev rule unbinds the kernel driver only while a padctl daemon is running (its control socket exists), so no extra setup step is needed — and a stopped daemon means the kernel driver keeps the device.

Source install fix:

sudo padctl install
systemctl --user restart padctl.service

Then unplug and replug the controller. For devices with block_kernel_drivers, the source installer installs the udev rules and also tries to unbind already attached matching devices during install. Do not use sudo padctl install as the normal fix for AUR or .deb installs because it rewrites files that the package manager owns.

padctl install warns "source 'devices/' directory not found"

Symptoms:

• padctl install prints a warning about a missing devices/ directory.
• After install, padctl scan or the daemon log reports "no devices found in config dirs".
• The daemon starts but no controller is recognized.

Root cause: pre-v0.1.5 .deb packages stripped one directory level from the devices/ tree during packaging, leaving device TOML files absent from the installed prefix (issue #216). Fixed in v0.1.5+.

Workaround: upgrade to v0.1.5 or later.

Verify the fix:

dpkg -L padctl | grep 'devices/'

The output should list multiple .toml files under /usr/share/padctl/devices/<vendor>/. If the list is empty, the old package is still installed — re-download and reinstall.

User service exits with status=218/CAPABILITIES on Ubuntu 26.04 / systemd 257+

Fixed in v0.1.6. If you are running an older release, use the workaround below.

Symptoms:

• systemctl --user status padctl.service shows:

  Failed at step CAPABILITIES spawning /usr/bin/padctl: Operation not permitted
  Main process exited, code=exited, status=218/CAPABILITIES
  

• The daemon never starts; padctl status returns cannot connect to padctl daemon.
• The restart counter climbs in journalctl --user -u padctl.service.

Root cause (pre-v0.1.6): the user service unit declared LockPersonality=true, ProtectClock=true, and NoNewPrivileges=true. systemd 257+ enforces these options more strictly on user instances; the kernel rejects the capability adjustments required to apply them, killing the process before it starts.

Workaround (pre-v0.1.6 only): install a drop-in that clears the three offending directives:

mkdir -p ~/.config/systemd/user/padctl.service.d
cat > ~/.config/systemd/user/padctl.service.d/no-cap-lockdown.conf <<'EOF'
[Service]
LockPersonality=
ProtectClock=
NoNewPrivileges=
EOF
systemctl --user daemon-reload
systemctl --user restart padctl

Assigning an empty value to a systemd directive resets it to the default (unset). The functional and security impact is small: the daemon runs as your user with no privileged operations, so removing these three flags does not expand what it can do.

Reference: issue #216

Build fails on Arch Linux: relocation R_X86_64_PC64 against symbol ...

Symptoms:

• zig build fails during linking:

  relocation R_X86_64_PC64 against symbol '__libc_start_main' can not be used when making a PIE object
  

  or similar R_X86_64_PC64 / .sframe section is unsupported errors.
• Affects Arch Linux with glibc 2.43 or later.

Root cause: glibc 2.43+ adds .sframe sections to crt1.o startup objects that Zig 0.15.x's linker does not handle. This is an upstream Zig limitation, not a padctl bug.

Workaround: build against the musl static target:

zig build -Doptimize=ReleaseSafe -Dtarget=x86_64-linux-musl

The resulting binary is fully static and works on any Linux distribution regardless of glibc version. This is the same target used for official padctl release tarballs.

Alternatively, build inside the canonical Docker image (./scripts/padctl-docker build, Debian bookworm + glibc 2.36) for a reproducible build environment.

Reference: issue #147

Device Config Reference

Device configs are TOML files in devices/<vendor>/<model>.toml.

[device]

[[device.interface]]

[device.init]

Optional initialization sequence sent after device open.

[[report]]

Describes one incoming HID report.

[report.match]

Disambiguates reports when multiple share an interface.

[report.fields]

Inline table mapping field names to their layout:

[report.fields]
left_x = { offset = 1, type = "u8", transform = "scale(-32768, 32767)" }
gyro_x = { offset = 16, type = "i16le" }
battery_level = { bits = [53, 0, 4] }

Use offset + type for whole-byte fields. Use bits for sub-byte bit extraction (e.g. a 4-bit battery level packed within a byte).

Note: When using bits, the type field must be null, "unsigned", or "signed" — standard type strings like "u8" or "i16le" are not valid.

Data Types

u8 i8 u16le i16le u16be i16be u32le i32le u32be i32be

Transform DSL

Transforms are applied left-to-right as a comma-separated chain:

Example: transform = "scale(-32768, 32767), negate" — scales a u8 (0–255) to -32768..32767, then negates the result.

[report.button_group]

Maps a contiguous byte range to named buttons via bit index.

[report.button_group]
source = { offset = 8, size = 3 }
map = { A = 5, B = 6, X = 4, Y = 7, LB = 8, RB = 9 }

Button names must be valid ButtonId values:

A B X Y LB RB LT RT Start Select Home Capture LS RS DPadUp DPadDown DPadLeft DPadRight M1 M2 M3 M4 Paddle1 Paddle2 Paddle3 Paddle4 TouchPad Mic C Z LM RM O

[report.checksum]

Optional integrity check on the report.

[commands.<name>]

Output command templates (rumble, LED, adaptive triggers, etc.). Template placeholders use {name:type} syntax.

[commands.rumble]
interface = 3
template = "02 01 00 {weak:u8} {strong:u8} 00 ..."

Adaptive Trigger Commands

DualSense-style adaptive triggers use a naming convention of adaptive_trigger_<mode>:

[commands.adaptive_trigger_off]
interface = 3
template = "02 0c 00 ..."

[commands.adaptive_trigger_feedback]
interface = 3
template = "02 0c 00 ... 01 {r_position:u8} {r_strength:u8} ... 01 {l_position:u8} {l_strength:u8} ..."

[commands.adaptive_trigger_weapon]
interface = 3
template = "02 0c 00 ... 02 {r_start:u8} {r_end:u8} {r_strength:u8} ... 02 {l_start:u8} {l_end:u8} {l_strength:u8} ..."

[commands.adaptive_trigger_vibration]
interface = 3
template = "02 0c 00 ... 06 {r_position:u8} {r_amplitude:u8} {r_frequency:u8} ... 06 {l_position:u8} {l_amplitude:u8} {l_frequency:u8} ..."

[output]

Declares the uinput device emitted by padctl.

[output.axes]

[output.axes]
left_x = { code = "ABS_X", min = -32768, max = 32767, fuzz = 16, flat = 128 }

[output.buttons]

[output.buttons]
A = "BTN_SOUTH"
B = "BTN_EAST"

[output.dpad]

[output.dpad]
type = "hat"   # or "buttons"

[output.force_feedback]

Two backends are supported: legacy rumble via uinput (default), and HID PID passthrough via UHID for devices whose firmware speaks the USB HID PID class spec directly (most racing wheels).

Rumble (uinput, default)

[output.force_feedback]
type = "rumble"
max_effects = 16
auto_stop = true     # default; set false to disable userspace auto-stop

HID PID passthrough (UHID, racing wheels)

For devices that already implement HID PID effects in firmware (constant force, spring, damper, friction, sine periodic, etc.), padctl can publish a UHID node with the device's own PID descriptor and forward UHID_OUTPUT events back to the physical wheel. The kernel's hid-pidff driver then exposes the standard evdev FF interface to games and SDL — no userspace effect synthesis.

Phase 13 Wave 6 introduced this path; closes issue #82 (Moza, Logitech G-series, Thrustmaster T-series, Fanatec ClubSport).

[output.force_feedback]
backend       = "uhid"
kind          = "pid"
clone_vid_pid = true   # publish the UHID node with the wheel's real VID/PID

Validation matrix — the parser rejects illegal combinations at config load:

clone_vid_pid = true requires [device].vid and [device].pid to be non-zero.

Kernel requirement: the hid-pidff driver must be loaded, and the hid-universal-pidff quirk module is recommended for non-Logitech wheels. See the Bazzite / Immutable Distros guide for distro-specific notes.

[output.aux]

Auxiliary output device (mouse or keyboard).

[output.touchpad]

Touchpad output device.

[output.imu]

IMU (accelerometer + gyroscope) output via a separate UHID node. When declared, padctl creates a second UHID device that shares the same uniq as the primary gamepad output, enabling SDL3 to pair the IMU sensor with the controller automatically (ADR-015 UHID IMU migration; see PR #159).

Validation rule: when [output.imu] is present, backend must be "uhid". The validator rejects "uinput" per ADR-015 — UHID is the only supported backend for IMU output. Omitting [output.imu] entirely keeps the legacy uinput-primary path.

Distinction from [output.aux]: [output.imu] is the gamepad's accelerometer/gyroscope UHID node; [output.aux] is a secondary uinput device for mouse/keyboard remapping. They serve different purposes and can coexist.

See ADR-015 for the design rationale. This section enables SDL3-visible sensor pairing on Steam games.

Force feedback limitation: enabling [output.imu] backend="uhid" places the primary gamepad on the UHID backend. On current kernels, evdev force feedback is unavailable for UHID devices unless the kernel's hid-universal-pidff module recognises the device VID/PID — generic UHID nodes get capabilities/ff=0. Wine/Lutris evdev rumble will not work in this mode. Rumble via SDL or Steam (HIDAPI path) is unaffected.

Example:

[output.imu]
backend = "uhid"
name = "vader5_imu"
vid = 0x11ff
pid = 0x1211
accel_range = [-16384, 16384]
gyro_range = [-32768, 32767]

[wasm]

WASM plugin for stateful/custom protocols (Phase 4+).

[wasm.overrides]

Mapping Config Reference

An optional --mapping TOML file overrides the default button/axis pass-through with remapping, gyro mouse, stick modes, layers, and macros.

Top-level Fields

name = "fps"
trigger_threshold = 100

Validation behaviour

padctl daemon runs a post-parse linter on every mapping TOML file at startup. Unknown keys produce warnings to stderr with line numbers and section context:

config: unknown key 'trigger_threshold' inside [layer] (line 42) — typo or misplaced field?
config: unknown key 'typo_field' at top-level (line 7) — typo or misplaced field?

The linter is fail-open: warnings only, the daemon still starts. This surfaces common mistakes such as placing trigger_threshold inside a [[layer]] block instead of at the top level (also surfaces preceding silent rewrites — see Diagnostic logging).

trigger_threshold — analog triggers as digital buttons

padctl models LT and RT as analog axes (ABS_Z / ABS_RZ) by default. To bind them to keys or mouse buttons in [remap], declare a threshold:

trigger_threshold = 100   # 0–255, shared by both LT and RT

[remap]
LT = "KEY_LEFTSHIFT"
RT = "mouse_right"

Axis value above threshold → synthesizes LT / RT button press. Value at or below threshold → release. Once declared, LT and RT behave like any other face button for [remap] sources and [[layer]] trigger fields.

Threshold tuning:

Use padctl dump enable to observe raw LT / RT axis readings and dial in the threshold. See Diagnostic Logging.

Jitter: If the axis hovers around the threshold and produces rapid press/release bursts, raise the threshold by 10–20.

Without trigger_threshold, LT / RT emit analog axis events only and do not participate in [remap] or layer trigger matching.

[remap]

Top-level button remapping (active when no layer overrides). Keys are ButtonId names, values are target button names, KEY_* codes, mouse_left/mouse_right/mouse_middle/mouse_side/mouse_extra/mouse_forward/mouse_back, disabled, or macro:<name>.

LT / RT as targets emit the digital trigger press plus a full analog pull (ABS_Z / ABS_RZ = 255) while the source button is held. Tap/double gesture legs targeting LT / RT emit only the digital press; use a plain remap or a hold leg for an analog pull.

[remap]
M1 = "RT"   # full analog pull (255) while M1 is held
M2 = "LT"

Note: BTN_* values (e.g. "BTN_SOUTH") are routed to the virtual mouse device, not the gamepad. To target a gamepad button use a friendly ButtonId name ("A", "Select", etc.) instead.

[remap]
M1 = "KEY_F13"
M2 = "mouse_side"
M3 = "disabled"
A = "B"
M4 = "macro:dodge_roll"

Array values (e.g. M1 = ["KEY_LEFTMETA", "KEY_1"]) are parsed and resolved as chord targets (2–4 keys) but are not yet dispatched — chord output is planned for a future release.

Gesture bindings (tap / hold / double-press)

A [remap] value may also be an inline table that binds different actions to short press, long press, and double press of the same button:

[remap]
A  = { tap = "KEY_X", hold = "KEY_Y", double = "KEY_Z" }
B  = { tap = "B", hold = "KEY_LEFTSHIFT" }
Y  = { tap = "Y", double = "KEY_F" }
RB = { tap = "RB", hold = "KEY_TAB", hold_ms = 400, double_ms = 200 }

At least one of tap / hold / double must be set. Each leg is a single target (ButtonId, KEY_*, mouse_*, or disabled); macro:<name> and chord arrays are not allowed inside a gesture. An empty table {} or an unknown key is rejected at parse time; out-of-range thresholds and a base-[remap] gesture key that collides with a [[layer]] trigger are rejected at validate time. Absent legs simply do nothing.

Latency trade-off: when double is set, tap cannot fire until the double-press window has elapsed (the engine must wait to see whether a second press arrives). Without double, tap fires immediately on release with zero added latency. Plain string and chord-array remap forms are unaffected and incur no extra latency.

[gyro]

Global gyro-to-mouse configuration.

[gyro]
mode = "mouse"
activate = "LS"
sensitivity = 2.0
deadzone = 300
smoothing = 0.4
curve = 1.0
invert_y = true

[stick.left] / [stick.right]

Per-stick mode configuration.

[stick.left]
mode = "gamepad"
deadzone = 128
sensitivity = 1.0

[stick.right]
mode = "mouse"
sensitivity = 2.5
deadzone = 100
suppress_gamepad = true

[dpad]

D-pad mode configuration.

[dpad]
mode = "gamepad"

[[layer]]

Each layer defines an activation condition and overrides for remap, gyro, sticks, and d-pad. Layers are evaluated in declaration order.

[[layer]]
name = "fps"
trigger = "LM"
activation = "hold"
tap = "mouse_side"
hold = "RB"
hold_timeout = 200

[layer.remap]

Per-layer button remapping. Same syntax as top-level [remap].

[layer.remap]
RT = "mouse_left"
A = "KEY_R"

[layer.gyro]

Per-layer gyro override. Same fields as [gyro].

[layer.gyro]
mode = "mouse"
sensitivity = 8.0
deadzone = 40
smoothing = 0.4
invert_y = true

[layer.stick_left] / [layer.stick_right]

Per-layer stick overrides. Same fields as [stick.left]/[stick.right].

[layer.stick_right]
mode = "mouse"
sensitivity = 2.5
deadzone = 100
suppress_gamepad = true

[layer.dpad]

Per-layer d-pad override. Same fields as [dpad].

[layer.dpad]
mode = "arrows"
suppress_gamepad = true

[layer.adaptive_trigger]

Per-layer adaptive trigger override. Same fields as top-level [adaptive_trigger].

[layer.adaptive_trigger]
mode = "weapon"

[layer.adaptive_trigger.left]
start    = 30
end      = 120
strength = 200

[adaptive_trigger]

DualSense adaptive trigger configuration.

[adaptive_trigger]
mode = "feedback"

[adaptive_trigger.left]
position = 70
strength = 200

[adaptive_trigger.right]
position = 40
strength = 180

[adaptive_trigger.left] / [adaptive_trigger.right]

[[macro]]

Named sequences of input steps bound via macro:<name> in remap values.

[[macro]]
name = "dodge_roll"
steps = [
    { tap = "B" },
    { delay = 50 },
    { tap = "LEFT" },
]

[[macro]]
name = "shift_hold"
steps = [
    { down = "KEY_LEFTSHIFT" },
    "pause_for_release",
    { up = "KEY_LEFTSHIFT" },
]

Step types:

Macro fields:

Implicit step delays

The top-level macro_step_delay = N (ms) sets a global default that is inserted between every pair of adjacent emitting steps (tap / down / up) in every macro. A per-macro step_delay overrides the global. Both default to 0 (no insertion, byte-identical to legacy behaviour).

Insertion rules:

• Only inserted between two adjacent emitting steps (tap/down/up).
• Never inserted adjacent to an explicit { delay = N } step (it already is a delay).
• Never inserted adjacent to "pause_for_release" (treat it as a synchronization point).
• Per-macro step_delay (including explicit 0) wins over global macro_step_delay.

macro_step_delay = 50   # global default for every macro

[[macro]]
name = "unarmed"
# step_delay omitted → inherits global 50
steps = [
    { down = "RB" },
    { down = "X" },
    "pause_for_release",
    { up = "X" },
    { up = "RB" },
]
# Effective after parse:
#   down RB, delay 50, down X, pause_for_release, up X, delay 50, up RB

Note: hold_timeout is a [[layer]] field (see above, default 200 ms). It is not a [[macro]] field — placing it under [[macro]] has no effect (the schema linter warns about it). To make a hold-activated layer respond faster, set hold_timeout on the [[layer]] block, e.g. hold_timeout = 50.

# Turbo: spam A while RM is held, 50 ms between presses.
[[macro]]
name = "spam_a"
repeat_delay_ms = 50
steps = [{ tap = "A" }]

# Combo: XYX every 100 ms while held.
[[macro]]
name = "xyx_combo"
repeat_delay_ms = 100
steps = [
    { tap = "X" },
    { delay = 30 },
    { tap = "Y" },
    { delay = 30 },
    { tap = "X" },
]

Bind a macro in remap: M1 = "macro:dodge_roll"

[chord_switch] — in-controller mapping switch

[chord_switch] lives in ~/.config/padctl/config.toml (the user config), not in a mapping file. It lets you switch the active mapping without touching a CLI: hold a modifier combination, then tap a selector button.

# ~/.config/padctl/config.toml
version = 1

[chord_switch]
modifier  = ["LM", "RM"]        # hold ALL of these to arm
selectors = ["A", "B", "X", "Y"] # tap one (while modifier held) to switch
hold_ms   = 120                  # debounce window in ms (default 80)

chord_index is declared per mapping file (not in config.toml):

# ~/.config/padctl/mappings/desktop.toml
chord_index = 1   # tap A (selectors[0]) while holding LM+RM → switch here

Selector selectors[i] maps to chord_index = i+1. Mappings that do not declare chord_index are not reachable via chord. Range is 1–255; duplicate chord_index values across files are resolved by lexicographic mapping name order (first match wins).

While the modifier is held, all selector buttons are suppressed from the output device so they do not fire their remapped actions.

A runnable example is at examples/configs/chord-switch.toml.

Device Reference

Device reference pages are generated from production TOML configs via padctl --doc-gen. This section lists supported device families; compatibility variants may share one generated page, and fixtures under devices/example/ are for parser/CI coverage rather than user support claims.

Run padctl --doc-gen devices/**/*.toml to regenerate all pages.

8BitDo Ultimate Controller

VID:PID 0x2dc8:0x6003

Vendor 8bitdo

Interfaces

Report: usb (64 bytes, interface 0)

Match: byte[0] = 0x01

Fields

Button Map

Source: offset 11, size 2 byte(s)

Output Capabilities

uinput device name: 8BitDo Ultimate Controller | VID 0x2dc8 | PID 0x6003

Axes

Buttons

Flydigi Vader 4 Pro

VID:PID 0x37d7:0x3001

Vendor flydigi

Interfaces

Report: extended (32 bytes, interface 0)

Match: byte[0] = 0x04

Fields

Button Map

Source: offset 7, size 4 byte(s)

Output Capabilities

uinput device name: Flydigi Vader 4 Pro | VID 0x37d7 | PID 0x3001

Axes

Buttons

Flydigi Vader 5 Pro

VID:PID 0x37d7:0x2401

Vendor flydigi

Interfaces

Report: extended (32 bytes, interface 1)

Match: byte[0] = 0x5a, 0xa5, 0xef

Fields

Button Map

Source: offset 11, size 4 byte(s)

Commands

Output Capabilities

uinput device name: Xbox Elite Series 2 | VID 0x045e | PID 0x0b00

Axes

Buttons

Force feedback: type=rumble, max_effects=16

HORI Horipad Steam

VID:PID 0x0f0d:0x00c5

Vendor hori

Interfaces

Report: bt (287 bytes, interface 0)

Match: byte[0] = 0x07

Fields

Button Map

Source: offset 5, size 3 byte(s)

Output Capabilities

uinput device name: HORI Horipad Steam | VID 0x0f0d | PID 0x00c5

Axes

Buttons

Lenovo Legion Go

VID:PID 0x17ef:0x6182

Vendor lenovo

Interfaces

Report: xinput (60 bytes, interface 0)

Match: byte[0] = 0x04

Fields

Button Map

Source: offset 18, size 3 byte(s)

Output Capabilities

uinput device name: Lenovo Legion Go | VID 0x17ef | PID 0x6182

Axes

Buttons

Lenovo Legion Go S

VID:PID 0x1a86:0xe310

Vendor lenovo

Interfaces

Report: gamepad (32 bytes, interface 6)

Match: byte[0] = 0x06

Fields

Button Map

Source: offset 0, size 4 byte(s)

Commands

Output Capabilities

uinput device name: Xbox Elite Series 2 | VID 0x045e | PID 0x0b00

Axes

Buttons

Force feedback: type=rumble, max_effects=16

Xbox Elite Series 2

VID:PID 0x045e:0x0b00

Vendor microsoft

Interfaces

Report: usb (64 bytes, interface 0)

Match: byte[0] = 0x01

Fields

Button Map

Source: offset 13, size 3 byte(s)

Commands

Output Capabilities

uinput device name: Xbox Elite Series 2 | VID 0x045e | PID 0x0b00

Axes

Buttons

Force feedback: type=rumble, max_effects=4

Nintendo Switch Pro Controller

VID:PID 0x057e:0x2009

Vendor nintendo

Interfaces

Report: bt_standard (49 bytes, interface 0)

Match: byte[0] = 0x30

Fields

Button Map

Source: offset 3, size 3 byte(s)

Output Capabilities

uinput device name: Nintendo Switch Pro Controller | VID 0x057e | PID 0x2009

Axes

Buttons

Sony DualSense

VID:PID 0x054c:0x0ce6

Vendor sony

Interfaces

Report: usb (64 bytes, interface 3)

Match: byte[0] = 0x01

Fields

Button Map

Source: offset 8, size 3 byte(s)

Report: bt (78 bytes, interface 3)

Match: byte[0] = 0x31

Fields

Button Map

Source: offset 9, size 3 byte(s)

Commands

Output Capabilities

uinput device name: Sony DualSense | VID 0x054c | PID 0x0ce6

Axes

Buttons

Force feedback: type=rumble, max_effects=16

Sony DualShock 4

VID:PID 0x054c:0x05c4

Vendor sony

Interfaces

Report: usb (64 bytes, interface 0)

Match: byte[0] = 0x01

Fields

Button Map

Source: offset 5, size 3 byte(s)

Report: bt (78 bytes, interface 0)

Match: byte[0] = 0x11

Fields

Button Map

Source: offset 7, size 3 byte(s)

Commands

Output Capabilities

uinput device name: Sony DualShock 4 | VID 0x054c | PID 0x05c4

Axes

Buttons

Force feedback: type=rumble, max_effects=16

Sony DualShock 4 v2

VID:PID 0x054c:0x09cc

Vendor sony

Interfaces

Report: usb (64 bytes, interface 0)

Match: byte[0] = 0x01

Fields

Button Map

Source: offset 5, size 3 byte(s)

Report: bt (78 bytes, interface 0)

Match: byte[0] = 0x11

Fields

Button Map

Source: offset 7, size 3 byte(s)

Commands

Output Capabilities

uinput device name: Sony DualShock 4 v2 | VID 0x054c | PID 0x09cc

Axes

Buttons

Force feedback: type=rumble, max_effects=16

Valve Steam Deck

VID:PID 0x28de:0x1205

Vendor valve

Interfaces

Report: main (64 bytes, interface 0)

Match: byte[1] = 0x09

Fields

Button Map

Source: offset 8, size 4 byte(s)

Commands

Output Capabilities

uinput device name: Valve Steam Deck | VID 0x28de | PID 0x1205

Axes

Buttons