29.09.2016

Универсальный драйвер ERFID.
Программный интерфейс

В настоящем документе представлено техническое описание программного интерфейса продукта «Универсальный драйвер RFID» компании ЭРФИД.

Глоссарий

Наименование	Описание
ИС	Информационная система
ОС	Операционная система
ПО	Программное обеспечение
УД	Универсальный драйвер
API	Англ.: Application Programming Interface [эй-пи-ай]. Интерфейс программирования приложений; Интерфейс прикладного программирования
GPIO	General Purpose Input-Output. Каналы TTL для чтения сигналов и управления внешними устройствами
GPO	General Purpose Output. Каналы TTL для управления внешними устройствами

Общие сведения

Универсальный драйвер ERFID (УД) является самостоятельным программным продуктом, работающим под управлением ОС Windows и предназначенным для организации работы со считывателями радио-меток. Для целей разработки другого программного обеспечения (ПО), использующего API УД для обращения к его функциям, установка лицензии УД не обязательна. В этом случае УД будет работать в демонстрационном режиме.

Демонстрационный режим

При запуске УД без лицензии, система будет работать в демонстрационном отладки, для которого действуют следующие ограничения:

После получения команды на начало работы считывателя меток система будет бездействовать в течение первых 90 секунд
По истечении указанного периода времени будет предоставлена возможность работы только с десятью различными метками. Если идентификатор метки изменяется (производится запись метки), то она будет восприниматься как новая уникальная метка. При превышении максимально допустимого количества уникальных меток потребуется перезапуск УД.

Технические требования

Для работы ПО УД необходимы следующие системные компоненты:

Операционная система Microsoft Windows версии 7, 8, 10, либо Windows Server 2008, 2012
.NET Framework v.3.5, v.4.0

Технические описания

Взаимодействие с УД построено на использовании web-сервисов системы. После установки и запуска драйвера, возможно получить его описание (WSDL) по следующему адресу:

http://127.0.0.1:8787/ERFIDCommunicationServer/?singleWsdl

Служба запускается на локальном адресе компьютера и может работать автономно без подключения к сети Ethernet.

Общение с системой происходит при помощи механизма SOAP (1.1). Сообщения “запрос-ответ” передаются по протоколу HTTP. Данные представлены в формате XML и передаются как простые тексты в кодировке UTF-8 (при использовании символов кириллицы - ОБЯЗАТЕЛЬНО).

Порядок работы

Типовой сценарий работы с ПО УД

Типовой сценарий работы с ПО УД включает следующую последовательность действий:

Получить установочный дистрибутив УД и установить его на компьютер, куда обычно подключаются физические считыватели меток. Дополнительные драйверы устройств необходимо доставить в ручную из под-каталога установки УД USBDrivers (Nordic, RoyalRay, ThingMagic).
Запустить приложение администрирования УД; нажать кнопку "Старт":

Рис.1. Форма управления УД

Важно:
При установке "по умолчанию" УД должен запуститься автоматически. Также он будет автоматически запускаться при старте ОС. Поэтому если УД не был остановлен вручную и на форме управления активна кнопка "Старт", то это может свидетельствовать о проблемах, связанных с настройками приложения.
Подробнее о возможных проблемах смотри документ "Универсальный драйвер ERFID. Решение проблем"
После запуска приложения активируется web-сервис УД, доступный по адресу:
http://127.0.0.1:8787/ERFIDCommunicationServer/
Из клиентского приложения выполнить команды на стороне УД:
- Инициализация (RFIDCommandInitPhysicalReader)
- Настройка мощности антенны (RFIDCommandSetAntennaPower)
- Проверка наличия лицензии (RFIDCommandGetPhysicalReaderLicenseStatus)
- Начало чтения меток (RFIDCommandStartRead)
  После выполнения этой команды необходимо внести в зону видимости антенны устройства одну или несколько меток
- Чтение всех меток (RFIDCommandGetTags)
- При необходимости:
  - Чтение полной информации о метке (RFIDCommandReadTag)
  - Запись информации на метку (RFIDCommandWriteTag)
- Окончание чтения меток (RFIDCommandStopRead)

Публикация данных в асинхронном режиме

Помимо работы "по запросу" в УД доступна функция публикация данных о прочитанных метках в асинхронном режиме, которая "по умолчанию" не активирована. Порядок её подключения и использования описание см.п. "Настройка функции обратного вызова (асинхронный режим)".

API

Для взаимодействия с УД используется один SOAP-запрос ExecCommand. Все команды УД выполняются посредством выполнения ExecCommand/ERFIDcommand с указанием типа команды и параметров.

Пример:

Список команд

Ниже перечислены команды, используемые при работе с драйвером:

