OTAMan Документация

5. Профайлер

Проверяет соответствие карты именованному профилю — упорядоченному набору правил, описывающих ожидаемую файловую систему и (опционально) содержимое файлов. Профили хранятся в localStorage.

Список профилей

• Новый профиль — создаёт пустой набор правил, запросив имя.
• Профиль с карты — сканирует подключённую карту и создаёт по одному правилу на каждый существующий файл (см. ниже), затем открывает редактор.
• Профиль из снимка — выбирает сохранённый снимок карты и создаёт по правилу на каждый захваченный файл с теми же опциями сканирования (см. ниже), без картридера; имя профиля подставляется из имени снимка.
• Импорт профиля — загружает набор правил из JSON-файла (имя хранится внутри JSON).
• В каждой строке профиля показаны имя и время создания, а также действия Проверить карту ▶, Проверить снимок карты, Редактировать, Клонировать, Экспорт (скачать JSON) и Удалить. Клонировать создаёт копию профиля с именем Копия <профиль> (с суффиксом (2), (3)…, если такое имя уже занято) и открывает копию в редакторе, чтобы изменить имя и содержимое перед сохранением.

Правила файловой системы

Правила выполняются последовательно. Редактор показывает символьное имя файла pySim (если известно) рядом с путём правила; Добавить правило добавляет правило, Сохранить сохраняет изменения. Правило файловой системы задаётся:

• Путь — начинается с MF (например, MF/7F10/6F3A) или с AID ADF (например, A0000000871002/6F07).
• Проверка FCP/FCI — какая часть информации об управлении файлом проверяется: Только тип файла (FCP) (существование + тип файла), Тип файла + размер (FCP) (добавляются размер файла либо длина/число записей для record-файлов) или Полный FCI (добавляется побайтовое сравнение сырого ответа SELECT — шаблона FCP '62' — выявляет изменения FID/AID, жизненного цикла, атрибутов безопасности и проприетарных параметров).
• Атрибуты файла — тип файла, размер, длина записи и число записей из FCP-шаблона (любой можно оставить незаданным).
• Проверить содержимое (опционально) — Точное (точное совпадение hex) или Маска, где ? — шаблон на один полубайт (маска без ? — совпадение префикса, например 0891 для MCC/MNC из IMSI). Для record-файлов хранится список по записям.

Проверить карту выполняет каждое правило на подключённой карте и показывает строку прогресса и отчёт прохождения. Рядом с путём файла указывается, что именно проверялось (например, тип файла и размер, содержимое или полный FCI); если часть проверок прошла, а часть нет — каждый аспект помечается (тип файла ✓, размер ✗, содержимое ✓), а расхождения расписываются ниже. Несовпавшие сырые данные (FCI, содержимое, данные записей) показываются как поля только для чтения с моноширинным шрифтом — ожидаемое над фактическим, в одной и той же колонке — для удобного сравнения; для расхождений FCI дополнительно показывается декодированное сравнение по параметрам (размер файла, дескриптор/структура, жизненный цикл, FID, SFI, проприетарные параметры…). Декодированный просмотр FCI также отображается рядом с полем FCI hex при редактировании правила. Если данные FCI повреждены, показывается всё, что удалось декодировать до места ошибки, вместе с явным сообщением об ошибке декодирования. Для record-файлов при расхождении содержимого добавляется пометка совпадающие записи: 1-5, 7-10 со списком записей, которые совпали. В отчёте поля расхождений и колонки сравнения FCI подписаны ожидалось (имя профиля) и фактически (ICCID карты), а в заголовке отчёта выводится Результаты проверки профиля: <профиль> → <ICCID карты>. Опция «Только расхождения» в заголовке отчёта скрывает все совпавшие файлы и оставляет только несовпадения и ошибки.

Опции сканирования «Профиль с карты»

Диалог сканирования запрашивает имя профиля и предлагает селектор «Проверка FCP/FCI» (те же три режима, по умолчанию Тип файла + размер (FCP)), применяемый ко всем создаваемым правилам, а также список «Игнорировать содержимое файлов» (все отмечены по умолчанию, кроме EF.ARR; флажок в заголовке отмечает или снимает весь список) часто перезаписываемых файлов, содержимое которых пропускается: 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. Ещё две отмеченные по умолчанию опции «Сравнивать первые 4 байта для» EF.IMSI и EF.ICCID захватывают содержимое этих файлов как маску только первых 4 байт (снимите для точного сравнения). Строка прогресса показывает N / всего файлов с текущим путём файла во время сканирования; при сканировании опции скрываются, а кнопки блокируются. Правила создаются только для файлов, которые реально существуют на карте (возвращён FCP-шаблон); отсутствующие файлы пропускаются. Пользовательские файлы из подвкладки «Пользовательские файлы» включаются с той же проверкой существования. Тот же диалог и опции использует «Профиль из снимка»: вместо карты обходятся захваченные файлы выбранного снимка; для файлов, содержимое которых не было захвачено, правило создаётся без проверки содержимого (при последующей проверке профиля они помечаются как непроверяемые).

