Flashing firmware with QMK Toolbox

QMK Toolbox is the simplest way to flash a Mechlovin' PCB on Windows or macOS. This guide walks through installing the app, putting your board in flashing mode, and applying the downloaded firmware file (.hex or .bin). Total time about 5 minutes.

Platform · Windows · macOSDifficulty · BeginnerTime · ~5 minUpdated · 14 Sep 2025

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.

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.

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 .hex or .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.

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:

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

Flash starts but fails partway

Board flashes but doesn’t type