№№	Название	Тип	Описание
1.	Инициализация	RFIDCommandInitPhysicalReader	Команда для инициализации физического устройства чтения радио-меток и перевода его в рабочее состояние
2.	Настройка мощности антенны	RFIDCommandSetAntennaPower	Команда для установки мощности антенны. Возможно задание мощности излучения и степень чувствительности приёма антенны
3.	Проверка наличия лицензии	RFIDCommandGetPhysicalReaderLicenseStatus	Команда для проверки наличия лицензии на использование физического устройства в УД
4.	Удаление устройства чтения меток	RFIDCommandRemovePhysicalReader	Команда для удаления из системы информации о физическом устройстве чтения меток
5.	Начало чтения меток	RFIDCommandStartRead	Команда для активации работы физического устройства чтения меток
6.	Окончание чтения меток	RFIDCommandStopRead	Команда для остановки работы физического устройства чтения меток
7.	Чтение всех меток	RFIDCommandGetTags	Команда для чтения всех меток из УД с момента последнего вызова этой же команды. Эта команда должна вызываться достаточно часто так, чтобы накопленные старые считанные метки не удалялись из памяти УД. Интервал чтения зависит от скорости появления новых меток в зоне видимости устройства чтения меток, и обычно колеблется от нескольких секунд до нескольких минут
8.	Чтение полной информации о метке	RFIDCommandReadTag	Команда для чтения всех сегментов данных указанной метки из физического устройства. Метка должна присутствовать в зоне видимости физического устройства чтения меток. В случае, если запрашиваемой метки нет в зоне видимости – возвращаются пустые значения полей и сконвертированный в формат EPC поступивший на вход команде идентификатор метки
9.	Запись информации на метку	RFIDCommandWriteTag	Команда для записи пользовательских данных в метку. В момент вызова этой команды метка должны присутствовать в зоне видимости считывающего устройства меток
10.	Управление фильтром меток	RFIDCommandSetFiltersData	Установка параметров фильтра меток в УД
11.	Считывание состояния каналов GPIO	RFIDCommandGetStatusGPIO	Получение информации о состоянии каналов GPIO физического считывателя
12.	Установка состояний каналов GPO	RFIDCommandSetGPO	Установка состояний каналов GPO физического считывателя
13.	Блокировка метки	RFIDCommandLockTagComplex	Команда для блокировки от перезаписи информации в метке. Используется, например, для предотвращения не санкционированного изменения данных метки.

Примеры использования

Инициализация (RFIDCommandInitPhysicalReader)

Команда должна быть сопровождена следующими параметрами:

№№	Поле	Тип	Значение	Описание
1.	ComandReceiver	Строка	SERVER	Признак, что команда адресована основному управляющему процессу УД
2.	Name	Строка	COM<n> либо IP-адрес	Адрес устройства, к которому подключен считыватель меток. Это может быть виртуальный или физический COM-порт, сетевой адрес и т.п.
3.	Type	Строка	RoyalRayReader	Тип устройства чтения меток. Может быть один из: CLOUReader KeytexReader LLRPReader NordicReader RoyalRayReader ThingMagicReader VanchReader TCPReader

Пример запроса (RFIDCommandInitPhysicalReader)

Пример ответа (RFIDCommandInitPhysicalReader)

Настройка мощности антенны (RFIDCommandSetAntennaPower)

Параметры команды:

№№	Поле	Тип	Значение	Описание
1.	ComandReceiver	Строка	PHISICAL_READER	Признак, что команда адресована физическому устройству чтения меток
2.	Name	Строка	COM<n> либо IP-адрес	Адрес устройства, к которому подключен считыватель меток. Это может быть виртуальный или физический COM-порт, сетевой адрес и т.п.
3.	ConfigToSet/AntennaInfo/Antenna	Число	1	Номер антенны на физическом устройстве, для которого производится настройка
4.	ConfigToSet/AntennaInfo/Tx	Число	100	Мощности излучения антенны в процентах от максимальной. Возможные значения: от "0" до "100".

Пример запроса (RFIDCommandSetAntennaPower)

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://www.w3.org/2003/05/soap-encoding"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ns3="http://schemas.microsoft.com/2003/10/Serialization/"
xmlns:ns4="http://schemas.datacontract.org/2004/07/ERFID.CommunicationClient.Interfaces"
xmlns:ns5="http://schemas.microsoft.com/2003/10/Serialization/Arrays"
xmlns:ns6="http://tempuri.org/"
xmlns:ns1="urn:erfid:command:wsdl:1">
<SOAP-ENV:Body>
<ns1:ExecCommand>
   <ns1:ERFIDcommand xsi:type="ns4:RFIDCommandSetAntennaPower">
   <ns4:ComandReceiver>PHISICAL_READER</ns4:ComandReceiver>
   <ns4:ReceiverName>COM3</ns4:ReceiverName>
   <ns4:ConfigToSet>
    <ns4:AntennaInfo>
     <ns4:Antenna>1</ns4:Antenna>
     <ns4:Tx>100</ns4:Tx>
    </ns4:AntennaInfo>
   </ns4:ConfigToSet>
   </ns1:ERFIDcommand>
</ns1:ExecCommand>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Пример ответа (RFIDCommandSetAntennaPower)

