== Диспенсер карт (черновик) == 

== Описание ==

Управляющий контроллер позволяет управлять выдачей карт с управляющего компьютера (хоста) через интерфейс USB.
Хост отслеживает состояние диспенсера (команда STATUS) на предмет наличия фатальных ошибок (JAMMED) и состояния стекера карт.

Диспенсер может находится в одном из четырех статусов 

 * 0x00 — инициализация. Производится при старте устройства. 
 * 0x01 — готов к работе. Штатное состояние устройства при ожидании команды на выдачу карт.
 * 0x02 — идет транзит карты.
 * 0x03 — карта в положении escrow.
 * 0xF0 - фатальная ошибка JAMMED. В данное состояние диспенсер переходит в случае если зафиксирован сбой работы.

Выход из состояния JAMMED может быть осуществлен двумя способами:
 * Перезагрузкой устройства
 * Длительным (2-3 сек) нажатием кнопки на устройстве. 




== Демонстрационная утилита ==

Демонстрационная утилита позволяет управлять диспенсером с командной строки.

Варианты запуска:

Проверка доступности устройства:
{{{
protodemo.exe ping
}}}

Проверка статуса:
{{{
protodemo.exe status
}}}

Выдача карты
{{{
priotodemo.exe dispense
}}}

Информация по последней выданной карте
{{{
priotodemo.exe dispense_result
}}}

== API ==

Управление БУ с хоста осуществляется через порт USB, который эмулирует работу последовательного порта (COM-порта). 
Для корректной работы необходимо установить драйвер (USB CDC):

Параметры последовательного порта:

 * Baudrate: 115200
 * Parity: none
 * 8 bits
 * 1 STOP

БУ и хост обмениваются командами и данными, инкапсулированными в пакеты следующего формата:

 * (1 байт) sync - байт синхронизации, 0x55
 * (1 байт) size - размер пакета (включая sync и crc)
 * (2 байта) адрес устройства, иные параметры - не используются, передавать 0x00 0x00
 * (1 байт) cmd/response - код команды или устройства
 * (N байт) data - блок данных команды (может быть пустым)
 * (2 байта) crc - контрольная сумма CRC16-CCIT



== PING (0x01): проверка связи с устройством ==

Без данных. Успешный ответна команду (response = 0x01) поступает без данных.

== TRANSIT (0x02): команда транзита карты ==

В запросе:
 * 1 байт: назначение транзита: 0x01 - в положение escrow, 0x02 - выдать карту, 0x03 - захват карты

Успешный ответ на команду (response = 0x02) поступает без данных, ошибка (response = 0x00) поступает с кодом ошибки размером 1 байт в блоке данных.

== CARD_INFO (0x03): команда запроса информации по карте ==

Команда выполняется только в случае наличия карты в положении escrow.

При успешном ответе (response = 0x03) в блоке данных последовательно возвращаются:  
 * 1 байт: результат операции (0x00 — карта выдана, 0x01 - операция выполняется, 0x02 - отказ в выдаче, карта отбракована, 0x03 - фатальная ошибка JAMMED)
 * последовательность TLV-блоков с описанием карты (только если карта выдана)

 TLV 0x01 : UID карты
 * 1байт: тип блока - 0x01
 * 2байт: размер содержимого блока (length) - переменный (для Mifare Classic 1K/4K - 4 байта, для Mifare UL - 7 байт)
 * length байт: UID карты

при ошибке (response = 0x00) поступает с кодом ошибки размером 1 байт в блоке данных.

== STATUS (0x03): текущее состояние устройства == 

Без данных, запрашивает текущее состояние устройства. 

В ответе (response = 0x01) в блоке данных последовательно возвращаются:  
 * 1 байт: статус устройства (0x00 — инициализация, 0x01 — готов к работе, 0x02 — в процессе выдачи, 0x03 - фатальная ошибка JAMMED)
 * 1 байт: состояние датчика нижнего уровня стека карт  (0x00 - магнитов достаточно, 0x01 - уровень низкий)

== Порядок операции выдачи карты ==
 * Выдать команду TRANSIT в положение escrow
 * Дождаться состояния 0x03 (карта в положении escrow) в ответе команды STATUS
 * Выполнить операцию CARD_INFO, получить информацию по карте
 * Выдать команду TRANSIT на выдачу или захват карты
 * Дождаться состояния 0x01 (готов к работе) в ответе команды STATUS

== Обработка ошибок ==
 При возникновении операционных ошибок транзита карт диспенсер переходит в состояние JAMMED (определяется командой STATUS) и требует обслуживания для восстановления работоспособности,