Снимки карт

Представление списка имеет две вкладки — «Профили» и «Снимки карт». Снимок карты — неизменяемая фиксация файловой системы карты: для каждого существующего файла сохраняются путь, символьное имя, тип, размер (или длина/число записей), сырой FCI из ответа SELECT и содержимое, если файл читается (без списка игнорирования и без масок). ICCID декодируется из EF.ICCID и показывается рядом с именем снимка. При сканировании измеряется время каждой команды карты (SELECT, READ BINARY, READ RECORD) от отправки до ответа; снимок хранит min/сред/max по каждому типу команд и общее время сканирования, а в представлении эти значения показываются в сводке под заголовком, время select/read — для каждого файла и время чтения — для каждой записи. Время носит информационный характер и не используется при проверках и сравнении.

• Новый снимок — запрашивает имя и сканирует карту, затем возвращает к списку.
• Импорт снимка — загружает снимок из JSON-файла.
• В каждой строке снимка — Открыть, Экспорт и Удалить. Открыть показывает все захваченные данные только для чтения (сырой FCI с декодированным FCI, содержимое); редактируется только имя снимка.
• Проверить снимок карты в строке профиля выполняет правила профиля на выбранном из списка снимке, без картридера. Отчёт такой же, как при проверке карты: фактическая сторона подписана именем снимка (фактически (имя снимка)), а в заголовке — Результаты проверки профиля: <профиль> → <имя снимка>; файлы, содержимое которых не было захвачено при сканировании, помечаются как непроверяемые ошибки.
• Сравнить снимки сравнивает два снимка без картридера так же, как проверка профиля, но всегда точно (маскирование содержимого не применяется): выберите эталонный снимок и снимок для проверки и получите такой же отчёт; в этом отчёте заголовок — Результаты сравнения снимков: <эталон> → <проверяемый>, а поля расхождений и колонки сравнения FCI подписаны именами эталонного и проверяемого снимков вместо expected/actual. Файлы, которые есть только в проверяемом снимке, помечаются как лишние. «К списку» возвращает на вкладку «Снимки карт».

6. Симулятор телефона

Работа с сессией Card Application Toolkit. Две подвкладки: «Телефон» (меню STK, STATUS и опрос, подписанные события, журнал проактивных команд) и «Конфигурация TR» (данные ответов, подставляемые в TERMINAL RESPONSE для проактивных команд).

6.1 Меню STK

Если карта выдала команду SET UP MENU, вверху этого представления появляется блок «Меню STK» с изумрудной кнопкой STK: <название>, открывающей оверлей меню (браузер STK-меню карты). Если карта не задала меню, вместо кнопки показывается «Меню не задано картой». Состояние меню обновляется при каждом открытии представления. Интерактивные проактивные команды всегда получают TERMINAL RESPONSE: оверлей ждёт вашего выбора, и если вы не ответили и не нажали Timeout, сервер сам отвечает результатом timeout через --menu-timeout секунд (по умолчанию 60, 0 отключает). Назад и Timeout продолжают диалог с картой: если карта в ответ выдаёт следующую проактивную команду (SELECT ITEM или DISPLAY TEXT), панель показывает её; кэшированное верхнее меню появляется только когда карте больше нечего выполнять.

6.2 Подписанные события (SET UP EVENT LIST)

События, которые отслеживает карта. У каждого события есть кнопка Отправить, открывающая форму, специфичную для типа события:

• События без данных (User Activity, Idle Screen, Data Available, …) — уведомление в один клик
• Location Status — выпадающий список: Normal / Limited / No service (тег 9B)
• Access Technology Change — 13 типов RAT (тег BF)
• Network Rejection — полная адаптивная форма: тип регистрации (LU / GPRS / EPS / 5GS), поля местоположения (MCC, MNC, LAC, RAC, TAC), технология доступа и единый выпадающий список из 53 кодов причин (EMM, GMM, 5GMM и LU)

Отправка события использует ENVELOPE(Event Download) по TS 102 223 / TS 131 111.

6.3 Журнал проактивных команд

Хронологический список извлечённых проактивных команд. Каждая строка показывает время, код типа, имя и декодированный квалификатор (для команд, у которых он есть). Раскрытие строки показывает декодированную команду: текст и пункты DISPLAY TEXT / SELECT ITEM / SET UP MENU, параметры BIP-каналов, действия TIMER MANAGEMENT, названия квалификаторов PROVIDE LOCAL INFORMATION (все стандартные, включая ESN 07, MEID 0B и Supported RATs 1A) и SEND SHORT MESSAGE — разбирается SMS TPDU (тип, TP-MR, TP-DA, TP-PID, TP-DCS, срок действия, TP-UDL), а пользовательские данные показываются как текст для текстовых кодировок (GSM 7-бит, UCS2, 8-бит) или как secured-пакет (TS 31.115) при TP-PID = 7F (SIM data download); заголовки конкатенации UDH декодируются. Для команд с данными ответа показывается строка Ответ: с байтами TERMINAL RESPONSE (без служебных TLV); ответы PROVIDE LOCAL INFORMATION декодируются через словарь данных PLI.

