====== Настройка и проброс COM-портов под Wine в ОС Astra Linux ======

===== 1. Общие сведения =====

Документ описывает порядок настройки последовательных портов (COM) в ОС Astra Linux и их проброса в Windows-приложения, запускаемые через Wine. Рассмотрены два типа источников портов:

  * **Штатные / встроенные COM-порты** — порты, реализованные на материнской плате или на плате расширения (PCI/PCIe-картах последовательных портов, мультипортовых адаптерах), которым в Linux соответствуют устройства ''%%/dev/ttyS*%%'' (а также ''%%/dev/ttyMI*%%'', ''%%/dev/ttyAP*%%'', ''%%/dev/ttyXR*%%'' и др. — в зависимости от драйвера платы расширения).
  * **USB-to-COM (USB2COM) адаптеры** — преобразователи интерфейсов USB ↔ RS-232/485, которым в Linux соответствуют устройства ''%%/dev/ttyUSB*%%'' (драйверы ''%%ftdi_sio%%'', ''%%pl2303%%'', ''%%ch341%%'', ''%%cp210x%%'' и др.) или ''%%/dev/ttyACM*%%'' (устройства класса CDC-ACM).

Принцип проброса в обоих случаях одинаков: устройство Linux (''%%/dev/tty*%%'') связывается символьной ссылкой с именем COM-порта в каталоге ''%%dosdevices%%'' нужного Wine-префикса, после чего Windows-приложение видит его как ''%%COM1%%'', ''%%COM2%%'' и т. д.

**Рисунок 1 — Общая схема проброса последовательного порта из ОС Astra Linux в Windows-приложение под Wine**

{{:doc:serialflow.png?400|Общая схема проброса COM-порта в Wine}}

===== 2. Предварительные требования =====

^Параметр            ^Значение                                                                        ^
|Операционная система|Astra Linux Special Edition / Common Edition                                    |
|Wine                |установлен и настроен Wine-префикс целевого приложения                          |
|Права               |пользователь должен входить в группу доступа к COM-устройствам (''%%dialout%%'')|
|Оборудование        |подключённая плата расширения COM либо адаптер USB-to-COM                       |

===== 3. Определение устройства в системе =====

==== 3.1 Штатные COM-порты и платы расширения ====

Просмотр доступных последовательных портов, зарегистрированных ядром:

<code>
ls -l /dev/ttyS*
dmesg | grep -i ttyS
</code>

Уточнение реально присутствующих (а не зарезервированных) портов с помощью утилиты ''%%setserial%%'':

<code>
setserial -g /dev/ttyS*
</code>

Порты с типом ''%%unknown%%'' физически отсутствуют; рабочему порту соответствует тип UART (например ''%%16550A%%'') и ненулевой адрес ввода-вывода.

Для плат расширения (PCI/PCIe) проверяется, что плата определена системой и для неё загружен драйвер:

<code>
lspci | grep -i serial
dmesg | grep -iE 'tty|serial|uart'
</code>

В зависимости от платы порты могут именоваться ''%%/dev/ttyS4%%'', ''%%/dev/ttyS5%%''… либо иметь собственный префикс (например ''%%/dev/ttyAP0%%'', ''%%/dev/ttyXR0%%''). При отсутствии портов после установки платы устанавливается соответствующий драйвер (модуль ядра) от производителя.

==== 3.2 USB-to-COM адаптеры ====

Подключить адаптер и определить присвоенное ему устройство:

<code>
dmesg | grep -i tty
ls -l /dev/ttyUSB* /dev/ttyACM*
</code>

Определить параметры адаптера (производитель, модель, серийный номер) — они понадобятся для закрепления имени устройства через ''%%udev%%'':

<code>
lsusb
udevadm info -a -n /dev/ttyUSB0 | grep -E 'idVendor|idProduct|serial'
</code>


===== 4. Настройка прав доступа =====

Доступ к последовательным устройствам в Astra Linux предоставляется членам группы ''%%dialout%%''.

Проверка членства пользователя в группе:

<code>
groups $USER
</code>

Добавление пользователя в группу (при отсутствии):

<code>
sudo usermod -aG dialout $USER
</code>

Изменение вступает в силу после повторного входа в сессию (logout/login) либо после перезагрузки.

Проверка прав на конкретное устройство:

<code>
ls -l /dev/ttyS0
ls -l /dev/ttyUSB0
</code>

Устройство должно принадлежать группе ''%%dialout%%'' с правами ''%%crw-rw----%%''.

> **Замечание по мандатному контролю целостности (МКЦ) Astra Linux.** В защищённых режимах Astra Linux доступ к устройству может дополнительно ограничиваться мандатными атрибутами. При недоступности порта из-под Wine, несмотря на корректное членство в ''%%dialout%%'', следует проверить мандатные метки устройства и при необходимости согласовать уровень целостности процесса Wine и устройства.

===== 5. Закрепление имени устройства (udev) =====

Имена ''%%/dev/ttyUSB*%%'' назначаются по порядку подключения и могут изменяться при переподключении адаптера или перезагрузке. Для предсказуемого именования создаётся правило ''%%udev%%'', привязывающее устройство к стабильной символьной ссылке по уникальным признакам (''%%idVendor%%'', ''%%idProduct%%'', серийный номер).

Создать файл правила, например ''%%/etc/udev/rules.d/99-com-chromos.rules%%'':

<code>
SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", \
  ATTRS{serial}=="A12B3C4D", SYMLINK+="com_chromos", GROUP="dialout", MODE="0660"
