Troubleshooting
What you'll learn
- How to recognise the common failures from their symptoms
- Which problems are known and still unresolved
Find your symptom in the tables below. Each fix is what worked on the tested build.
Building and uploading
Section titled “Building and uploading”| Symptom | Cause | Fix |
|---|---|---|
Compile error 'GPIO' was not declared in this scope |
MCUFRIEND_kbv not patched for the ESP32 core 3.3.10 | Apply patch 1 |
Compile error implicit declaration of function 'esp_random' |
uBitcoin not patched for the ESP32 core 3.3.10 | Apply patch 4 |
| A library update and then new compile errors | Updating or reinstalling a patched library removes its patches | Re-apply the library patches |
| Upload fails: “Access is denied” or port busy | Another program (such as a serial terminal) has the port open | Close it. Only one program can use a port |
DevKit upload fails: Failed to connect to ESP32: No serial data received or Wrong boot mode detected |
The DevKit’s automatic reset doesn’t reliably enter download mode | Hold BOOT during the upload, then release and press EN (step 7). A 1–10 µF capacitor from EN to GND may fix it for good (untested here) |
Camera board upload fails: Invalid head of packet (0xF9) |
Not in download mode: the GPIO0 bridge wasn’t making contact at reset | Reseat the GPIO0-to-GND bridge, press RESET, retry |
Boards and wiring
Section titled “Boards and wiring”| Symptom | Cause | Fix |
|---|---|---|
DevKit loops at power-up with Failed to verify partition table or invalid header: 0xffffffff |
LCD_D0 on GPIO12, a strapping pin, makes the chip run its flash at the wrong voltage |
Move LCD_D0 to GPIO22 and apply patch 3. Don’t burn the flash-voltage eFuse |
| Uploads blocked whenever the shield is attached | LCD_RD on GPIO2, a strapping pin |
Move LCD_RD to GPIO21 (patch 2) |
| Taps land in the wrong place | Touch calibration is specific to each shield | Dev tests → Recalibrate, then copy the values into config.h (step 7) |
| No scans at all, camera console silent, and the DevKit receives lots of junk | The ground wire is on the camera board’s GND/R pin, which is tied to reset |
Move it to the GND next to the 5V pin (step 5) |
| The Scan test’s skipped counter goes up | GPIO34 floats while the camera board is off or starting |
Normal: the junk is thrown away. A 10 kΩ pull-up from GPIO34 to 3V3 keeps the line quiet (optional) |
Camera board reboots every few seconds with Detected camera not supported |
The camera’s ribbon connection | Unplug the power, reseat the camera ribbon, power up again |
Camera board resets with Brownout detector was triggered |
Its 5V supply dips | Power it from a separate 5V supply and keep the grounds connected |
Seeds and Sparrow
Section titled “Seeds and Sparrow”| Symptom | Cause | Fix |
|---|---|---|
| The public test phrase fails with “invalid checksum” | The twelfth word must be about, not a twelfth abandon |
See step 10 |
| The fingerprint after loading isn’t the one you noted | A wrong word, or a mistyped passphrase. A passphrase typo gives a different wallet with no error | Wipe & lock and load again, carefully |
Sparrow: announced block header at height … does not meet its claimed proof of work target |
Sparrow is in mainnet mode but connected to a signet server | Quit every Sparrow window and restart it with -n signet (step 9) |
| The device reads Sparrow’s animated QR very slowly | Sparrow’s frames are too dense for the camera | Set Sparrow’s QR density to its lowest. Keep the camera steady, with the code filling most of its view |
| Sparrow’s webcam can’t read the signed QR | The frames are too dense for the webcam | Use the device’s density button to switch to smaller frames |
| The device refuses: an input has no previous transaction | A multi-input transaction without the earlier transactions attached | See “Known unresolved problems” below |
Known unresolved problems
Section titled “Known unresolved problems”These are open. They are described as far as they’re understood, without guessing. The Known issues page has more detail, including a memory-safety bug in the Bitcoin library and how the firmware avoids it.
- Sparrow’s QR code leaves out the earlier transactions for multi-input spends. In testing, Sparrow’s saved transaction file included them, but its QR code didn’t, even with the device entry that Sparrow’s source code says should include them. The cause is unknown. The device then refuses, as designed. Workaround: save the transaction to a file in Sparrow and show it as an animated QR with the firmware’s
tools/psbt_show(needs Node.js). One multi-input transaction was signed and confirmed that way. - Random restarts. The DevKit has occasionally restarted by itself (a power-on reset, with no crash, watchdog or brownout message) while the screen was being tapped, including once during a review. Nothing was signed. It’s thought to be loose wiring or the USB cable, but that isn’t confirmed. Check your wiring and cable.
- Large single QR codes are untested. The camera has read single codes of up to 118 bytes. Transactions arrive as animated codes with small frames, which work, but a single dense code of 300 or more characters has never been tested.
- Long continuous scanning is unverified. Two minutes of non-stop scanning without a brownout wasn’t verified.
- Very low fee rates are cut short on the summary screen. 0.29 sat/vB shows as 0.2. The fee itself is shown exactly.
The security side of these, and the project’s other limits, are on Security and limits.