﻿# ЗАПУСК КМАЗС-ОФИС на Linux - подключение ридера IronLogic Z-2 USB

Внимание! В инструкции предполагается, что в ридере используется чип ftdi для организации COM-порта.
Если используется другой чип, то информация может оказаться неактуальной.

Для использования ридера IronLogic Z-2 USB необходимо:

1. Подключить устройство к компьютеру (если используется виртуальная машина, то выполнить проброс устройства).

2. Выполнить в терминале команду lsusb для определения списка подключенных USB-устройств. Пример вывода этой команды:
	$ lsusb
	Bus 002 Device 002: ID 8087:8001 Intel Corp.
	Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
	Bus 001 Device 002: ID 8087:8009 Intel Corp.
	Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
	Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
	Bus 003 Device 011: ID 046d:c050 Logitech, Inc. RX 250 Optical Mouse
	Bus 003 Device 016: ID 0403:1234 Future Technology Devices International, Ltd IronLogic RFID Adapter [Z-2 USB]
	Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Внимание! Должна появиться строка «Future Technology Devices International, Ltd IronLogic RFID Adapter [Z-2 USB]».
Эта строка свидетельствует о том, что в ридере используется чип ftdi.

Необходимо запомнить ID: 0403:1234, он может потребоваться при дальнейших действиях по подключению устройства. 
Для других устройств, отличных от "Iron Logic", либо для других моделей ридера "Iron Logic", ID может быть другим.

2.1 Убедиться в том, что для ридера IronLogic отсутствует загруженный драйвер в оперативной памяти.
Дело в том, что чип ридера IronLogic может оказаться неоригинальным, в таком случае он не зарегистрирован в конфигурационных файлах ОС Linux. 
В связи с этим Linux не сможет автоматически загрузить в оперативную память подходящий драйвер. В таком случае потребуется самостоятельно вызвать функцию загрузки драйвера для чипов ftdi.
Выполните команду usb-devices (см. п. 8), отыщите раздел со строкой "Product=USB IL Mifare Adapter" и найдите в этом разделе строку, которая начинается с "I:".
Проверьте, какое значение указано после "Driver=". Если указано Driver=(none), то необходимо выполнить дополнительные команды "modprobe" и "echo 0403 1234...", а также разработать скрипт настройки и службу для автоматического запуска этого скрипта. Если же указано Driver=ftdi_sio (либо другое название драйвера, если в ридере используется другой чип), значит в линуксе имеется инфорация о карт-ридере и разработка скрипта/службы не потребуется.

3. Предположим, что Driver=(none). Отключите ридер "Iron Logic".

4. Добавить модуль ядра ftdi_sio:
sudo modprobe ftdi_sio

5. Указываем драйверу какое устройство является FTDI:
sudo su
echo 0403 1234 > /sys/bus/usb-serial/drivers/ftdi_sio/new_id

6. Снова подключить устройство. В этот момент устройство будет доступно по RS-232

7. Выполнить команду "sudo dmesg | tail" для того, чтобы убедиться, что Linux увидел устройство и создал виртуальный
COM-порт (dmesd – команда просмотра файла сообщений, сформированных ядром Linux). Если подключено несколько USB-устройств, 
то есть вероятность, что информация по IronLogic окажется не в самом конце файла. Пример вывода:
[793134.996159] usb 3-1: new full-speed USB device number 20 using xhci_hcd
[793135.131301] usb 3-1: New USB device found, idVendor=0403, idProduct=1234
[793135.131303] usb 3-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[793135.131305] usb 3-1: Product: USB IronLogic RFID Adapter
[793135.131306] usb 3-1: Manufacturer: ILogic
[793135.131307] usb 3-1: SerialNumber: IL02KQQ9
[793135.135463] ftdi_sio 3-1:1.0: FTDI USB Serial Device converter detected
[793135.135502] usb 3-1: Detected FT232RL
[793135.135641] usb 3-1: FTDI USB Serial Device converter now attached to ttyUSB0

Запомните, к какому порту подключен ридер (в данном примере к порту "ttyUSB0").

