OTAMan Documentation

5. Card reader (pySim) tab

Connects to a local pysim-otaman-server for live card operations: enter the server URL (default http://127.0.0.1:8080) and press Connect. The status area shows the reader/card state, and Equip card (re)initializes the card after insertion. Sub-tabs: File manager, Custom files, Profiler, pySim command line, Raw APDU, and Proactive UICC.

5.1 File manager

The file system tree is displayed on the left; selecting a file opens its detail pane on the right.

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

5.2 Custom files

Add files that pySim’s model does not cover: enter the full path (e.g. 3F00/7F20/6F46) and an alias (e.g. EF.SPN), then press Add; added files appear in the File manager tree. The list persists in localStorage and can be shared with Export as JSON / Export to file and restored with Import from file / Paste & import / Import JSON from clipboard.

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 Check card ▶, Edit, Export (download JSON), and Delete actions.

Filesystem rules

Rules run sequentially. The editor shows the symbolic pySim name (when known) next to each rule’s path; use Add rule to append one and Save to keep the changes. A filesystem rule is defined by:

• Path — starts with MF (e.g. MF/7F10/6F3A) or an ADF AID (e.g. A0000000871002/6F07).
• FCP/FCI check — how much of the file control information to verify: Filetype only (FCP) (existence + file type), Filetype + size (FCP) (adds file size, or record length/count for record files), or Exact FCI (adds a byte-for-byte comparison of the raw SELECT response — the FCP template '62' — catching FID/AID, life-cycle status, security-attribute and proprietary-parameter changes).
• File attributes — file type, size, record length and record count, taken from the FCP template (any may be left unset).
• Check 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 card runs every rule against the equipped card and shows a live progress line plus a pass/fail report. Each row states exactly what was verified next to the file path (e.g. filetype and size, contents or exact FCI); when some checks pass and others fail, each aspect is marked (filetype ✓, size ✗, contents ✓) with the mismatches detailed below. Mismatched raw data (FCI, contents, record data) is shown as read-only monospace fields — expected above actual, aligned in the same column — for easy comparison; FCI mismatches additionally show a decoded per-parameter comparison (file size, file descriptor/structure, life cycle, FID, SFI, proprietary parameters…). A decoded FCI preview is also shown beside the FCI hex field while editing a rule. If the FCI data is corrupt, whatever was decoded before the faulty part is shown together with an explicit decode-failure note. For record files with a contents mismatch, a matching records: 1-5, 7-10 note lists the records that did match.

“Profile from card” scan options

The scan dialog asks for a profile name and offers a “FCP/FCI check” selector (the same three modes above, default Filetype + size) applied to every generated rule, plus an “Ignore contents of files” checklist (all checked by default except EF.ARR; the header checkbox checks or unchecks the whole list) 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, EF.ACC, EF.EPSNSC, EF.START-HFN, EF.ARR. Two further checked-by-default options “Match first 4 bytes for” EF.IMSI and EF.ICCID capture those files’ contents as a mask of only the first 4 bytes (uncheck for exact matching). A progress line shows N / total files with the current file path while scanning; during the scan the options are hidden and the buttons are locked. Rules are created only for files that actually exist on the card (a FCP template is returned); missing files are skipped. Custom files from the Custom files sub-tab are included under the same existence check.

Card snapshots

The list view has two tabs — Profiles and Card snapshots. A card snapshot is an immutable capture of the card filesystem: for every existing file it stores the path, symbolic name, file type, size (or record length/count), the raw FCI from the SELECT response, and the contents whenever the file is readable (no ignore list, no masking). The ICCID is decoded from EF.ICCID and shown next to the snapshot name.

• New snapshot — asks for a name and scans the card, then returns to the list.
• Import snapshot — loads a snapshot from a JSON file.
• Each snapshot row has Open, Export, and Delete. Open shows all captured data read-only (raw FCI with the decoded FCI, contents); only the snapshot name is editable.

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