Troubleshooting

Things that go wrong during a build or in daily use, and how to fix them.

This page grows over time from real questions sent through the ask-a-question form on every wiki page. If you hit something that isn't covered here, that's the form to use — your question becomes the next entry.

During the build

Screen doesn't light up after first power-on

Most common cause is the battery connector. Check:

The MX1.25 connector is fully seated in the Waveshare JST socket.
Polarity is correct — red lead to the + side. Verify with a multimeter if you're unsure.
The battery itself isn't flat. Plug in USB-C and wait 10 minutes.

Also check the board works on USB-C alone, with the battery disconnected. If it does, the fault is in the battery wiring.

Scanner won't read QR codes

On the Receive screen, tapping Scan QR code does nothing or never captures a code. The scanner's UART RX and TX are easy to swap — try reversing them. Also check that the scanner is getting 3.3 V (not 5 V) and that all four wires are properly soldered. (There's no "scanner detected" check at boot — the scanner is only polled while you're on the scan screen, so a wiring fault shows up there, not as a startup warning.)

"timeout waiting for v2 card" when accessing the guest SD

You have the wrong SD breakout. The variant with a regulator or a level shifter needs ≥4.5 V on VCC and won't init on the gadget's 3.3 V supply. See the BOM "do NOT use" note. You need the bare 6-pin 3.3 V-only version.

Case parts don't fit together

The case is dimensioned around the exact off-the-shelf modules in the BOM. Substitutions don't fit. If you've used a different battery or a different SD breakout, you'll need to adjust the case design.

If you're using the exact BOM parts and it still doesn't fit, you probably printed with too much elephant's foot — try reprinting with a higher first-layer Z offset.

During first use

PIN screen accepts the PIN but then hangs

PBKDF2 takes ~1.7 seconds on the RP2350 to derive the KEK. The gadget isn't hung — it's deliberately slow. If it's still on the same screen after 10 seconds, something is wrong; reboot with PWR button and try again.

"New card inserted. Set up this card?" prompt on what should be my own card

The card looks empty to the gadget (its /secret/ material is missing). This is normal for a fresh card — tap Set up to initialize it. But if it's a card you'd previously used, something has wiped the secret folder, and there's no recovery path without your device secret backup.

Forgot my PIN

PIN screen → ? button (upper right) → "Restore using device secret backup". You'll need the device_secret shown on the gadget's first power-on. Scan the QR you saved, or type the hex.

If you don't have the device secret backup, you can't recover the card. The only path is Wipe card & start fresh, which destroys all pad data on it.

During day-to-day use

"Couldn't decode - unknown sender."

The message's MAC tag didn't verify against any of your contacts' receive pads, so the gadget can't attribute it to anyone. Possible causes:

The message was corrupted in transit (a QR scan error, or a typo when hand-entering hex).
The sender used the wrong contact's send pad (their bug, not yours).
The message is from someone you haven't done a key exchange with.
Someone tampered with the ciphertext between the sender and you.

The gadget doesn't tell you which of these happened — it can't. (A separate "Invalid code format - check what you typed." means the code is malformed before any pad is even tried — usually a mistyped or truncated hex entry.)

"Already decoded - received before." warning

You received a message whose offset range overlaps a range your receive pad's bookkeeping already marks as consumed. The content is still shown, but the warning means either: the sender resent the same QR, or you somehow restored an old SD card state. Treat with care.

Gadget appears frozen

Long-press PWR for ~5 seconds to trigger an AXP2101 hardware shutdown. Power back on with a short press. The hardware watchdog should normally reboot the device within 8 seconds before you'd need this — if you're regularly seeing freezes longer than that, send a question.

Battery icon shows charging but battery level doesn't increase

USB-C is supplying power but the battery isn't charging. Common causes:

The cable is charge-only (no data — but in this case, also no good for charging at proper current). Try a different cable.
The battery's protection circuit kicked in (very low cell voltage from being flat too long). Leave it on charge for an hour and re-check.
The MX1.25 cable connection to the battery is intermittent.

Asking a question

If your problem isn't listed here, use the form on any wiki page. Common questions land here over time.