6.4 Опрос STATUS

Кнопка Отправить STATUS отправляет STATUS (F2) вручную. Переключатель Опрос включает фоновый опрос: после настраиваемого интервала бездействия (аргумент сервера --poll-interval, 1–255 с, по умолчанию 30 с, 0 отключает опрос) сервер отправляет STATUS и обрабатывает любую ожидающую проактивную команду. При извлечении карты опрос останавливается, а состояние карты сбрасывается.

6.5 «Конфигурация TR» — данные ответа PROVIDE LOCAL INFORMATION

Редактируемые hex-значения для всех 22 квалификаторов PLI (TS 102 223 §8.6 + TS 131 111). У десяти квалификаторов есть встроенные формы декодирования/кодирования:

• 00 Location Info (MCC, MNC, LAC/TAC, Cell ID)
• 01 IMEI · 03 Дата/время/TZ · 04 Язык · 05 Timing Advance
• 06 Access Technology · 08 IMEISV · 09 Search Mode
• 0A Battery · 0E Multiple Access Technologies

Значения хранятся на сервере до перезапуска. Когда карта выдаёт PLI, сервер вставляет значения словаря в TERMINAL RESPONSE.

7. Установка сервера

Для работы с картой (вкладка «Картридер», «Симулятор телефона», доставка OTA) нужен локальный pysim-otaman-server — встроенный в OTAMan HTTP-сервер, оборачивающий pySim, работающий с ридером через PC/SC или serial и раздающий сам PWA (откройте http://127.0.0.1:8080).

7.1 Требования

• Python 3.8+ с pip
• Git
• Смарт-картридер (PC/SC или serial/FTDI). Предпочтителен PC/SC; на Linux требуются pcsc-lite + ccid
• Только Windows — используйте Python 3.10–3.13 (рекомендуется 3.13): pyscard (обёртка драйвера PC/SC) поставляет готовые wheels для этих версий. На Python 3.9 / 3.14 pip собирает pyscard из исходников, для чего требуются Microsoft C++ Build Tools («Desktop development with C++»). Мост SMPP (smpp.twisted3) на Windows намеренно не устанавливается, поэтому для Python 3.10–3.13 C++ Build Tools не нужны.

7.2 Быстрый старт — Linux / macOS

git clone https://github.com/anttro/otaman.git
cd otaman
chmod +x setup.sh start.sh
./setup.sh          # создаёт .venv, устанавливает pysim + сервер (однократно)
./start.sh          # запускает сервер (PWA + API, автоопределение ридера)

7.3 Быстрый старт — Windows

git clone https://github.com/anttro/otaman.git
cd otaman
setup.bat           # создаёт .venv, устанавливает pysim + сервер (однократно)
start.bat           # запускает сервер (PWA + API)

7.4 Вспомогательные скрипты

7.5 Автоопределение ридера

• PC/SC (Linux) — start.sh передаёт -p 0, если запущен демон pcscd
• PC/SC (Windows) — start.bat всегда использует -p 0 (PC/SC встроен в Windows)
• Резерв сервера — при запуске без аргументов ридера сервер сам опрашивает PC/SC-ридер при старте (3 попытки с интервалом 2 с)
• Serial-ридеры — запустите сервер вручную с -d /dev/ttyUSB0 (Linux)

Если карта отсутствует, вкладка «Картридер» показывает «Карта не обнаружена. Вставьте карту и нажмите Подключить карту».

7.6 Ручная установка

# Создать и активировать venv
python3 -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows

# Установить pysim
pip install git+https://github.com/osmocom/pysim.git

# Установить pysim-otaman-server (editable — раздаёт встроенный PWA)
pip install -e .

# Запустить сервер (PWA + API)
pysim-otaman-server --http-port 8080

Подключите PC/SC-ридер с SIM-картой и откройте http://127.0.0.1:8080 — PWA и API на одном origin, поэтому CORS не требуется.

Если PWA раздаётся с публичного HTTPS-хоста (например, https://otaman.example.com), для доступа к локальному серверу карт нужны два условия: (1) сервер отвечает на preflight заголовком Access-Control-Allow-Private-Network: true (pysim-otaman-server ≥ 1.6.1 делает это автоматически), и (2) браузеру должно быть разрешено обращаться к локальной сети — в Chrome/Edge/Vivaldi: Настройки сайта → Доступ к локальной сети → разрешить сайт (или подтвердить запрос). Без разрешения браузера запрос к 127.0.0.1 блокируется ещё до отправки preflight.