When flashing fails
What to try when the browser or esptool cannot find the Cardputer, cannot connect, or loses the connection halfway.
1. Use a cable that carries data
A charge-only USB-C cable powers the device but never shows up as a serial port. If a cable has worked for data before, use that one.
2. Put the Cardputer in download mode
Hold G0, the button next to the screen, while you plug in the USB cable, or while you press the reset button. Then try again. This is the first thing to try when an upload "can't connect".
3. Browser flashing: Chrome or Edge, on a desktop
The Install page flashes through the browser's Web Serial feature, which Firefox and Safari don't have. In Chrome or Edge, the browser asks you to pick the serial port from a list: pick the one that appears when you plug the Cardputer in. If the list is empty, go back to steps 1 and 2.
4. Linux: "permission denied" on the port
Your user needs access to serial devices. Run this once, then log out and back in:
sudo usermod -aG dialout "$USER"5. In a virtual machine
USB passthrough can fail with OSError: [Errno 71] Protocol error. Retrying alone doesn't help; resetting the Cardputer does, and putting it in download mode moves the serial port to a new name, so pick the port again afterwards.
Still stuck?
The esptool steps on the Install page flash the same file without a browser, and their error messages are more detailed. If it still fails, open an issue and say what you see.