Проверка наличия лицензии (RFIDCommandGetPhysicalReaderLicenseStatus)

Параметры команды:

№№	Поле	Тип	Значение	Описание
1.	ComandReceiver	Строка	PHISICAL_READER	Признак, что команда адресована физическому устройству чтения меток
2.	ReceiverName	Строка	COM<n> либо IP-адрес	Адрес устройства, к которому подключен считыватель меток. Это может быть виртуальный или физический COM-порт, сетевой адрес и т.п.

Пример запроса (RFIDCommandGetPhysicalReaderLicenseStatus)

Пример ответа (RFIDCommandGetPhysicalReaderLicenseStatus)

Удаление устройства чтения меток (RFIDCommandRemovePhysicalReader)

Параметры команды:

№№	Поле	Тип	Значение	Описание
1.	ComandReceiver	Строка	PHISICAL_READER	Признак, что команда адресована физическому устройству чтения меток
2.	ReceiverName	Строка	COM<n> либо IP-адрес	Адрес устройства, к которому подключен считыватель меток. Это может быть виртуальный или физический COM-порт, сетевой адрес и т.п.

Пример запроса (RFIDCommandRemovePhysicalReader)

Пример ответа (RFIDCommandRemovePhysicalReader)

Начало чтения меток (RFIDCommandStartRead)

Параметры команды:

№№	Поле	Тип	Значение	Описание
1.	ComandReceiver	Строка	PHISICAL_READER	Признак, что команда адресована физическому устройству чтения меток
2.	ReceiverName	Строка	COM<n> либо IP-адрес	Адрес устройства, к которому подключен считыватель меток. Это может быть виртуальный или физический COM-порт, сетевой адрес и т.п.

Пример запроса (RFIDCommandStartRead)

Пример ответа (RFIDCommandStartRead)

Окончание чтения меток (RFIDCommandStopRead)

Параметры команды:

№№	Поле	Тип	Значение	Описание
1.	ComandReceiver	Строка	PHISICAL_READER	Признак, что команда адресована физическому устройству чтения меток
2.	ReceiverName	Строка	COM<n> либо IP-адрес	Адрес устройства, к которому подключен считыватель меток. Это может быть виртуальный или физический COM-порт, сетевой адрес и т.п.

Пример запроса (RFIDCommandStopRead)

Пример ответа (RFIDCommandStopRead)

Чтение всех меток (RFIDCommandGetTags)

Описание команды:

УД накапливает в памяти данные о метках, появившихся в зоне действия считывателей. Те метки, которые кратковременно исчезают из поля видимости антенны, не считаются вышедшими из зоны его действия. При этом максимальная задержка между последовательными событиями регистрации метки указывается в настройках фильтра, которые можно изменять при помощи отдельной команды: Управление фильтром меток (RFIDCommandSetFiltersData).

RFIDCommandGetTags возвращает список меток, накопленных с момента последнего её вызова. Для того, чтобы данные по метке были получены повторно необходимо, чтобы метка покинула зону действия считывателя на период времени, больший указанного в параметре Timeout команды Управление фильтром меток (RFIDCommandSetFiltersData).

Важно!
Если метка непрерывно читается устройством, и при этом несколько раз вызывается команда RFIDCommandGetTags, то ее данные будут предоставлены только при первом вызове команды.

Параметры команды:

№№	Поле	Тип	Значение	Описание
1.	ComandReceiver	Строка	LOGICAL_READER	Признак, что команда адресована логическому устройству чтения меток, объединяющего несколько физических антенн устройств чтения
2.	ReceiverName	Строка	COM<n> либо IP-адрес	Адрес устройства, к которому подключен считыватель меток. Это может быть виртуальный или физический COM-порт, сетевой адрес и т.п.

Пример запроса (RFIDCommandGetTags)

Пример ответа (RFIDCommandGetTags)

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
  <ExecCommandResponse xmlns="urn:erfid:command:wsdl:1">
   <ExecCommandResult i:type="a:RFIDCommandGetTagsResult" xmlns:a="http://schemas.datacontract.org/2004/07/ERFID.CommunicationClient.Interfaces" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <a:IsOK>true</a:IsOK>
    <a:TagsList>
     <a:RFIDMessageTagData>
      <a:CreationDate>2016-09-12T19:21:23</a:CreationDate>
      <a:MessageFrom>AccumulateFilter</a:MessageFrom>
      <a:MessageNumber>feddcc7e-db0a-4337-8985-2f0e04010745</a:MessageNumber>
      <a:Reader>COM3</a:Reader>
      <a:Antenna>1</a:Antenna>
      <a:Count>1</a:Count>
      <a:Direction>IN</a:Direction>
      <a:RSSI/>
      <a:RfidTag>300DBC6A3A30456D7EF5E51D</a:RfidTag>
     </a:RFIDMessageTagData>
     <a:RFIDMessageTagData>
      <a:CreationDate>2016-09-12T19:21:23</a:CreationDate>
      <a:MessageFrom>AccumulateFilter</a:MessageFrom>
      <a:MessageNumber>35e1d080-76d0-462e-9f2a-b4d4863a61b4</a:MessageNumber>
      <a:Reader>COM3</a:Reader>
      <a:Antenna>1</a:Antenna>
      <a:Count>1</a:Count>
      <a:Direction>IN</a:Direction>
      <a:RSSI/>
      <a:RfidTag>300DBC6A3A30456861050DDC</a:RfidTag>
     </a:RFIDMessageTagData>
    </a:TagsList>
   </ExecCommandResult>
  </ExecCommandResponse>