</code>

Значения ''%%idVendor%%''/''%%idProduct%%''/''%%serial%%'' берутся из вывода ''%%udevadm%%'' (п. 3.2).

Применить правила без перезагрузки:

<code>
sudo udevadm control --reload-rules
sudo udevadm trigger
</code>

Проверить появление стабильной ссылки:

<code>
ls -l /dev/com_chromos
</code>

После этого вместо изменчивого ''%%/dev/ttyUSB0%%'' в пробросе используется постоянный путь ''%%/dev/com_chromos%%''. Для штатных портов плат расширения путь обычно стабилен, и отдельное правило не требуется.

**Рисунок 2 — Привязка USB-to-COM адаптера к стабильному имени устройства правилом udev**

{{:doc:serialudev.png?400| Привязка устройства правилом udev}}

===== 6. Проброс порта в Wine-префикс =====

Проброс выполняется созданием символьной ссылки в каталоге ''%%dosdevices%%'' целевого Wine-префикса. Имя ссылки (''%%com1%%'', ''%%com2%%'', …) задаёт номер COM-порта, под которым устройство будет видно Windows-приложению.

Перейти к каталогу ''%%dosdevices%%'' нужного префикса (пример для префикса win32):

<code>
WINEPREFIX=/home/user/.local/share/wineprefixes/win32
ls -l "$WINEPREFIX/dosdevices"
</code>

Создать ссылку на устройство:

<code>
# для USB-to-COM, закреплённого через udev:
ln -s /dev/com_chromos "$WINEPREFIX/dosdevices/com1"

# или напрямую на устройство:
ln -s /dev/ttyUSB0 "$WINEPREFIX/dosdevices/com1"

# для штатного порта / платы расширения:
ln -s /dev/ttyS0   "$WINEPREFIX/dosdevices/com2"
</code>

Проверить созданные ссылки:

<code>
ls -l "$WINEPREFIX/dosdevices/" | grep -i com
</code>


**Рисунок 3 — Сопоставление устройств Linux именам COM-портов Windows-приложения через каталог ''%%dosdevices%%''**

{{:doc:serialmapping.png?400| Сопоставление устройств именам COM-портов}}

===== 7. Проверка и настройка портов в Wine =====

Запустить конфигуратор Wine для нужного префикса:

<code>
WINEPREFIX=/home/user/.local/share/wineprefixes/win32 winecfg
</code>

Сопоставление портов хранится в реестре префикса в разделе ''%%[Software\\Wine\\Ports]%%''. При необходимости его можно задать напрямую, создав файл ''%%ports.reg%%'' и импортировав его:

<code>
REGEDIT4

[HKEY_LOCAL_MACHINE\Software\Wine\Ports]
"COM1"="/dev/com_chromos"
"COM2"="/dev/ttyS0"
</code>

<code>
WINEPREFIX=/home/user/.local/share/wineprefixes/win32 wine regedit ports.reg
</code>

После изменения реестра перезапустить службу Wine, чтобы порты были перечитаны:

<code>
WINEPREFIX=/home/user/.local/share/wineprefixes/win32 wineserver -k
</code>

===== 8. Проверка работоспособности порта =====

На стороне Linux — базовая проверка параметров и доступности порта:

<code>
stty -F /dev/ttyUSB0 -a
</code>

На стороне Linux — контроль обмена (например, чтение «сырых» данных):

<code>
cat /dev/ttyUSB0
</code>

На стороне Windows-приложения — выбор соответствующего COM-порта (''%%COM1%%'', ''%%COM2%%'', …) в настройках подключения к устройству и проверка связи (опрос, чтение статуса/данных). Параметры обмена (скорость, биты данных, чётность, стоп-биты) задаются средствами приложения и должны соответствовать настройкам подключаемого устройства.

===== 9. Типовые неисправности и их устранение =====

^Признак                                         ^Возможная причина                       ^Действие                                        ^
|Приложение не видит COM-порт                    |Не создана ссылка в ''%%dosdevices%%''  |Выполнить п. 6 для нужного префикса             |
|«Доступ запрещён» при открытии порта            |Пользователь не в группе ''%%dialout%%''|Выполнить п. 4, перезайти в сессию              |
|Порт «пропадает» после переподключения          |Изменилось имя ''%%/dev/ttyUSB*%%''     |Закрепить имя через ''%%udev%%'' (п. 5)         |
|Порт платы расширения отсутствует в ''%%/dev%%''|Не загружен драйвер платы               |Установить модуль ядра производителя (п. 3.1)   |
|Нет обмена при корректном порту                 |Несовпадение скорости/параметров        |Согласовать параметры порта с устройством (п. 8)|
|Порт недоступен, права корректны                |Ограничения МКЦ Astra Linux             |Проверить мандатные метки устройства и процесса |

===== 10. Краткая последовательность действий (чек-лист) =====

  - Подключить устройство (плату расширения или USB-to-COM).
  - Определить путь устройства ''%%/dev/ttyS*%%'' или ''%%/dev/ttyUSB*%%'' (раздел 3).
  - Убедиться в членстве пользователя в группе ''%%dialout%%'' (раздел 4).
  - При необходимости закрепить имя устройства через ''%%udev%%'' (раздел 5).
  - Создать символьную ссылку ''%%comN%%'' в ''%%dosdevices%%'' Wine-префикса (раздел 6).
  - Проверить/задать сопоставление портов в реестре Wine (раздел 7).
  - Проверить связь с устройством из Windows-приложения (раздел 8).