8. Выполнить команду usb-devices, она покажет информацию обо всех подключенных USB-устройствах:
	T:  Bus=02 Lev=02 Prnt=03 Port=00 Cnt=01 Dev#=  5 Spd=12  MxCh= 0
	D:  Ver= 2.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
	P:  Vendor=0403 ProdID=1234 Rev=06.00
	S:  Manufacturer=ILogic
	S:  Product=USB IL Mifare Adapter
	S:  SerialNumber=ILV9N58B
	C:  #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=132mA
	I:  If#= 0 Alt= 0 #EPs= 2 Cls=ff(vend.) Sub=ff Prot=ff Driver=ftdi_sio
	
Найти устройство "Product=USB IL Mifare Adapter" и убедиться, что используется драйвер «ftdi_sio»
Если указано Driver=(none), значит драйвер «ftdi_sio» не используется.

9. Убедиться в работоспособности ридера. Для этого достаточно использовать стандартные средства в Линуксе:

	9.1 Выполнить команду конфигурирования COM-порта "ttyUSB0" на скорость 9600:
	stty 9600 -F /dev/ttyUSB0 raw -echo
	Внимание! Если возникла ошибка «отказано в доступе», значит у пользователя нет прав для работы с данным COM-портом.
	Обратите внимание! Для использования COM-порта пользователь должен находиться в группе "dialout".
	Проверьте это с помощью команды "groups". Если в данный момент вы работаете с правами пользователя "root", то группа dialout не требуется.

	9.2 Открыть COM-порт для просмотра данных от ридера:
	cat /dev/ttyUSB0

	9.3 Приложить карту к ридеру (Mifare либо em-marine, в зависимости от модификации ридера). Должен отобразиться текст от ридера, например:
	Mifare[A06AD64E] 1K (0004,08) 214,27296
	Внимание! Для завершение работы программы cat следует нажать Ctrl+C.

10. Если программа КМАЗС-ОФИС уже установлена, то создать файл "/opt/kmazs/serial-ports.txt" и добавить в него короткое название COM-порта, например "IronLogic"
(оно будет отображаться в окне настройки программы при выборе COM-порта), а также длинное наименование устройства, которое отображается в папке "/dev/serial/by-id/", если устройство подключено к компьютеру. Для этого:

10.1 Определяем список файлов в папке "/dev/serial/by-id/"
	ls /dev/serial/by-id/
	пример ответа:
	usb-ILogic_USB_IL_Mifare_Adapter_XXXXX-if00-port0
В данном случае "usb-ILogic_USB_IL_Mifare_Adapter_XXXXX-if00-port0" - длинное наименование устройства, которое требуется внести в файл "serial-ports.txt".
Примечание: если вы хотите выяснить, на какой именно системный COM-порт (ttyUSB) ссылается это длинное наименование, то воспользуйтесь командой "ls -l /dev/serial/by-id/"

10.2 Создать текстовый файл "/opt/kmazs/serial-ports.txt";
Внимание! Для создания текстового файла используйте простой текстовый редактор (например Kate для Астра Линукс или pluma для РЭД ОС). Категорически не используйте для этих целей LibreOffice!
Внимание! Для создания файлов в каталоге "/opt/kmazs/" текущий пользователь должен быть включен в группу "kmazs-admins" (см. setup-user-groups.txt).
Пример команды создания текстового файла с помощью редактора Kate:
	kate /opt/kmazs/serial-ports.txt
Пример команды создания текстового файла с помощью редактора pluma:	
	pluma /opt/kmazs/serial-ports.txt	
	
10.3 Скопируйте длинное название устройства из терминала (шаг 10.1) и добавьте в файл serial-ports.txt строку следующего вида:	
-------------------------------------------------------------
# Карт-ридер IronLogic Z2 USB
IronLogic=usb-ILogic_USB_IL_Mifare_Adapter_XXXXX-if00-port0
-------------------------------------------------------------
Здесь "#" - комментарий. Он нужен для того, чтобы вы не забыли, какому устройству соответствует данная настройка. Он не является обязательным.
Не забудьте сохранить файл!

