When do I need to flash my microcontroller?

You've built your keyboard. Maybe you'd like to test it for the first time, or maybe you've made some changes to your keymap and you'd like to flash the new firmware to your keyboard. In this article you'll learn when to flash your keyboard, and why.

Any non-split keyboard, or split keyboards with one controller

For keyboards that aren't split or for keyboards that only have one controller (and so only have one USB port), the answer is simple. You need to flash your keyboard before you first use it, and for every change you make to your firmware afterwards.

If you've ordered a custom assembled keyboard from splitkb.com, the default firmware should be flashed to your keyboard already when you get it.

Split keyboards with two controllers

When you've just built your keyboard, you'll need to flash both controllers with your firmware.

If you've ordered a custom assembled keyboard from splitkb.com, the default firmware should be flashed to your keyboard already when you get it.

Flash both halves when:

• You use either half as the main side interchangeably;
• You're using a newer version of QMK compared to what you're using now;
• You've made changes to what's displayed on the OLED display;
• You've made changes to the RGB underglow;
• You've made changes to key backlighting;
• You've made changes to what the rotary encoder does when you turn it;
• You've made changes to audio if the keyboard has a speaker per side;
• You've made changes to haptic feedback if the keyboard has a haptic feedback module per side;
• You've made changes to other custom hardware that's present on both sides.

Making changes also includes enabling or disabling the features listed above.

Flash only the main side when you only use that half as the main side and:

• You've made changes to the keymap.

It doesn't hurt to flash both sides just to be sure. The above are only guidelines so you'll save some time for convenience. If flashing only the main side does not give the result you've expected, flash both sides anyway.

Most often, you'll only make changes to the keymap, so if you only use one half as the main side (when you only connect the USB cable to one half), it's good enough to flash only that half.

Why is the firmware the same for both halves?

QMK knows to which half you've connected the USB cable. That half will be the so-called main side while the USB cable is connected. The other half, connected to the main side by a TRRS cable, is called the peripheral side. These terms are used in computer engineering to denote that one half has control over what happens, and the other listens to that half.

The reason you flash the same firmware to both halves is twofold. For one, it allows you to switch which side is the main side, simply by connecting the USB cable to the other half. The other reason is to keep it simple: you won't need to make and maintain two separate firmwares for your keyboard.

Why do I need to flash both sides?

When you've just assembled your keyboard, the reason is simple: a controller doesn't have any firmware on it by default, and both sides need to know what to do when they get power. Flashing firmware gives them the instructions so the controllers know that they are keyboards.

By default, the main side connects to the computer, and as far as the computer is concerned, only the main side exists. While the main side has to do it all, the peripheral half only has to do a few things:

• The peripheral side tells the main side which keys you've pressed.
• The peripheral side tells its own hardware what to do, like displaying images on the OLED display, or changing the color of the RGB underglow.

So, when you make changes to the keymap, nothing really changes for the peripheral side: it still only has to tell the main side which keys you've pressed, which are simply the coordinates of the key. The peripheral side tells the main side: the key at row 2, column 3 was pressed. What that means for the computer is determined by the main side, and so keymap changes do not concern the peripheral side.

When you make changes to the hardware, though, the peripheral side does need to know about it, so that the peripheral side knows how to handle those changes. If you change the text on the OLED, then the peripheral side needs to know what text to display; the main side doesn't tell that to the peripheral side. What exactly each half is responsible for is determined by QMK.