Install RemSIM streaming
Prepare a Linux lab host or Raspberry Pi for the full APDU streaming stack: YggdraSIM HIL bridge, Osmocom RemSIM client for SIMtrace2, GSMTAP capture, and optional Card Bridge remote-card input.
On this page
Use this page before Run a HIL Capture or Card Bridge over SSH.
Supported hosts
| Host | Recommended install |
|---|---|
| Linux x86_64 lab host | scripts/install/install-linux.sh --flavor full |
| Raspberry Pi OS 64-bit | scripts/install/install-raspberrypi.sh --flavor full |
| Source checkout | python -m pip install -e '.[full]' or '.[hil]' |
| Windows / macOS | clean tools plus Card Bridge / remote APDU streaming; direct SIMtrace2/RemSIM HIL is Linux-only |
System packages
Debian / Ubuntu / Raspberry Pi OS:
sudo apt-get update
sudo apt-get install --no-install-recommends \
pcscd pcsc-tools libpcsclite1 libpcsclite-dev \
usbutils dfu-util git build-essential pkg-config \
autoconf automake libtool \
wireshark tshark termshark \
python3 python3-venv python3-pip
Add the user to groups needed by your distro:
sudo usermod -a -G plugdev,wireshark "$USER"
Log out and back in after group changes.
External dependency references
Use distro packages where possible. These upstream links are the reference points when a package is missing, stale, or needs to be built from source.
| Dependency | Used for | Upstream install/source reference |
|---|---|---|
Osmocom RemSIM / osmo-remsim-client-st2 |
SIMtrace2 RemSIM client attached to the HIL bridge | Osmocom RemSIM, Osmocom binary packages, osmo-remsim source |
| SIMtrace2 firmware and tools | card-emulation firmware, board utilities, USB bring-up | SIMtrace2 wiki, firmware binaries, simtrace2 source |
PC/SC Lite / pcscd |
reader middleware on Linux and BSD-like hosts | PCSC-Lite project, pcsc-tools |
dfu-util |
flashing SIMtrace2 card-emulation firmware | dfu-util homepage |
Wireshark / tshark / dumpcap |
GSMTAP capture, live decode, offline pcap review | Wireshark downloads, Wireshark documentation |
| Termshark | optional terminal UI around tshark on headless rigs |
Termshark |
| OpenSSH | ssh -L / ssh -R APDU bridge forwarding |
OpenSSH manual pages |
| Raspberry Pi OS | supported arm64 lab rig baseline | Raspberry Pi software |
| pySim | optional SAIP/SCP11 helper dependency pulled by YggdraSIM extras | pySim GitHub mirror, pySim Osmocom source |
Install YggdraSIM full/HIL support
Release script:
scripts/install/install-linux.sh --flavor full
Source checkout:
python -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[full]'
For a lighter source install that only adds the HIL runtime:
python -m pip install -e '.[hil]'
Install or locate osmo-remsim-client-st2
First check whether your distro already provides it:
command -v osmo-remsim-client-st2
osmo-remsim-client-st2 --help
If it is not packaged for your host, build/install it using your normal
Osmocom toolchain process and make sure the resulting executable is on
PATH, or note the absolute path for the supervisor's --remsim-binary
/ GUI RPi REMSIM binary field.
Validate the path:
/usr/local/bin/osmo-remsim-client-st2 --help
Prepare SIMtrace2
- Flash or update the SIMtrace2 card-emulation firmware. Use
guides/SIMTRACE2_CARDEM_GUIDE.mdfor the firmware procedure. -
Confirm USB enumeration:
lsusb | rg -i 'simtrace|1d50:60e3' -
Confirm optional tool visibility:
command -v simtrace2-list || true command -v simtrace2-tool || true
Verify PC/SC
systemctl status pcscd --no-pager
pcsc_scan -n
python main/main.py --card-bridge --card-bridge-no-token --card-bridge-reader-index 0
Stop the bridge with Ctrl-C after the startup banner confirms the reader
opened. On HIL-capable Linux hosts you can also list readers through the HIL
bridge:
python -m Tools.HilBridge.main --list-readers
If the reader is remote, start the Card Bridge on the reader host and validate the SSH tunnel before starting HIL:
python main/main.py --card-bridge \
--card-bridge-port 8642 \
--card-bridge-reader-index 0
curl -s http://127.0.0.1:8642/ping
Run doctor
python main/main.py --doctor
Expected HIL-related rows:
hil-bridge-runtimeosmo-remsim-client-st2tsharkdfu-utillsusb- PC/SC reader status
Warnings for optional tools are acceptable for offline-only work. A live SIMtrace2 rig needs the RemSIM client and USB visibility.
First local HIL start
yggdrasim-hil-supervisor \
--reader-index 0 \
--host 127.0.0.1 \
--port 9997 \
--advertise-host 127.0.0.1 \
--usb-vidpid 1d50:60e3
If the RemSIM binary is not on PATH, pass it explicitly:
yggdrasim-hil-supervisor \
--reader-index 0 \
--remsim-binary /usr/local/bin/osmo-remsim-client-st2 \
--usb-vidpid 1d50:60e3
First remote-card HIL start
After Card Bridge and SSH forwarding are ready:
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:60e3
This keeps the modem/SIMtrace2 rig local to the Linux host while APDUs are served by the workstation card through SSH.
From the unified CLI you can manage the reader-side piece without opening the GUI:
python main/main.py
# choose [CB] Card Bridge / Card Bridge over SSH
The [CB] menu can start or stop the local Card Bridge, print SSH tunnel
commands, apply --remote-card-url / token-file settings to the current CLI
session, and probe /ping plus authenticated /status.
Optional systemd --user service
Copy the example:
mkdir -p ~/.config/systemd/user
cp guides/systemd/yggdrasim-hil-supervisor.service.example \
~/.config/systemd/user/yggdrasim-hil-supervisor.service
Edit:
WorkingDirectory- Python or executable path
- reader selector or remote-card flags
--remsim-binaryif needed--usb-vidpid
Leave the ordering alone. A unit that is WantedBy=default.target must not
also be After=default.target: that closes an ordering cycle, and systemd
breaks a cycle by deleting one of the start jobs, so a unit silently never
starts at boot. Order against a concrete unit when one service needs another
first, as yggdrasim-lab-agent.service.example does with the Card Bridge.
Then:
systemctl --user daemon-reload
systemctl --user start yggdrasim-hil-supervisor.service
systemctl --user status yggdrasim-hil-supervisor.service
For unattended Raspberry Pi rigs:
loginctl enable-linger "$USER"
Validation checklist
pcsc_scan -nsees the card or Card Bridge/statusreturns an ATRlsusbsees the SIMtrace2osmo-remsim-client-st2 --helpworkspython main/main.py --doctorreports HIL readinesspython main/main.py->[CB]->[3]probes the configured bridgestate/hil_bridge_supervisor.jsonshowsstatus: runningstate/hil_bridge_card_relay.jsonshowsstatus: ok- Wireshark or
tsharksees GSMTAP on UDP4729 - the GUI live APDU dock receives rows during card traffic
Related pages
- Card Bridge over SSH
- Run a HIL Capture
- Universal GUI Command Center
- HIL Bridge
guides/INSTALL_FULL.mdguides/INSTALL_RASPBERRYPI.mdguides/SIMTRACE2_CARDEM_GUIDE.md