OTAMan Documentation

5. 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 ▶, Check card snapshot, 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. An Only mismatches option in the results header hides all passing files and keeps only failures and errors.

“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.
• Check card snapshot on a profile row runs the profile rules against a snapshot you pick from the list, without a card reader. The report is the same as a live check; files whose contents were not captured during the scan are reported as unverifiable errors.
• Compare snapshots compares two snapshots offline, exactly like a profile check: pick the master snapshot and the snapshot to check, optionally masking the first 4 bytes of EF.IMSI/EF.ICCID (on by default), and get the same pass/fail report. Files present only in the checked snapshot are reported as extra files. Back to list returns to the Card snapshots tab.

6. Phone simulator

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.

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. User-interactive proactive commands always get a TERMINAL RESPONSE: the overlay pauses for your choice, and if you neither answer nor press Timeout, the server answers with a timeout result after the --menu-timeout seconds (default 60, 0 disables).

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

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

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

6.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, 0 disables polling) the server sends STATUS and handles any pending proactive command. Polling stops and card state resets if the card is removed.

7. Server installation

Live card operations (Card reader tab, Phone simulator, OTA delivery) require the local pysim-otaman-server — a small HTTP server bundled with OTAMan that wraps pySim, talks to the reader over PC/SC or serial, and also serves the PWA itself (open http://127.0.0.1:8080).

7.1 Prerequisites

• Python 3.8+ with pip
• Git
• Smart card reader (PC/SC or serial/FTDI). PC/SC is preferable; on Linux it requires pcsc-lite + ccid
• Windows only — use Python 3.10–3.13 (3.13 recommended): pyscard (the PC/SC driver wrapper) ships precompiled wheels for these versions. On Python 3.9 / 3.14 pip builds pyscard from source, which requires Microsoft C++ Build Tools (“Desktop development with C++”). The SMPP bridge (smpp.twisted3) is intentionally not installed on Windows, so no C++ Build Tools are needed for Python 3.10–3.13.

7.2 Quick start — Linux / macOS

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)

7.3 Quick start — Windows

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)

7.4 Helper scripts

7.5 Reader auto-detection

• PC/SC (Linux) — start.sh passes -p 0 when the pcscd daemon is running
• PC/SC (Windows) — start.bat always uses -p 0 (PC/SC is built into Windows)
• Server fallback — started without reader arguments, the server itself probes for a PC/SC reader at startup (3 attempts, 2 s apart)
• Serial readers — start the server manually with -d /dev/ttyUSB0 (Linux)

If no card is present, the Card reader tab shows “No card detected”. Insert the card and click Equip card to initialize it.

7.6 Manual installation

# 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

Connect a PC/SC reader with a SIM card, then open http://127.0.0.1:8080 — the PWA and API share one origin, so no CORS is involved.

If the PWA is served from a public HTTPS host (e.g. https://otaman.example.com), two things are required to reach a local card server: (1) the server must answer the preflight with Access-Control-Allow-Private-Network: true (pysim-otaman-server ≥ 1.6.1 does this automatically), and (2) the browser must be allowed to access the local network — in Chrome/Edge/Vivaldi: Site settings → Local network access → allow the site (or accept the permission prompt). Without the browser permission, the request to 127.0.0.1 is blocked before any preflight is sent.