Magnetic Switches: Rapid Trigger

Rapid trigger is a feature of analog magnetic keyboards built on the MAGDA library (for example the Praxis HE). These keyboards measure how far each key is pressed, not only whether it is pressed, and rapid trigger uses that: a key presses and releases according to the direction it moves, instead of at fixed heights.

What rapid trigger does

On an ordinary keyboard, and on MAGDA with rapid trigger off, every key has two fixed heights: it presses when it goes below the actuation point and releases when it comes back above a slightly higher release point. To press the same key twice you must lift it above the release point in between, and any movement between the two heights changes nothing.

With rapid trigger on, after the first press the key follows its movement:

moving up by the rapid-trigger distance releases it, wherever it is;
moving down by the same distance presses it again, wherever it is.

depth
 ▲ top of the keystroke
 │
 │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─   actuation point (first press only)
 │    ╲         ╱╲         ╱
 │     ╲       ╱  ╲       ╱
 │      ╲_____╱    ╲_____╱
 │   pressed │released│pressed │ released
 ▼ bottom                time →

A key can therefore be pressed, released and pressed again with small movements deep in the keystroke, without coming back up. This is mostly used in games, where letting go of a direction key registers as soon as the finger starts to lift.

How it works in MAGDA

First press: at the actuation point, as with rapid trigger off.
While pressed: the keyboard follows the deepest point the key reaches. When the key rises by the distance above that point, it releases.
While released: it follows the highest point since the release. When the key goes down by the distance below that point, it presses again. This works anywhere below the reset point, including above the actuation point.
Back to normal: when the key rises above the reset point, slightly above the actuation point, it is fully released, and the next press needs the actuation point again.

The reset point is the same as the release point with rapid trigger off (about 6 % of travel above the actuation point). Above it, rapid trigger does not apply. Some keyboards offer "continuous" rapid trigger, which keeps following the key up to the very top of the keystroke; MAGDA does not.

Rapid trigger applies to all keys at once.

Turning it on and off

Keycode	Description
`MAG_RT_TOG`	Toggle rapid trigger for all keys

With the keycode: where it sits depends on the board's keymap (on the Praxis HE: hold MO(1) and press R).
From a configurator app, where the keyboard supports one: MAGDA exposes rapid trigger as an on/off setting, which an app such as VIA can show as a switch (on the Praxis HE's VIA build: Rapid trigger in the Magnetic switches menu).

Each change prints Rapid trigger on or Rapid trigger off on the console (QMK Toolbox, or qmk console). The setting is saved on the keyboard and survives unplugging and firmware updates.

A board may show the state with an indicator; the Praxis HE lights its LED D4 while rapid trigger is on. See the board's readme.md.

A key that is being held when rapid trigger is switched keeps its current behaviour until it is fully released, so switching never presses or releases a key by itself.

Adjusting it

Two settings shape rapid trigger:

The actuation point sets where the first press happens, and with it the reset point. It is the same setting as with rapid trigger off: the MAG_ACT_UP / MAG_ACT_DN keycodes, or a configurator app where the keyboard supports one (10–90 % of travel).
The distance sets how far the key must move up to release, or down to press again: 1–20 % of key travel in 1 % steps. It has no keycode: it is changed from a configurator app, where the keyboard supports one (e.g. a slider in VIA). The default is set by the board (6 % unless the board changes it; the Praxis HE uses 10 %), and keyboards without configurator support keep it. Each change prints e.g. Rapid trigger distance 4%.

Percentages are fractions of the physical keystroke, converted from the sensor reading with a model of the magnet's field, calibrated per key. They are approximate.

A smaller distance makes the key react to smaller movements, but also to sensor noise. Near the top of the keystroke a small movement changes the sensor reading very little, so a very small distance can make a key held still release or press again by itself. How small a distance works depends on the board; on the Praxis HE no such events were seen down to 1 %. To find a comfortable value, start at the default and lower the distance step by step; if a key held still (deep in the keystroke, and just below the actuation point) starts to release or re-press on its own, or keys register while you are not touching them, go back up.

The settings in use, including rapid trigger and its distance, are printed by MAG_CAL_DUMP, e.g. Rapid trigger on, distance 6% (default).

Troubleshooting

A key releases or presses again by itself while held still: the distance is too small for this keyboard's sensor noise. Raise it.
A key does not release when lifted a little: the movement is smaller than the distance, or rapid trigger is off (check the indicator or the console). Lower the distance, or switch rapid trigger on.
Rapid trigger stops working near the top of the keystroke: above the reset point the key behaves normally, by design. Lowering the actuation point (pressing earlier) moves the reset point up with it.
After flashing older firmware (without rapid trigger), the actuation point or the key response is wrong: older firmware does not know the rapid-trigger settings stored alongside the actuation point and the field exponent. Clear the EEPROM (EE_CLR) and calibrate again.
EE_CLR switches rapid trigger off and returns the distance to its default, along with all other stored settings.

For board makers

The behaviour, storage and interfaces are specified in the MAGDA architecture; how to test and tune a board is in the maker guide.

Defaults (config.h, #ifndef guarded): MAG_RT_DOWN_DEFAULT and MAG_RT_UP_DEFAULT (61 travel units of 1023, 6 %; Praxis HE: 102, 10 %) are the distance used until a user sets one; MAG_HYSTERESIS_DEFAULT (64) sets the reset point below the actuation point, shared with the release point in fixed mode.
Distance and noise. The distance must stay larger than the filtered sensor noise in raw counts (ADC counts; see How magnetic switches work), and a given distance is the fewest raw counts near the top of the keystroke (just below the reset point) and on keys whose rest reading is closest to the sensor's zero-field output. Compute it for your board from a calibration (MAG_CAL_DUMP) with the noise-margin method in the MAGDA architecture, section 3.2, then test on hardware. On the Praxis HE, a distance of 5 % near the top of the keystroke spans 6–15 raw counts (smallest key to median) against about 10–13 counts of filtered idle noise, yet a sweep down to 1 % showed no extra events; the method is therefore conservative for rapid trigger, and the hardware test decides.
Indicator hook. Override the weak hook to show the state; it is called once at start-up with the stored state and on every change:

void mag_rapidtrigger_kb(bool active) {
    // e.g. light an LED while rapid trigger is on
}

Configurator apps. Through QMK's VIA protocol: value ids MAG_VIA_RAPID_TRIGGER (3, on/off) and MAG_VIA_RT_DISTANCE (4, percent) on the custom channel, handled by mag_via_command; add a toggle and a range (1–20) item to the board's VIA JSON, and MAG_RT_TOG to its custom keycodes after MAG_ACT_DN.
Storage. The on/off state and the distance use spare bits of the stored actuation point and field exponent, so adding rapid trigger did not change the datablock format.