XFS-сервис класса CRM. Модель Hitachi HCM HT-3842

Используемые сокращения:

  • AB – Acceptance box (кассета приема наличных);

  • RB – Recycler box (рециклинг-кассета);

  • URJB – Upper reject box (кассета сброса банкнот верхнего уровня устройства);

  • MAB – Multi acceptance box (кассета с отдельными физическими отсеками для задержания, отбраковки, приема банкнот);

  • nnList – Note number list (список счетчиков банкнот логической CIM кассеты с разбивкой по номиналам).

Файлы

  • shqPS.CRM.HCM-HT-3842.exe;

  • shqSPCDM.dll;

  • shqSPCIM.dll;

  • VHUSB.dll.

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

Параметры реестра

Раздел реестра: [HKEY_LOCAL_MACHINE\SOFTWARE\XFS\PHYSICAL_SERVICES\HCM-HT-3842]

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

  • PORT – порт, к которому подключено устройство. Возможные значения порта: COMx, USB (здесь x – номер порта).

Параметры конфигурационного файла

Все настройки, относящиеся к устройству, находятся в файле ht3842settings.xml. Данный файл должен располагаться в одной директории с исполнительным модулем. Если при запуске сервис-провайдера файл не обнаруживается, то создается файл с параметрами по умолчанию.

Пример формирования конфигурации кассет по умолчанию:

../../_images/ht3842-default_confguration.jpg

Конфигурация кассет

На основании ht3842settings.xml строится структура логических кассет XFS, за исключением случаев использования памяти кассет. Настройка каждой кассеты выделена в отдельный блок <cassette>. Количество данных блоков соответствует количеству кассет устройства. Порядок расположения блоков <cassette> должен соответствовать расположению кассет в устройстве сверху вниз.

Формирование параметров кассеты

  • <frame> – конструкция под кассету:

    • 1 – существует;

    • 2 – не существует.

  • <type> – тип кассеты:

    • 1 – RB;

    • 2 – AB;

    • 5 – MAB;

    • 0 – кассета не участвует в работе.

  • <denomination> – номинал, на который сконфигурирована кассета. Атрибуты:

    • currency – валюта в формате ISO4217 (ex. RUB, EUR, USD, …);

    • value – номинал, приведенный к нулевой экспоненте (фактический номинал банкноты).

    Для AB-кассеты поле currency может иметь значение ALL, что означает прием всех банкнот, на которые сконфигурировано устройство. Для RB кассет всегда указывается конкретный номинал.

  • <operation> – операционный тип кассеты:

    • для RB-кассеты: 0 (рециклинг), 1 (только выдача), 2 (только прием);

    • для AB-кассеты: 3 (для задержания, отбраковки, приема банкнот, ветхие + неветхие), 4 (для задержания и отбраковки), 5 (для приема, ветхие + неветхие), 6 (для приема, неветхие);

    Значения 3 и 5 не сочетаются, т.е. если уже есть одна кассета retract/reject/deposit (fit+unfit), то не может быть еще одной кассеты deposit (fit+unfit), в противном случае устройство сообщит об ошибке настройки. Взамен рекомендуется использовать сочетание 3 и 6.

    • для MAB-кассеты: 3 (для задержания, отбраковки, приема банкнот).

  • <lock> – первоначальное значение блокировки (параметр на будущее использование).

Тип и количество логических кассет CIM/CDM зависит от поля <operation>:

Значение <operation>

Логические кассеты CIM

Логические кассеты CDM

0 (recycling)

RECYCLING

RECYCLING

1 (dispensing only)

BILL (CDMSPECIFIC)

BILL

2 (depositing only)

CASHIN

—

3 (retract/reject/deposit)

CASHIN, RETRACT,REJECT

RETRACT, REJECT

4 (retract/reject)

RETRACT, REJECT

RETRACT, REJECT

5 (deposit: fit + unfit)

CASHIN

—

6 (deposit: fit)

CASHIN

—
../../_images/ht3842-sheme_cassette1.jpg

Рисунок 30. Структура логических кассет XFS #1 (рециклинг, рекомендованная)

.

Reject

Retract

Cashin

Recycling

Всего

Сервис CIM

1

2

1

4

8

Сервис CDM

1

2

0

4

7
../../_images/ht3842-sheme_cassette2.jpg

Рисунок 31. Структура логических кассет XFS #2 (рециклинг без URJB)

.

Reject

Retract

Cashin

Recycling

Всего

Сервис CIM

1

1

1

4

7

Сервис CDM

1

1

0

4

6
../../_images/ht3842-sheme_cassette3.jpg

Рисунок 32. Структура логических кассет XFS #3 (только прием без URJB)

.

Reject

Retract

Cashin

Всего

Сервис CIM

1

1

5

7

Сервис CDM

1

1

0

2
../../_images/ht3842-sheme_cassette4.jpg

Рисунок 33. Структура логических кассет XFS #4 (только прием)

.

Retract

Cashin

Всего

Сервис CIM

1

5

6

Сервис CDM

1

0

1
../../_images/ht3842-sheme_cassette5.jpg

Рисунок 34. Структура логических кассет XFS #5 (выдача/прием)

.

Reject

Retract

Cashin

Bill (Cashout)

Всего

Сервис CIM

1

2

1

4

8

Сервис CDM

1

2

0

4

7
../../_images/ht3842-sheme_cassette6.jpg

Рисунок 35. Структура логических кассет XFS #6 (выдача/прием без URJB)

.

Reject

Retract

Cashin

Bill (Cashout)

Всего

Сервис CIM

1

1

1

4

7

Сервис CDM

1

1

0

4

6
../../_images/ht3842-sheme_cassette7.jpg

Рисунок 36. Структура логических кассет XFS #7 (только выдача)

.

Reject

Retract

Bill (Cashout)

Всего

Сервис CIM

1

1

4

6

Сервис CDM

1

1

4

6

Примечание

В данную схему можно подключить URJB ретракт-кассету.

../../_images/ht3842-sheme_cassette8.jpg

Рисунок 37. Структура логических кассет XFS #8 (рециклинг, прием)

.

Reject

Retract

Cashin

Recycling

Всего

Сервис CIM

1

1

2

3

7

Сервис CDM

1

1

0

3

5

Примечание

В данную схему можно подключить URJB ретракт-кассету. Также можно комбинировать кассеты типа CashIn и Recycling в разных соотношениях для RB-кассет.

../../_images/ht3842-sheme_cassette9.jpg

Рисунок 38. Структура логических кассет XFS #9 (рециклинг, выдача)

.

Reject

Retract

Cashin

Bill (Cashout)

Recycling

Всего

Сервис CIM

1

1

1

1

3

7

Сервис CDM

1

1

0

1

3

6

Примечание

В данную схему можно подключить URJB ретракт-кассету. Также можно комбинировать кассеты типа Bill (Cashout) и Recycling в разных соотношениях для RB-кассет.

../../_images/ht3842-sheme_cassette10.jpg

Рисунок 39. Структура логических кассет XFS #10 (2 AB-кассеты)

.

Reject

Retract

Cashin

Recycling

Всего

Сервис CIM

1

1

1

3

6

Сервис CDM

1

1

0

3

5

Примечание

В данную схему можно подключить URJB ретракт-кассету.

Настройка пороговых значений емкости кассет

Пороговые значения емкостей кассет настраиваются в секции <thresholds> конфигурационного файла и зависят от операционного типа кассеты (AB, MAB, RB, URJB).

Атрибуты:

  • full – кассета заполнена (ulMaximum физической кассеты);

  • high – кассета близка к переполнению (ulMaximum логической кассеты, ссылающейся на данную физическую);

  • low – кассета близка к опустошению (ulMinimum логической кассеты, ссылающейся на данную физическую);

  • force_status_full – программное выставление статуса кассеты WFS_CIM_STATCUFULL при достижении значения параметра full.

  • type – тип отсека кассеты (выше перечисленные параметры будут относиться к данному типу отсека кассеты);

Пример:

