XFS-сервис класса CIM. Модель JCM (протокол ID003)¶

Файлы¶

CimLimitsCheckerSrv.exe;
shqPS.CIM.JCM-ID003.exe;
shqSPCIM.dll.

Настройки XFS-провайдера¶

Инсталляционные настройки¶

Раздел реестра: [HKLM\Software\XFS\PHYSICAL_SERVICES\CIM-JCM-ID003]

Параметры драйвера:

PORT – номер порта, к которому подключено устройство.
CassetteCapacity – емкость кассеты в банкнотах. Возможные значения: 600, 1000, 2000. Этот параметр необходим для формирования полей структуры WFSCIMCASHINFO.

Если появилась небходимость изменить текущее значение параметра CassetteCapacity, то необходимо выполнить следующие действия, чтобы изменения вступили в силу: изменить значение CassetteCapacity, закрыть ОЦ (чтобы не потерять статистику), удалить файл jcm_id003_persistents.xml, перезапустить ОС.
CashInFinishIfBanknoteRefused – завершать/не завершать операцию приема наличных (WS_CMD_CIM_CASH_IN) при отбракованной банкноте. Возможные значения: YES, NO. При установке значения NO операция продолжится до вставки банкноты.
DelayTimeAcceptanceStop – время задержки (в мс) подачи команды завершения приема банкнот на устройство после отработки запроса WFS_CMD_CIM_CASH_IN_END. Актуально для устройств с псевдопачечным приемом ввиду того, что устройство при складировании очередной банкноты уже подхватывает следующую. Команды WFS_CMD_CIM_CASH_IN, WFS_CMD_CIM_CONFIGURE_NOTETYPES производят сброс отложенной подачи команды запрета приема. Значение по умолчанию 2000 мс.
ExpReductionToZero – приводить/не приводить номиналы банкнот к нулевому значению экспоненты. Возможные значения: YES (номинал будет иметь свое действительное значение, указанное на банкноте), NO (номиналы банкнот будут приводиться к значению, полученному по запросу WFS_INF_CIM_CURRENCY_EXP для своего типа валюты).
DISABLE_CU_MANIPULATED – отключить отслеживание и перевод кассеты в состояние MANIPULATED (если кассета извлекалась вне рамок процедуры инкассации). Возможные значения: 1, 0.

Настройка под специфичные прошивки¶

Некоторые прошивки устройства имеют специфику в области разбивки номиналов для протокольной команды ENABLE/DISABLE DATA (разрешение/запрещение номиналов к приему). Для каждой прошивки производитель поставляет ее описание, обычно это PDF-документ, в названии которого фигурирует модель устройства, типы валют и идентификатор. Чтобы определить, является ли данная прошивка стандартной или специфичной, нужно в описании найти пункт «ID-003 Data Setting specification». Для стандартной прошивки порядок данных, возвращаемой командой CURRENCY ASSIGN DATA будет совпадать с порядком формирования данных для команды ENABLE/DISABLE DATA, в противном случае, прошивка считается специфичной.

Примечание

Настройка драйвера необходима, только для специфичных прошивок, если же прошивка является стандартной, то ничего дополнительного делать не нужно.

Все настройки, относящиеся к специфичным прошивкам устройства, должны находиться в файле jcm_enable_disable_data_specifics.xml. Данный файл должен располагаться в одной директории с исполнительным модулем. Пример файла показан ниже:

<?xml version="1.0" encoding="windows-1251" ?>
<jcm_specifics>
  <!-- see firmware specification for details -->
  <country_code val="68">
      <denomination code="61" byte_no="2" bit_no="1"/>
      <denomination code="62" byte_no="1" bit_no="1"/>
      <denomination code="63" byte_no="1" bit_no="2"/>
      <denomination code="65" byte_no="1" bit_no="4"/>
      <denomination code="66" byte_no="1" bit_no="5"/>
      <denominaion code="67" byte_no="1" bit_no="6"/>
      <denomination code="68" byte_no="1" bit_no="7"/>
      <denomination code ="69" byte_no="2" bit_no="0"/>
  </country_code>
</jcm_specifics>

../../_images/jcmid003-config_file_structure.png

Рисунок 24. Пример формирования настроечного файла для мультивалютной прошивки (RUB, USD, EUR, BYR) TBV-100-FSH M06-003-V1.06-23, где белорусский рубль имеет специфичную разбивку номиналов для команды ENABLE/DISABLE DATA.¶

Мультивалютный режим¶

