PIoT Helper

Windows diagnostics tool for the TS PIoT (ЕСМ) + Frontol 6 + ATOL fiscal register chain: finds why marking-code checks fail while the module shows "green", and offers safe one-click fixes. Interface and docs are in Russian.

Диагностика связки ТС ПИоТ (ЕСМ) + Frontol 6 + ККМ АТОЛ. Помогает найти, почему модуль «горит зелёным», а коды маркировки не проходят: проверяет службы, порты, сертификаты, время, версии, лицензии и разбирает логи по базе известных ошибок. Для части проблем предлагает безопасные исправления (только после подтверждения). Пути к логам программа находит сама (автопоиск) или вы указываете их вручную.

Важно. Проект неофициальный и не связан с АТОЛ, ЦРПТ («Честный знак»), ЕСП и разработчиками Frontol. Названия продуктов используются только для описания совместимости. Программа читает логи и состояние служб, а по вашей команде может запускать и останавливать службы, добавлять сертификат в доверенные, синхронизировать время и править таймаут в конфиге ЕСМ (с резервной копией). Используйте на свой риск и не делайте этого во время продаж. Проверялась на одной кассе: Windows 10, Frontol 6.28–6.29, драйвер АТОЛ 10.10.8.x, ЕСМ от ЕСП. Расхождения на других конфигурациях возможны.

Лицензия: GPL-3.0. Программа предоставляется «как есть», без каких-либо гарантий.

Запуск

Вариант 1 — один файл (рекомендуется для касс). Скачайте PIoTHelper.exe из раздела Releases репозитория. Python на кассе не нужен: скопируйте файл в любую папку и запустите. Настройки (config.json) и журнал исправлений (fixes.log) создаются рядом с ним. Для действий, меняющих систему, программа сама предложит перезапуск от администратора.

Вариант 2 — из исходников. Нужен Python 3.10+ (tkinter входит в стандартную поставку), сторонние пакеты не нужны:

run.bat            # без консоли (ищет Python через py/pythonw/стандартные папки)
python main.py     # с консолью

Сборка exe. build.bat (ставит PyInstaller при необходимости и собирает dist\PIoTHelper.exe). Сборка «в один файл» распаковывается при запуске во временную папку, поэтому часть антивирусов может её проверять дольше или ругаться. Если так, добавьте файл в исключения или соберите папкой: уберите --onefile в build.bat.

Служебные режимы exe (для проверки): PIoTHelper.exe --selftest --out файл.json — самопроверка без окна.

Вкладки