<thresholds>
  <cassette type="CST_AB" full="2000" high="1800" low="20" force_status_full="false" />
  <cassette type="CST_RB" full="2000" high="1800" low="20" force_status_full="false" />
  <cassette type="CST_URJB" full="100" high="80" low="20" force_status_full="false"/>
  <cassette type="CST_MAB_DEPOSIT" full="350" high="250" low="20" force_status_full="true" />
  <cassette type="CST_MAB_RETRACT" full="100" high="50" low="20" force_status_full="true" />
  <cassette type="CST_MAB_REJECT" full="100" high="50" low="20" force_status_full="true" />
</thresholds>

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

Дополнительные опции устройства

Дополнительные опции устройства указываются в секции <extra>:

  • URJBExistence – наличие URJB-кассеты.

    При значении true будет создана дополнительная логическая RETRACT кассета в сервисе CIM и CDM, ссылающаяся на физическую кассету URJB.

  • URJBFullErrorCheck – возврат ошибки при переполнении URJB на последующие команды;

  • FitnessCheckInStacking – складирование ветхих банкнот в AB кассету, в противном случае ветхие банкноты будут попадать в RB.

    Внимание

    Не рекомендуется устанавливать параметр FitnessCheckInStacking при наличии более одной AB кассеты, настроенной на прием всех номиналов таким образом, что одна принимает ветхие и неветхие, а другая только неветхие. В противном случае, может расходиться статистика по конкретным кассетам, и итоговая статистика по всем кассетам будет корректна. Данная рекомендация связна с особенностью реализации коммуникационного протокола с устройством, из которого нельзя точно установить, какие номиналы в какие кассеты были складированы.

  • FitnessCheckInDispensing – отбраковка ветхих банкнот при наборе в AB кассету, в противном случае ветхие банкноты будут выданы клиенту;

  • DogEarCheck – возврат банкнот с сильно загнутыми углами клиенту при приеме;

  • CimStopAcceptorIfNoCiTypAllAvailable – остановка приема наличных, если перестала быть доступной хотя бы одна CASHIN кассета с типом WFS_CIM_CITYPALL | WFS_CIM_CITYPUNFIT (DropBox);

  • ConstructConfigurationByCassetteMemory – формирование конфигурации кассет на основе памяти кассет (не рекомендуется к использованию).

  • IgnoreCassetteManipulation – игнорирование факта извлечения кассеты в не рамок инкассации.

Все значения параметров секции <extra> определяется следующим образом:

  • true – установлено;

  • false – не установлено.

Country code: в настройках необходимо указать параметр <country_code> для конкретной прошивки устройства. Параметр указывается в десятичном виде в диапазоне 0 .. 255. По умолчанию <country_code val="66" /> (hex: 42).

Bill validator hard setting: параметр <bv_hard_setting> необходимо выставить в зависимости от типа аппаратной части валидатора устройства. Тип валидатора имеет числовой формат в диапазоне 0..3. По умолчанию: <bv_hard_setting val="3" />.

Cash in limit: параметр <cash_in_limit> – максимальная емкость пачки транзакции приема наличных. Значение 0 – использовать максимальное возможное количество банкнот, предусмотренное устройством, т.е. 200. По умолчанию <cash_in_limit val ="0" />.

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

Сервис CIM

WFS_INF_CIM_STATUS

Команда возвращает статус устройства. Ниже в таблицах представлены комментарии к полям структуры WFSCIMSTATUS.

fwDevice:

  • WFS_CIM_DEVONLINE – устройство готово к работе.

  • WFS_CIM_DEVOFFLINE – устройство подключено, но находится не в рабочей позиции. Открыта задняя/передняя дверь, выдвинут верхний/нижний модуль устройства. В процессе инкассации устройство в OFFLINE не переходит.

  • WFS_CIM_DEVPOWEROFF – выставляется в случае потери связи с устройством, в случае изначальной невозможности открыть COM-порт, к которому подключено устройство, в случае аппаратной ошибки при считывании данных из порта. Любой CMD-запрос к сервису сопровождается ответом WFS_ERR_DEV_NOT_READY.

  • WFS_CIM_DEVNODEVICE – выставляется в случае некорректной конфигурации XFS-драйвера или устройства: отсутствие настройки COM-порта или других настроек реестра, неверная конфигурация файла ht3842settings.xml. Несанкционированное изменение файла ht3842_persistents.xml. В extra-поле в ответе STATUS под ключом DETECTED_PROBLEM записывается причина, повлекшая переход в данное состояние.

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

  • WFS_CIM_DEVBUSY – устройство занято отработкой CMD-запроса. Любые CMD-запросы, требующие эксклюзивного доступа к аппаратному обеспечению, ставятся в очередь на исполнение, остальные запросы (такие как INF-STATUS и пр.) исполняются немедленно.

fwSafeDoor:

  • WFS_CIM_DOORNOTSUPPORTED – сейфовая дверь не поддерживается.

fwAcceptor:

  • WFS_CIM_ACCOK – все кассеты приема наличных (CASHIN, RECYCLER, RETRACT) в состоянии OK; устройство готово к приему.

  • WFS_CIM_ACCCUSTATE – одна или несколько кассет имеют статус, отличный от OK, однако прием наличных по-прежнему разрешен.

  • WFS_CIM_ACCCUSTOP – устройство не готово к приему:

    • все RETRACT кассеты недоступны (переполнены, отсутствуют, в ошибке) при наличии их в конфигурации кассет;

    • недоступны все CASHIN, RECYCLER кассеты;

    • недоступно ни одной CASHIN кассеты с типом WFS_CIM_CITYPALL | WFS_CIM_CITYPUNFIT при активном флаге CimStopAcceptorIfNoCiTypAllAvailable.

  • WFS_CIM_ACCCUUNKNOWN – из-за поломки/недоступности аппарата невозможно определить состояние.

fwIntermediateStacker:

  • WFS_CIM_ISEMPTY – временный накопитель (escrow) пуст.

  • WFS_CIM_ISNOTEMPTY – Escrow содержит банкноты, но может принять еще.

  • WFS_CIM_ISFULL – Escrow заполнен.

  • WFS_CIM_ISUNKNOWN Из-за поломки/недоступности аппарата невозможно определить состояние.

lpszExtra:

  • VENDOR=DORS[SYSTEMA];

  • PRODUCT=ProAtm/Xfs;

  • VERSION=X.X.X.X (текущая версия сервис-провайдера XFS);

  • DEVICE=HCM-HT3842;

  • DETECTED_PROBLEM: описываются ошибки, выявленные в конфигурации;

  • HW_ERROR: состав ошибок оборудования;

  • LAST_ACTION_COMMAND_HW_ERROR: последняя ошибка в ходе исполнения HW-команд (номер + описание);

  • LAST_ACTION_COMMAND_HW_WARNING: последнее предупреждение в ходе исполнения HW-команд (номер + описание).

fwStackerItems:

  • WFS_CIM_CUSTOMERACCESS – в escrow находятся банкноты, которые были в доступе клиента. Через escrow ведется только прием, выдача происходит сразу в слот приема/выдачи. Банкноты, находящиеся в escrow, изначально были в доступе клиента.

  • WFS_CIM_NOITEMS – Escrow пуст.

  • WFS_CIM_ACCESSUNKNOWN – из-за поломки/недоступности аппарата невозможно определить состояние.

fwBanknoteReader:

  • WFS_CIM_BNROK – валидатор банкнот в рабочем состоянии;

  • WFS_CIM_BNRINOP – крышка валидатора открыта;

  • WFS_CIM_BNRUNKNOWN – из-за поломки/недоступности аппарата невозможно определить состояние.

bDropBox:

  • FALSE – не поддерживается.

lppPositions[0] -> fwPosition:

  • WFS_CIM_POSINCENTER – центральная входная позиция. В устройстве один слот приема/выдачи, соответственно входная и выходная позиция совпадают, поэтому состояния полей входных и выходных позиций будут одинаковы.

