HIL testing framework for hardware wallet verification

[Amperstrand]

Goal

A hardware-in-the-loop (HIL) testing framework that runs the full integration test suite (3 basic + 3 seedkeeper + 13 RPC = 19 tests) against real hardware via serial communication.

How It Works

1. HIL firmware (make hil) — builds with HIL_ENABLED = True, which starts a UART command listener on the ST-Link debug port (9600 baud)
2. HIL controller (test/hil/controller.py) — connects to debug UART and USB VCP, automates the GUI flow (PIN entry, secret selection, popup dismissal)
3. HIL test runner (test/hil/run_integration.py) — loads test modules, auto-starts Bitcoin Core, runs all 19 tests

HIL Commands (via debug UART)

Command	Response	Purpose
TEST_WIPE	OK:WIPED	Wipe wallet storage + hard reset
TEST_KEYSTORE	OK:KEYSTORE:SeedKeeper or OK:KEYSTORE:Internal	Detect active keystore
TEST_SECRETS	OK:SECRETS:id:label,...	List BIP39 secrets on card
TEST_FINGERPRINT	OK:FINGERPRINT:hex	Get current fingerprint
TEST_MNEMONIC	OK:MNEMONIC:words	Get loaded mnemonic (debug only)
TEST_STATUS	OK:STATUS:...	Get device status
TEST_SCREEN	OK:SCREEN:ClassName:...	Get current GUI screen
TEST_UI:value	OK:UI	Send GUI input
TEST_RESET	(resets device)	Hard reset

Test Results

19/19 pass (~332 seconds) on STM32F469 Discovery board with SeedKeeper card:

• 3 basic tests: fingerprint, xpub, sign_psbt
• 3 seedkeeper tests: fingerprint format, xpub, read-only error
• 13 RPC tests: legacy, legacy_sh, miniscript, no_derivation, sh_wpkh, sh_wsh, sighashes, sighashes_legacy, strange_derivation, weird_wsh, with_private, wpkh, wsh

New Files

File	Purpose
src/hil.py	HIL command handler (UART listener, commands)
manifests/disco-hil.py	HIL firmware build manifest
test/hil/controller.py	Hardware controller (serial, popup drain, keystore loading)
test/hil/run_integration.py	HIL test runner
test/integration/tests/test_seedkeeper.py	SeedKeeper-specific HIL tests
test/integration/util/bitcoin_core.py	BitcoinCoreManager (auto-start bitcoind)

Modified Files

File	Change
src/platform.py	hil_test_mode flag
src/specter.py	HIL listener, heartbeat disable, USB auto-enable
src/hosts/usb.py	HIL auto-enable USB
src/main.py	dupterm guard, network = "regtest" override
src/gui/tcp_gui.py	TEST_STATUS/TEST_SCREEN/TEST_RESET for simulator
Makefile	hil and hil-test targets
test/integration/util/controller.py	SIGSEGV detection

Known Limitations

• Internal flash keystore path is broken — _load_internal_flash() needs the correct screen flow after wipe. Currently only works with SeedKeeper card.
• Requires specific hardware — STM32F469 Discovery board + ST-LINK + SeedKeeper card
• Requires USART T=1 reconfig — local submodule override to 4fd3e51 in f469-disco (see ISO 7816 T=1 USART reconfig needed for smartcard support on STM32F469 [PROVEN ON HARDWARE] #1)

Upstream Target

Depends on SeedKeeper PR (#2). PR to cryptoadvance/specter-diy. Does NOT touch any submodule.

[Amperstrand]

Resolved

HIL testing framework is fully implemented. PR cryptoadvance#347 opened to upstream cryptoadvance/specter-diy:master.

What was implemented

• HIL firmware (make hil) — builds with HIL_ENABLED=1, UART command listener on ST-Link debug port (9600 baud)
• HIL controller (test/hil/controller.py) — connects via serial, automates GUI flow (PIN entry, secret selection, popup dismissal)
• HIL commands: TEST_WIPE, TEST_RESET, TEST_STATUS, TEST_KEYSTORE, TEST_FINGERPRINT, TEST_MNEMONIC, TEST_SECRETS, TEST_ALL_SECRETS, TEST_IMPORT_SECRET, TEST_DELETE_SECRET, TEST_CARD_RESET, TEST_SCREEN

Commits (on hardwareintheloop branch)

1. 77dee4b Add hardware-in-the-loop testing support
2. 6d564cb Fix HIL race: add _detect_keystore() with retry
3. 6477aeb Fix HIL reset: use TEST_RESET instead of st-info --reset
4. 0e56ff8 Fix HIL build targets and storage wipe
5. 29c0f7f Fix Makefile echo quoting for POSIX shell compatibility

Test results

• 14/14 simulator tests pass
• 15/17 HIL tests pass on hardware (12 RPC failures from pre-existing USB VCP disconnect)
• Both internal flash and SeedKeeper keystores supported

PR

cryptoadvance#347