On-device CAP file loading from SD card and serial

[Amperstrand]

Summary

Currently, DGP files must be pre-converted on a host PC and uploaded via mpremote cp. This issue tracks future work to allow the device itself to receive and process CAP files directly.

Background

DGP is a preprocessed format (CAP components concatenated in GP tag order, excluding Descriptor.cap and Java bytecode). It's ~5x smaller than the original CAP file. See tools/cap_to_dgp.py and applets.yaml for the current pipeline.

Proposed delivery methods

1. SD card loading

• User puts CAP file on SD card
• Device reads from /sd/gp/*.cap, converts to DGP in RAM, loads to card
• Requires: minimal ZIP reader (STORE-only, ~50-80 lines Python)
• Trade-off: larger file transfer (93KB vs 18KB) but no PC step
• Memory: need ~93KB RAM during conversion (currently tight on fragmented heap)

2. USB serial upload

• Host sends CAP/DGP file over serial to device
• Device streams to card LOAD commands directly (no full file in RAM)
• Could be integrated into Specter-Desktop USB protocol
• Already partially possible via mpremote cp

3. QR code (airgapped)

• Encode DGP as a sequence of QR codes (alphanumeric mode, ~2.9KB per QR)
• ~7 QR codes for SeedKeeper (18KB DGP)
• Device scans QR codes, reassembles, loads to card
• Maximum security: no USB or network connection needed
• Trade-off: slow UX, but enables fully airgapped provisioning

Open questions

• Should we support raw CAP or only DGP? (CAP needs ZIP extraction code)
• Memory constraints: 93KB CAP in RAM may fail on fragmented heap (we saw this with SeedKeeper DGP at 18KB)
• Streaming LOAD: read CAP components from SD and LOAD one at a time without buffering the whole file
• QR encoding: BCQR/UR types vs custom encoding

Related

• Issue On-device GlobalPlatform card management via SCP02 — hardware-verified #25: On-device GP card management (current state)
• applets.yaml: current applet distribution config
• tools/cap_to_dgp.py: current host-side CAP-to-DGP converter
• tools/make_dgps.py: make dgps pipeline script

[Amperstrand]

Status update — 2026-03-22

Commit: 04bf591 on gp-repl-tests branch

Progress

The DGP distribution pipeline (tools/cap_to_dgp.py, applets.yaml, make dgps) is fully working and hardware-tested:

Applet	CAP size	DGP size	DGP SHA256	Hardware tested
SeedKeeper v0.2-0.1	93KB	18KB	e447e45f...	19/19 pass
MemoryCard 1.0	63KB	10KB	ab52bb9c...	19/19 pass

Current delivery method (working)

DGP files are pre-converted on the host and uploaded via base64 exec:

# Convert
python3 tools/cap_to_dgp.py bin/applets/MemoryCard.cap bin/applets/MemoryCard.dgp

# Upload (mpremote cp hangs, use base64)
mpremote exec "import ubinascii; f=open('/flash/gp/MemoryCard.dgp','wb'); f.write(ubinascii.a2b_base64('$(base64 -w0 bin/applets/MemoryCard.dgp)')); f.close()"

What's not done

• SD card loading — need minimal ZIP reader in MicroPython
• USB serial streaming — stream LOAD blocks directly without buffering whole DGP
• QR code airgapped delivery — encode DGP as QR sequence
• On-device CAP→DGP conversion — requires ZIP extraction in constrained RAM

Memory constraints

The GUI's asyncio event loop fragments the heap. We now use gc.collect() before reading DGP files. MemoryCard DGP at 10KB loads fine; SeedKeeper at 18KB also works. Raw CAP (63-93KB) caused hard faults — DGP is the right approach.

Related

• On-device GlobalPlatform card management via SCP02 — hardware-verified #25: GP card management (hardware-verified)
• applets.yaml: distribution config with SHA256 checksums