Сервис-провайдер XFS поддерживает мультивалютный прием наличных, но неодновременно. В рамках одной транзакции приема наличных устройство будет принимать только банкноты одной определенной валюты, которая была установлена командой WFS_CMD_CIM_CONFIGURE_NOTETYPES. Переключить на другую валюту возможно только после завершения транзакции приема наличных. Данный режим работы обусловлен особенностью устройства и коммуникационного протокола ID003.

В параметрах lpszExtra запроса WFS_INF_CIM_STATUS поле FW_VER содержит данные о прошивке устройства, где спецификатор «M» указывает на мультивалютность прошивки.

Примеры мультивалютных прошивок:

FW_VER=T(M06)-100-FSH ID003-05V106-23 06JUL12 06C6;
FW_VER=U(M01)-12-SS ID003-05MV207-37 20JAN12 D9AD.

Для одновалютных прошивок параметр FW_VER будет содержать в скобках код конкретной страны.

Возможна ситуация, когда устройство одновременно может принимать банкноты различных валют, но не более двух. Обычно это два типа валют, которые не содержат большого множества номиналов (не более восьми каждый). В данном случае поле FW_VER не будет содержать спецификатор «M», что не требует переключения между валютами, например:

FW_VER =i(USA/CAN)100-SS ID003-05V184-18 05SEP12 AC12

Как видно из кодов стран прошивка предназначена для американских и канадских долларов.

Инициализация устройства¶

Инициализация устройства – это сброс состояния устройства и проверка механических узлов (RESET).

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

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

При подаче питания устройство может принять три возможных состояния:

POWER_UP (устройство после подачи питания).
POWER_UP_ACCEPTOR_BILL (устройство после подачи питания, во временном накопителе обнаружена банкнота). В данном случае банкнота будет возращена клиенту.
POWER_UP_STACKER_BILL (устройство после подачи питания, обнаружена банкнота на этапе складирования в кассету). В данном случае банкнота будет помещена в кассету и учтена в статистике с индексом 0 (как неизвестная).

Если в процессе инициализации обнаруженная на транспорте банкнота была возвращена обратно клиенту, то инициализация не завершится, пока банкнота не будет забрана.

Информационные запросы¶

WFS_INF_CIM_STATUS¶

Данная команда возвращает статус устройства, которое состоит из набора параметров. Например, параметр fwDevice определяет состояние купюроприемника, а fwAcceptor – модуля приема банкнот.

Определение состояния fwDevice:

WFS_CIM_DEVONLINE – устройство готово к работе
WFS_CIM_DEVPOWEROFF – устанавливается в случаях:
- потери связи с устройством;
- изначальной невозможности открыть COM-порт, к которому подключено устройство;
- достижения таймаута при считывании данных из порта.
Любой CMD-запрос к сервису сопровождается ответом WFS_ERR_DEV_NOT_READY.
WFS_CIM_DEVNODEVICE – устанавливается в случае некорректной конфигурации XFS-драйвера:
- отсутствие настройки COM-порта или других настроек реестра;
- несанкционированное изменение файла jcm_id003_persistents.xml.
В extra-поле в ответе STATUS под ключом DETECTED_PROBLEM записывается причина, повлекшая переход в данное состояние. Любой CMD-запрос к сервису сопровождается ответом WFS_ERR_SOFTWARE_ERROR.
WFS_CIM_DEVHWERROR – механическая неисправность одного из узлов сервиса, препятствующая дальнейшей работе устройства. Выставляется в случае неуспешного выполнения протокольных команд коммуникации с устройством.
WFS_CIM_DEVBUSY – устройство занято отработкой CMD-запроса. Любые CMD-запросы, требующие эксклюзивного доступа к аппаратному обеспечению, ставятся в очередь на исполнение, остальные запросы (такие как INF-STATUS и пр.) исполняются немедленно.

Определение состояния fwAcceptor:

WFS_CIM_ACCOK – кассета в состоянии OK. Устройство готово к приему.
WFS_CIM_ACCCUSTATE – кассета близка к переполнению. Устройство готово к приему.
WFS_CIM_ACCCUSTOP – кассета переполнена или в состоянии ошибки. Прием банкнот запрещен.
WFS_CIM_ACCCUUNKNOWN – в силу поломки/недоступности аппарата невозможно определить состояние.

Поле lpszExtra:

