# КМАЗС-ОФИС на Linux: подключение считывателя IronLogic Z-2 USB (упрощенная инструкция)

Эта инструкция написана для пользователей с минимальным опытом Linux.
Все команды выполняйте по очереди и проверяйте результат после каждого шага.

## 1) Что важно знать заранее

1. Официально для Z-2 USB обычно используется USB-UART на базе FTDI (чаще всего VID:PID 0403:1234).
2. На практике у некоторых ридеров и совместимых устройств USB-чип может отличаться.
3. Если чип другой, логика подключения та же: Linux должен назначить драйвер и создать порт /dev/ttyUSB* или /dev/ttyACM*.

Проверенные признаки:
- в lsusb виден ридер;
- в usb-devices у ридера указан Driver=... (не Driver=(none));
- в dmesg после подключения есть строка про ttyUSB0/ttyUSB1/ttyACM0 и т.д.

## 2) Подключите ридер и проверьте, что Linux его видит

1. Подключите ридер к USB-порту.
2. Выполните:
lsusb
3. Найдите строку с IronLogic.

Для классического Z-2 USB часто видно:
ID 0403:1234 Future Technology Devices International, Ltd IronLogic RFID Adapter [Z-2 USB]

Сохраните пару VID:PID (например, 0403:1234) - она может понадобиться дальше.

## 3) Проверьте, назначен ли драйвер

1. Выполните:
usb-devices
2. Найдите блок вашего ридера (удобно ориентироваться по Vendor/ProdID, Manufacturer и Product).
3. В строке, начинающейся с I:, проверьте параметр Driver=.

Если видите Driver=ftdi_sio (или другой драйвер, но не (none)), переходите к шагу 5.
Если видите Driver=(none), переходите к шагу 4.

## 4) Если Driver=(none) (вариант для FTDI 0403:1234)

Ниже - самый частый случай для Z-2 USB (FTDI).

1. Отключите ридер.
2. Загрузите модуль драйвера:
sudo modprobe ftdi_sio
3. Зарегистрируйте устройство в драйвере:
echo 0403 1234 | sudo tee /sys/bus/usb-serial/drivers/ftdi_sio/new_id > /dev/null
4. Подключите ридер снова.
5. Проверьте последние сообщения ядра:
dmesg | tail -n 30

Ожидаемый результат: появится строка вида
... attached to ttyUSB0 (номер может быть другим).

Если у вас не 0403:1234, не используйте эту команду с чужими значениями "наугад" - сначала уточните чип/драйвер по lsusb, usb-devices и dmesg.

## 5) Определите имя COM-порта (последовательного порта)

После подключения выполните:
ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null

Обычно будет что-то вроде /dev/ttyUSB0.
Запомните это имя (дальше в примерах используется /dev/ttyUSB0).

## 6) Быстрый тест чтения карты

1. Настройте порт на скорость 9600:
stty 9600 -F /dev/ttyUSB0 raw -echo
2. Откройте поток данных с ридера:
cat /dev/ttyUSB0
3. Приложите карту/брелок к считывателю.

Если все работает, в терминале появится строка похожая на:
Mifare[A06AD64E] 1K (0004,08) 214,27296

Для выхода нажмите Ctrl+C.

Если есть ошибка "Permission denied", проверьте:
- пользователь добавлен в группу dialout;
- вы перелогинились после добавления в группу.

## 7) Настройка КМАЗС-ОФИС через стабильный путь /dev/serial/by-id

Использовать "голый" ttyUSB0 в настройках программы не рекомендуется - номер может меняться после перезагрузки.

### 7.1 Узнайте постоянное имя устройства

Выполните:
ls /dev/serial/by-id/

Пример:
usb-ILogic_USB_IL_Mifare_Adapter_XXXXX-if00-port0

### 7.2 Создайте (или отредактируйте) файл /opt/kmazs/serial-ports.txt

Пример через редактор:
kate /opt/kmazs/serial-ports.txt
или
pluma /opt/kmazs/serial-ports.txt

Добавьте строку:
IronLogic=usb-ILogic_USB_IL_Mifare_Adapter_XXXXX-if00-port0

Комментарий можно добавить строкой выше:
# Карт-ридер IronLogic Z-2 USB