lppPositions[i] -> fwShutter:

  • WFS_CIM_SHTCLOSED – шаттер закрыт;

  • WFS_CIM_SHTOPEN – шаттер открыт;

  • WFS_CIM_SHTUNKNOWN – в силу поломки/недоступности аппарата невозможно определить состояние.

lppPositions[i] -> fwPositionStatus:

  • WFS_CIM_PSEMPTY – слот приема/выдачи пуст;

  • WFS_CIM_PSNOTEMPTY – в слоте приема/выдачи есть банкноты;

  • WFS_CIM_PSUNKNOWN – в силу поломки/недоступности аппарата невозможно определить состояние.

lppPositions[i] -> fwTransport:

  • WFS_CIM_TPUNKNOWN – из-за поломки/недоступности аппарата невозможно определить состояние;

  • WFS_CIM_TPNOTSUPPORTED – информация о транспорте не поддерживается.

lppPositions[i] -> fwTransportStatus

  • WFS_CIM_TPSTATNOTEMPTY_UNK – из-за поломки/недоступности аппарата невозможно определить состояние;

  • WFS_CIM_TPNOTSUPPORTED – информация о транспорте не поддерживается.

dwGuidLights:

  • WFS_CIM_GUIDANCE_NOT_AVAILABLE – не поддерживается.

wDevicePosition:

  • WFS_CIM_DEVICEINPOSITION – устройство в рабочей позиции;

  • WFS_CIM_DEVICENOTINPOSITION – устройство не в рабочей позиции: открыта задняя/передняя дверь, выдвинут верхний/нижний модуль устройства.

  • WFS_CIM_DEVICEPOSUNKNOWN – в силу поломки/недоступности аппарата невозможно определить состояние.

usPowerSaveRecoveryTime: значение``0`` не поддерживается.

WFS_INF_CIM_CAPABILITIES

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

Максимальное кол-во принимаемых банкнот за одну операцию (wMaxCashInItems): 200 банкнот.

Емкость escrow (fwIntermediateStacker): 200 банкнот.

Максимальное кол-во выдаваемых банкнот за одну операцию (wMaxDispenseItems): 200 банкнот.

Датчики банкнот в слоте приема/выдачи: взятие банкнот (bItemsTakenSensor), вставка банкнот (bItemsInsertedSensor).

Инкассация (fwExchangeType): ручная инкассация кассет.

Область ретракта (fwRetractAreas): RETRACT-кассета, RECYCLER-кассеты (BILLCASSETTES – CIM, ITEMCASSETTE – CDM).

WFS_INF_CIM_CASH_UNIT_INFO

Информация о кассетах предоставляется по двум интерфейсам: CIM и CDM. При этом информации, полученной через интерфейс CIM всегда достаточно для получения представления о содержимом каждой из физических кассет, а также для формирования статистики по операциям приема и выдачи.

Как следствие, инкассация и конфигурирование рециклера допускается только через интерфейс CIM.

Логические кассеты, работающие только на прием (CashIn, Reject, Retract) никогда не имеют статус LOW или EMPTY. Логические кассеты, работающие только на выдачу (CDM BILL), никогда не имеют статус HIGH или FULL.

Статусы кассет CIM и CDM, относящиеся к наполнению кассеты (EMPTY, LOW, HIGH, FULL), меняются в зависимости от аппаратного статуса кассет.

Определение пороговых статусов кассет CIM/CDM:

XFS-статус

Аппаратный статус

WFS_CXM_STATCUEMPTY

Кассета полностью пуста

WFS_CXM_STATCULOW

В кассете находится хотя бы одна банкнота

WFS_CXM_STATCUOK

Если от устройства не пришло по кассете ни EMPTY, ни LOW, ни FULL

WFS_CXM_STATCUHIGH

Такого статуса никогда не будет, аппаратный HIGH отсутствует

WFS_CXM_STATCUFULL

Аппаратное переполнение кассеты

Отклонение от стандарта при работе со счетчиками. В случае выполнения команды CdmReject с возвратом банкнот в Recycling-кассеты, ПО выполняет «транзакционный откат» значений счетчиков:

  • ulDispensedCount – восстанавливается до первоначального значения (до набора);

  • ulCashInCount – не начисляется.

В целом, XFS-сервис придерживается правил ведения счетчиков, описываемых в спецификациях.

Счетчики и особенности их ведения:

  • ulCount – текущее количество банкнот в кассете. Для логической кассеты включает набранные банкноты до тех пор, пока они не будут предъявлены либо сброшены.

  • noteNumberList – текущий состав банкнот по номиналам в логической кассете.

  • ulCashInCount – количество банкнот, помещенных в данную кассету безотносительно типа кассеты и операции. Исключение (отклонение от стандарта): в случае возврата (Reject) набранных банкнот в Recycling-кассеты, данный счетчик не увеличивается.

  • ulInitialCount – начальное значение счетчика банкнот (после проведения инкассации).

  • ulDispensedCount – количество набранных (слистнутых) из кассеты банкнот. Исключение (отклонение от стандарта): в случае возврата (Reject) набранных банкнот в Recycling-кассеты, данный счетчик возвращается в исходное (до набора) состояние. Если удается вернуть лишь часть банкнот (в силу возможной отбраковки при повторной валидации), то счетчик восстанавливается частично.

  • ulPresentedCount – количество набранных из кассеты и предъявленных банкнот.

  • ulRetractedCount – количество банкнот, помещенных в данную кассету в рамках операции Retract.

  • ulRejectCount – количество банкнот, набранных из данной кассеты и попавших в Reject-кассету (в силу отбраковки при наборе либо по команде Reject после набора).

WFS_INF_CIM_CURRENCY_EXP

По данному запросу можно узнать значение установленной экспоненты для каждой поддерживаемой устройством валюты. Ответ записывается в структуру WFSCIMCURRENCYEXP.

WFSCIMCURRENCYEXP:

  • cCurrencyID – валюта в формате ISO 4217 (EUR, RUB, USD, KZT и т.д.);

  • sExponent – значение экспоненты.

WFS_INF_CIM_BANKNOTE_TYPES

По данному запросу можно получить информацию о типах банкнот, поддерживаемых устройством. Ответ записывается в структуру WFSCIMNOTETYPELIST.

WFSCIMNOTETYPELIST:

  • usNumOfNoteTypes Количество разных типов банкнот, поддерживаемых устройством

WFSCIMNOTETYPELIST.lppNoteTypes[i]:

  • usNoteID – индекс банкноты.

  • cCurrencyID – валюта в формате ISO 4217.

  • ulValues – базовое значение номинала банкноты. Чтобы узнать фактический номинал, нужно умножить это значение на 10 в степени sExponent.

  • usRelease – всегда 0.

  • bConfigured – если TRUE, то данный тип банкнот сконфигурирован и при операции приема наличных будет разрешен. В противном случае, если данный тип банкноты попадет в устройство при приеме наличных, то он будет возвращен обратно клиенту.

Для каждого номинала может быть несколько релизов, но с точки зрения XFS, одинаковые номиналы имеют один и тот же индекс независимо от релиза.

WFS_INF_CIM_CASH_IN_STATUS

Запрос возвращает данные о последней транзакции приема наличных. Ответ записывается в структуру WFSCIMCASHINSTATUS.

WFSCIMCASHINSTATUS:

  • wStatus – текущий статус транзакции приема наличных:

    • WFS_CIM_CIOK (прием наличных завершен, банкноты отправлены в кассеты);

    • WFS_CIM_CIROLLBACK (прием наличных завершен, банкноты возвращены клиенту);

    • WFS_CIM_CIACTIVE (прием наличных активен, после подачи WFS_CIM_CASH_IN_START);

    • WFS_CIM_CIRETRACT (прием наличных завершен, банкноты отправлены в область ретракта);

    • WFS_CIM_CIRESET (прием наличных завершен сбросом состояния оборудования).

  • usNumOfRefused Общее кол-во отвергнутых банкнот в рамках транзакции приема наличных.

  • lpNoteNumberList Список принятых банкнот в рамках транзакции приема наличных с разбивкой по индексам номиналов.