VENDOR = DORS[SYSTEMA];
PRODUCT = ProAtm/Xfs;
VERSION = X.X.X.X (текущая версия сервис-провайдера XFS);
DETECTED_PROBLEM: описываются ошибки, выявленные в конфигурации;
HW_ERROR: состав ошибок оборудования;
DEVICE = JCM ID003;
FW_VER: информация о прошивке устройства;
BOOT_VER: информация о загрузочной прошивке устройства.

Рисунок 25. Описание поля FW_VER¶

WFS_INF_CIM_CAPABILITIES¶

Команда возвращает возможности устройства:

Максимальное количество принимаемых банкнот за одну операцию (wMaxCashInItems): 1 банкнота.
Наличие шаттера (bShutter): нет.
Наличие сейфовой двери (bSafeDoor): нет.
Емкость escrow (fwIntermediateStacker): 1 банкнота.
Датчики банкнот в слоте приема/возврата: взятие банкнот (bItemsTakenSensor), вставка банкнот (bItemsInsertedSensor).
Позиции приема/возврата (fwPositions): WFS_CIM_POSINCENTER, WFS_CIM_POSOUTCENTER.
Инкассация (fwExchangeType): ручная инкассация кассет.
Ретракт: не поддерживается.

WFS_INF_CIM_CASH_UNIT_INFO¶

Команда возвращает информацию о кассете устройства: устройство имеет одну физическую кассету. Структура данных WFSCIMCASHINFO содержит в себе одну логическую кассету, которая ссылается на одну физическую кассету.

Определение статуса кассеты(usStatus):

WFS_CIM_STATCUOK – готова к приему.
WFS_CIM_STATCUFULL – заполнена (аппаратное переполнение).
WFS_CIM_STATCUHIGH – близка к переполнению. Статус выставляется программно по достижению максимума логической кассеты (ulMaximum).
WFS_CIM_STATCUINOP – не в рабочем состоянии, например, произошло замятие банкноты.
WFS_CIM_STATCUMISSING – извлечена.
WFS_CIM_STATCUMANIP – извлекалась вне рамок exchange-сессии (инкассация).

Счетчики кассеты:

ulCount – текущее количество банкнот в кассете;
ulCashInCount – счетчик банкнот, помещенных в кассету, равен ulCount;
noteNumberList – текущий пономинальный состав банкнот в логической кассете.

Расчет значения максимума(ulMaximum) по умолчанию: значение максимума формируется с использованием настроечного параметра емкости кассеты (CassetteCapacity).

lppCashIn[0].ulMaximum = CassetteCapacity – 200 (логическая кассета);
lppCashIn[0].lppPhysical[0].ulMaximum = CassetteCapacity (физическая кассета).

WFS_INF_CIM_CURRENCY_EXP¶

По данному запросу можно узнать значение установленной экспоненты для каждой поддерживаемой устройством валюты. Валюта (cCurrencyID) указывается в формате ISO 4217.

WFS_INF_CIM_BANKNOTE_TYPES¶

По данному запросу можно получить информацию о типах банкнот, поддерживаемых устройством. Валюта (cCurrencyID) указывается в формате ISO 4217. У каждого номинала может быть несколько релизов, но с точки зрения XFS одинаковые номиналы имеют один и тот же индекс (usNoteID) в независимости от релиза.

WFS_INF_CIM_CASH_IN_STATUS¶

По данному запросу можно получить данные о последней транзакции приема наличных.

Определение статуса транзакции(wStatus):

WFS_CIM_CIOK – прием наличных завершен, банкнота сложена в кассету;
WFS_CIM_CIROLLBACK – прием наличных завершен, банкнота возвращена обратно клиенту;
WFS_CIM_CIACTIVE – прием наличных активен, после подачи WFS_CIM_CASH_IN_START;
WFS_CIM_CIUNKNOWN – прием наличных завершен с ошибкой. WFS_ERR_CIM_NOITEMS ошибкой не является!

Таймаут нахождения банкноты в escrow ~ 10 сек., если за это время не было подано команды WFS_CMD_CIM_CASH_END или WFS_CMD_CIM_ROLLBACK, то банкнота будет возвращена обратно клиенту, noteNumberList обнулится, статус останется в WFS_CIM_CIACTIVE. Время удержания банкноты не регулируется XFS-стандартами.

Команды¶

WFS_CMD_CIM_CASH_IN_START¶

Данная команда открывает транзакцию приема наличных. Статус транзакции выставляется в WFS_CIM_CIACTIVE. Никаких механических действий не происходит, команда носит логический характер.

Валидация контекста исполнения:

