Run HIL capture
Bring up the HIL supervisor, attach a real UICC/eUICC, expose it to both a modem and a YggdraSIM shell, and capture the combined APDU traffic in Wireshark for post-mortem review.
On this page
Prerequisites
pcscdrunning on the hostosmo-remsim-client-st2installed onPATH- a SIMtrace2 flashed for card emulation
- a physical UICC or eUICC in a PC/SC reader
- Wireshark with a loopback interface available
- optional
simtrace2-list/simtrace2-toolfor USB inspection - optional Card Bridge and SSH tunnel when the physical card is remote
Steps
-
Start Wireshark listening on the loopback interface, filter
gsm_simorudp.port == 4729. -
Launch the supervisor.
yggdrasim-hil-supervisor \ --reader-index 0 \ --host 127.0.0.1 \ --port 9997 \ --advertise-host 127.0.0.1 \ --usb-vidpid 1d50:60e3If the card is on a remote workstation, use remote-card mode instead:
yggdrasim-hil-supervisor \ --remote-card-url http://127.0.0.1:8642/apdu \ --remote-card-token-file ~/.config/yggdrasim/card_bridge/8642.token \ --apdu-timeout-ms 30000 \ --usb-vidpid 1d50:60e3See Card Bridge over SSH for the Card Bridge and SSH setup.
-
Confirm healthy state.
cat state/hil_bridge_supervisor.json cat state/hil_bridge_card_relay.jsonLook for
status: running,usbPresent: true, and a relaystatus: okwith a non-emptyatr. -
Let the modem attach to the SIMtrace2. Wireshark should now populate with GSMTAP APDUs between modem and card.
-
Open a YggdraSIM shell that can be pointed at the relay side-channel.
python -m SCP11.liveTraffic from the shell appears in the same Wireshark capture, serialized with modem traffic on the one live card.
In the GUI, open the HIL module or Card bridge view and watch the live APDU dock. The GUI receives APDU rows from the same process-wide recorder that card-consuming actions use.
-
Save the capture when the observation is complete.
If the session used a secure channel and you want to be able to unwrap it during later offline review, dump the session keys into a keybag JSON next to the capture (see Replay a HIL pcap offline):
# from the SCP03 admin shell, after AUTH-SD [A0...00] > EXPORT-KEYBAG Workspace/hil/captures/session-2026-04-20.keys.json case-1234 # or from SCP11 Local Access, after a BSP-building verb [Local SMDPP] > EXPORT-KEYBAG Workspace/hil/captures/session-2026-04-20.keys.json case-1234 -
Shut the supervisor down cleanly. It terminates both the bridge and
osmo-remsim-client-st2.
Validation
- Wireshark shows APDUs from both the modem and the YggdraSIM side
- no reader contention errors surface from other PC/SC clients
- state files show
status: running/status: okthroughout the session
Common failures
| Symptom | Likely cause |
|---|---|
supervisor reports usbPresent: false |
SIMtrace2 not enumerated. Check dmesg and lsusb. |
relay never reports status: ok |
osmo-remsim-client-st2 is failing to attach. Check its logs. |
missing atr in relay state |
card not powered or seated. Reseat it in the reader. |
| Wireshark sees modem traffic but not YggdraSIM traffic | YggdraSIM shell is using a direct PC/SC handle instead of the relay. Verify the configuration. |
| remote-card HIL starts but APDUs time out | SSH tunnel latency or stale token |
Related pages
- HIL Bridge
- Card Bridge over SSH
- Install RemSIM / APDU Streaming
- Universal GUI Command Center
- HIL Model
- Replay a HIL pcap offline
guides/HIL_BRIDGE_GUIDE.md