Skip to main content

Troubleshooting

Common issues and solutions for Lightning Piggy

Classic refers to the original e-paper Lightning Piggy running C++ firmware.

MicroPythonOS refers to the newer touchscreen version running MicroPythonOS.

Getting Started

Creating an LNbits Wallet

We recommend setting up LNbits on your own node such as a Raspiblitz, Start 9 or an Umbrel. Please follow the set-up instructions provided by the node provider.

Connecting your device

Nothing happens when I plug the device into the computer.

Ensure you are using a USB cable that can transmit data. Many micro USB cables only supply power and lack data transmission capabilities. Often, these cables have no distinguishing markings, so the simplest method to determine if your cable supports data transfer is to connect a memory device (like a data drive) to the computer using the cable and check if the computer recognizes the data drive.

Sourcing Parts MicroPythonOS

WaveShare ESP32-S3-Touch (2 inch screen) — including the optional camera makes setup a breeze: Waveshare

Flashing the Firmware MicroPythonOS

Flash MicroPythonOS to your compatible device and then install the Lightning Piggy app via the built-in app store.

Sourcing Parts Classic

LILYGO T5 V2.3.1 (2.13 inch screen) e-paper device: AliExpress

Flashing the Firmware Classic

Use our custom built web installer to flash the firmware to the device.

Serial port access errors Classic

Failed to open serial port error when trying to flash firmware.

This indicates a permission restriction. On Linux/macOS, run sudo chmod 777 /dev/ttyUSB* to grant access. On Windows/macOS, install drivers if prompted — Linux systems typically include the necessary drivers by default.

Browser extension conflicts during flashing Classic

JavaScript errors like "Trying to access beyond buffer length" appear during firmware installation.

Ad blockers or browser extensions can interfere with the web installer. Disable extensions for the installer page, or use an incognito/private window. The installer is tested on Google Chrome (Linux, macOS, Windows).

LILYGO TTGO T5 2.66 inch E-paper device Classic

The device does not turn on (device leds stay dark) when connected to my computer.

  1. Check you have a USB to TTL (T-U2T) connector connected between the device and your USB cable.
  2. Check the device is not faulty by connecting it to a power supply, instead of the computer. The red power led should light up.

Connectivity & Configuration

Wallet connection issues with Coinos

The device shows "null" or fails to connect when using Coinos wallet.

This issue was resolved in firmware version 6.1.0. Update your device to the latest firmware via the web installer. See GitHub #30

Connection errors when fetching balance MicroPythonOS

The device shows errors such as -202, 29312, or ECONNRESET when trying to connect to your LNbits server.

The ESP32's TLS library (mbedTLS) does not support ECDSA certificates, which some servers issue by default. If your LNbits server uses a reverse proxy like Caddy, you may need to force RSA certificates. In your Caddyfile, add a tls block with key_type rsa2048 to the relevant site:
your-lnbits-domain.com {
    tls {
        key_type rsa2048
    }
    reverse_proxy ...
}

After updating, restart Caddy and delete any cached ECDSA certificates so a new RSA certificate is obtained. You can verify the fix by checking that openssl s_client -connect your-server:443 shows "Server public key is 2048 bit" and the issuer contains "R" (RSA) rather than "E" (ECDSA).

WiFi connection issues after waking from sleep Classic

The device fails to reconnect to WiFi after waking from sleep mode.

Ensure your WiFi access point is stable and within range. If the device shows connection errors after waking, press the reset button to force a fresh connection attempt. You can also try positioning the Piggy closer to your router. See GitHub #34

Default configuration login credentials Classic

I'm trying to connect to my Lightning Piggy and I don't know the default credentials.

The web address and login credentials are displayed on the Piggy's screen. The default username is piggy and the default password is oinkoink.
Lightning Piggy Configuration Login
Lightning Piggy Configuration Login

Configuration common mistakes Classic

Device won't connect to wallet after configuration.

When configuring your Piggy, enter only the hostname (not the full URL with https://). Note: For MicroPythonOS piggies the full https:// URL is used. Settings are case-sensitive — use YES not Yes. Apply case sensitivity to timezone and currency fields too.

Display & QR Codes

Device Display Information Classic

The screen only displays "0 sats" i.e. there is no QR code on the screen to scan.

If using LNbits, check that you enabled and configured the LNURLp extension during the wallet set-up.

"NOBAT" is displayed on the screen, even though a charged battery is connected.

The system's battery detection relies on heuristics and is not always 100% accurate. Rapid voltage fluctuations lead to an assumption that the device is not on battery power, while very stable voltage suggests that it is running on the battery. If the battery is charged and you have a power cable connected, try disconnecting the power cable. Alternatively, if you wish to power the device by an external source (USB power), disconnect the device battery.

LNBits QR code does not change to Lightning Address Classic

After configuring NWC with a Lightning Address, the display still shows the old LNBits QR code.

This can occur when both LNBits and NWC credentials are configured. To display your Lightning Address QR code, ensure only NWC credentials are set. Access the Piggy Config interface (connect to the device's WiFi access point) and clear the LNBits server URL and invoice key fields, then save and restart. See GitHub #1

QR Code Scanner shows white screen (app) Classic

The QR scanner in the companion app displays a blank white screen instead of the camera view.

This issue may be related to camera permissions or app initialization. Ensure the app has camera permissions enabled in your device settings. Try force-closing and reopening the app. If the problem persists, try reinstalling the app. See GitHub #2

Battery Classic

Unsure if the battery is working correctly?

To check that the battery is working correctly, unplug any connected USB power source and press the reboot button so that the device boots while on battery power.
Lilygo T5 2.13 inch Controls
Lilygo T5 2.13 inch Controls

App & Firmware

MicroPythonOS app store fails to install Lightning Piggy MicroPythonOS

The Lightning Piggy app cannot be installed from the MicroPythonOS app store.

This issue was resolved in app version 0.0.11. Ensure you are running the latest version of the MicroPythonOS app store. If the problem persists, try manual installation via the web installer. See GitHub #38

Balance Bias setting not showing on restart MicroPythonOS

The Balance Bias configuration option disappears or resets after restarting the device.

This bug has been fixed. Update to the latest firmware version via the web installer to resolve this issue. See GitHub #19

Diagnostics and logging Classic

Need to debug device behaviour.

Use the "Logs and Console" option in the web installer to monitor device operations. Press F12 or CTRL+SHIFT+I in your browser for developer tools. Note: "Improv Wi-Fi Serial" errors in the console are normal and can be safely ignored.

Building From Source Classic

MacOS iCloud and Arduino library conflicts

Arduino library folder Conflicts: It has been noted in Arduino version 1.8.16 that conflicts can occur due to the iCloud upload status of files in the Arduino library folder that can prevent successful builds. One solution is wait until all folders and files have synchronised with iCloud before building.

Community Q&A

Have a question not answered here? Join our Telegram group for live support from other Lightning Piggy builders.

If you've discovered a solution to a common problem, please share it with the community or email oink@lightningpiggy.com so we can add it here.