OTAMan Documentation

6. Card reader (pySim) tab

Connects to a local pysim-otaman-server for live card operations. Sub-tabs: File manager, Custom files, pySim command line, Raw APDU, and Proactive UICC.

6.1 File manager

• Read — reads the selected file (auto-detects transparent vs record files)
• Edit — modify hex data, Save to write back
• Raw / Decoded — toggle between hex dump and pySim-decoded JSON

6.2 Custom files

Add files that pySim’s model does not cover. Persists in localStorage; JSON export/import.

6.3 pySim command line

Execute any pySim-shell command with usage hints (300 ms) and autocomplete.

6.4 Raw APDU

Send an arbitrary APDU and view the raw response.

6.5 Proactive UICC

Interacts with the Card Application Toolkit session: subscribed events, the proactive command log, the PROVIDE LOCAL INFORMATION data dictionary, and STATUS polling.

6.5.1 Subscribed events (SET UP EVENT LIST)

The events the card monitors. Each event has a Send button that opens a form specific to the event type:

• No-data events (User Activity, Idle Screen, Data Available, …) — one-click notification
• Location Status — dropdown: Normal / Limited / No service (tag 9B)
• Access Technology Change — 13 RAT types (tag BF)
• Network Rejection — full adaptive form: registration type (LU / GPRS / EPS / 5GS), location fields (MCC, MNC, LAC, RAC, TAC), access technology, and a 53-cause unified rejection cause dropdown covering EMM, GMM, 5GMM and LU causes

Sending an event uses ENVELOPE(Event Download) per TS 102 223 / TS 131 111.

6.5.2 Proactive command log

Chronological list of fetched proactive commands. Each row shows the elapsed time, type code, name, and a decoded qualifier (for commands that have one). Commands with response data show a Response: line with the TERMINAL RESPONSE bytes (boilerplate TLVs stripped); PROVIDE LOCAL INFORMATION responses are decoded using the PLI data dictionary decoders.

6.5.3 PROVIDE LOCAL INFORMATION data dictionary

Editable hex values for all 22 PLI qualifiers (TS 102 223 §8.6 + TS 131 111). Ten qualifiers have inline decode/encode forms:

• 00 Location Info (MCC, MNC, LAC/TAC, Cell ID)
• 01 IMEI · 03 Date/Time/TZ · 04 Language · 05 Timing Advance
• 06 Access Technology · 08 IMEISV · 09 Search Mode
• 0A Battery · 0E Multiple Access Technologies

Values persist server-side until restart. When the card issues PLI, the server injects the dictionary values into the TERMINAL RESPONSE.

6.5.4 STATUS polling

A Send STATUS button issues a manual STATUS (F2). A Polling toggle enables background polling: after a configurable idle interval (server CLI --poll-interval, 1–255 s, default 30 s) the server sends STATUS and handles any pending proactive command. Polling stops and card state resets if the card is removed.

6.6 Usage scenarios

Scenario A — Working with files not in pySim’s model (Custom files)

1. Obtain the FID of the target file (vendor documentation or ATR/file-system analysis; such files are often not in public specs).
2. Open the Card reader tab → Custom files sub-tab.
3. Enter the full path (e.g. 3F00/7F20/6F46) and an alias (e.g. EF.SPN).
4. Click Add — the file appears in the tree in italics (unverified).
5. Click the file to verify existence; on success (9000) it behaves like a normal file.
6. Read, edit and save hex data; toggle Raw/Decoded views.
7. Export the custom-file list as JSON to share with other machines.

Scenario B — Simulating a real network environment for SIM testing

B.1 Answer PROVIDE LOCAL INFORMATION (PLI)

1. Open Proactive UICC → PROVIDE LOCAL INFORMATION response data.
2. Use the decode/encode forms to set IMEI (01), Location Info (00), Access Technology (06), etc.
3. Click Save — values persist server-side.
4. Enable Polling (interval 30 s) so the card issues PLI periodically.
5. The server injects the dictionary values into each TERMINAL RESPONSE.
6. Verify in the proactive log: the PLI entry shows the decoded response.

B.2 Simulate network actions via ENVELOPE (event download)

1. Check the subscribed events list (from SET UP EVENT LIST).
2. Click Send on an event (e.g. Location Status) and fill the form; an ENVELOPE(Event Download) is sent.
3. For Network Rejection, select registration type → location fields → access technology → rejection cause.
4. The card may respond with a proactive command, which the chain handler logs and answers automatically.

B.3 Verify the simulated environment

• The proactive command log shows the full round-trip (command + TERMINAL RESPONSE bytes).
• The STATUS button / auto-polling keep the CAT session alive (drain loop).

git clone https://github.com/anttro/otaman.git
cd otaman
chmod +x setup.sh start.sh
./setup.sh          # creates .venv, installs pysim + server (run once)
./start.sh          # starts the server (serves PWA + API, auto-detects reader)

git clone https://github.com/anttro/otaman.git
cd otaman
setup.bat           # creates .venv, installs pysim + server (run once)
start.bat           # starts the server (serves PWA + API)

# Create and activate a venv
python3 -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows

# Install pysim
pip install git+https://github.com/osmocom/pysim.git

# Install pysim-otaman-server (editable, so it serves the bundled PWA)
pip install -e .

# Start the server (serves PWA + API)
pysim-otaman-server --http-port 8080