Данные транзакции сохраняются до подачи следующей команды WFS_CMD_CIM_CASH_IN_START.

Сервис CDM

WFS_INF_CDM_STATUS

Команда возвращает статус устройства в терминах CDM.

В силу схожести структур WFSCIMSTATUS и WFSCDMSTATUS, комментарии к полям fwDevice, fwSafeDoor, lppPositions, lpszExtra, dwGuidLights, wDevicePosition, usPowerSaveRecoveryTime см. описание WFS_INF_CIM_STATUS.

fwDispenser:

  • WFS_CDM_DISPOK – устройство готово к выдаче. Все кассеты выдачи (BILL, RECYCLER) + RETRACT, REJECT кассеты в рабочем состоянии.

  • WFS_CDM_DISPCUSTATE – устройство готово к выдаче. Одна из кассет выдачи пуста или близка к опустошению.

  • WFS_CDM_DISPCUSTOP – устройство не готово к выдаче: все RETRACT кассеты недоступны (переполнены, отсутствуют, в ошибке); все REJECT кассеты недоступны; все кассеты выдачи наличных недоступны.

  • WFS_CDM_DISPCUUNKNOWN – в силу поломки/недоступности аппарата невозможно определить состояние.

fwIntermediateStacker:

  • WFS_CDM_ISEMPTY – емкость escrow пуста.

  • WFS_CDM_ISNOTEMPTYCUST – емкость escrow не пуста. Банкноты транзакции приема наличных.

  • WFS_CDM_ISUNKNOWN – в силу поломки/недоступности аппарата невозможно определить состояние.

WFS_INF_CDM_CAPABILITIES

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

Максимальное кол-во принимаемых банкнот за одну операцию (wMaxCashInItems): 200 банкнот.

Емкость escrow (fwIntermediateStacker): 200 банкнот.

Максимальное кол-во выдаваемых банкнот за одну операцию (wMaxDispenseItems): 200 банкнот.

Датчики банкнот в слоте приема/выдачи:

  • взятие банкнот (bItemsTakenSensor);

  • вставка банкнот (bItemsInsertedSensor).

Инкассация (fwExchangeType): ручная инкассация кассет.

Область ретракта (fwRetractAreas):

  • RETRACT-кассета;

  • RECYCLER-кассеты (BILLCASSETTES – CIM, ITEMCASSETTE – CDM).

WFS_INF_CDM_CASH_UNIT_INFO

Информация о кассетах предоставляется по двум интерфейсам: CIM и CDM. При этом информации, полученной через интерфейс CIM всегда достаточно для получения представления о содержимом каждой из физических кассет, а также для формирования статистики по операциям приема и выдачи.

Как следствие, инкассация и конфигурирование рециклера допускается только через интерфейс CIM.

Логические кассеты, работающие только на прием (CashIn, Reject, Retract) никогда не имеют статус LOW или EMPTY. Логические кассеты, работающие только на выдачу (CDM BILL), никогда не имеют статус HIGH или FULL.

Статусы кассет CIM и CDM, относящиеся к наполнению кассеты (EMPTY, LOW, HIGH, FULL), меняются в зависимости от аппаратного статуса кассет.

Определение пороговых статусов кассет CIM/CDM:

XFS-статус

Аппаратный статус

WFS_CXM_STATCUEMPTY

Кассета полностью пуста

WFS_CXM_STATCULOW

В кассете находится хотя бы одна банкнота

WFS_CXM_STATCUOK

Если от устройства не пришло по кассете ни EMPTY, ни LOW, ни FULL

WFS_CXM_STATCUHIGH

Такого статуса никогда не будет, аппаратный HIGH отсутствует

WFS_CXM_STATCUFULL

Аппаратное переполнение кассеты

Отклонение от стандарта при работе со счетчиками. В случае выполнения команды CdmReject с возвратом банкнот в Recycling-кассеты, ПО выполняет «транзакционный откат» значений счетчиков:

  • ulDispensedCount – восстанавливается до первоначального значения (до набора);

  • ulCashInCount – не начисляется.

В целом, XFS-сервис придерживается правил ведения счетчиков, описываемых в спецификациях. Ниже кратко представлены счетчики, их назначение, а также особенности ведения.

Счетчики и особенности их ведения:

  • ulCount – текущее количество банкнот в кассете. Для логической кассеты включает набранные банкноты до тех пор, пока они не будут предъявлены либо сброшены.

  • noteNumberList – текущий состав банкнот по номиналам в логической кассете.

  • ulCashInCount – количество банкнот, помещенных в данную кассету безотносительно типа кассеты и операции. Исключение (отклонение от стандарта): в случае возврата (Reject) набранных банкнот в Recycling-кассеты, данный счетчик не увеличивается.

  • ulInitialCount – начальное значение счетчика банкнот (после проведения инкассации).

  • ulDispensedCount – количество набранных (слистнутых) из кассеты банкнот. Исключение (отклонение от стандарта): в случае возврата (Reject) набранных банкнот в Recycling-кассеты, данный счетчик возвращается в исходное (до набора) состояние. Если удается вернуть лишь часть банкнот (в силу возможной отбраковки при повторной валидации), счетчик восстанавливается частично.

  • ulPresentedCount – количество набранных из кассеты и предъявленных банкнот.

  • ulRetractedCount – количество банкнот, помещенных в данную кассету в рамках операции Retract WFS_INF_CDM_CURRENCY_EXP.

  • ulRejectCount Количество банкнот, набранных из данной кассеты и попавших в Reject-кассету (в силу отбраковки при наборе либо по команде Reject после набора).

WFS_CIM_CURRENCY_EXP

По данному запросу можно узнать значение установленной экспоненты для каждой поддерживаемой устройством валюты. Ответ записывается в структуру WFSCIMCURRENCYEXP.

WFSCIMCURRENCYEXP:

  • cCurrencyID – валюта в формате ISO 4217 (EUR, RUB, USD, KZT и т.д.);

  • sExponent – значение экспоненты.

WFS_INF_CDM_MIX_TYPES

Команда возвращает поддерживаемые алгоритмы набора банкнот из кассет.

Поддерживаемые алгоритмы (usSubType):

  • WFS_CDM_MIX_EQUAL_EMPTYING_OF_CASH_UNITS (равномерное опустошение кассет);

  • WFS_CDM_MIX_MINIMUM_NUMBER_OF_BILLS (минимум банкнот в пачке);

  • WFS_CDM_MIX_MAXIMUM_NUMBER_OF_CASH_UNITS (использование максимального кол-ва кассет).

WFS_INF_CDM_PRESENT_STATUS

Команда возвращает данные по набранным/выданным банкнотам в рамках последней операции набора/выдачи. Информация по полям lpDenomination->lpulValues представлена по состоянию, актуальному на момент проведения набора/выдачи (порядок следования логических кассет). Данные могут быть изменены только посредством подачи команд WFS_CMD_CDM_DISPENSE, WFS_CMD_CDM_PRESENT.

wPresentState:

  • WFS_CDM_PRESENTED (набранные банкноты выданы клиенту);

  • WFS_CDM_NOTPRESENTED (банкноты были набраны, но еще не выданы клиенту).

Возможен вариант набора банкнот и последующий сброс (WFS_CMD_CDM_REJECT), данные по набранным банкнотам сохранятся, не смотря на физическое отсутствие набранной пачки, wPresentState останется в состоянии WFS_CDM_NOTPRESENTED.

Команды

Сервис CIM

WFS_CMD_CIM_CASH_IN_START

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

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • транзакция приема наличных неактивна;

  • кассеты устройства готовы к приему (fwAcceptor != WFS_CIM_ACCCUSTOP).

  • кассеты устройства готовы к приему (fwAcceptor != WFS_CIM_ACCCUSTOP).

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

  • fwOutputPosition – WFS_CIM_POSNULL, WFS_CIM_POSOUTCENTER;

  • fwInputPosition – WFS_CIM_POSNULL, WFS_CIM_POSINCENTER.

WFS_CMD_CIM_CASH_IN