• Сводка — «Проверить всё»: пути, службы, порты, свежесть и ошибки логов. Кнопка «Собрать отчёт» делает zip со сводкой, результатом диагностики, настройками и хвостами логов для техподдержки. По умолчанию отчёт маскируется: лицензионные ключи, заводские номера ККТ/ФН/РНМ, ИНН, коды маркировки, токены и пароли, e-mail, идентификаторы, внешние IP, имя пользователя и компьютера заменяются метками [SN1], [KEY1]… (одинаковые значения — одинаковые метки, поэтому логи остаются читаемыми). Названия организаций, адреса и фамилии автоматически не определяются: добавьте их в mask_extra в config.json. Просмотрите отчёт перед отправкой или публикацией: автоматическая маскировка не даёт полной гарантии. В архив входят также diagnostics.txt (результат диагностики) и timeline.txt (хронология за сутки). «Сравнить два отчёта…» показывает, что изменилось между двумя архивами: новые проблемы, исправленное, ухудшения.
• Исправления — диагностика «зелёный, но коды не бьются» с предложением исправлений. Проверяет: службы (в т.ч. «ATOL: Fptr grpc service»), порты связки (8000, 51401, 4041, 50063), время по NTP, сертификаты ЕСМ (ca.crt/server.crt в доверенных корневых), cdnCodesCheckTimeout, версии и разрядность Frontol/драйвера АТОЛ, прокси, доступность внешних адресов (регистрация и проверка кодов ЦРПТ, лицензирование ЕСП: порты 19100/19101/443), возраст смены (ЕСМ требует смену младше 24 ч), версию ЕСМ и известные ошибки в логах: коды ЕСМ и драйвера (12029, 403, 514, 0x3464 и др.), статусы ЛМ ЧЗ (not_configured, sync_error, failure), коды ЛМ ЧЗ 4045/5040 (правила лежат в данных: piothelper/rules.json, см. «Правила разбора» ниже), статистику проверок марок (доля успешных, время ответа ГИС МТ против таймаута ЕСМ — предупреждает до первой ошибки 514). Просроченный товар и права кассиров. Ответ ГИС МТ на проверку кода содержит срок годности (expireDate): программа считает за период сканирования кодов с истёкшим сроком и предупреждает (сами коды в находку и отчёт не попадают; факт сканирования не значит, что товар продан). Предупреждает, если Frontol старше 6.29.0 (по сведениям поставщика, с этой версии он не даёт пробить просроченный маркированный товар), и ловит сообщения «Истек срок годности». По руководству Frontol Mark Unit запрет на продажу маркированного товара не блокирует кассу: кассир может добавить товар в чек, если в его профиле во Frontol включены права обхода — «Документ продажи \ Регистрация \ С не корректным результатом проверки штрихкода маркировки» и «Документ \ Игнорировать ошибки повторной продажи маркированной продукции» («Системные справочники → Пользователи» во Frontol Администратор). Базу Frontol программа не читает и не меняет, поэтому показывает напоминание с точными названиями; кнопка «Отметить: права проверены» запоминает дату и не напоминает 90 дней (rights_review_days). После каждой диагностики внизу показано, что изменилось с прошлой (новое, исправленное, ухудшившееся). Для исправимых проблем доступна кнопка: запуск службы, установка сертификата, синхронизация времени, правка таймаута (с резервной копией). Всё выполняется только после подтверждения и записывается в fixes.log. «Перезапустить связку ПИоТ» — безопасный перезапуск служб в нужном порядке (список restart_chain в config.json, по умолчанию: драйвер АТОЛ gRPC → ESM Control Module → ESM Local Module Controller → ESM Orchestrator). Останавливает в обратном порядке, запускает в прямом, ждёт нужного состояния каждой службы; если остановка не удалась, возвращает уже остановленные службы. В конце до 90 с ждёт, пока в логах перестанут появляться ошибки связи ЕСМ с драйвером («Client is not found», «Не найден заводской номер» и т.п.), и сообщает итог. Нужны права администратора; на время перезапуска (обычно 1–2 мин) касса не сможет пробивать чеки с маркировкой. Не исправляется автоматически (нужны ваши действия): лицензия и регистрация в ЛК ЕСП, признак ТМТ в ФН, неотправленные уведомления, настройки сканера (GS), антивирус и брандмауэр.
• Хронология — события из всех логов одной лентой по времени (за N часов; только предупреждения и ошибки, только ошибки или всё). Одинаковые повторы сворачиваются в одну строку «×N», известные ошибки помечены и поднимаются до своего уровня, по выбранной строке показан совет. Время в UTC (логи ЛМ ЧЗ) приводится к местному. Вверху — статистика проверок марок. Ленту можно сохранить в файл.
• Настройки — фоновая проверка, правила, сведения о программе. Фоновая проверка: раз в N минут (не реже 5) запускает диагностику и показывает уведомление у значка в области уведомлений только о новых или ухудшившихся проблемах (по умолчанию только об ошибках; одну и ту же проблему не чаще, чем раз в monitor_repeat_hours, по умолчанию 6 ч). При включённой проверке крестик окна прячет программу в значок (правый клик: открыть / проверить сейчас / выход). По отдельной галочке и с подтверждением можно включить автозапуск (запись в HKCU\…\Run, права администратора не нужны). Журнал: monitor.log, снимки: history/. Правила: версия набора, «Обновить правила (GitHub)» (скачивает rules.json из этого репозитория, только по https и только с GitHub, файл проверяется перед установкой), «Перечитать правила».
• Пути — список папок/файлов (логи и папки ПИоТ, Frontol, Атол). Добавить, изменить, удалить; двойной щелчок открывает редактирование. Состояние показывается сразу. Автопоиск ищет в реестре установленных программ, в путях служб и по именам папок на фиксированных дисках и в профиле пользователя (ProgramFiles, ProgramData, AppData и др.). Внутри найденных папок ищет логи. Дополнительно: типовые пути ЕСМ (known_paths) и папки по файлам-маркерам (ca.crt+server.crt, config_…ККТ.yml). Если программу только что поставили, а найти её не удаётся, нажмите «Недавние папки»: покажет все папки, созданные или изменённые за последние N часов, независимо от названия. Что считать «своим», задают слова search_keywords в config.json («=esm» — только как отдельное слово). Найденное подставляется в пустые строки списка с подходящим названием, остальное добавляется новыми строками.
• Порт ККМ — что занимает порт. COM: список портов, пробное открытие (свободен / занят) и процесс, который держит порт. Для процесса перебираются открытые дескрипторы системы отдельным дочерним процессом (handles.py, таймаут 90 с). Без прав администратора видны только процессы вашего пользователя, поэтому есть кнопка перезапуска от администратора. TCP: порт или IP:порт ККМ — кто слушает локальный порт и какие процессы подключены к этому порту/адресу.
• Службы — поиск служб Windows по словам (имя или описание). Слова сохраняются.
• Порты — проверка TCP-портов (хост + порт). По умолчанию список пуст: порты ПИоТ добавьте сами.
• Логи — просмотр хвоста лога, подсветка ошибок и предупреждений, фильтр, автообновление.

