Skip to content
YggdraSIM

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

  1. Flash or update the SIMtrace2 card-emulation firmware. Use guides/SIMTRACE2_CARDEM_GUIDE.md for the firmware procedure.
  2. Confirm USB enumeration:

    lsusb | rg -i 'simtrace|1d50:60e3'
    
  3. 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-runtime
  • osmo-remsim-client-st2
  • tshark
  • dfu-util
  • lsusb
  • 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-binary if 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 -n sees the card or Card Bridge /status returns an ATR
  • lsusb sees the SIMtrace2
  • osmo-remsim-client-st2 --help works
  • python main/main.py --doctor reports HIL readiness
  • python main/main.py -> [CB] -> [3] probes the configured bridge
  • state/hil_bridge_supervisor.json shows status: running
  • state/hil_bridge_card_relay.json shows status: ok
  • Wireshark or tshark sees GSMTAP on UDP 4729
  • the GUI live APDU dock receives rows during card traffic