What you’ll need
You don’t need any soldering tools or special hardware; just a computer, a cable, and the correct firmware file for your PCB. Before you start, gather these three things.
- QMK Toolbox: the flashing app. Free, Windows + macOS. Linked in the next step.
- The firmware file (.hex or .bin) for your PCB: grab it from the PCB’s page on this site, under the Downloads section. You will be linked to Github where our firmware resources are stored and downloadable.
- A USB cable: make sure that it supports data transfer and not power-only.
Note: ZMK firmware (used by wireless PCBs) is flashed differently. See the Flashing wireless PCBs guide instead.
Install QMK Toolbox
Download the latest stable release from the official GitHub page. Both Windows and macOS builds are signed, so you shouldn’t see warnings.
- Windows: download
qmk_toolbox.exe - macOS: download
QMK.Toolbox.pkg
Download from: github.com/qmk/qmk_toolbox/releases
Download the firmware
Each PCB has its own firmware build. Find yours HERE. Open your PCB’s detail page on this site, scroll to the Downloads section, and open the QMK Firmware link.
Note: a firmware file can be
.hexor.bin
Load the firmware file into QMK Toolbox
Open QMK Toolbox. You’ll see a window with a file path field at the top, a console area below, and a Flash button on the right.
Click Open (or drag the .hex or .bin file directly onto the Toolbox window). The path appears in the file-path field at the top.
Put the board in DFU mode
DFU mode (Device Firmware Update) is the special state your PCB enters to accept new firmware. There are three ways to get there, depending on what’s accessible on your board.
Method A - Reset button (recommended)
Most Mechlovin PCBs (apart from very early 2019-2020 models) have a physical reset button. Plug the board in via USB, then press the reset button. The console in QMK Toolbox should print something like:
*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)
Method B - Reset key combo on a built keyboard
Try one of these:
- Bootmagic reset: Hold down the key at (0,0) in the matrix (usually the top left key or Escape) and plug in the keyboard
- Bootloader reset: Hold down the key at (0,13) in the matrix (usually the Back Space) and plug in the keyboard
- Keycode in layout: Press the key mapped to `QK_BOOT` if it is available
Method C - Short the reset pads
If neither button nor keymap is available, you can briefly short the two RESET pads on the back of the PCB using tweezers or a paperclip.
Flash the board
If your PCB uses AVR-family MCU (Atmega32U4 or Atmega32A), make sure you choose the correct one from the MCU drop-down list. If it uses ARM STM MCU, ignore this.
With the firmware file loaded and the board in DFU mode, click the Flash button on the right side of the QMK Toolbox window. The console will print the progress. You should see something like:
*** Attempting to flash, please don't remove device
>>> dfu-programmer atmega32u4 erase --force
>>> dfu-programmer atmega32u4 flash adelais-v0.24.3.hex
>>> dfu-programmer atmega32u4 reset
*** Validating ... SUCCESS
*** Resetting
Important: While the flash is running (usually 5–10 seconds), do not disconnect the USB cable. If you do, you may need to reset and start over. Once the flash completes, unplug and replug the USB cable.
Verify it worked
Once flashing completes, the board reboots into the newly flashed firmware. Your computer should recognize it as a keyboard again. Open a text editor and type a few keys to confirm.
For a more thorough check and to configure your PCB, open the Mechlovin’ PCB Configurator or VIA web app. If the board is recognized and your keymap loads, the firmware is working correctly.
Note: Our Mechlovin’ PCB online configurator should recognize your PCB automatically. For VIA, you may need to load your PCB’s VIA JSON file from the Downloads section. After that, VIA webapp remembers your board between sessions.
Troubleshooting
Toolbox doesn’t detect the board
- Try a different USB cable. Many cables are charge-only.
- Try a different USB port. Hubs and front-panel ports can be flaky.
- On Windows, install the driver via the
Tools → Install Driversmenu in Toolbox. - Press the reset button again. The DFU window times out after about 10 seconds on some boards.
Flash starts but fails partway
- Unplug and replug the board, then retry. A flaky USB connection during write can cause this.
- Make sure no other software (VIA, Vial, another Toolbox instance) is talking to the board at the same time.
Board flashes but doesn’t type
- Confirm you flashed the correct firmware for your PCB
- Reset the EEPROM by holding the reset button while plugging in, then flash again.
- Check that your switches are seated all the way into the hot-swap sockets.