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.