Skip to content

Magnetic Switches

MAGDA (Magnetic AnaloG Distance Analyzer) is the firmware library behind analog magnetic keyboards such as the Praxis HE. This page explains how to use such a keyboard: calibrating it, setting where keys actuate, and fixing common problems. Where a key or setting sits on a particular keyboard is in that keyboard's readme.md.

Pages in this section:

  • Calibration guide: calibrating step by step, checking the result, tips and tricks.
  • How magnetic switches work: how the keyboard measures a key, from the basics (sensors, ADC, raw counts), the travel curve, hysteresis and noise.
  • Rapid trigger: pressing and releasing by the direction a key moves.

Building your own board: the Magnetic Switches Guide (under Keyboard Building).

What an analog keyboard does differently

Each key carries a small magnet, and a sensor under it measures how far the key is pressed, continuously, not only whether it is pressed. The firmware turns that measurement into key presses:

  • Calibration teaches the keyboard each key's released and fully pressed positions. Every key differs a little, so each key is calibrated on its own.
  • The actuation point is how far a key must go down to count as pressed. You choose it, for all keys at once.
  • Rapid trigger (optional) presses and releases keys by the direction they move instead of at fixed heights; see Magnetic Switches: Rapid Trigger.

Calibrating

Calibration is done on the keyboard itself, guided by messages on the console (QMK Toolbox or qmk console): press the calibration key (MAG_CAL), keep your hands off while the keyboard measures every key at rest, then press every key fully once. It is saved on the keyboard and survives unplugging and firmware updates. A new keyboard works before its first calibration, from a factory calibration or provisionally.

The whole process, how to check the result with MAG_CAL_DUMP, and tips for a good calibration: Calibration guide.

Actuation point

The actuation point is how far a key must travel before it registers, as a percentage of its full travel: 10 % presses very early, 90 % needs an almost full press. A key releases a little above its actuation point (about 6 % of travel higher), so a key held right at the actuation point does not flicker between pressed and released.

Set it for all keys:

Keycode Description
MAG_ACT_UP Actuate deeper: +5 % of travel per press, up to 90 %
MAG_ACT_DN Actuate earlier: −5 % of travel per press, down to 10 %

Each press prints the new level, e.g. Actuation 55%. The level is saved about a second after the last change. The default depends on the keyboard (50 %, or as set by the board; the Praxis HE uses 60 %).

The percentages are converted from the sensor readings with a model of the magnet's field, using each key's calibration, so they follow each key's own range and stay right after recalibrating. They are approximate. Very low levels make keys register at the lightest touch.

A key that is held down while the level changes keeps its old level until it is released, so changing the level never presses or releases a key by itself.

Rapid trigger

With rapid trigger on, a key releases as soon as it starts to rise and presses again as soon as it goes back down, anywhere in its travel, instead of at fixed heights. MAG_RT_TOG switches it on and off; the distance it reacts to can be changed where the keyboard supports a configurator app (below). How it works and how to adjust it: Magnetic Switches: Rapid Trigger.

Settings from a configurator app

MAGDA exposes its settings and keycodes through QMK's VIA protocol, so dynamic keymap and configurator apps that speak it, such as VIA, can offer controls for them: sliders, switches, and the MAGDA keycodes to place on keys. Whether your keyboard supports this is up to the keyboard: it needs firmware built with that support and a matching definition for the app. The keyboard's readme.md says what it offers and where the controls are (the Praxis HE's VIA build has a Magnetic switches menu).

The settings MAGDA exposes:

  • Actuation point: 10–90 %, in 5 % steps; the same setting as MAG_ACT_UP / MAG_ACT_DN.
  • Field exponent: a parameter of the model that converts sensor readings to key travel, times 10 (30 = 3.0). The keyboard ships with a factory value; change it only if you have measured your switches. Clearing the EEPROM (EE_CLR) restores the factory value.
  • Rapid trigger (on/off) and rapid-trigger distance (1–20 %): see Magnetic Switches: Rapid Trigger.

Changes apply immediately and are saved, the same as with the keycodes. On a keyboard without configurator support, the keycodes are the way to change settings, and settings without a keycode (field exponent, rapid-trigger distance) stay at the keyboard's defaults.

Keycodes

Keycode Description
MAG_CAL Start calibration (on release)
MAG_CAL_DUMP Print the calibration and settings in use on the console
MAG_ACT_UP Actuation point +5 % of travel (up to 90 %)
MAG_ACT_DN Actuation point −5 % of travel (down to 10 %)
MAG_RT_TOG Toggle rapid trigger
MAG_DUMP Toggle a stream of raw sensor and travel values on the console (for troubleshooting)

Messages appear only on keyboards built with the console enabled.

Troubleshooting

  • A key does not register, or registers much too early or late. Check it with MAG_CAL_DUMP: provisional, (factory) or a much smaller span than its neighbours means it needs calibrating. Calibrate again, pressing that key fully and in the centre (Calibration guide). If all keys feel early or late, change the actuation point.
  • Keys register by themselves, or a held key flickers, at a very low actuation point: raise the actuation point.
  • Calibration never finishes or times out: see Calibration guide: Troubleshooting.
  • A bad calibration makes the keyboard unusable, including the calibration key: clear the EEPROM with EE_CLR (its position is in the keyboard's readme.md). This discards the stored calibration: the keyboard returns to its factory calibration, or to provisional keys if it has none. Then calibrate again. Clearing also resets the actuation point, rapid trigger, the field exponent, other QMK settings and a VIA keymap. If even EE_CLR cannot be reached, enter the bootloader (see the keyboard's readme.md) and flash; note that flashing alone does not clear the calibration.
  • After swapping switches, keys register at the wrong depth: calibrate again.

More