</s:Body>
</s:Envelope>

Чтение полной информации о метке (RFIDCommandReadTag)

Параметры команды:

№№	Поле	Тип	Значение	Описание
1.	ComandReceiver	Строка	PHISICAL_READER	Признак, что команда адресована физическому устройству чтения меток
2.	ReceiverName	Строка	COM<n> либо IP-адрес	Адрес устройства, к которому подключен считыватель меток. Это может быть виртуальный или физический COM-порт, сетевой адрес и т.п.
3.	RfidTagToSeek	Строка	<TagId>	Строка-идентификатор метки, данные которой следует прочитать
4.	TagBank	Строка	ALL	Тип банка данных метки для чтения. Возможные значения: TID, USER, EPC, RESERVED, ALL

Важно!
Для корректного чтения метки необходимо, чтобы в запросе был указан её идентификатор EPC (параметр RfidTagToSeek) и она находилась в зоне видимости физического устройства чтения.

Параметры ответа:

№№	Поле	Тип	Описание
1.	IsOK	Строка	Признак возникновения ошибки В случае ошибки = "false"
2.	Status	Строка	Если "IsOK = false", содержит описание ошибки. При успешном выполнении команды - всегда "Success"
3.	AllMemBanks/ MemBankData/ TagMemBankInfo/ HEXData	Строка	Содержимое банка данных памяти в формате HEX-string.
4.	AllMemBanks/ MemBankData/ TagMemBankInfo/ MemBank	Строка	Тип банка данных метки из которого получены данные. Возможные значения: TID, USER, EPC, RESERVED
5.	AllMemBanks/ Target	Строка	EPC идентификатор метки в формате HEX-string
6.	BusinessData/ MemBankData/ BusinessDataInfo/ Data	Строка	Для типа данных SERIAL содержит сериализованный TID в десятичном формате. Для типа данных SGTIN содержит идентификатор метки EPC, представленный в стандартном формате. Правила сериализации и форматирования SGTIN описываются стандартами GS1.
7.	BusinessData/ MemBankData/ BusinessDataInfo/ Name	Строка	Тип бизнес-данных. Возможные значения: SGTIN, SERIAL
8.	BusinessData/ Target	Строка	EPC идентификатор метки в формате HEX-string

Важно!
Обычная последовательность использования команды заключается в предварительном вызове команды Чтение всех меток (RFIDCommandGetTags). В полученном результате проверяется наличие интересующей нас метки и её идентификатор EPC в формате HEX-String используется для запроса полной информация по ней.

Пример запроса (RFIDCommandReadTag)

Пример ответа (RFIDCommandReadTag)

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
  <ExecCommandResponse xmlns="urn:erfid:command:wsdl:1">
   <ExecCommandResult i:type="a:RFIDCommandReadTagResult" xmlns:a="http://schemas.datacontract.org/2004/07/ERFID.CommunicationClient.Interfaces" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <a:IsOK>true</a:IsOK>
    <a:Status>Success</a:Status>
    <a:AllMemBanks>
     <a:MemBankData>
      <a:TagMemBankInfo>
       <a:HEXData>E280110020004B5C90500066</a:HEXData>
       <a:MemBank>TID</a:MemBank>
      </a:TagMemBankInfo>
      <a:TagMemBankInfo>
       <a:HEXData>00000000</a:HEXData>
       <a:MemBank>USER</a:MemBank>
      </a:TagMemBankInfo>
     </a:MemBankData>
     <a:Target>300DBC6A3A30456861050DDC</a:Target>
    </a:AllMemBanks>
    <a:BusinessData>
     <a:MemBankData>
      <a:BusinessDataInfo>
       <a:Data>urn:epc:tag:sgtin-96:0.466002851.0277.173426413020</a:Data>
       <a:Name>SGTIN</a:Name>
      </a:BusinessDataInfo>
      <a:BusinessDataInfo>
       <a:Data>173426413020</a:Data>
       <a:Name>SERIAL</a:Name>
      </a:BusinessDataInfo>
     </a:MemBankData>
     <a:Target>300DBC6A3A30456861050DDC</a:Target>
    </a:BusinessData>
   </ExecCommandResult>
  </ExecCommandResponse>
</s:Body>
</s:Envelope>

Запись информации на метку (RFIDCommandWriteTag)

