exchanger/docs/operations/TECHNICAL_CONFIGURATION.md

Техническая конфигурация Exchanger

Назначение и расположение

Монтажные параметры автомата хранятся отдельно от настроек владельца и не выводятся ни в одной доступной вкладке приложения. Технический специалист меняет TOML при установке или обслуживании автомата.

Встроенный шаблон:

res://config/technical_settings.toml

Рабочий файл конкретного автомата:

user://config/technical_settings.toml

Для текущей Windows-сборки это обычно %APPDATA%\Godot\app_userdata\Exchanger\config\technical_settings.toml.

Для Linux-сборки это обычно ~/.local/share/godot/app_userdata/Exchanger/config/technical_settings.toml.

При первом запуске приложение копирует встроенный шаблон в user://config/. Дальше рабочий файл не перезаписывается автоматически, поэтому комментарии и монтажные значения сохраняются.

Порядок применения

При старте приложение:

1. загружает обычные настройки владельца из appsettings.json;
2. читает и полностью проверяет technical_settings.toml;
3. применяет аппаратные значения и optional [theme] из TOML поверх обычных JSON-настроек;
4. применяет явные аргументы --theme-dlc, --no-theme-dlc и --mock-hardware последними;
5. загружает выбранную тему и создаёт mock- или COM-транспорт.

Изменение TOML во время работы ничего не переключает. После редактирования приложение необходимо полностью перезапустить.

Полный пример

version = 1

[theme]
enabled = true
directory = "user://theme_dlc"
file_name = "active_theme"

[controller]
use_mock = true
port = "COM3"
baud_rate = 115200
reconnect_interval_seconds = 30
handshake_timeout_ms = 2000
frame_timeout_ms = 100
max_frame_length = 1024
cashless_keep_alive_seconds = 120

[hopper_1]
enabled = true
stock_sensor_input = 1
stock_low_active_high = false
dispense_sensor_input = 24
dispense_pulse_active_high = false

[hopper_2]
enabled = true
stock_sensor_input = 4
stock_low_active_high = false
dispense_sensor_input = 25
dispense_pulse_active_high = false

[service]
button_input = 8
button_active_high = false

[polling]
input_poll_ms = 100
stock_poll_seconds = 5

Каталог и выбор темы

Необязательный раздел [theme] позволяет монтажнику выбрать PCK без изменения настроек владельца:

[theme]
enabled = true
directory = "/opt/exchanger/themes"
file_name = "space-pixel"

Приложение загрузит /opt/exchanger/themes/space-pixel.pck. directory принимает user:// либо абсолютный локальный путь текущей ОС; относительные пути, res:// и сегменты .. запрещены. file_name содержит только имя файла без каталога и расширения .pck. На Windows поддерживаются оба обычных представления:

# Рекомендуемый вариант с literal-строкой: обратные слеши не экранируются.
directory = 'D:\Exchanger\themes'

# Либо путь с прямыми слешами.
directory = "D:/Exchanger/themes"

Если Windows-путь записывается в двойных кавычках с обратными слешами, каждый \ по правилам TOML необходимо удвоить: directory = "D:\\Exchanger\\themes".

enabled = false отключает внешний PCK. Раздел является авторитетным относительно полей Themes в appsettings.json, но разовый аргумент --theme-dlc=<полный путь> или --no-theme-dlc имеет более высокий приоритет. Старые файлы версии 1 без [theme] остаются совместимыми: тогда выбор темы по-прежнему берётся из appsettings.json.

Основной контроллер