На момент выполнения данной операции ПО верхнего уровня должно выполнить следующие действия:

  1. открыть шаттер (WFS_CMD_CIM_OPEN_SHUTTER);

  2. дождаться от сервис-провайдера события вставки банкнот (WFS_SRVE_CIM_ITEMSINSERTED);

  3. закрыть шаттер (WFS_CMD_CIM_CLOSE_SHUTTER).

По данной команде осуществляется пересчет вставленной пачки в слот приема/выдачи и последующая транспортировка банкнот во временный накопитель (escrow). Банкноты, не прошедшие валидацию или не сконфигурированные к приему, а также с загнутыми углами при установленном флаге DogEarCheck, будут возвращены обратно.

Шаттер закроется автоматически, если на момент начала выполнения данной операции не был закрыт.

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • транзакция приема наличных активна;

  • escrow (отсек) не заполнен.

На выходе формируется список принятых банкнот (lpNoteNumberList) в рамках данной операции.

WFS_CMD_CIM_CASH_IN_END

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

В рамках исполнения данной команды:

  • происходит складирование принятой пачки в кассеты;

  • пересчитываются счетчики кассет;

  • происходит механическая подготовка устройства к следующей транзакции.

Принцип распределения банкнот по кассетам:

Тип кассеты

Банкноты

WFS_CIM_TYPERECYCLING, WFS_CIM_TYPECASHIN (WFS_CIM_CITYPEINDIVIDUAL)

Сконфигурированные для конкретной кассеты (указана валюта и номинал)

WFS_CIM_TYPE_CASHIN (WFS_CIM_CITYPALL + WFS_CIM_CITYPUNFIT)

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

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • транзакция приема наличных активна;

  • слот приема/выдачи пуст.

На выходе формируется структура кассет (WFSCIMCASHINFO), принимавших участие в процессе исполнения данной операции.

WFS_CMD_CIM_CASH_IN_ROLLBACK

Команда закрывает транзакцию приема наличных. Статус транзакции выставляется в WFS_CIM_CIROLLBACK в любом случае. Принятые ранее банкноты возвращаются обратно в слот приема/выдачи.

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • транзакция приема наличных активна.

WFS_CMD_CIM_RETRACT

По данной команде удерживаются на хранение банкноты, забытые клиентом:

  • после выдачи (DISPENSE+PRESENT);

  • после отката приема наличных (ROLLBACK);

  • отвергнутые банкноты в процессе приема наличных (REFUSEDITEMS).

Команда позволяет очистить слот приема/выдачи от банкнот для проведения следующих операций с наличными. При исполнении команды RETRACT через сервис CIM – закрывается транзакция приема наличных со статусом WFS_CIM_CIRETRACT.

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

Шаттер закроется автоматически, если на момент начала выполнения данной операции не был закрыт.

Операция может механически длиться дольше, если банкноты присутствуют в слоте приема/выдачи и в escrow одновременно.

При отсутствии в конфигурации RETRACT кассет сброс будет произведен в платежные кассеты, аналогично подаче команды с параметром RA_BILLCASSETTES (CIM), RA_ITEMCASSETTE (CDM).

Поддерживаемые области ретракта:

  • RA_RETRACT – сброс банкнот в RETRACT кассету. Приоритет имеет URJB кассета (счетчики будут учтены в логической RETRACT кассете, ссылающейся на физическую URJB). При отсутствии URJB кассеты (не установлен флаг URJBExistence) или при невозможности сброса пачки в URJB (емкость всего 100 листов), сброс будет осуществляться в AB кассету нижнего уровня (счетчики будут учтены в логической RETRACT кассете, ссылающейся на физическую AB).

  • RA_BILLCASSETTES (CIM), RA_ITEMCASSETTE (CDM) – сброс банкнот в RECYCLER кассеты. Нераспознанные банкноты или банкноты, не поддерживаемые RECYCLER кассетами, будут помещены в AB кассету, предназначенную для ретракта (счетчики будут учтены в логической RETRACT кассете, ссылающейся на физическую AB).

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • слот приема/выдачи не пуст.

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

  • fwOutputPosition – CIM: WFS_CIM_POSNULL, WFS_CIM_POSOUTCENTER; CDM: WFS_CDM_POSNULL, WFS_CDM_POSCENTER.

  • usRetractArea – CIM: WFS_CIM_RA_RETRACT, WFS_CDM_RA_BILLCASSETTES; CDM: WFS_CDM_RA_RETRACT, WFS_CDM_RA_ITEMCASSETTE.

  • usIndex – значение игнорируется.

Параметры на выход:

  • CIM: структура кассет (WFSCIMCASHINFO), принимавших участие в процессе исполнения данной операции;

  • CDM: структура WFSCDMITEMNUMBER с данными по каждой сброшенной в ретракт банкноте, в независимости от версии интерфейса XFS под которой открыт сервис.

Примечание

Поддержка WFSCDMITEMNUMBER реализована, начиная с версии CEN/XFS 3.20.

WFS_CMD_CIM_OPEN_SHUTTER

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

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • шаттер закрыт.

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

  • lpfwPosition – CIM: WFS_CIM_POSNULL, WFS_CIM_POSINCENTER, WFS_CIM_POSOUTCENTER; CDM: WFS_CDM_POSNULL, WFS_CDM_POSCENTER.

WFS_CMD_CIM_CLOSE_SHUTTER

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

Если на момент проведения данной операции в области движения шаттера появился/имеется посторонний предмет, мешающий корректному закрытию, то шаттер будет открываться-закрываться снова, пока посторонний предмет не перестанет мешать рабочему движению шаттера, в течение ~1,5 минут. После достижения таймаута команда завершится с результатом WFS_ERR_HARDWARE_ERROR.

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • шаттер открыт.

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

  • lpfwPosition – CIM: WFS_CIM_POSNULL, WFS_CIM_POSINCENTER, WFS_CIM_POSOUTCENTER; CDM: WFS_CDM_POSNULL, WFS_CDM_POSCENTER.

WFS_CMD_CIM_SET_CASH_UNIT_INFO

Команда доступна только через интерфейс CIM и используется для изменения счетчиков и пороговых значений. В текущей версии поддержка программной блокировки кассет (флаг bAppLock) не поддерживается.

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

  • сервис в состоянии готовности (иначе WFS_ERR_DEV_NOT_READY);

  • замена кассет (инкассация) неактивна (иначе WFS_ERR_CIM_EXCHANGEACTIVE);

  • транзакция приема банкнот неактивна (иначе возвращается непредусмотренный спецификацией код ошибки WFS_ERR_CIM_CASHINACTIVE);

  • транзакция выдачи банкнот неактивна (иначе WFS_ERR_DEV_NOT_READY).

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

  • структура предъявленных логических кассет идентична текущей:

    • валюта;

    • номинал;

    • тип кассеты;

    • тип принимаемых банкнот;

    • перечень принимаемых банкнот;

    • привязка к физическим кассетам;

    • noteNumberList согласуется с ulCount.

  • для кассет, не предполагающих выдачу наличных, а, как следствие, и начальную загрузку:

    • все счетчики должны быть обнулены;

  • для кассет, допускающих выдачу наличных:

    • счетчик ulCount и noteNumberList могут быть ненулевыми;

    • noteNumberList включает единственный идентификатор банкнот usNoteID, соответствующий номиналу банкнот, выдаваемых из данной кассеты;

    • счетчики ulCount и ulInitialCount должны совпадать;

    • остальные счетчики должны быть сброшены в ноль;

    • счетчики физических кассет согласуются со счетчиками логических кассет.

Если входные данные не прошли валидацию, возвращается код ошибки WFS_ERR_INVALID_DATA или WFS_ERR_UNSUPP_DATA.

WFS_CMD_CIM_START_EXCHANGE

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

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

  • сервис в состоянии готовности (иначе DEV_NOT_READY);

  • замена кассет (инкассация) неактивна (иначе WFS_ERR_CIM_EXCHANGEACTIVE);

  • транзакция приема банкнот неактивна (в противном случае возвращается непредусмотренный спецификацией код ошибки WFS_ERR_CIM_CASHINACTIVE);

  • транзакция выдачи банкнот неактивна.

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

  • выбран ручной тип замены WFS_CIM_EXBYHAND;

  • в списке кассет перечислены все логические кассеты.

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