10.4 Альтернативный быстрый способ (без ручного редактирования файла):
Если вы не хотите открывать текстовый редактор и копировать длинное название вручную, вы можете автоматически дописать настройку в файл одной командой в терминале.
Важно: Устройство должно быть физически подключено к USB-порту компьютера!
Выполните команду (на примере ридера IronLogic):
-------------------------------------------------------------
echo "IronLogic=$(ls /dev/serial/by-id/ | grep -i ILogic)" >> /opt/kmazs/serial-ports.txt
-------------------------------------------------------------
Здесь:
1) ls /dev/serial/by-id/ 	- выдает список чистых длинных названий.
2) grep -i ILogic 	- находит среди них строку, содержащую "ILogic" (игнорируя регистр букв).
3) echo "IronLogic=..." 	- формирует готовую строку вида IronLogic=usb-ILogic_USB....
4) ">> /opt/kmazs/serial-ports.txt" - добавляет полученный текст в конец файла "/opt/kmazs/serial-ports.txt"

11. Настроить автоматическую загрузку драйверов при включении Linux
Для автоматической загрузки драйвера «ftdi_sio» и для автоматической регистрации устройства Iron Logic Z-2 USB необходимо создать два файла: файл-скрипт для выполнения необходимых команд и файл-службу для того, чтобы файл-скрипт запускался при загрузке Linux. Файл-скрипт проще всего сначала создать в папке пользователя, а затем скопировать в папку /etc с помощью командной строки.

11.1. Создать в каталоге пользователя файл "load-iron-logic.sh" со следующим содержимым:
-------------------------------------------------------------
#! /bin/bash
# Скрипт для загрузки драйвера ftdi для Iron Logic Z-2 USB
# Убедиться, что у Iron Logic Z-2 USB Идентификатор=0403:1234
# Можно с помощью команды lsusb
modprobe ftdi_sio
echo 0403 1234 > /sys/bus/usb-serial/drivers/ftdi_sio/new_id
-------------------------------------------------------------
	
11.2. Скопировать файл "load-iron-logic.sh" в папку /etc/ и выдать разрешение на запуск:	
-------------------------------------------------------------
sudo cp ~/load-iron-logic.sh /etc/
sudo chmod +x /etc/load-iron-logic.sh
-------------------------------------------------------------

11.3. Создать в профиле пользователя файл «load-iron-logic.service» со следующим содержимым:
-------------------------------------------------------------
[Unit]
Description=Запуск скрипта загрузки драйвера Iron Logic
[Service]
Type=oneshot
ExecStart=/etc/load-iron-logic.sh
[Install]
WantedBy=multi-user.target
-------------------------------------------------------------	
	
Параметр Type=oneshot означает, что служба завершится сразу же после выполнения заданного скрипта.

11.4. Скопировать файл «load-iron-logic.service» в папку /etc/systemd/system/ зарегистрировать службу в системе:	
-------------------------------------------------------------
sudo cp ~/load-iron-logic.service /etc/systemd/system/
sudo systemctl enable load-iron-logic
-------------------------------------------------------------	
	
11.5. Выполнить команду "systemctl status load-iron-logic" для проверки статуса службы. Так можно убедиться, что служба была успешно установлена.

11.6. Выполнить перезагрузку Linux и убедиться, что устройство работает.

12. Если программа КМАЗС-ОФИС установлена, то зайдите в меню Настройки / Настройки программы, затем в раздел "ключи / карты". 
Включите флаг "Ридер бесконтактных карт подключен". В поле "Тип ридера" укажите "IronLogic". В поле "COM-порт" в выпадающем списке найдите пункт "IronLogic" (название берётся из файла "serial-ports.txt") и выберите его. Нажмите "ОК" и перезапустите программу.
Внимание! Несмотря на то, что порт "ttyUSB0" также отображается в выпадающем списке, не рекомендуется его выбирать, т.к. в Линуксе привязка COM-портов к подключенным USB-устройствам осуществляется динамически. Если сегодня ридер IronLogic был подключен к COM-порту "ttyUSB0", то завтра он может оказаться подключен к COM-порту "ttyUSB1".