Параметр	Назначение	Допустимое значение
use_mock	Программный имитатор вместо платы	true или false
port	Порт основного контроллера	Windows: COM1…COM256 или COM для автопоиска; Linux: /dev/ttyUSB*, /dev/ttyACM*, /dev/serial/by-id/* или ttyUSB//dev/ttyUSB для автопоиска
baud_rate	Скорость последовательного порта	9600, 19200, 38400, 57600, 115200, 230400, 460800 или 921600
reconnect_interval_seconds	Пауза перед повторным подключением	1…60 с
handshake_timeout_ms	Общий предел ожидания авторизации платы	1000…60000 мс
frame_timeout_ms	Ожидание продолжения неполного кадра	10…5000 мс
max_frame_length	Максимальная длина входного кадра	2…65536 байт
cashless_keep_alive_seconds	Интервал keep-alive Вендиста	30…170 с; штатно 120 с

Первое открытие порта выполняется сразу при запуске. Если платы нет или открыть устройство не удалось, следующая попытка выполняется через reconnect_interval_seconds, после чего повторяется с тем же интервалом. При физическом отключении уже работавшей платы новый полный интервал отсчитывается от обнаруженного обрыва: старый дедлайн запуска не используется. Штатное значение — 30 секунд. Автоматически повторяются только подключение и авторизация; команда оплаты или выдачи после обрыва не отправляется повторно. Полное имя (COM3, /dev/ttyUSB0, ttyUSB0 и т. п.) всегда открывается как один заданный порт. Значение COM включает автопоиск: на каждом начальном подключении и каждом reconnect приложение получает список доступных COM-портов, сортирует их по номеру от COM0 и последовательно пробует до успешной авторизации. Значение ttyUSB (также допустимо /dev/ttyUSB) аналогично перебирает /dev/ttyUSB0, /dev/ttyUSB1 и далее. Открытие чужого последовательного устройства или ошибка/таймаут авторизации не считаются успешным подключением: поиск продолжается со следующим номером.

Безопасный шаблон содержит use_mock = true: простого копирования файла недостаточно для выхода на реальную плату. При вводе автомата в эксплуатацию нужно задать правильный порт, проверить остальные разделы и только затем изменить значение на false.

Формат port проверяется по ОС, на которой запущено приложение. Windows-сборка с реальной платой принимает строгие имена COM1…COM256 или префикс COM; Linux-сборка — /dev/ttyUSB*, /dev/ttyACM*, стабильные udev-ссылки by-id, префикс ttyUSB (с необязательным /dev/) и короткие точные имена ttyUSB0, ttyUSB1 и т. д. При use_mock = true имя порта не используется и не проверяется, поэтому общий безопасный шаблон с COM3 запускается и в Linux.

Для Silicon Labs CP210x после подключения обычно используется:

[controller]
use_mock = false
port = "/dev/ttyUSB0"

Если каталог /dev/serial/by-id/ создан udev, предпочтительнее указать находящуюся в нём постоянную ссылку: она не меняется при перестановке USB-устройств. Отсутствие самого каталога не является ошибкой — тогда используется /dev/ttyUSB0 или другой фактически назначенный номер. Каталог /dev/usb/ не является заменой узла последовательного порта.

Хопперы

Разделы hopper_1 и hopper_2 имеют одинаковую структуру:

Параметр	Назначение
enabled	Установлен ли хоппер
stock_sensor_input	Индекс входа датчика малого остатка
stock_low_active_high	true, если высокий уровень означает «мало жетонов»
dispense_sensor_input	Индекс отдельного физического датчика выдачи
dispense_pulse_active_high	true, если высокий уровень означает импульс выдачи

Индекс входа задаётся числом 0…25. Значение -1 означает, что отдельный физический вход не назначен. Для текущей разводки первый датчик выдачи использует IN24, второй — IN25. Обычная выдача подтверждается ответами HOPPER1/2 OK, а сервисный пересчёт — ответами HOPPER1/2 PULSE=1, поэтому физические входы не создают двойной программный учёт.

По enabled автоматически выбирается профиль команд:

Хоппер 1	Хоппер 2	Профиль
включён	включён	DualHopperAuto — команды 30X и 40X
включён	выключен	Hopper1Auto — команды 30X
выключен	включён	Hopper2Auto — команды 40X
выключен	выключен	выдача не поддерживается

У отключённого хоппера его входы принудительно становятся неактивными независимо от записанных чисел. Так узел можно временно отключить, не удаляя его монтажную схему из файла.

Если включён только один хоппер, приложение работает как одноканальное: выдача, сервисный пересчёт, ручное пополнение, доступный покупателю остаток и mock-режим используют только этот хоппер. Строка и кнопки отключённого хоппера скрываются в разделе «Сервис». Его сохранённый учётный остаток не удаляется и снова станет доступен, если хоппер вернуть в конфигурацию.

Сервисная кнопка и опрос

service.button_input задаёт индекс сервисной кнопки, 0…25 либо -1, если физическая кнопка отключена. service.button_active_high задаёт полярность. Для текущей разводки используются IN8 и false.

polling.input_poll_ms задаёт частоту резервного чтения входов в диапазоне 50…1000 мс. polling.stock_poll_seconds задаёт медленный опрос запаса в диапазоне 1…60 с.

Проверка и безопасное восстановление

Все прежние разделы и поля обязательны; новый [theme] целиком необязателен для совместимости. Если [theme] присутствует, обязательны все три его поля. Приложение отклоняет файл целиком, если:

• TOML имеет синтаксическую ошибку;
• отсутствует поле или раздел;
• версия схемы не равна 1;
• значение вышло за разрешённый диапазон;
• один неотрицательный индекс IN назначен нескольким активным функциям.
• каталог темы не является user:// или абсолютным локальным путём;
• file_name содержит путь либо расширение.

Некорректный пользовательский файл не исправляется и не перезаписывается автоматически. Приложение выдаёт предупреждение и запускается со встроенным профилем, где use_mock = true. Ошибочный монтажный файл поэтому не может случайно включить реальное оборудование.

AES-ключ, платёжные секреты, PIN владельца, сырые команды и ответы платы в TOML не добавляются.

Чек-лист технической настройки

1. Остановить приложение.
2. Открыть рабочий user://config/technical_settings.toml.
3. Проверить имя последовательного порта текущей ОС и наличие каждого хоппера.
4. Проверить reconnect_interval_seconds = 30 либо установить другой допустимый интервал.
5. Сверить индексы и полярности подключённых входов.
6. Проверить [theme].directory и указать [theme].file_name без .pck.
7. Оставить use_mock = true для первой проверки интерфейса.
8. После проверки платы изменить use_mock на false.
9. Полностью запустить приложение заново и выполнить отдельный приёмочный прогон оборудования.