WFS_CMD_CIM_END_EXCHANGE

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

Допускается изменение полей cUnitID и lpszCashUnitName в логических и физических кассетах, порогов ulMaximum/ulMinimum логических кассет.

В настоящей версии не поддерживается режим конфигурирования: изменение валют и номиналов кассет, перестановка и объединение кассет, и т.п. Также не поддерживается режим программной блокировки кассет (флаг bAppLock).

Не учитывается следующее требование спецификации: «If the fields ulCount, and ulCashInCount of lppPhysical are set to zero by this command, the application is indicating that it does not wish counts to be maintained for the physical cash units.»

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

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

  • сервис в состоянии готовности (иначе DEV_NOT_READY);

  • замена кассет (инкассация) активна (иначе WFS_ERR_CIM_NOEXCHANGEACTIVE).

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

  • допускается NULL в качестве указателя на входную структуру. В этом случае, замена кассет завершается без изменения счетчиков;

  • структура логических кассет идентична текущей (иначе используется команда WFS_ERR_UNSUPP_DATA);

  • требование к содержимому счетчиков идентично SetCashUnitInfo.

WFS_CMD_CIM_RESET

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

Поддерживаемые области см. в описании команды WFS_CMD_CIM_RETRACT.

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

  • замена кассет (инкассация) неактивна (для версии XFS 3.03);

  • транзакция приема наличных неактивна (для версии XFS 3.03).

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

  • usNumber – значение игнорируется;

  • lpRetractArea – см. описание команды WFS_CMD_CIM_RETRACT;

  • fwOutputPosition – CIM: WFS_CIM_POSNULL, WFS_CIM_POSOUTCENTER; CDM: WFS_CDM_POSNULL, WFS_CDM_POSCENTER.

WFS_CMD_CIM_CONFIGURE_NOTETYPES

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

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • транзакция приема наличных неактивна.

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

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

WFS_CMD_CIM_SET_CASH_IN_LIMIT

Данная команда описана в спецификациях, начиная с версии 3.20, и предназначена для временной установки лимита на количество листов и суммы вносимой пачки наличных.

Для правильной работы ограничения суммы, транзакция должна быть моновалютной. Значение параметра lpAmountLimit->cCurrencyID игнорируется.

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

WFS_CMD_CIM_CONFIGURE_CASH_IN_UNITS

Данная команда осуществляет установку номиналов и валют логических кассет. Установка возможна не только для CASHIN/RECYCLER кассет, но и для кассет с типом CDMSPECIFIC/RETRACT/REJECT.

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

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

  • usNumber – должна быть логическая CIM кассета с таким номером. Счетчики кассеты должны быть нулевые, в противном случае должна быть активна сессия замены кассет. К данной логической кассете должна быть привязана физическая. Физическая кассета должна находиться в нижнем модуле устройства (не URJB). При ошибке валидации результат – WFS_ERR_CIM_INVALIDCASHUNIT.

  • dwType – комбинация WFS_CIM_CITYPALL + WFS_CIM_CITYPUNFIT для кассет с типом RETRACT/REJECT и CASHIN, которые привязаны к физическим AB кассетам. WFS_CIM_CITYPINDIVIDUAL для кассет с типом CASHIN/ RECYCLER/CDMSPECIFIC. При ошибке валидации результат WFS_ERR_INVALID_DATA.

  • lpusNoteIDs – должен содержать не более одного элемента:

    • для dwType = WFS_CIM_CITYPALL + WFS_CIM_CITYPUNFIT должен быть пустым;

    • для dwType = WFS_CIM_CITYPINDIVIDUAL должен содержать один идентификатор (идентификатор должен поддерживаться устройством).

    При ошибке валидации результат WFS_ERR_INVALID_DATA.

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

Запись комплекта кассет с пустой памятью: кроме кода деноминации (валюта + номинал), в кассету будет записаны поля type и operation (см. Конфигурация кассет). Значения данных полей будут взяты из текущей аппаратной конфигурации кассет (исходя из порядкового номера кассет в устройстве сверху вниз), которая была построена на основе конфигурационного файла ht3842settings.xml при старте приложения.

Перезапись памяти кассет: команда WFS_CMD_CIM_CONFIGURE_CASH_IN_UNITS без дополнительных настроек и манипуляций позволяет перезаписать деноминацию кассеты. Маловероятна ситуация, когда потребуется перезаписать поле type, потому как AB-кассета, исходя из физических характеристик, не сможет стать RB-кассетой и наоборот.

Для перезаписи поля operation (операционный тип кассеты) необходимо:

  1. Сбросить установленный параметр «ConstructConfigurationByCassetteMemory», чтобы при последующей загрузке приложения аппаратная конфигурация кассет была сформирована относительно конфигурационного файла, а не памяти кассет. Если параметр не был установлен, то начинать с п.4.

  2. Указать в файле ht3842setting.xml желаемые значения полей operation.

  3. Перезапустить приложение (XFS-драйвер).

  4. Выполнить команду WFS_CMD_CIM_CONFIGURE_CASH_IN_UNITS.

  5. Установить параметр «ConstructConfigurationByCassetteMemory» в конфигурационном файле.

  6. Перезапустить приложение, чтобы аппаратная конфигурация и xfs конфигурация логических кассет сервисов CIM и CDM были построены на основе данных памяти.

Подразумевается, что операционный тип кассеты (RECYCLER, CASHIN, CASHOUT, RETRACT/REJECT) создается 1 раз, а далее возможно изменение только деноминации кассеты любое кол-во раз.

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

Сервис CDM

WFS_CMD_CDM_DENOMINATE

Команда используется для проведения разбивки, а также выявления возможности набора указанной суммы.

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

  • сервис в состоянии готовности (иначе DEV_NOT_READY);

  • замена кассет (инкассация) неактивна (иначе WFS_ERR_CDM_EXCHANGEACTIVE).

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

  • если usMixNumber не входит в подмножество поддерживаемых, возвращается WFS_ERR_CDM_INVALIDMIXNUMBER;

  • если поле cCurrencyID содержит неподдерживаемую валюту, возвращается WFS_ERR_CDM_INVALIDCURRENCY;

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

Предусмотрено три режима функционирования:

  1. Подтверждение возможности набора суммы по индивидуально предоставленной разбивке:

    {
usMixNumber = WFS_CDM_INDIVIDUAL;
ulAmount = 0;
cCurrencyID = “ ”, либо выдаваемая валюта;
usCount != 0;
lpulValues = индивидуальная разбивка.
}

Если usCount и lpulValues не соответствуют структуре логических кассет, то возвращается WFS_ERR_INVALID_DATA.

Если указанная индивидуальная разбивка не может быть набрана (в силу недостатка банкнот по указанным кассетам, или из-за того, что предпринимается выдача из логических REJECT/RETRACT-кассет), то возвращается WFS_ERR_CDM_INVALIDDENOMINATION.

Если указанная разбивка может быть набрана, но не умещается в емкость временного накопителя/слота выдачи, то возвращается WFS_ERR_CDM_TOOMANYITEMS.

Если задана определенная валюта разбивки cCurrencyID, а одна из кассет содержит валюту, отличную от указанной, то возвращается WFS_ERR_CDM_NOCURRENCYMIX.

  1. Подтверждение возможности набора суммы по индивидуально предоставленной разбивке с проверкой соответствия указанной сумме:

    {
usMixNumber = WFS_CDM_INDIVIDUAL;
ulAmount > 0;
cCurrencyID != “ ”;
usCount != 0;
lpulValues = индивидуальная разбивка.
}

Если указанная сумма, как таковая, не может быть набрана, то возвращается WFS_ERR_CDM_NOTDISPENSABLE.

