Troubleshooting the finished board

Here is the most reassuring fact in this book: nearly every problem a freshly built Lily58 can have is either a solder joint or a bent pin. Not a fried chip, not a ruined board, not a mystery. A joint or a pin. Both cost nothing to fix, and because you socketed the controller in Chapter 10, even the worst realistic case (a genuinely dead controller) costs one replacement board and thirty seconds of swapping, not a rebuild.

The other reassuring fact is that a keyboard fails in legible ways. One key, one row, one half, or everything: each pattern points to a different, specific place, because you know exactly how the signal travels. Switch, socket, diode, trace, controller pin, firmware, USB. A fault is just a break somewhere along that chain, and the symptom tells you which stretch of road to search.

So work like a repair tech: read the symptom, run the checks in the order given (they are ordered by likelihood and by effort), change one thing, retest. Do not shotgun five fixes at once, for the same reason the lemon-squeezer book gives about failed prints: if it works afterward, you will not know why, and you will not trust the board.

Keep the tools from Chapter 5 nearby: tweezers, the multimeter, the iron, and a browser tab with a keyboard tester open.

One dead key

The most common fault, and the one with the most satisfying fix rate.

  1. Pull the switch and look at its pins. This is the cause about 90 percent of the time on a hotswap board: one of the switch's two metal legs folded flat under the housing instead of entering the socket. Use the switch puller, pull straight up, and look at the underside. A bent pin is obvious. Straighten it gently with tweezers or pliers (they survive one or two straightenings), then reinsert while supporting the socket from below, as in Chapter 11. This fixes most dead keys on the spot.
  2. Tweezer-test the socket. Pins were straight? Bridge the empty socket's two contacts with tweezers, watching the tester. If a letter appears, the electronics are fine and the problem was switch seating (or, rarely, a dud switch: try a spare in that socket).
  3. Tug and reflow the socket. No letter from the tweezers? Flip the board and push each of the socket's two solder pads gently with a fingernail or the tweezers. Any movement at all means a cracked or cold joint. Even without visible movement, the cheap fix is to reflow both joints: touch the iron with a whisper of fresh solder to each pad for a second, as in Chapter 8. Retest.
  4. Check that key's diode. Still dead? Look at the diode belonging to that key. Is its orientation mark (the band or arrow) pointing the same way as its neighbours'? Are both its joints shiny and full, not grey and cratered? Reflow them, or if the orientation is wrong, desolder and turn it around (Chapter 8 again).
  5. Trace continuity with the multimeter. The last resort, and a genuine skill-builder. The walkthrough below shows the whole procedure on a real example.

A continuity walkthrough, told as a story

Say the K key is dead. Tweezers on the socket give nothing, the joints look fine, the diode looks fine. Time to let the multimeter tell the truth, because eyes lie about joints and meters do not.

Set the meter to continuity mode (the beep symbol, from Chapter 5) with the board unplugged from USB. The signal path for one key has three legs, so test three stretches:

First, socket to diode. One probe on the socket contact that leads toward the diode (follow the visible trace, or just try both), the other probe on the diode's near leg. Beep: that stretch is good. On our imaginary K key, it beeps.

Second, through the diode itself. Continuity mode often reads a diode in one direction only, which is fine, that is what a diode is for. Many meters have a dedicated diode mode showing a voltage drop around 0.6 for a healthy diode. Probe both ways; conduction one way and not the other means healthy. Our K diode passes.

Third, diode to controller. One probe on the diode's far leg, the other touching each pin of the controller socket in turn until something beeps (patience; there are 24). On the K key, nothing beeps on any pin. There is the break: between the diode and the controller. And the most common break on that stretch is not the buried trace, which almost never fails, it is the joint at either end. A close look under bright light shows the row's controller-header pin has a dull, grey joint with a hairline ring around the pin: a classic cold joint from Chapter 6. Ten seconds of reflow, the meter beeps, the tweezer test types a K, and the switch goes back in. Total time: fifteen minutes, most of it learning.

