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 master 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 master when you only use that half as the master 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 master 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 master (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 master while the USB cable is connected. The other half, connected to the master by a TRRS cable, is called the slave. 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 master, 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 master connects to the computer, and as far as the computer is concerned, only the master exists. While the master has to do it all, the slave only has to do a few things:
- The slave tells the master which keys you've pressed.
- The slave tells hardware local to that side what to do, like displaying things 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 slave: it still only has to tell the master which keys you've pressed, which are simply the coordinates of the key. The slave tells the master: the key at row 2, column 3 was pressed. What that means for the computer is determined by the master, and so keymap changes do not concern the slave.
When you make changes to the hardware, though, the slave does need to know about it, so that the slave knows how to handle those changes. If you change the text on the OLED, then the slave needs to know what text to display, the master doesn't tell that to the slave. What exactly each half is responsible for is determined by QMK.