Что считается ошибкой

Ошибки и предупреждения считаются только за последние recent_hours часов (по умолчанию 48), если в логе есть метки времени: старые сбои не выглядят свежими. Записи вида "error": 0 и «Ошибок нет» ошибкой не считаются. Трёхзначные коды (514, 408…) учитываются только рядом со словами «код/ошибка/error» — иначе совпадают миллисекунды в метках времени.

Регулярные выражения error_patterns / warn_patterns в config.json (без учёта регистра). Если формат логов ПИоТ использует другие слова, поправьте их там. Кодировка файлов: UTF-8 / UTF-16 (по BOM) / cp1251.

Правила разбора логов

Известные ошибки описаны в данных, а не в коде: piothelper/rules.json (ключ, регулярное выражение, уровень, название, совет, признак «разовый сбой»). Слои, каждый следующий перекрывает предыдущий по ключу: встроенные правила → скачанные кнопкой «Обновить правила» (если версия новее) → ваши rules_user.json рядом с программой (можно добавить своё, заменить встроенное или отключить: {"key": "514", "disabled": true}). Как добавить правило и обязательные примеры к нему: CONTRIBUTING.md.

Разработка

python -m pip install -r requirements-dev.txt
python -m pytest

Тесты (более 240) работают на вымышленных данных и проверяют правила на примерах и на «шуме» (миллисекунды во времени, шестнадцатеричные дампы), маскирование на утечки, перезапуск связки, диагностику, хронологию, сравнение, фоновый монитор, значок в трее и окно. На GitHub запускаются автоматически (Python 3.10 и 3.12), а по тегу vX.Y.Z из исходников собирается PIoTHelper.exe и прикладывается к релизу вместе с SHA-256.

Ограничения

• Правила написаны по открытым источникам и логам одной кассы, поэтому на других конфигурациях возможны ложные срабатывания и пропуски: присылайте замаскированные отчёты (см. CONTRIBUTING.md).
• Значок в трее сделан на чистом WinAPI; его работа проверена программно (создание окна, маршрутизация кликов и команд меню, вызовы уведомлений), но не на разных версиях Windows и не при нескольких мониторах и пользователях.
• Проверка COM пробно открывает порт и сразу закрывает его, ничего не записывая. У некоторых USB-устройств драйвер при открытии кратковременно меняет линии DTR/RTS. Не запускайте проверку во время чека и операций с ФН.
• Если ККМ подключена по USB без виртуального COM-порта (HID/WinUSB), в списке COM её не будет.
• Сканер COM проверен на тестовом символьном устройстве. На реальном COM-порту ККМ он ещё не проверялся.