A whole row or column dead

Several keys dead in a line is actually good news: one shared thing serves them all, so there is exactly one fault, not five.

  1. Identify the shared line. Keys dead in a horizontal line share a row; a vertical line (on a columnar board like the Lily58, a finger's column) shares a column.
  2. Reflow the controller header joint for that line. Each row and column arrives at exactly one controller pin, through one joint on the header you soldered in Chapter 10. One cold joint there silences the whole line. Since you probably do not yet know which pin it is, the pragmatic move is to reflow all 12 header joints on that half; it takes three minutes and cures the majority of row/column faults.
  3. Find the exact pin, if you want to. The kit's schematic (a wiring diagram, usually a PDF in the kit's GitHub repository) lists which controller pin serves each row and column, and so does the Lily58's configuration file inside QMK's source (a file that literally lists pin names next to the words "rows" and "cols"). You do not need to read either fluently: search the page for "row" and match up the pin names printed on the controller board. Then continuity-test from any dead key's diode to that specific pin, as in the walkthrough.
  4. Check for a bridge. If instead of dead keys you get wrong or doubled keys along a line, look for a solder bridge between two adjacent header pins (Chapter 8 shows the wick fix).

An entire half dead

The half with USB works perfectly; the other half is a brick. The chain to suspect is everything between the two halves.

  1. Reseat the TRRS cable, both ends, with USB unplugged. Push until it clicks fully home. A half-seated TRRS plug is embarrassingly common.
  2. Check the cable is TRRS, not TRS. Count the rings on the plug's metal tip: three separator rings (four contacts) is TRRS and correct; two rings (three contacts) is TRS, an audio cable that looks identical and cannot carry the data line. This one cable mix-up may be the single most common "dead half" cause in the hobby.
  3. Try another cable. Any four-pole 3.5 mm cable works. Cables fail internally with no visible damage.
  4. Inspect and reflow the TRRS jack joints on both halves. The jack's pins are stubby and easy to have under-soldered, and the jack takes mechanical stress every time you plug in.
  5. Confirm the dead half's firmware. Plug USB directly into the dead half, alone. If it types (as the wrong hand, which is expected), its electronics are fine and the fault is in the link or the jacks. If it does nothing even on USB, reflash it.
  6. The hard question: was it hot-plugged? If the TRRS cable was plugged or unplugged while USB power was connected, and the half died at that moment, the controller may be damaged. This is the case the socket was bought for: swap in a spare controller (or the other half's, temporarily, after flashing) and see if the half revives.

Halves work alone, but not together

Each half types when it has the USB cable, but the far half is dead when connected by TRRS. This is the "entire half dead" chain minus the firmware step: it is the cable (TRS versus TRRS again, step 2 above), the jacks' solder joints, or, rarely, the handedness confusion covered under "wrong letters" below.

The computer does not see the keyboard at all

Nothing types, and the operating system shows no new device.

  1. Suspect the USB cable first. Many USB-C and micro-USB cables that come with gadgets are charge-only: power wires, no data wires, and no marking to warn you. Swap in a cable you know carries data (one that has synced a phone, for example), and try a different USB port, directly on the computer rather than through a hub.
  2. Check the bootloader responds. Double-tap reset on the USB half. On an RP2040 board, does the RPI-RP2 drive appear? If yes, the controller, its USB circuitry, and the cable are all fine, and the problem is the firmware: the file may be wrong for this controller or corrupted. Re-download and reflash, per Chapter 12. If the drive never appears with a known-good data cable, check the controller header joints, then suspect the controller board itself.
  3. On ATmega32u4 boards, the equivalent check is whether QMK Toolbox reports a device connecting during the eight-second bootloader window.

Keys type the wrong letters

The board types, but a key gives a different character than expected.

  1. Wrong keymap flashed? If the pattern of wrongness looks like an entirely different layout, you may have flashed a different keymap (or a different keyboard's firmware) than you thought. Reflash the file you intended, on both halves.
  2. A stuck layer? If letters come out as symbols or numbers, a layer key may be held down by a misseated switch, or a one-shot layer got latched. Unplug, replug, and test with the thumb keys untouched.
  3. Left and right swapped? If the left half types the right half's letters, the handedness is inverted: the firmware decided the wrong half is "left." With the default setup, just move the USB cable to the other half. To make your preferred side work permanently, use QMK's EEPROM handedness procedure from Chapter 12.
  4. Operating system layout. If punctuation in particular is scrambled, check the OS is not set to a different language layout. The keyboard reports key positions; the OS decides what they print.

One key types multiple letters, or letters appear you never pressed

Ghosting on a diode-per-key board points at one culprit: a diode soldered backwards. A reversed diode lets current sneak the wrong way through the matrix, so pressing certain combinations conjures phantom presses at other positions. Find the key at the intersection of the phantoms, check its diode's orientation mark against its neighbours, and reverse it (Chapter 8). A solder bridge between adjacent pads produces similar mischief; inspect under bright light.

A key chatters (one press, double letters)

If a key sometimes registers twice per press, the switch contacts are bouncing more than the firmware's debounce (the short wait that filters contact bounce) expects.

  1. Reseat or swap the switch. This is the hotswap payoff: pull the chattering switch, drop in a spare, done in a minute. Chattering is nearly always the individual switch, from a dust fleck or a manufacturing dud.
  2. Raise the debounce in firmware if several switches chatter, via a QMK setting (search the QMK docs for "debounce"). This needs the full toolchain, so try the switch swap first.

The OLED stays blank

  1. Check the jumpers. The Lily58's OLED needs solder jumpers bridged on the correct side of the board, done back in Chapter 10. If a screen never lived, this is the first suspect: confirm against the build guide that the bridged jumpers are on the same side as the components for that half.
  2. Reflow the four header pins on both the display and the board. The OLED header is a common cold-joint site because its pins are short.
  3. Is it enabled in firmware? The default Lily58 firmware drives the OLED, but some prebuilt or minimal firmwares ship with the display disabled. Flash a firmware known to include OLED support and retest before doing any more soldering.
  4. Screens themselves do occasionally arrive dead; if you bought a spare, swap it as the last check.

When to ask for help, and how to ask well

If you have run a symptom's full checklist twice and the board still misbehaves, stop and ask. The communities are friendly and have seen everything: r/olkb (the home of QMK-adjacent DIY boards), r/ErgoMechKeyboards (splits specifically), and your kit vendor's Discord server, where people know your exact PCB revision.

A good help post gets good answers. Include:

  • Sharp, well-lit photos of the actual joints in the suspect area, close enough to count pins. "It doesn't work" with no photo gets guesses; a photo often gets the answer in minutes, because experienced eyes spot a cold joint instantly.
  • Exactly which firmware you flashed (file name, where it came from, which controller you have).
  • The symptom in matrix terms: which keys, which half, one key or a line.
  • What you already tried, so nobody repeats your first hour for you.

Takeaways

  • Read the pattern first: one key, one line, one half, or nothing, and each pattern has its own short checklist. Run checks in order, change one thing, retest.
  • One dead key is a bent switch pin until proven otherwise. Pull the switch and look before touching the iron.
  • A dead row or column is one controller-header joint. A dead half is the TRRS chain. Wrong letters are firmware or handedness. Phantom letters are a backwards diode.
  • The multimeter's continuity beep settles arguments your eyes cannot. Trace socket, diode, controller pin, and the silence shows you the break.
  • Charge-only USB cables and TRS-instead-of-TRRS cables cause an outsized share of "my keyboard is dead" panic. Check cables before checking solder.
  • Never plug or unplug TRRS under USB power, and remember the socketed controller means even the worst case is a cheap swap, not a rebuild.
  • Ask for help with photos, firmware details, and what you tried.

👉 The board works. Now comes the part nobody warns you about enough: the two weeks where you type like it is your first day on earth, and everything after that, in Chapter 14.