Calibration guide

Calibration teaches the keyboard where each key rests and how far it goes when fully pressed. Every switch's magnet, and the sensor under it, differs a little, so each key is measured on its own; the keyboard then works out every key's travel, the actuation point and rapid trigger from these two levels. This page walks through the whole process, how to check the result, and how to get a good calibration the first time.

Calibrate:

when you get a new keyboard (it works before, see Before the first calibration, but not tuned to your unit);
after swapping switches, since each switch's magnet differs;
after clearing the EEPROM (EE_CLR), which discards the stored calibration;
whenever a key actuates noticeably earlier or later than its neighbours.

Before you start

Open QMK Toolbox (or run qmk console). Calibration is guided by messages on the console, and messages printed while nothing is listening are lost.
Find the calibration key (MAG_CAL) and the calibration dump key (MAG_CAL_DUMP) in your keyboard's readme.md. They are usually on a layer, reached by holding a layer key.
Put the keyboard on a flat, stable surface, with nothing resting on it.
Take your time: calibration waits for you for up to 10 minutes.

Step by step

Press the calibration key (MAG_CAL). Calibration starts when you release it. Let go of all keys, including the layer key you held to reach it. The console prints:
```
Calibration mode started
```
While calibration runs, no keys are sent to the computer. A keyboard may show calibration with its LEDs (the Praxis HE lights all three white).
Keep your hands off the keyboard. The keyboard measures every key at rest:
```
Low level sensing initiated. Please wait.
Key (0,0) low level sensed as 2231
Key (0,1) low level sensed as 2054
...
```
The numbers are raw counts: the sensor's output voltage as the keyboard's analog-to-digital converter measures it, on a scale of 0 to 4095 (about 0.8 mV per count). They differ from key to key; what matters is how far a key's number moves between rest and fully pressed. If a key is touched, its measurement starts over, so it prints later. More about counts: Readings: from a magnet to a number.

When every key is measured:

Low level sensing done. Press keys for high level sensing.

Press every key fully down once, and release it. Each key prints when you release it:
```
Key (2,5) high level sensed as 3104
```
Press every key in the centre of its keycap, and firmly. Pressing a key again only prints if it went deeper.

Warning

Press each key once, and one key at a time. Press every key equally firmly: calibration takes each key's deepest reading as its fully pressed position, so if one key is pressed lightly and another hard, their calibrations differ and the keys will actuate at noticeably different heights.
When every key has been pressed:
```
Calibration done. Values saved.
```
The keyboard works normally again, with the new calibration already saved.

There is no way to end calibration early: it finishes when every key has been pressed. If it is still running 10 minutes after it started, it stops with:

Calibration timed out. Previous calibration kept.

Nothing changed: the keyboard keeps the calibration it had before. Start again when ready.

Checking the result

To see what the keyboard is using, press MAG_CAL_DUMP. The console lists the settings, then each key's rest level, bottom level and span (the difference), with where they come from, for example:

Calibration (format 1), actuation 60% (614, default)
Travel curve power, zero field 2048, exponent 3.00 (factory)
Rapid trigger off, distance 10% (default)
Key (0,0) rest 2231 (now 2233) bottom 3052 span 821 (stored)
...
Key (4,14) provisional, rest now 2158

(stored): your own calibration. (factory): the keyboard's factory calibration, because this key has none of its own. provisional: no calibration at all.
now is the key's current rest level, adjusted at every power-up and slowly over time; a few counts from the calibrated rest are normal.
default means you have not changed that setting.

After a calibration, every key should be (stored). Then compare the spans: keys of the same switch type have similar spans, so a key whose span is much smaller than its neighbours' was not pressed fully, or was only touched. On a Praxis HE most spans are between about 750 and 900 counts; a right Ctrl recorded from an accidental brush of the hand showed a span of 139. Such a key actuates far too early: calibrate again.

The table printed after the key lines is for board makers (it is how a factory calibration is made).

Tips and tricks

Press every switch at its centre, even keys with stabilizers. An off-centre press tilts the keycap and the switch stem sideways, so the magnet does not travel straight down over its sensor, and the key records a smaller span than it really has. Stabilizers on long keys (space bars, Shift, Enter, Backspace) keep the keycap level but do not remove this skew: press long keys in the middle too.
Keep other fingers and your palms off the keyboard. In the second part, a key counts as pressed once it moves a small part of its travel (on a Praxis HE, 100 of its roughly 800 counts), so a light brush of another key is recorded as that key's fully pressed position. Rest your hands beside the keyboard between presses, and watch the console: a high level sensed line for a key you did not mean to press gives it away.
Fix a brushed key in the same run. Pressing a key again updates its calibration if it goes deeper, so press a brushed key fully before you press the last key. Once the last key has been pressed, calibration ends; then run it again.
Go in a fixed order — row by row, left to right, long keys last — so that no key is forgotten and each is pressed once. The console does not list the keys still waiting.
Press all keys the same way, fully down, as you would bottom them out when typing. The deepest reading of each key becomes its bottom, so pressing some keys harder than others makes them actuate at different heights.
Let go of the layer key. Calibration starts when the calibration key is released and waits up to 3 seconds for every key to come up. A key still held after that is measured at its pressed level.
Keep a dump of a good calibration. Save the MAG_CAL_DUMP output after a calibration you are happy with; comparing a later dump with it shows at once which key changed.

Before the first calibration

A new keyboard works before it is calibrated, so the calibration key can be reached:

if its firmware carries a factory calibration (taken on a reference keyboard, as on the Praxis HE), keys work normally, just not tuned to your unit;
otherwise keys work provisionally: a key registers once its sensor reading has moved a fixed amount from rest, partway down, with no adjustable actuation point; keys may flicker near that point. This is only meant to get you to the calibration key.

Calibrate anyway for values that match your keyboard.

Stored calibration

Calibration is saved on the keyboard and survives unplugging and firmware updates (one exception: the first update to firmware with MAGDA as a QMK community module stores calibration and settings in a new place, so the keyboard starts from its factory calibration and default settings, and a VIA keymap resets; calibrate once after it). To recalibrate, run it again: the new values replace the old ones. There is no need to clear anything first.

Troubleshooting

Calibration never finishes. It waits until every key has been pressed. Look at the console: the keys without a high level sensed line have not been registered yet; press them fully. During the first part, a key that is being touched keeps restarting its measurement: keep your hands off until Low level sensing done.
Calibration timed out. Nothing changed; start again and press every key within 10 minutes.
One key actuates much earlier than the others after calibrating. Its span in MAG_CAL_DUMP is probably much smaller than its neighbours': it was brushed or pressed lightly. Calibrate again.
A bad calibration makes the keyboard unusable, including the calibration key: clear the EEPROM; see Troubleshooting.