Assembly

Putting it together. Plan on a relaxed evening per device: ~10 minutes to flash the firmware, ~1 hour soldering, ~1 hour to fit, screw down, and close the case.

Before you start

Print both case shells. See Case for slicer settings.
Have the BOM parts on the desk.
Have a USB-C data cable — many cheap ones are charge-only.
Open the wiring diagram on your phone or a second screen.

If you're soldering for the first time, watch a 10-minute through-hole soldering video. There's nothing surface-mount and nothing fine-pitch here — it's hobby-level work.

Step 0 — flash the firmware FIRST

The BOOTSEL button is on the bare Waveshare board and is deliberately not exposed through the assembled case. If you assemble first and flash second, you will have to take the case apart again. Do both flashes now, with the board still bare.

Two separate flashes have to happen:

Flash 1 — MicroPython runtime (one-time per board, BOOTSEL mode)

A fresh Waveshare RP2350-Touch-LCD-3.5 ships with a Waveshare C demo, not MicroPython. scripts/flash.sh won't work until MicroPython is on the board.

Download the Waveshare MicroPython build for this exact board model: WAVESHARE_RP2350_Touch_LCD_3.5.uf2 (On the GitHub page, click Download raw file.)
Press and hold the BOOTSEL button on the Waveshare board.
While still holding BOOTSEL, plug the board into your computer with a USB-C data cable. Charge-only cables silently fail.
Release BOOTSEL. The board mounts on your computer as a USB drive named RPI-RP2.
Drag the .uf2 file onto that drive. The board reboots automatically; the drive disappears. MicroPython is now installed.

Success signal: the RPI-RP2 drive vanishes from your file manager within a couple of seconds of the drag.

Flash 2 — OTP firmware (every time the source changes, USB-C, no BOOTSEL)

Once MicroPython is on the board, scripts/flash.sh from the public repo deploys the OTP firmware on top of it via mpremote over USB-C.

From the cloned public repo root, set up the script venv once: python3 -m venv scripts/venv && scripts/venv/bin/pip install -r scripts/requirements.txt.
Plug the board in via USB-C (no BOOTSEL this time — just plug it in).
Run ./scripts/flash.sh. On first flash the script prompts you for a friendly label for the board (e.g. alice); on later flashes it remembers.

Success signal: per-file upload progress, ending with a successful flash message. The board reboots into the OTP setup flow on its own.

Both flashes done? Now you can solder and assemble.

Step by step

The order matters: solder while everything is still loose, then drop modules into the case once the wiring is done.

Attach the battery cable. The MX1.25 cable from the BOM has a connector on one end and bare wires on the other — splice or solder the bare end to the battery leads. Don't trust wire colour to set polarity — colour and pin order aren't standardised across MX1.25 cables. Before you plug the connector into the Waveshare JST socket, measure with a multimeter: the pin going to + on the socket must read positive against the pin going to -. If it's reversed, pop the contacts out of the MX1.25 connector with a small pick and re-seat them swapped. Reversed polarity will damage the AXP2101 PMIC and brick the board.
Wire up the guest SD breakout. Six solder joints: CS, SCK, MOSI, MISO, VCC (3.3 V), GND. Use the GPIO pins shown in the wiring diagram. Confirm you're feeding 3.3 V, not 5 V.
Wire up the QR scanner. The GM861XS ships with a 4-wire harness — TX, RX, 3.3 V, GND — terminating in a connector that plugs into the scanner. Solder the other end of the harness to the Waveshare GPIO pins shown in the wiring diagram.
Drop the Waveshare board into the case bottom. It locates on plastic posts; no screws needed for the board itself.
Screw down the QR scanner and the guest SD breakout. One screw each — these are the only two components that get fixed to the case. Everything else stays in place because the case is shaped around it.
Tuck the battery into its cavity and route the cable around the side. Plug the JST connector into the Waveshare board.
Power on. PWR button short press. The screen should light up and show the OTP setup flow — that's the firmware you flashed in Step 0 running for the first time.
Close the case. Top shell screws on; check that no wire is being pinched.

Soldering tips

Tin every wire before soldering it. A pre-tinned wire takes about half a second to bond.
Use flux. Even on clean pads, flux turns a frustrating joint into a clean one.
If a joint looks dull or grainy, reflow it.
Two-handed work: helping hands or a small vise on the receiving board, your dominant hand on the iron, your other hand feeding solder. If you're holding the workpiece, you're going to slip.

First power-on

The very first boot runs through:

Device setup — the gadget generates a random device_secret (256 bits of MCU-flash-stored entropy that's used in every key derivation later). It shows it once on screen as a QR code and as hex. You should photograph this or write it down somewhere safe — it's the only thing that can recover your card if you forget your PIN.
Card init — insert your blank own card. The gadget asks you to set a 4–6 digit PIN and writes the on-card key material (master key, recovery token, salt, verify blob).
Home screen — three buttons (Send, Receive, Contacts), a settings gear, a lock icon. You're ready.

To actually send messages, you also need a second gadget paired with yours via the key exchange. That's covered in Using the gadget.

Common things that go wrong

Screen doesn't light up. Check the battery connector polarity and that the JST is fully seated. The board should also work on USB-C alone, with the battery disconnected — try that to isolate the battery as the fault.
"QR scanner not detected" warning. The two data wires (TX/RX) are reversed — try swapping them. Or one of the four wires is loose.
"WRONG_FS" on the guest card. The card isn't FAT32. Reformat it.
"timeout waiting for v2 card" during boot. The guest SD breakout is the wrong variant (one with a regulator or a level shifter). See the BOM "do NOT use" note.
Anything else. Troubleshooting or ask a question.

Next: Firmware — what's running inside, and how to update it later.