We receive quite a few e-mails from customers about troubleshooting their keyboards because something is not functioning the way they are expected to. Since there are so many parts involved, it's important to find out what part is causing trouble and see what can be done to make it function properly.
This article will help you narrow down what the problem is, and provide basic guidance on helping you rule out common issues.
The suggestions I make may sound trivial, irrelevant, useless, or annoying, but I have resolved many customer issues where the problems were things outlined in this article. I strongly recommend you go through the boring stuff, even if you think they have nothing to do with your problem.
For further help
If you cannot perform the steps we provided here for any reason, you can e-mail us and send your board in for us to diagnose and troubleshoot for you.
While you're free to e-mail us for help (without sending your board in), we may not be able to respond quickly enough for your needs. In the meantime, you can try to search and ask in the following communities for help and advice:
- Reddit (links TBD) - any you find should have a thread you can ask questions in
- Discord (links TBD) - any you find, if it's active, will have a #help channel you can ask questions in
Testing your setup
Sometimes, your setup is not compatible with your keyboard and a part of it is causing your problems. These problems are often related to power and data transfer and can cause issues such as:
- Delays in keypresses
- Keys triggering improperly
- Keys triggering multiple times
- Board is not working at all when plugged in
- Lighting isn't functioning
- Your board will suddenly stop working and you have to replug the board regularly
Rule out power issues
- Plug your keyboard into a port directly connected to your device (not a hub). Some boards require a lot more power than what a hub can deliver.
- Change the cable you're using. Some cables are not made to deliver a lot of power to boards that require more power- this is especially true for prebuilts and boards with lighting!
Change the device
- Try a different computer
- Try a device with a different OS (Windows is usually least problematic)
Testing key functionality
This test checks to see whether the pads on your PCB that connect your switches to the PCB are working. You can do this test on both a soldered and hot swap PCB.
I recommend this test if:
- Specific keys are not triggering at all when pressed
- Keypresses of one key are triggering multiple keys - these are often due to shorts
In general, it's good practice to test your PCB with the tweezer test when you get it and before you start installing switches or building your board.
How to test your PCB:
- Disassemble your board and remove the assembly (plate+switches+PCB) from the keyboard case.
- Plug in your keyboard. You may also need to remove the daughterboard if your keyboard uses one, so that you can plug in the board outside of the case.
- I recommend plugging your board into a USB port directly connected to your computing device if possible.
- Open up a key tester (you can use the one available here!)
- Flip over your PCB.
- Use tweezers to connect the circuit for each switch- each end of the tweezer needs to touch the holes where the switch legs would connect to. This is also helpful if you have a hot swap PCB- for these, you can touch the metal area that come into contact with the switch legs, or the two pads on the side.
- As you go through each key, check the tester software to ensure something is being triggered- hopefully the correct key it is assigned to.
Remap tricky keys
Some keys do not show up on testers and you will want to re-map the key to something that will show up so ensure it is functional. These keys include:
- Bottom row keys
- fn / function or layer keys
- F-row keys
- Nav cluster keys
If your board already supports VIA out of the box, this is easy to do. You can use the web app- it's pretty intuitive to use! Just click the key on the diagram that is not responsive, then select another key (I like to use a random letter such as "a") to map to it.
Now flip your board over and do the tweezer test again. If it works, after remapping your board is functional, but you may need to reach out to support channels and communities to understand better why it did not function the way it did. Sometimes, it's simply your OS doesn't support that function.
Replacing sockets and switches
If the tweezer test shows the pad/key on the PCB is functional, the problem may be the switch or the socket it's connected to.
For hot swap boards:
- Remove the switch and install a different switch.
- If the replacement switch works, it was likely the switch causing the problem. Reasons why may be:
- The switch leg was bent and needs to be bent back with flat-head pliers (you can use other tools, but this works best in my experience). Once bent back, you can install it again to see if it still works.
- The switch leg was pushed into the housing. This is common with switches that have clear housings (including smokey ones) as the material is soft and doesn't hold the leg in place well. You can use tweezers or pliers to pull the leg back out. In my opinion, these switches are best used in soldered builds and not intended for hot swap builds.
- Check the hot swap socket. It may need to be replaced.
- The socket pins may not be touching the switch legs. Using tweezers, gently try pushing the pins that hold the switch leg back in from the back side of the PCB, then install the switch- see if it makes contact better.
- If you can't make the socket pins touch the legs, try replacing the socket with a new one. You will need to know how to and have soldering tools to do this, and you will need to purchase replacement sockets- note that sockets are not always interchangeable be sure you purchase the right ones (Kailh sockets, Gateron sockets, Mill-Max sockets, etc.)!
For soldered boards:
- Check the soldering work on the affected switch. You may need to reflow and resolder it.
- Remove the switch and replace it with another switch.
- Be careful if you are desoldering with a desoldering pump or gun as you can potentially lift the pads and rip the traces!
- The switch can be removed without desoldering tools using an iron and a wick. Use the wick to remove as much solder as possible. Hold the switch from the front side with a switch puller. Apply the iron to the back side on the switch pin, and gently wiggle the switch back and forth while pulling, and switching the iron between the two soldered switch pins, until the switch is out.
When your keypresses are triggering other keys, it's likely due to a short- something is touching an area that is causing those keys to be pressed.
If you're experiencing shorts, take note of:
- What keys are you pressing when you notice other keys being pressed unintentionally?
- What keys are unintentionally being triggered? Are they always the same keys?
If you performed the previous tests and everything is fine, the problem may be the case.
- Try using your board unassembled to see if problems are still occuring.
- Then, reinstall the assembly into the case.
- If you no longer experience issues, it may be because your reassembly resolved the problem (something in the case touching the PCB may no longer be touching it)
If you are still experiencing issues once the assembly is back in the case, then something in the case is likely the culprit.
- First, if your assembly is hot swap, I recommend ensuring your switches are secured tightly onto the PCB and plate, especially if you are using flexible PCBs such as polycarbonate.
- The bottom of your PCB may be touching metal on the case. This may be the case bottom itself or a screw post.
- If you are using screw-in stabilizers, add washers between the PCB and the screw.
- Add a layer (eg. static-free foam) between the bottom of the case and the PCB.
- Your build may be too tight. You may want to remove a layer of dampening material. See if
- Flex: Flex features such as soft gasket mounting, soft plates, and flex cuts in the PCB may be causing the PCB to touch the case bottom. Try not to overdo it with the flex and see if it still happens.
Still having problems?
If you are still experiencing problems, you might need real help. Take a photo of the back side of the PCB and send it to someone for diagnosis help (like us!).