Важно: для записи в /opt/kmazs/ у пользователя должны быть права (группа kmazs-admins, см. setup-user-groups.txt).

### 7.3 Альтернатива без ручного редактирования

Если устройство подключено, можно дописать строку командой:
echo "IronLogic=$(ls /dev/serial/by-id/ | grep -i ILogic)" | sudo tee -a /opt/kmazs/serial-ports.txt

## 8) Настройка в программе КМАЗС-ОФИС

1. Откройте: Настройки -> Настройки программы -> Ключи / карты.
2. Включите флаг: Ридер бесконтактных карт подключен.
3. В поле Тип ридера выберите IronLogic.
4. В поле COM-порт выберите IronLogic (имя из serial-ports.txt).
5. Нажмите ОК и перезапустите программу.

## 9) Автозагрузка настройки FTDI при старте Linux (только если это действительно нужно)

Делайте этот раздел только если после перезагрузки снова появляется Driver=(none) для 0403:1234.

### 9.1 Создайте скрипт /etc/load-iron-logic.sh

Сначала создайте файл в домашнем каталоге текущего пользователя (это проще и безопаснее):
nano ~/load-iron-logic.sh

Вставьте в файл следующее содержимое (обычно в терминале: Ctrl+Shift+V, либо Shift+Insert, либо правая кнопка мыши -> Вставить):

#! /bin/bash
modprobe ftdi_sio
echo 0403 1234 > /sys/bus/usb-serial/drivers/ftdi_sio/new_id

Сохраните файл и закройте редактор (в nano: Ctrl+O, Enter, затем Ctrl+X).

Команды установки:
sudo cp ~/load-iron-logic.sh /etc/
sudo chmod +x /etc/load-iron-logic.sh

### 9.2 Создайте службу /etc/systemd/system/load-iron-logic.service

Сначала создайте файл службы сразу в системном каталоге:
sudo nano /etc/systemd/system/load-iron-logic.service

Вставьте в файл следующее содержимое (обычно в терминале: Ctrl+Shift+V, либо Shift+Insert, либо правая кнопка мыши -> Вставить):

[Unit]
Description=Load FTDI driver for IronLogic Z-2 USB
[Service]
Type=oneshot
ExecStart=/etc/load-iron-logic.sh
[Install]
WantedBy=multi-user.target

Сохраните файл и закройте редактор (в nano: Ctrl+O, Enter, затем Ctrl+X).

Команды включения:
sudo systemctl daemon-reload
sudo systemctl enable load-iron-logic
sudo systemctl start load-iron-logic
systemctl status load-iron-logic

Что означает каждая команда:
1. sudo systemctl daemon-reload
   - systemd перечитывает файлы служб после добавления нового .service.
2. sudo systemctl enable load-iron-logic
   - включает автозапуск службы при старте Linux.
3. sudo systemctl start load-iron-logic
   - запускает службу сразу, без перезагрузки.
4. systemctl status load-iron-logic
   - показывает состояние службы.

Как понять результат проверки:
- если видите Active: active (exited), служба отработала успешно;
- если видите failed, посмотрите текст ошибки в этом же выводе и проверьте:
  - существует ли файл /etc/load-iron-logic.sh;
  - выдано ли ему право на запуск (chmod +x);
  - нет ли опечаток в файле /etc/systemd/system/load-iron-logic.service.

## 10) Если у ридера не FTDI-чип

По открытым источникам для Z-2 USB базовый вариант - FTDI (0403:1234), но у других моделей/совместимых устройств могут быть иные USB-мосты.

Что делать безопасно:
1. Всегда сначала смотрите lsusb, usb-devices, dmesg.
2. Если Linux уже назначил драйвер (например, не ftdi_sio, а другой), обычно дополнительная ручная регистрация не нужна.
3. Цель одна: получить рабочий порт /dev/ttyUSB* или /dev/ttyACM* и затем настроить /dev/serial/by-id/ для КМАЗС-ОФИС.
4. Если драйвер не назначается (Driver=(none)), зафиксируйте вывод трех команд и передайте его специалисту для точного подбора драйвера.

Минимальный набор диагностики для обращения в поддержку:
- lsusb
- usb-devices
- dmesg | tail -n 80