сервис в состоянии готовности;
режим инкассации неактивен;
транзакция приема наличных неактивна;
кассета устройства готова к приему (fwAcceptor != WFS_CIM_ACCCUSTOP).

Валидация входных данных:

fwOutputPosition – WFS_CIM_POSNULL, WFS_CIM_POSOUTCENTER;
fwInputPosition – WFS_CIM_POSNULL, WFS_CIM_POSINCENTER.

WFS_CMD_CIM_CASH_IN¶

Данная команда активирует готовность устройства к приему наличных, после чего ожидается вставка банкноты. При обнаружении банкноты в слоте приема/возврата устройство осуществляет транспортировку банкноты в escrow. Команда завершается в следующих ситуациях:

возникновение ошибки;
подача асинхронной отмены (cancelasyncrequest);
вставленная банкнота распознана и помещена в escrow;
банкнота отвергнута, если установлен настроечный параметр cashinfinishifbanknoterefused, в противном случае xfs-сервис будет ожидать вставки валидной банкноты.

При наличии отвергнутой банкноты на выходе слота приема/возврата команда не завершится, пока банкнота не будет забрана клиентом.

Валидация контекста исполнения:

сервис в состоянии готовности;
режим инкассации неактивен;
транзакция приема наличных активна;
емкость escrow не переполнена;
устройство находится в состоянии IDLING или INHIBIT.

На выход формируется список принятых банкнот (noteNumberList) в рамках данной операции, для модели JCM список будет содержать не более одной банкноты.

Если операция выполнена с ошибкой, то статус транзакции выставляется в WFS_CIM_CIUNKNOWN, чтобы в дальнейшем можно было выполнить сброс состояния оборудования (Reset).

WFS_CMD_CIM_CASH_IN_END¶

Команда закрывает транзакцию приема наличных. Статус транзакции выставляется в WFS_CIM_CIOK. В рамках исполнения данной команды:

происходит складирование принятой банкноты в кассету;
пересчитываются счетчики кассеты;
деактивируется готовность устройства к приему наличных.

Валидация контекста исполнения:

сервис в состоянии готовности;
режим инкассации неактивен;
транзакция приема наличных активна.

WFS_CMD_CIM_CASH_IN_ROLLBACK¶

Команда закрывает транзакцию приема наличных. Статус транзакции выставляется в WFS_CIM_CIROLLBACK. В рамках исполнения данной команды:

происходит возврат ранее принятой в escrow банкноты;
деактивируется готовность устройства к приему наличных.

Валидация контекста исполнения:

сервис в состоянии готовности;
режим инкассации неактивен;
транзакция приема наличных активна.

Команда не завершится, пока возвращенная обратно банкнота не будет забрана клиентом.

WFS_CMD_CIM_SET_CASH_UNIT_INFO¶

Данная команда позволяет менять следующие данные по кассетам:

cUnitID (для логической и физической кассеты);
ulMaximum (для логической кассеты);
bAppLock.

Примечание

Команда не позволяет менять значения счетчиков.

При изменении других полей или общей структуры кассет команда будет выполнена с результатом WFS_ERR_UNSUPP_DATA.

Валидация контекста исполнения: режим инкассации неактивен.

WFS_CMD_CIM_START_EXCHANG¶

Команда используется для старта замены кассет (инкассации).

Валидация контекста исполнения:

режим инкассации неактивен;
сервис в состоянии готовности;
транзакция приема наличных неактивна.

Валидация входных данных:

fwExchangeType – WFS_CIM_EXBYHAND;
usCount – 1 (кол-во кассет)
lpusCUNumList – первый элемент должен быть равен 1 (номер логической кассеты).

WFS_CMD_CIM_END_EXCHANG¶

Команда используется для завершения замены кассет (инкассации).

Примечание

Команда позволяет установить только нулевые счетчики кассеты и сбросить пономинальный список банкнот, находящихся в кассете (noteNumberList).

Валидация контекста исполнения: режим инкассации неактивен.

Валидация входных данных:

допускается NULL в качестве указателя на входную структуру. В данном случае замена кассет завершится без изменения счетчиков;
ulCount, ulCashInCount = 0;
noteNumberList пустой;
не поддерживается изменение структуры кассет, изменение валют и номиналов;
значение порогов кассет ulMaximum/ulMinimum игнорируется.

WFS_CMD_CIM_RESET¶

Команда выполняет сброс состояния оборудования. Устройство производит внутреннюю проверку механических узлов. Выполняется инициализация устройства (~3 сек.).

Валидация контекста исполнения: режим инкассации неактивен.

