What you’ll need
To follow this guide you’ll need:
- A Mechlovin PCB running its latest firmware: all of our PCBs come flashed with the latest firmware to the date of fulfillment. You can download your PCB’s firmware from its dedicated page on this site and refer to this guide: Flashing firmware with QMK Toolbox.
- A Chromium-based browser: Chrome, Edge, Brave, or Opera. Our webapp talks to the board through WebHID, which Firefox and Safari don’t support.
- A USB cable that supports data: the same cable you used to flash. Charge-only cables won’t work.
Mechlovin’ Configurator runs entirely in your browser, there’s nothing to install. Go to config.mechlovin.studio and you’ll land on the main KEYMAP screen.
Connect your keyboard
Plug your keyboard into the computer, then in Mechlovin’ Configurator click Devices/Pair new device (top left of the screen). Your browser opens a small pop-up listing connected devices.
Select your keyboard from the list and click Connect. Mechlovin’ Configurator reads the current layout off the board and draws it on screen. There’s no need to load a jsondraft definition.
Find your way around
With the board connected, there are four items on the main menu up top:
- Keymap: the main view, where you remap keys.
- Lighting: RGB controls, if your PCB supports them.
- Macros: record a sequence of keystrokes onto a single key.
- Key Tester
These functions are drawn to the main screen for ease of access:
- Export & Import: export your layout to a file or load one back.
- Layout: toggles for different layouts that your PCB supports. For example, Split Backspace, ANSI/ISO Enter.
Remap a key
- Make sure you’re on Layer 0 (the base layer) using the layer buttons (top-left).
- Click the key on the on-screen keyboard that you want to change - it highlights.
- Pick the new key from the key set shown below the board.
The change is written to the board immediately. Press the key to confirm it now does the new thing.
If you can’t find a key in the default BASIC set, look through the other categories (Applications, Special and so on).
Work with layers
A layer is an additional set of assignments that activates while you hold, or after you tap, a special key. That’s how a compact board fits arrows, function keys, and media controls without extra keys.
To set up a layer key:
-
Select the key you want to use as your “Fn” key (many builds use Caps Lock or a key near the spacebar).
-
In the key set, open the Layers category.
-
Choose a layer action. The two you’ll use most are:
- MO(1) - momentary: the layer is active only while you hold the key.
- TG(1) - toggle: tap to switch the layer on, tap again to switch it off.
-
Now click the Layer 1 button at the top left and remap keys. For example, put arrows on WASD and media keys on the number row.
Note: Keys you leave untouched on an upper layer fall through to the layer below, so you only need to fill in the keys you actually want to change.
Record a macro
A macro types a whole sequence from one key, handy for an email address, a Discord command, or a shortcut.
- Open the Macros tab on the top main menu and pick a slot (M0, M1, …).
- Type or record the sequence you want.
- Save it, then go back to Keymap, open the Macro category in the key set, and assign
M0to any key.
Note: Keep macros short and avoid storing anything sensitive like passwords. A macro is plain text on the board and offers no security.
Adjust lighting
If your PCB has per-key or underglow RGB, the Lighting tab lets you change the effect, brightness, color, and speed. Move the sliders and the board updates live. These settings save to the board just like your keymap.
Note: No Lighting tab? Your PCB either has no lighting or the current firmware build doesn’t expose it. That’s expected on many models.
Back up your keymap
Because your layout lives on the board, backing it up allows you to restore everything instantly after a firmware update or on a new board.
Click Export on the main screen and keep the .json file somewhere safe.
To restore later, come back to the main screen and click Import
Note: Re-flashing firmware can reset the board’s memory to the layout’s defaults. Save a backup before you re-flash, then load it back afterwards.
Troubleshooting
Mechlovin’ Configurator doesn’t list my keyboard in Devices
- Make sure you’re in Chrome or Edge. Firefox and Safari can’t connect.
- Try a different USB cable (charge-only cables won’t work) and a different port.
- Confirm the PCB is running the latest firmware from this site.
My changes don’t stick
Changes save automatically; there’s no Save button for remapping. If a key reverts, you may have edited it on the wrong layer. Check the layer buttons.
- If the board behaves erratically, reset its memory by holding the reset button while plugging in, then re-load your saved layout.
A remapped key does nothing
- Open Key Tester and press it. If nothing lights up, the switch may not be seated in its socket; if it lights up but types the wrong thing, remap it again on Layer 0.