Параметры команды:

№№	Поле	Тип	Значение	Описание
1.	ComandReceiver	Строка	PHISICAL_READER	Признак, что команда адресована физическому устройству чтения меток
2.	ReceiverName	Строка	COM<n> либо IP-адрес	Адрес устройства, к которому подключен считыватель меток. Это может быть виртуальный или физический COM-порт, сетевой адрес и т.п.
3.	RfidTagToSeek	Строка	<TagId>	Строка-идентификатор метки, данные которой следует прочитать
4.	AddressWrite	Число	2	Смещение относительно начала банка памяти, начиная с которого записываются данные. Размерность - "слово" (1 слово = 2 байт)
5.	ByteCount	Число	12	Количество байт, которые следует записать в метку. Пример: Для записи метки в формате SGTIN-96 используется "96 / 8 = 12" байт данных
6.	HEXData	Строка	urn:epc:tag:sgtin-96:0.46055443.03213.173426413020	Данные в формате HEX String, для записи в метку. При записи данных в область EPC (параметр TagBank), данные можно передавать в стандартном формате URN-EPC
7.	TagBank	Строка	EPC	Наименование банка данных метки для записи. Возможные значения: EPC, USER, RESERVED.
8.	ReaderAntennas/ unsignedShort	Строка	1	Номер антенны, которая будет использована в процессе записи данных на метку. Этот номер следует взять из результата работы команды GetTags для обрабатываемой метки

Пример запроса (RFIDCommandWriteTag)

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://www.w3.org/2003/05/soap-encoding" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns3="http://schemas.microsoft.com/2003/10/Serialization/" xmlns:ns4="http://schemas.datacontract.org/2004/07/ERFID.CommunicationClient.Interfaces" xmlns:ns5="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:ns6="http://tempuri.org/" xmlns:ns1="urn:erfid:command:wsdl:1">
<SOAP-ENV:Body>
<ns1:ExecCommand>
  <ns1:ERFIDcommand xsi:type="ns4:RFIDCommandWriteTag">
   <ns4:ComandReceiver>PHISICAL_READER</ns4:ComandReceiver>
   <ns4:ReceiverName>COM3</ns4:ReceiverName>
   <ns4:RfidTagToSeek>30115F600983236861050DDC</ns4:RfidTagToSeek>
   <ns4:AddressWrite>2</ns4:AddressWrite>
   <ns4:ByteCount>12</ns4:ByteCount>
   <ns4:HEXData>urn:epc:tag:sgtin-96:0.46055443.03213.173426413020</ns4:HEXData>
   <ns4:ReaderAntennas>
    <ns5:unsignedShort>1</ns5:unsignedShort>
   </ns4:ReaderAntennas>
   <ns4:TagBank>EPC</ns4:TagBank>
  </ns1:ERFIDcommand>
</ns1:ExecCommand>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Пример ответа (RFIDCommandWriteTag)

Управление фильтром меток (RFIDCommandSetFiltersData)

Параметры команды:

№№	Поле	Тип	Значение	Описание
1.	ComandReceiver	Строка	SERVER	Признак, что команда адресована основному управляющему процессу УД
2.	Data	Число		Устанавливаемое значение для параметра фильтра
3.	FilterName	Строка	AccumulateFilter	Название фильтра, для которого устанавливается параметр
4.	OptionName	Строка	MinRSSI	Название изменяемого параметра фильтра. Возможные параметры: Timeout Время обновления фильтра MinRSSI минимальный уровень силы сигнала от метки, для которого включается работа фильтра TagMaskHEX Маска для меток, публикующихся через фильтр. Несколько значений фильтра можно перечислить через ",". Внутри шаблона"%"

Пример запроса (RFIDCommandSetFiltersData)

Пример ответа (RFIDCommandSetFiltersData)

Считывание состояния каналов GPIO (RFIDCommandGetStatusGPIO)

Параметры команды:

№№	Поле	Тип	Значение	Описание
1.	ComandReceiver	Строка	PHISICAL_READER	Признак, что команда адресована физическому устройству чтения меток
2.	ReceiverName	Строка	COM<n> либо IP-адрес	Адрес устройства, к которому подключен считыватель меток. Это может быть виртуальный или физический COM-порт, сетевой адрес и т.п.

Пример запроса (RFIDCommandGetStatusGPIO)

