OTAMan Documentation

5. Card reader (pySim) tab

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

5.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

5.2 Custom files

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

5.3 pySim command line

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

5.4 Raw APDU

Send an arbitrary APDU and view the raw response.

5.5 Proactive UICC

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

5.5.1 STK menu

When the card has issued a SET UP MENU command, a “STK menu” block appears at the top of this view with an emerald STK: <title> button that opens the menu overlay (same as the card’s STK menu browser). If the card has not set up a menu, the block shows “No menu set by the card” instead. The menu state is refreshed each time the view is opened.

5.5.2 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.

5.5.3 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.

5.5.4 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.

5.5.5 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.

5.6 Profiler

Verifies that a card matches a named profile — an ordered set of rules describing the expected file system and (optionally) file contents. Profiles are stored in localStorage.

Profile list

• New profile — creates an empty ruleset after prompting for a name.
• Profile from card — scans the equipped card and generates one rule per existing file (see below), then opens the editor.
• Import profile — loads a ruleset from a JSON file (the name is stored inside the JSON).
• Each profile row shows its name and creation time, with Edit, Check, Export (download JSON), and Delete actions.

Filesystem rules

Rules run sequentially. A filesystem rule is defined by:

• Path — starts with MF (e.g. MF/7F10/6F3A) or an ADF AID (e.g. A0000000871002/6F07).
• File attributes — file type, size, record length and record count, taken from the FCI template (any may be left unset).
• Contents (optional) — Exact hex equality, or Mask where ? is a per-nibble wildcard (a mask with no ? is a prefix match, e.g. 0891 for the IMSI MCC/MNC). Record files store a per-record list.

Check runs every rule against the equipped card and shows a live progress line plus a pass/fail report (existence, each FCI attribute, and the content match).

“Profile from card” scan options

The scan dialog asks for a profile name and offers an “Ignore contents of” checklist (all checked by default) of frequently-overwritten files whose contents are skipped: EF.LOCI, EF.PSLOCI, EF.EPSLOCI, EF.5GS3GPPLOCI, EF.Keys, EF.KeysPS, EF.SMS, EF.Kc, EF.KcGPRS, EF.LOCIGPRS, EF.CBMID, EF.SMSS. Rules are created only for files that actually exist on the card (an FCI template is returned); missing files are skipped. Custom files from the Custom files sub-tab are included under the same existence check.

5.7 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