Дальнейшая процедура валидации аналогична п.1, с добавлением проверки соответствия указанной суммы: если указанная сумма не совпадает с указанной разбивкой, то возвращается WFS_ERR_CDM_INVALIDDENOMINATION.

  1. Подтверждение возможности набора указанной суммы:

    {
usMixNumber = {подмножество поддерживаемых разбивок};
ulAmount > 0;
cCurrencyID = {поддерживаемая валюта};
usCount = 0;
lpulValues = 0.
}

Если usMixNumber не входит в подмножество поддерживаемых, то возвращается WFS_ERR_CDM_INVALIDMIXNUMBER.

Если ulAmount = 0, то возвращается WFS_ERR_INVALID_DATA.

Если cCurrencyID представлена значением » «, то возвращается WFS_ERR_INVALID_DATA.

Если cCurrencyID не входит в текущую конфигурацию кассет, возвращается WFS_ERR_CDM_INVALIDCURRENCY.

Если usCount отлично от нуля, то возвращается WFS_ERR_INVALID_DATA.

Если указанная сумма не может быть набрана, то возвращается WFS_ERR_CDM_NOTDISPENSABLE.

WFS_CMD_CDM_DISPENSE

Команда выполняет:

  • набор требуемого кол-ва банкнот или суммы из кассет;

  • транспортировку набранной пачки в слот приема/выдачи;

  • выдачу пачки (предъявление клиенту) при установленном параметре bPresent;

  • пересчет счетчиков кассет.

Отбракованные в процессе набора банкноты попадут в AB-кассету, предназначенную для отбраковки. Счетчики будут учтены в логической REJECT-кассете, ссылающейся на физическую AB.

При неполном наборе (из-за большого количества отбраковки) устройство показывает ошибку. Для возврата устройства в рабочее состояние автоматически запускается процесс его инициализации, которая происходит автоматически, в результате чего время исполнения команды WFS_CMD_CDM_DISPENSE увеличивается на минуту. Набранная пачка банкнот возвращается обратно в RECYCLER кассеты (идентично операции WFS_CMD_CDM_REJECT ).

Если заказан набор из кассет, которые сконфигурированы на одинаковые номиналы , то набор будет разбит на несколько итераций (особенности коммуникационного протокола с устройством). Количество итераций равно максимальному числу кассет, имеющих одинаковые деноминации, из которых требуется набор. Т.е., если имеем 2 кассеты по 10RUB и 3 кассеты по 50RUB и из всех кассет требуется набрать банкноты, то набор будет осуществлен в 3 подхода. Каждая итерация увеличивает итоговое время исполнения требуемого набора примерно на 5 секунд.

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • транзакция приема наличных неактивна (в противном случае WFS_ERR_DEV_NOT_READY);

  • слот приема/выдачи пуст.

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

  • usTellerID – значение игнорируется;

  • usMixNumber – должен поддерживаться устройством;

  • fwPosition – WFS_CDM_POSSNULL, WFS_CDM_POSCENTER;

  • lpDenomination – см. WFS_INF_CDM_PRESENT_STATUS.

WFS_CMD_CDM_PRESENT

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

В рамках исполнения данной команды:

  • осуществляется механическая подготовка устройства для предъявления набранной пачки клиенту;

  • открытие шаттера слота приема/выдачи.

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • транзакция приема наличных неактивна (в противном случае WFS_ERR_DEV_NOT_READY);

  • существует набранная пачка для предъявления клиенту.

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

  • lpfwPosition – WFS_CDM_POSSNULL, WFS_CDM_POSCENTER.

WFS_CMD_CDM_REJECT

По данной команде осуществляется сброс ранее набранной пачки обратно в RECYCLER кассеты.

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

Существует теоретическая вероятность, что часть из ранее набранных банкнот при возврате обратно в RECYCLER кассеты будет сброшена в REJECT кассету (из-за ветхости банкноты или ошибки распознавания валидатора устройства).

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • транзакция приема наличных неактивна (в противном случае WFS_ERR_DEV_NOT_READY);

  • существует ранее набранная пачка.

Счетчики логических и физических кассет:

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

  • ulCount уменьшается на количество набранных банкнот, если из кассеты было набрано, но сброшено в другую кассету.

  • ulDispensedCount возвращается в прежнее состояние (до набора) за исключением банкнот, сброшенных в REJECT кассету (по ветхости или подлинности).

  • ulCashInCount не инкрементируется, если банкноты были сброшены обратно в RECYCLING-кассеты.

  • ulCashInCount инкрементируется только для REJECT-кассет.

  • ulRejectCount увеличивается в том случае, если банкноты были сброшены в REJECT-кассету.

WFS_CMD_CDM_RETRACT

По данной команде удерживаются на хранение банкноты, забытые клиентом:

  • после выдачи (DISPENSE+PRESENT);

  • после отката приема наличных (ROLLBACK);

  • отвергнутые банкноты в процессе приема наличных (REFUSEDITEMS).

Команда позволяет очистить слот приема/выдачи от банкнот для проведения следующих операций с наличными. При исполнении команды RETRACT через сервис CIM – закрывается транзакция приема наличных со статусом WFS_CIM_CIRETRACT.

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

Шаттер закроется автоматически, если на момент начала выполнения данной операции не был закрыт.

Операция может механически длиться дольше, если банкноты присутствуют в слоте приема/выдачи и в escrow одновременно.

Поддерживаемые области ретракта:

  • RA_RETRACT – cброс банкнот в RETRACT-кассету. Приоритет имеет URJB-кассета (счетчики будут учтены в логической RETRACT-кассете, ссылающейся на физическую URJB). При отсутствии URJB-кассеты (не установлен флаг URJBExistence) или при невозможности сброса пачки в URJB (емкость всего 100 листов), сброс будет осуществляться в AB-кассету нижнего уровня (счетчики будут учтены в логической RETRACT-кассете, ссылающейся на физическую AB).

При отсутствии в конфигурации RETRACT-кассет – сброс будет произведен в платежные кассеты, аналогично подаче команды с параметром RA_BILLCASSETTES (CIM), RA_ITEMCASSETTE (CDM).

  • RA_BILLCASSETTES (CIM), RA_ITEMCASSETTE (CDM) – сброс банкнот в RECYCLER кассеты. Нераспознанные банкноты или банкноты, не поддерживаемые RECYCLER-кассетами, будут помещены в AB-кассету, предназначенную для ретракта (счетчики будут учтены в логической RETRACT кассете, ссылающейся на физическую AB).

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • слот приема/выдачи не пуст.

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

  • fwOutputPosition – CIM: WFS_CIM_POSNULL, WFS_CIM_POSOUTCENTER; CDM: WFS_CDM_POSNULL, WFS_CDM_POSCENTER.

  • usRetractArea – CIM: WFS_CIM_RA_RETRACT, WFS_CDM_RA_BILLCASSETTES; CDM: WFS_CDM_RA_RETRACT, WFS_CDM_RA_ITEMCASSETTE.

  • usIndex – значение игнорируется.

Параметры на выход:

  • CIM: структура кассет (WFSCIMCASHINFO), принимавших участие в процессе исполнения данной операции;

  • CDM: структура WFSCDMITEMNUMBER с данными по каждой сброшенной в ретракт банкноте, в независимости от версии интерфейса XFS под которой открыт сервис.

Примечание

Поддержка WFSCDMITEMNUMBER реализована, начиная с версии CEN/XFS 3.20.

Отклонение от стандарта: по итогам успешного выполнения запроса устройство осуществляет пересчет удерживаемой пачки банкнот. О результатах пересчета сообщается в выходном параметре запроса WFSCDMITEMNUMBERLIST (описание см. в спецификации, начиная с версии 3.20).

WFS_CMD_CDM_OPEN_SHUTTER

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

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • шаттер закрыт.

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

  • lpfwPosition – CIM: WFS_CIM_POSNULL, WFS_CIM_POSINCENTER, WFS_CIM_POSOUTCENTER; CDM: WFS_CDM_POSNULL, WFS_CDM_POSCENTER.

WFS_CMD_CDM_CLOSE_SHUTTER

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