Пример ответа (RFIDCommandGetStatusGPIO)

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
  <ExecCommandResponse xmlns="urn:erfid:command:wsdl:1">
   <ExecCommandResult i:type="a:RFIDCommandGetStatusGPIOResult" xmlns:a="http://schemas.datacontract.org/2004/07/ERFID.CommunicationClient.Interfaces" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <a:IsOK>true</a:IsOK>
    <a:Status>GetStatusGPIO - Complete</a:Status>
    <a:GPIStatus>
     <a:ChannelGPO>
      <a:GPOIndex>1</a:GPOIndex>
      <a:TurnON>false</a:TurnON>
     </a:ChannelGPO>
     <a:ChannelGPO>
      <a:GPOIndex>2</a:GPOIndex>
      <a:TurnON>false</a:TurnON>
     </a:ChannelGPO>
     <a:ChannelGPO>
      <a:GPOIndex>3</a:GPOIndex>
      <a:TurnON>false</a:TurnON>
     </a:ChannelGPO>
     <a:ChannelGPO>
      <a:GPOIndex>4</a:GPOIndex>
      <a:TurnON>false</a:TurnON>
     </a:ChannelGPO>
    </a:GPIStatus>
    <a:GPOStatus>
     <a:ChannelGPO>
      <a:GPOIndex>1</a:GPOIndex>
      <a:TurnON>false</a:TurnON>
     </a:ChannelGPO>
     <a:ChannelGPO>
      <a:GPOIndex>2</a:GPOIndex>
      <a:TurnON>false</a:TurnON>
     </a:ChannelGPO>
     <a:ChannelGPO>
      <a:GPOIndex>3</a:GPOIndex>
      <a:TurnON>false</a:TurnON>
     </a:ChannelGPO>
     <a:ChannelGPO>
      <a:GPOIndex>4</a:GPOIndex>
      <a:TurnON>false</a:TurnON>
     </a:ChannelGPO>
    </a:GPOStatus>
   </ExecCommandResult>
  </ExecCommandResponse>
</s:Body>
</s:Envelope>

Установка состояний каналов GPO (RFIDCommandSetGPO)

Параметры команды:

№№	Поле	Тип	Значение	Описание
1.	ComandReceiver	Строка	PHISICAL_READER	Признак, что команда адресована физическому устройству чтения меток
2.	ReceiverName	Строка	COM<n> либо IP-адрес	Адрес устройства, к которому подключен считыватель меток. Это может быть виртуальный или физический COM-порт, сетевой адрес и т.п.
3.	ChannelsConfig/ ChannelGPO/ GPOIndex	Число	1
4.	ChannelsConfig/ ChannelGPO/ TurnON	Флаг	true / false	Признак для включения(true) либо отключения(false) канала GPIO

Пример запроса (RFIDCommandSetGPO)

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://www.w3.org/2003/05/soap-encoding" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns3="http://schemas.microsoft.com/2003/10/Serialization/" xmlns:ns4="http://schemas.datacontract.org/2004/07/ERFID.CommunicationClient.Interfaces" xmlns:ns5="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:ns6="http://tempuri.org/" xmlns:ns1="urn:erfid:command:wsdl:1">
<SOAP-ENV:Body>
  <ns1:ExecCommand>
   <ns1:ERFIDcommand xsi:type="ns4:RFIDCommandSetGPO">
    <ns4:ComandReceiver>PHISICAL_READER</ns4:ComandReceiver>
    <ns4:ReceiverName>COM3</ns4:ReceiverName>
    <ns4:ChannelsConfig>
     <ns4:ChannelGPO>
      <ns4:GPOIndex>1</ns4:GPOIndex>
      <ns4:TurnON>false</ns4:TurnON>
     </ns4:ChannelGPO>
     <ns4:ChannelGPO>
      <ns4:GPOIndex>2</ns4:GPOIndex>
      <ns4:TurnON>false</ns4:TurnON>
     </ns4:ChannelGPO>
     <ns4:ChannelGPO>
      <ns4:GPOIndex>3</ns4:GPOIndex>
      <ns4:TurnON>true</ns4:TurnON>
     </ns4:ChannelGPO>
     <ns4:ChannelGPO>
      <ns4:GPOIndex>4</ns4:GPOIndex>
      <ns4:TurnON>true</ns4:TurnON>
     </ns4:ChannelGPO>
    </ns4:ChannelsConfig>
   </ns1:ERFIDcommand>
  </ns1:ExecCommand>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Пример ответа (RFIDCommandSetGPO)

Блокировка метки (RFIDCommandLockTagComplex)

Параметры команды:

№№	Поле	Тип	Значение	Описание
1.	ComandReceiver	Строка	PHISICAL_READER	Признак, что команда адресована физическому устройству чтения меток
2.	ReceiverName	Строка	COM<n> либо IP-адрес	Адрес устройства, к которому подключен считыватель меток. Это может быть виртуальный или физический COM-порт, сетевой адрес и т.п.
3.	RfidTagToSeek	Строка	<TagId>	Идентификатор метки, данные которой следует прочитать
4.	LockPassword	Строка	11111111	Строка пароля в формате HEX-string длиной не более 8-ми символов
5.	Payloads/ LockPayload/ DataField	Строка	EPC_Memory	Область памяти для блокировки. Список возможных значений: Kill_Password Access_Password EPC_Memory TID_Memory User_Memory
6.	Payloads/ LockPayload/ Privilege	Строка	Read_Write	Тип блокировки. Список возможных значений: Read_Write Perma_Lock Perma_Unlock Unlock
7.	PasswordLockType	Строка	Read_Write	Тип блокировки для области памяти RESERVED (для сохранения пароля). Список возможных значений: Read_Write Perma_Lock Perma_Unlock Unlock