Валидация входных данных: все входные параметры игнорируются.

Независимо от версии версии API, с которым работает прикладное ПО, осуществляется сброс флага активной транзакции приема наличных.

WFS_CMD_CIM_CONFIGURE_NOTETYPES¶

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

Примечание

В случае мультивалютной прошивки конфигурируемое множество деноминаций (входные данные) должно относиться к одной валюте, иначе команда завершится с результатом WFS_ERR_INVALID_DATA (см. :ref:` jcm-multicurrency_mode`). Также данная команда является переключателем между разными типами валют.

Валидация контекста исполнения:

сервис в состоянии готовности;
режим инкассации неактивен;
транзакция приема наличных неактивна.

Валидация входных данных: lpusNoteIDs – индексы банкнот должны поддерживаться устройством.

События¶

WFS_USRE_CIM_CASHUNITTHRESHOLD – событие генерируется в случае достижения счетчиком логической кассеты значения максимума логической кассеты (WFSCIMCASHINFO.lppCashIn[0].ulMaximum). Статус кассеты устанавливается в значение WFS_CIM_STATCUHIGH. Значение максимума логической кассеты должно быть больше нуля.
WFS_SRVE_CIM_CASHUNITINFOCHANGED – событие генерируется в случае изменения статуса кассеты (кроме ситуаций, описанных в предыдущем пункте) и в случаях изменения данных кассеты после конфигурации/инкассации. Консолидирующим событием в случае возникновения ситуации, требующей рассылки событий WFS_USRE_CIM_CASHUNITTHRESHOLD и WFS_SRVE_CIM_CASHUNITINFOCHANGED, будет WFS_SRVE_CIM_CASHUNITINFOCHANGED.
WFS_SRVE_CIM_ITEMSTAKEN – событие генерируется в случае извлечения банкноты клиентом из слота приема/возврата.
WFS_SRVE_CIM_ITEMSPRESENTED – событие генерируется в случае предъявления банкноты клиенту в слот приема/возврата для изъятия. Случаи предъявления: откат транзакции приема наличных (wfs_cmd_cim_rollback), возврат отвергнутой банкноты (refuseditems).
WFS_SRVE_CIM_MEDIADETECTED – событие генерируется в случае обнаружения банкноты на транспорте (временный накопитель, на этапе складирования в кассету) на этапе инициализации устройства. В параметрах события указывается место нахождения обнаруженных ранее банкнот по окончанию операции инициализации (кассета, слот приема/возврата).
WFS_SRVE_CIM_INPUTREFUSE – событие генерируется в случае наличия отвергнутой банкноты в процессе операции приема наличных (WFS_CMD_CIM_CASH_IN). Возможные причины возврата: WFS_CIM_INVALIDBILL (ошибка валидации, банкнота не разрешена к приему).
WFS_SRVE_CIM_ITEMSINSERTED – событие генерируется в случае вставки банкноты в слот приема/возврата устройства.

Коды ошибок оборудования¶

Таблица 30. Коды ошибок оборудования JCM-ID003¶
ERROR CODE	ERROR NAME	DESCRIPTION
43H	STECKER FULL	A stacker box full condition
44H	STACKER OPEN( STACKER BOX REMOVE)	The stacker box full is open or the stacker box is not mounted
45H	JAM IN ACCEPTOR	Jamming has occurred inside the ACCEPTOR
46	JAM IN STACKER	Jamming has occurred in the stacker conveying section. An abnormal condition has developed at the time of stroing
47	PAUSE	A condition in which the ACCEPTOR cannot operate because a second bill has been inserted while the first bill is being stored or conveyed (When the second bill is removed, conveying is started).
48	CHEATED	An action thoughht to be mischievous agaiinnst ACCEPTOR has been committed.
49	FAILURE	A status in which normal operation cannot be made because of a failure. An abnormal condition, or incorrect setting of the ACCEPTOR. [ FAILURE DATA ] of 1 byte are added. [ FAILURE DATA ] (abnormal contents) DATA Contents A2h Stock motor failure A5h Transport (feed) motor speed failure A6h Transport (feed) motor failure ABh Cash box not ready AFh Validator head remove B0h BOOT ROM failure B1h External ROM failure B2h ROM failure B3h External
4AH	COMMUNICATION ERROR	An error has developed in the communication data
[4BH]	INVALID COMMAND	Command from the CONTROLLER is not valid.

Подробное описание статусов устройств приведено в документе «Communication Specification. ID-003».