Card Bridge over SSH
Expose a PC/SC reader over a loopback HTTP bridge, carry the traffic through SSH, and make YggdraSIM use that card as if it were local. The same bridge can also feed a HIL rig, so a card on a workstation can serve a modem on a Raspberry Pi or lab host.
On this page
Topologies
Tool uses a remote reader
YggdraSIM tool host --ssh -L--> reader host
local URL :8642 Card Bridge :8642 -> PC/SC reader
Use this when the operator shell or GUI runs on one machine and the card is plugged into another.
Remote card feeds a HIL rig
workstation reader -> Card Bridge -> SSH forward -> rig HIL bridge -> RemSIM client -> SIMtrace2 -> modem
Use this when the modem/SIMtrace2 rig is remote but the card must stay with the operator.
Prerequisites
Reader side:
- Python 3.10+
- YggdraSIM source install or a build that includes
Tools.CardBridge pcscdandpyscard- PC/SC reader visible to
pcsc_scan
Tool or rig side:
- YggdraSIM installed
- SSH access to the reader side
- for HIL: Linux, SIMtrace2,
osmo-remsim-client-st2, and the full/HIL source dependencies
Card Bridge itself is cross-platform: the reader-side bridge and the remote-card consumer flags are supported on Windows, macOS, Linux, and Raspberry Pi as long as PC/SC and SSH are available. Only the direct SIMtrace2/RemSIM HIL rig process is Linux-only.
For a complete dependency install path, use Install RemSIM / APDU Streaming. The main upstream references are:
| Dependency | Reference |
|---|---|
| SSH forwarding | OpenSSH manual pages |
| PC/SC middleware and tools | PCSC-Lite project, pcsc-tools |
| RemSIM client | Osmocom RemSIM, Osmocom binary packages |
| SIMtrace2 rig | SIMtrace2 wiki, SIMtrace2 firmware binaries |
Start the Card Bridge
On the reader host, start the bridge from the unified launcher:
python main/main.py --card-bridge \
--card-bridge-port 8642 \
--card-bridge-reader-name "ACR"
Installed environments can use the dedicated console script or module form:
yggdrasim-card-bridge \
--port 8642 \
--reader-name "ACR"
# equivalent from a source checkout
python -m Tools.CardBridge \
--port 8642 \
--reader-name "ACR"
The bridge binds to 127.0.0.1, writes a bearer token under
${XDG_CONFIG_HOME:-~/.config}/yggdrasim/card_bridge/<port>.token, and
prints the /apdu and /status URLs in its startup banner. /card/reset
and /ping are served on the same base URL. The token file is created with
mode 0600.
Use --reader-index 0 instead of --reader-name when reader ordering is
stable. In the interactive launcher, the same controls are available under
python main/main.py -> [CB] Card Bridge / Card Bridge over SSH.
Open the SSH tunnel
From the YggdraSIM host to the reader host:
ssh -fN -L 8642:127.0.0.1:8642 user@reader-host
For a HIL rig that must consume a workstation card, either run that command on the rig, or run the reverse form from the workstation:
ssh -fN -R 8642:127.0.0.1:8642 user@rig-host
Configure YggdraSIM consumers
Copy or otherwise stage the token file on the consumer side:
mkdir -p ~/.config/yggdrasim/card_bridge
scp user@reader-host:~/.config/yggdrasim/card_bridge/8642.token \
~/.config/yggdrasim/card_bridge/8642.token
chmod 600 ~/.config/yggdrasim/card_bridge/8642.token
Then point a shell at the forwarded bridge:
python main/main.py \
--remote-card-url http://127.0.0.1:8642/apdu \
--remote-card-token-file ~/.config/yggdrasim/card_bridge/8642.token
python -m SCP03 \
--remote-card-url http://127.0.0.1:8642/apdu \
--remote-card-token-file ~/.config/yggdrasim/card_bridge/8642.token
The first command opens the normal CLI menu with the remote card already selected for card-consuming tools launched from that process. Other card-consuming surfaces that use the shared backend accept the same flags. Environment equivalents are:
export YGGDRASIM_CARD_RELAY_URL=http://127.0.0.1:8642/apdu
export YGGDRASIM_CARD_RELAY_TOKEN_FILE=~/.config/yggdrasim/card_bridge/8642.token
Feed a HIL rig with the remote card
On the rig, after the SSH tunnel is up:
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 \
--host 127.0.0.1 \
--port 9997 \
--advertise-host 127.0.0.1 \
--usb-vidpid 1d50:60e3
The HIL bridge now reads and writes the remote card through the tunnel while still exposing its normal rig-side relay state and GSMTAP mirror. Local YggdraSIM tools on the rig continue to talk to the HIL relay, not directly to the Card Bridge.
Use the GUI instead
The Universal GUI Command Center wraps this flow in the Card bridge panel. The Start full rig action can start the local bridge, open SSH forwards, sync the token, install or restart the remote HIL service, and verify the final state.
Use the GUI when you need repeated lab sessions against the same rig. Use the CLI flow above when you need a minimal, auditable setup sequence.
Validation
Cheap liveness check:
curl -s http://127.0.0.1:8642/ping
Authenticated status:
curl -s \
-H "Authorization: Bearer $(cat ~/.config/yggdrasim/card_bridge/8642.token)" \
http://127.0.0.1:8642/status | jq .
YggdraSIM preflight:
python main/main.py --doctor \
--remote-card-url http://127.0.0.1:8642/apdu \
--remote-card-token-file ~/.config/yggdrasim/card_bridge/8642.token
CLI menu probe:
python main/main.py
# then choose [CB] -> [3] Probe configured remote APDU bridge
For HIL, also check:
cat state/hil_bridge_supervisor.json
cat state/hil_bridge_card_relay.json
Look for a running supervisor, an ok card relay, and a non-empty ATR.
Security rules
- Keep Card Bridge bound to loopback.
- Use SSH for transport encryption and peer authentication.
- Keep bearer tokens in
0600files, not shell history. - Enable full APDU audit only on test cards; APDUs can contain PINs and operator secrets.
- Do not expose
/apdudirectly on a lab subnet. If a non-loopback bind is unavoidable, use a token, TLS termination, and host firewall rules.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
/ping works, /status returns 401 |
wrong or missing bearer token | copy the token again and verify mode 0600 |
| YggdraSIM still opens the local reader | remote-card URL not applied | pass --remote-card-url on the exact command being run, or export the env vars |
reader busy on the reader host |
another process holds the PC/SC reader exclusively | close the local shell or GUI that owns it; Card Bridge already defaults to --pcsc-share-mode shared, so passing it again changes nothing |
| HIL starts but no modem APDUs appear | RemSIM/SIMtrace2 side not attached | validate osmo-remsim-client-st2, SIMtrace2 firmware, and USB permissions |
| APDUs time out over WAN | SSH path too slow for default timeout | raise --apdu-timeout-ms on Card Bridge and HIL |
Sharing rigs across a team
One Card Bridge plus one SSH forward serves one operator. When several people
share a set of rigs, put a Remote Lab agent in front: it keeps this same
/apdu data plane and adds rig inventory, per-person tokens, and exclusive
session locking so two operators cannot drive one card at once. See
Run a Remote Lab Agent.