Пример запроса (RFIDCommandLockTagComplex)
Блокируется банк данных метки EPC от возможности его дальнейшей пере-записи

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://www.w3.org/2003/05/soap-encoding" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns3="http://schemas.microsoft.com/2003/10/Serialization/" xmlns:ns4="http://schemas.datacontract.org/2004/07/ERFID.CommunicationClient.Interfaces" xmlns:ns5="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:ns6="http://tempuri.org/" xmlns:ns1="urn:erfid:command:wsdl:1">
<SOAP-ENV:Body>
  <ns1:ExecCommand>
   <ns1:ERFIDcommand xsi:type="ns4:RFIDCommandLockTagComplex">
    <ns4:ComandReceiver>PHISICAL_READER</ns4:ComandReceiver>
    <ns4:ReceiverName>COM3</ns4:ReceiverName>
    <ns4:RfidTagToSeek>30115F600983236861050DFF</ns4:RfidTagToSeek>
    <ns4:LockPassword>11111111</ns4:LockPassword>
    <ns4:Payloads>
    <ns4:LockPayload>
     <ns4:DataField>EPC_Memory</ns4:DataField>
     <ns4:Privilege>Perma_Lock</ns4:Privilege>
    </ns4:LockPayload>
   </ns4:Payloads>
   <ns4:PasswordLockType>Perma_Lock</ns4:PasswordLockType>
   </ns1:ERFIDcommand>
  </ns1:ExecCommand>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Пример ответа (RFIDCommandSetGPO)

Обработка исключительных ситуаций

В случае возникновения исключительной ситуации при выполнении команд, сервер возвращает ответ с данными типа RFIDCommandGeneralErrorResult в котором содержатся следующие данные:

№№	Поле	Тип	Значение	Описание
1.	IsOK	Строка	false	Признак возникновения ошибки
2.	Status	Строка		Текстовое описание ошибки

Пример ответа, содержащего данные об ошибке

Настройка режимов работы УД

При необходимости изменения настроек режимов работы УД все изменения вносятся в файл CommunicationServer.exe.config, который находится в основном каталоге УД

Основные настройки

Изменение сетевого адреса

Сервис УД может быть не только локальным, но и сетевым. Для того, чтобы позволить приложениям обращаться к его функция с использованием сетевого интерфейса, необходимо внести изменения в файл CommunicationServer.exe.config. В нем все значения локального адреса «127.0.0.1» необходимо изменить на действующий IP-адрес рабочей станции, на которой установлен сервис и перезапустить приложение.

Для постоянного использования УД в качестве сетевой службы необходимо гарантировать неизменность адреса рабочей станции. Для решения этой задачи потребуется помощь администратора сети.

Работа с банками памяти RFID-метки

Установка длины блока памяти TID метки

Обычно, изменение этого параметра никогда не требуется. В настройках "по умолчанию", прописанных при установке приложения, указана минимальная длина TID, использующаяся всеми производителями меток в настоящее время. Исключения могут возникнуть только в случае использования меток, выпущенных в предыдущие годы. Также возможна ситуация, когда в наличии имеются метки с большей длиной TID и конечным приложениям по каким-то причинам необходимо получить полную информацию, хранящуюся в этой области памяти

Важно!
Если длина TID, установленная в настройках УД, будет больше реальной (соответствующей типу метки), то операция чтения данных будет невозможна и всегда будет возвращаться ошибка чтения данных метки.

Настройка длины блока TID находится в разделе applicationSettings и задаётся параметром TIDMEMORYLengthReadBytes.
Значение по умолчанию – 12 байт
Установка длины блока памяти USER метки

Настройка длины блока USER находится в разделе applicationSettings и задаётся параметром USERMEMORYLengthReadBytes.
Значение по умолчанию – 4 байта

Важно!
Также, как и в случае с настройками длины TID, если длина блока USER, установленная в настройках УД, будет больше реальной то всегда будет возвращаться ошибка чтения данных метки.

В случае, если размеры буферов TIDMEMORYLengthReadBytes и(или) USERMEMORYLengthReadBytes не указаны, или их значения равны нулю, данные, содержащиеся в соответствующих банках памяти все равно будут читаться, но время чтения многократно увеличивается по причине того, что будет выполняться последовательная серия чтений блоками по 2 байта (словами). Признаком окончания операции чтения будет служить ответ считывателя о выходе за границы доступной области памяти.

Обоснование выбора размера буферов

TIDMEMORYLengthReadBytes
Размер буфера "по умолчанию" выбран из условия минимальной необходимости и достаточности для получения данных, требующихся для получения уникального серийного номера метки.