Если на момент проведения данной операции в области движения шаттера появился/имеется посторонний предмет, мешающий корректному закрытию, то шаттер будет открываться-закрываться снова, пока посторонний предмет не перестанет мешать рабочему движению шаттера, в течение ~1,5 минут. После достижения таймаута команда завершится с результатом WFS_ERR_HARDWARE_ERROR.

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

  • сервис в состоянии готовности;

  • замена кассет (инкассация) неактивна;

  • шаттер открыт.

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

  • lpfwPosition – CIM: WFS_CIM_POSNULL, WFS_CIM_POSINCENTER, WFS_CIM_POSOUTCENTER; CDM: WFS_CDM_POSNULL, WFS_CDM_POSCENTER.

WFS_CMD_CDM_RESET

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

Поддерживаемые области ретракта см. комментарии к команде WFS_CMD_CIM_RETRACT.

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

  • замена кассет (инкассация) неактивна (для версии XFS 3.03);

  • транзакция приема наличных неактивна (для версии XFS 3.03).

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

  • usNumber – значение игнорируется;

  • lpRetractArea – поддерживаемые области см. в описании команды WFS_CMD_CDM_RETRACT;

  • lpfwPosition – CIM: WFS_CIM_POSNULL, WFS_CIM_POSOUTCENTER; CDM: WFS_CDM_POSNULL, WFS_CDM_POSCENTER.

Cобытия

  • WFS_USRE_CXM_CASHUNITTHRESHOLD – событие генерируется в случае изменения статуса кассеты c OK, HIGH, FULL на LOW (мало банкнот).

  • WFS_SRVE_CXM_CASHUNITINFOCHANGED – событие генерируется в случае изменения статуса кассеты (кроме ситуаций WFS_USRE_CXM_CASHUNITTHRESHOLD), а также изменения данных по кассете после конфигурации/инкассации. Консолидирующим событием между WFS_USRE_CXM_CASHUNITTHRESHOLD и WFS_SRVE_CXM_CASHUNITINFOCHANGED будет WFS_SRVE_CXM_CASHUNITINFOCHANGED.

  • WFS_SRVE_CXM_ITEMSTAKEN – событие генерируется в случае извлечения банкнот клиентом из слота приема/выдачи. В параметрах события указывается выходная позиция, из которой были взяты банкноты: WFS_CIM_POSOUTCENTER, WFS_CDM_POSCENTER.

  • WFS_SRVE_CXM_ITEMSPRESENTED – событие генерируется в случае транспортировки банкнот из устройства в слот приема/выдачи для предъявления клиенту. Случаи транспортировки: выдача набранных из кассет банкнот (WFS_CMD_CDM_DISPENSE + WFS_CMD_CDM_PRESENT), откат транзакции приема наличных (WFS_CMD_CIM_ROLLBACK), возврат отвергнутых банкнот (REFUSEDITEMS).

  • WFS_SRVE_CXM_MEDIADETECTED – событие генерируется в случае обнаружения банкнот на транспорте, в слоте приема/выдачи в процессе исполнения сброса состояния оборудования (WFS_CMD_CXM_RESET). В параметрах события указывается место нахождения обнаруженных ранее банкнот по окончанию операции сброса (кассеты, слот приема/выдачи).

  • WFS_SRVE_CIM_INPUTREFUSE – событие генерируется в случае наличия отвергнутых банкнот в процессе операции приема наличных (WFS_CMD_CIM_CASH_IN). Отвергнутая часть банкнот (невалидные, не поддерживаемые устройством, не разрешены к приему) возвращается обратно в слот приема/выдачи. Возможные причины возврата: WFS_CIM_INVALIDBILL.

  • WFS_SRVE_CIM_ITEMSINSERTED – событие генерируется в случае вставки пачки банкнот в слот приема/выдачи. Генерация события удерживается до того момента, пока шаттеру слота приема/выдачи ничего (посторонний предмет; рука клиента, удерживающая вставленную пачку) не мешает закрыться (рабочее пространство движения шаттера свободно). Данное поведение реализовано для удобства управляющего ПО верхнего уровня, которое при получении события о вставке банкнот посылает команду закрытия шаттера (WFS_CMD_CXM_CLOSE_SHUTTER).

  • WFS_EXEE_CIM_INSERTITEM – событие генерируется в случае готовности XFS сервиса и устройства принять очередную пачку банкнот. Фактически, генерация события происходит после открытия шаттера при активной транзакции приема наличных.

Управление шаттером

Транзакция приема наличных

См. спецификацию «Extensions for Financial Services (XFS) interface specification. Release 3.10 - Part 15: Cash In Module Device Class Interface», пункт «7. ATM Cash-In Transaction Flow - Application Guidelines (Explicit Shutter Control)».

Транзакция выдачи наличных

Управление шаттером при наборе и выдаче наличных описано ниже в таблице, аналогичной таблице CEN/XFS, описывающей управление шаттером при приеме наличных.

№

Клиент

Управляющее ПО

XFS команды и события

1

Клиент выбирает операцию выдачи наличных.

WFS_CMD_CXM_DISPENSE (bPresent =true) или WFS_CMD_CXM_DISPENSE + WFS_CMD_CXM_PRESENT. Сервис-провайдер открывает шаттер, генерирует событие FS_SRVE_CXM_ITEMSPRESENTED, после чего сообщает о завершении команды DISPENSE/PRESENT.

2

Информирование клиента о том, что он может забрать банкноты.

3

Клиент забирает банкноты.

Генерируется событие WFS_SRVE_CXM_ITEMSTAKEN.

4

Закрытие шаттера.

WFS_CMD_CXM_CLOSE_SHUTTER.

Если после предъявления пачки банкнот клиент бездействует, то по команде WFS_CMD_CXM_RETRACT шаттер закроется автоматически.

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

Инициализация устройства – процесс проверки устройством всех необходимых механических узлов и установки конфигурационных параметров.

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

  • старт ПО;

  • переход устройства из состояния OFFLINE в ONLINE (открытие-закрытие дверей, выдвижение-вставка верхнего/нижнего модулей устройства);

  • после восстановления коммуникационной связи с устройством;

  • завершение инкассации (команда END_EXCHANGE), если в процессе инкассации выдвигался верхний/нижний уровень устройства, вытаскивались кассеты;

  • после неудачного набора, если часть банкнот была набрана.

При нормальных условиях процесс инициализации длится около 60 секунд.

Настройка АДМ

Данный раздел описывает настройку устройства и XFS драйвера для использования в режиме автоматической депозитной машины (АДМ). Все кассеты устройства должны быть настроены только на прием. Рассмотрим настройку отдельных параметров конфигурационного файла ht3842settings.xml:

  1. Настройка кассет (с отдельной ретракт кассетой):

    В верхнюю кассету будут производиться ретракты, а также прием наличных после заполнения остальных кассет. Также учитываем тот факт, что значения поля operation 3 и 5 конфликтуют.

<cassette>
…
<denomination currency="ALL" value="0" />
<operation val="3" />
…
</cassette>
<cassette>
…
<denomination currency="ALL" value="0" />
<operation val="6" />
…
</cassette>
<cassette>
…
<denomination currency="ALL" value="0" />
<operation val="6" />
…
</cassette>

  1. Настройка кассет (без ретракт кассеты):

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

<cassette>
…
<denomination currency="ALL" value="0" />
<operation val="5" />
…
</cassette>
<cassette>
…
<denomination currency="ALL" value="0" />
<operation val="5" />
…
</cassette>

  1. Настройка дополнительных полей (extra):

<extra>
// Исключение URJB кассеты из конфигурации. Ретракты только в нижний уровень
<URJBExistence val="false" />
<URJBFullErrorCheck val="true" />
// Не сортировать банкноты по ветхости, все кассеты на прием
<FitnessCheckInStacking val="false" />
<FitnessCheckInDispensing val="false" />
<DogEarCheck val="true" />
<CimStopAcceptorIfNoCiTypAllAvailable val="true" />
// Нет смысла использовать память кассет, все кассеты одинаковы
<ConstructConfigurationByCassetteMemory val="false" />
</extra>