Правила сериализации TID согласуются производителями меток и описываются внутренними (закрытыми) стандартами. С общими сведениями о порядке сериализации данных TID можно ознакомиться по ссылке: документ...
USERMEMORYLengthReadBytes
Соответствует минимальному размеру области памяти меток, использующихся в настоящее время.

Настройка функции обратного вызова (асинхронный режим)

При необходимости получения уведомлений по событиям регистрации меток требуется внести следующие изменения в конфигурационный файл УД:

<setting name="ClientHTTPCallback" serializeAs="Xml">
<value>
   <ArrayOfString xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <string>EnableEventCallback=false</string>
   <string>CallbackEndpoint=127.0.0.1:9090</string>
   <string>CallbackUserName=</string>
   <string>CallbackPassword=</string>
  </ArrayOfString>
</value>
</setting>

Где:

№№	Параметр	Значение	Описание
1.	EnableEventCallback	true/false	Включение/выключение функционала отправки сообщений на внешний сервис
2.	CallbackEndpoint	http://<address>:<port>/path	Адрес конечной точки сервиса получателя данных
3.	CallbackUserName	<Username>	Имя пользователя для авторизации на конечном сервисе. Используется Basic Authentification.
4.	CallbackPassword	<Password>	Пароль пользователя для авторизации на конечном сервисе. Используется Basic Authentification

Важно!
Если <Username> и <Password> не заданы, то обращение к внешнему сервису происходит без авторизации (анонимно).

После установки параметра EnableEventCallback=true УД начинает вызывать удаленный сервис, расположенный по адресу, указанному в параметре CallbackEndpoint. Для вызова используется метод HTTP-POST. В теле сообщения будут содержаться данные в формате JSON, отображающие сведения о метках, регистрируемых считывателем.

Пример сообщения о зарегистрированной метке

{ "Antenna": "1",
"Direction": "IN",
"EventTime": "2016-09-27T20:19:12",
"Reader": "COM3",
"TagData": [{
  "MemBank": "EPC",
  "Value": "300DBC6A3A30C9286104FDCD"
},
{
  "MemBank": "TID",
  "Value": "E280110020004B0D904F0066"
}]
}

Описание полей сообщения

№№	Поле	Тип	Значение	Описание
1.	Antenna	Число	1	Номер антенны считывателя, которой была зарегистрирована метка
2.	Direction	Строка	IN	Направление движения метки. УД в поставляемой конфигурации всегда публикует только события типа "IN"
3.	EventTime	Время	2016-09-27T20:19:12	Время события в формате ISO
4.	Reader	Строка	COM3	Идентификатор считывателя, зарегистрировавшего метку
5.	TagData/ MemBank	Строка	EPC / TID	Идентификатор банка памяти метки. Возможные значения: EPC TID USER RESERVER Обычно при публикации данных доступны только банки памяти EPC и TID (зависит от возможностей и настроек считывателя). Для чтения данных, содержащихся в остальных банках, необходимо явно вызывать команду Чтение полной информации о метке (RFIDCommandReadTag)
6.	TagData/ Value	Строка	300DBC6A3A30C9286104FDCD / E280110020004B0D904F0066	Значения прочитанных банков памяти в формате HEX-String

Приложения

Приложение 1. WSDL-схема

Получить WSDL документ web-сервиса УД вместе со схемой сообщений можно после установки драйвера по адресу: http://127.0.0.1:8787/ERFIDCommunicationServer/?singleWsdl

Решение проблем

Возможные проблемы установки и настройки драйвера RFID и способы решения см. в отдельном документе "Универсальный драйвер ERFID. Решение Проблем"

Универсальный драйвер ERFID. Программный интерфейс

Оглавление

Глоссарий

Общие сведения

Демонстрационный режим

Технические требования

Технические описания

Порядок работы

Типовой сценарий работы с ПО УД

Публикация данных в асинхронном режиме

API

Список команд

Примеры использования

Инициализация (RFIDCommandInitPhysicalReader)

Настройка мощности антенны (RFIDCommandSetAntennaPower)

Проверка наличия лицензии (RFIDCommandGetPhysicalReaderLicenseStatus)

Удаление устройства чтения меток (RFIDCommandRemovePhysicalReader)

Начало чтения меток (RFIDCommandStartRead)

Окончание чтения меток (RFIDCommandStopRead)

Чтение всех меток (RFIDCommandGetTags)

Чтение полной информации о метке (RFIDCommandReadTag)

Запись информации на метку (RFIDCommandWriteTag)

Управление фильтром меток (RFIDCommandSetFiltersData)

Считывание состояния каналов GPIO (RFIDCommandGetStatusGPIO)

Установка состояний каналов GPO (RFIDCommandSetGPO)

Блокировка метки (RFIDCommandLockTagComplex)

Обработка исключительных ситуаций

Настройка режимов работы УД

Основные настройки

Работа с банками памяти RFID-метки

Настройка функции обратного вызова (асинхронный режим)

Приложения

Приложение 1. WSDL-схема

Решение проблем

Универсальный драйвер ERFID.
Программный интерфейс