XFS-сервис класса CIM. Модель DORS PMU-820

Поддерживаемые версии CEN/XFS: 3.02, 3.10. Различие в поведении физического сервиса в зависимости от версии ПО, отражены ниже по тексту.

Файлы

  • shqPS.CIM.DORS-PMU820.exe;

  • shqSPCIM.dll;

  • pmu820_persistents.xml (файл подписывается) – счетчики банкнот, настройки номиналов, кассеты и статусы операций приема. При повреждении структуры, удалении или переименовании данного файла создается новый файл pmu820_persistents.xml. Поврежденный файл при этом переименовывается.

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

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

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

  • PORT – номер порта, к которому подключено устройство.

  • CASSETTE_CAPACITY – емкость кассеты (сумки) в банкнотах. Значение по умолчанию – 15000. Емкость (максимум) логической кассеты устанавливается в 80% от установленного значения CASSETTE_CAPACITY. Емкость (максимум) физической кассеты определяется значением CASSETTE_CAPACITY. При достижении 80% от емкости статус логической кассеты перейдет в состояние HIGH («близка к переполнению»). Если после складирования пачки банкнот значение CASSETTE_CAPACITY будет достигнуто или превышено, то прием наличных останавливается, статус логической кассеты переходит в состояние FULL («переполнена»), а статус физической кассеты – в состояние HIGH.

  • DISABLE_CU_MANIPULATED – отключить отслеживание и перевод кассеты в состояние MANIPULATED (если кассета извлекалась вне рамок процедуры инкассации).

    Возможные значения:

    • 1 (задано по умолчанию) – извлечение кассеты вне процедуры инкассации допустимо;

    • <любое> – извлечение кассеты вне процедуры инкассации приведет к блокировке купюроприемника.

  • LIMIT_STACKER – емкость приемного кармана (эскроу). Возможные значения: 100, 200. По умолчанию – 200.

  • LIMIT_REJECT – емкость кармана отбраковки. Возможные значения: 25, 50, 100. По умолчанию – 25.

  • EXP_REDUCTION_TO_ZERO – приведение валют к нулевой экспоненте.

    Возможные значения:

    • 1 (по умолчанию) – номиналы будут иметь свои действительные значения, указанные на банкнотах (sExponent = 0).

    • <любое> – номиналы банкнот будут приводиться к значению, полученному от устройства (sExponent = -2);

Внимание

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

Запуск и выключение устройства

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

Инициализация включает в себя следующие шаги:

  1. Включение питания устройства.

  2. Дожидаемся загрузки устройства.

  3. Установка конфигурации устройства.

В случае завершения работы физического сервиса уровня XFS питание устройства будет отключено. В случае потери связи с устройством физический сервис XFS включает и выключает устройство (операция длится около 35 секунд).

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

Устройство оборудовано шторкой (шаттером/shutter) приемного кармана (эскроу). Шторка обеспечивает санкционированный доступ в приемный карман (эскроу) со стороны клиента. Подающий карман и карман отбраковки шаттером не оборудованы.

Отмена внесения наличных

После пересчета и валидации банкноты находятся в приемном кармане (эскроу). Вернуть клиенту банкноты можно только путем открытия шаттера. В данном случае управление шаттером должно осуществляться управляющим ПО (приложение).

Клиент

Приложение

Команда CEN/XFS API

1

Клиент отменяет операцию внесения наличных.

2

Информирование о возврате внесенных банкнот.

WFS_CMD_CIM_CASH_IN_ROLLBACK

3

Подает команду на открытие шаттера.

WFS_CMD_CIM_OPEN_SHUTTER

4

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

5

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

WFS_SRVE_CIM_ITEMSTAKEN

6

Подает команду на закрытие шаттера.

WFS_CMD_CIM_CLOSE_SHUTTER

Замятие при внесении наличных

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

Клиент

Приложение

Команда CEN/XFS API

Устройство

1

Открывается транзакция внесения наличных.

WFS_CMD_CIM_CASH_IN_START

2

WFS_CMD_CIM_CASH_IN

3

Происходит замятие банкнот. На дисплее устройства отображаются действия по устранению замятия.

4

WFS_CMD_CIM_CASH_IN завершается с кодом WFS_ERR_HARDWARE_ERROR.

5

WFS_CMD_CIM_OPEN_SHUTTER.

6

Клиент забирает банкноты из всех карманов (подающий, отбраковки, приемный). Откидывает тракт и освобождает его от замятых банкнот. Закрывает тракт.

Дожидаемся пока в WFS_INF_CIM_STATUS все позиции и тракты не станут работоспособны и пусты.

7

WFS_CMD_CIM_CLOSE_SHUTTER.

8

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

9

Сервис-провайдер закрывает шаттер.

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

WFS_INF_CIM_STATUS

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

Значения полей:

  • fwDevice:

    • WFS_CIM_DEVHWERRROR – аппаратная ошибка/замятие банкнот;

    • WFS_CIM_DEVBUSY – устройство занято отработкой команды;

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

    Поля fwAcceptor, fwIntermediateStacker, fwStackerItems, fwBanknoteReader имеют статус UNKNOWN при fwDevice = DEVNODEVICE/DEVHWERROR.

  • lpszExtra:

    • VENDOR = DORS [SYSTEMA];

    • PRODUCT = ProAtm/Xfs;

    • VERSION = [значение в формате «MAJOR.MINOR.MICRO.REVISION»];

    • DEVICE = DORS PMU820;

    • SERIAL = значение в формате D820-XXX-YYYYYYYY (серийный номер устройства);

    • VERSION_CONTROLLER = значение в формате «XX.YY.ZZZZ» (версия прошивки устройства);

    • VERSION_VALIDATOR = значение в формате «X.X.XXX» (версия валидатора);

    • VERSION_CURRENCY_BASE = значение в формате «X.X.X» (версия базы валют);

    • VERSION_CCM = значение в формате «X.X.XXX» (версия CCM);

    • JAMMED = FALSE (сообщает про состояние замятия, может иметь значение TRUE или FALSE, по умолчанию FALSE).

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

Таблица 13. Статусы поля fwAcceptor

Статус

Причина

WFS_CIM_ACCCUUNKNOWN

Устройство не инициализировано

WFS_CIM_ACCCUSTOP

Транзакция не активна и одна или несколько причин(кассета заблокирована, один или несколько карманов переполнены, замятие банкнот в устройстве, приемный карман не пуст. Включена настройка bAppLock командой WFS_CMD_CIM_SET_CASH_UNIT_INFO

WFS_CIM_ACCOK

Физическая кассета в хорошем состоянии

WFS_CIM_ACCCUSTATE

Физическая кассета переполнена

Таблица 14. Статусы поля fwIntermediateStacker

Статус

Причина

WFS_CIM_ISUNKNOWN

Состояние не известно

WFS_CIM_ISNOTEMPTY

Промежуточный стекер не пустой

WFS_CIM_ISEMPTY

Промежуточный стекер пустой

WFS_CIM_ISFULL

Промежуточный стекер переполнен

Таблица 15. Статусы поля fwStackerItems

Статус

Причина

WFS_CIM_ACCESSUNKNOWN

Состояние не известно

WFS_CIM_CUSTOMERACCESS

Промежуточный стекер не пустой

WFS_CIM_NOITEMS

Промежуточный стекер пустой

Таблица 16. Статусы поля fwBanknoteReader

Статус

Причина

WFS_CIM_BNRUNKNOWN

Состояние не известно

WFS_CIM_BNROK

Возможные причины: обычное состояние, замятие в устройстве

Таблица 17. Статусы позиций

Позиция

Поле

Статус

Причина

WFS_CIM_POSINTOP

fwShutter

fwPositionStatus

fwPositionStatus

fwPositionStatus

fwTransport

fwTransport

fwTransport

fwTransportStatus

fwTransportStatus

fwTransportStatus

WFS_CIM_SHTNOTSUPPORTED

WFS_CIM_PSUNKNOWN

WFS_CIM_PSEMPTY

WFS_CIM_PSNOTEMPTY

WFS_CIM_TPOK

WFS_CIM_TPINOP

WFS_CIM_TPUNKNOWN

WFS_CIM_TPSTATEMPTY

WFS_CIM_TPSTATNOTEMPTYCUST

WFS_CIM_TPSTATNOTEMPTY_UNK

Не поддерживается

Состояние не известно

Подающий карман пустой

Подающий карман не пустой

Верхний датчик тракта не перекрыт

Верхний датчик тракта перекрыт

Состояние не изветсно

Верхний датчик тракта не перекрыт

Верхний датчик тракта перекрыт

Состояние не известно

WFS_CIM_POSOUTCENTER

fwShutter

fwPositionStatus

fwPositionStatus

fwPositionStatus

fwTransport

fwTransport

fwTransport

fwTransportStatus

fwTransportStatus

fwTransportStatus

WFS_CIM_SHTNOTSUPPORTED

WFS_CIM_PSUNKNOWN

WFS_CIM_PSEMPTY

WFS_CIM_PSNOTEMPTY

WFS_CIM_TPOK

WFS_CIM_TPINOP

WFS_CIM_TPUNKNOWN

WFS_CIM_TPSTATEMPTY

WFS_CIM_TPSTATNOTEMPTYCUST

WFS_CIM_TPSTATNOTEMPTY_UNK

Не поддерживается

Состояние не известно

Карман отбраковки пустой

Карман отбраковки не пустой

Нижние датчики тракта не перекрыты

Один или два нижних датчика тракта перекрыты

Состояние не изветсно

Нижние датчики тракта не перекрыты

Один или два нижних датчика тракта перекрыты

Состояние не известно

WFS_CIM_POSOUTBOTTOM

fwShutter

fwShutter

fwShutter

fwShutter

fwPositionStatus

fwPositionStatus

fwPositionStatus

fwTransport

fwTransport

fwTransport

fwTransportStatus

fwTransportStatus

fwTransportStatus

WFS_CIM_SHTUNKNOWN

WFS_CIM_SHTCLOSED

WFS_CIM_SHTOPEN

WFS_CIM_SHTJAMMED

WFS_CIM_PSUNKNOWN

WFS_CIM_PSEMPTY

WFS_CIM_PSNOTEMPTY

WFS_CIM_TPOK

WFS_CIM_TPINOP

WFS_CIM_TPUNKNOWN

WFS_CIM_TPSTATEMPTY

WFS_CIM_TPSTATNOTEMPTYCUST

WFS_CIM_TPSTATNOTEMPTY_UNK

Состояние не известно

Шаттер закрыт

Шаттер открыт

Ошибка шаттера

Состояние не известно

Промежуточный стекер пустой

Промежуточный стекер не пустой

Во вторичном слистователе нет банкнот

Во вторичном слистователе есть банкнота

Состояние не известно

Во вторичном слистователе нет банкнот

Во вторичном слистователе есть банкнота

Состояние не известно

WFS_INF_CIM_CAPABILITIES

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

Значения полей:

  • wMaxCashInItems – соответствует настраиваемой величине емкости приемного кармана (эскроу).

  • bShutter – TRUE (см. Управление шаттером).

  • bShutterControl – FALSE (см. Отмена внесения наличных).

  • fwIntermediateStacker – соответствует настраиваемой величине емкости приемного кармана (эскроу).

  • bItemsTakenSensor – TRUE (см. События).

  • bItemsInsertedSensor – TRUE (см. События).

  • wPositions:

    • WFS_CIM_POSINTOP (подающий карман);

    • WFS_CIM_POSOUTCENTER (карман отбраковки);

    • WFS_CIM_POSOUTBOTTOM (приемный карман – эскроу).

  • lpszExtra:

    • VENDOR=DORS [SYSTEMA];

    • PRODUCT=ProAtm/Xfs;

    • VERSION=[Значение в формате «MAJOR.MINOR.MICRO.REVISION»];

    • DEVICE=DORS PMU820.

Поля fwRetractAreas, fwRetractTransportActions и fwRetractStackerActions не поддерживаются.

WFS_INF_CIM_CASH_UNIT_INFO

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

Идентификатор физической кассеты: cUnitID = PCAS1.

Имя физической позиции: lpPhysicalPositionName = DROPBOX.

Максимум физической кассеты: ulMaximum = CASSETTE_CAPACITY.

Идентификатор логической кассеты: cUnitID = LCAS1.

Максимум логической кассеты: ulMaximum = 80% от CASSETTE_CAPACITY.

WFS_INF_CIM_CURRENCY_EXP

Если значение параметра EXP_REDUCTION_TO_ZERO = 1, то sExponent = 0. Если – 0, то sExponent = -2.

WFS_INF_CIM_BANKNOTE_TYPES

Поддерживаются только рубли.

WFS_INF_CIM_CASH_IN_STATUS

Выполнение команды соответствует спецификации CEN/XFS.

Команды

WFS_CMD_CIM_CASH_IN_START

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

Значения входных параметров:

  • fwOutputPosition – WFS_CIM_POSNULL, WFS_CIM_POSOUTCENTER, WFS_CIM_POSOUTBOTTOM;

  • fwInputPosition – WFS_CIM_POSNULL, WFS_CIM_POSINTOP.

Коды ошибок:

  • WFS_ERR_DEV_NOT_READY – устройство не готово к выполнению команды/fwAcceptor = WFS_CIM_ACCCUSTOP/в приемном кармане (эскроу) есть банкноты/есть банкноты в кармане отбраковки/шаттер открыт подачей команды WFS_CMD_CIM_OPEN_SHUTTER.

WFS_CMD_CIM_CASH_IN

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

В случае пропадания банкнот из подающего кармана до запуска процесса пересчета генерируется событие WFS_SRVE_CIM_ITEMSTAKEN.

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

В случае замятия необходимо с помощью команды WFS_INF_CIM_STATUS проверять опустошение карманов и трактов (см. Замятие при внесении наличных).

Если логическое состояние кассеты WFS_CIM_STATCUFULL, то команда WFS_CMD_CIM_CASH_IN отправляет событие WFS_EXEE_CIM_CASHUNITERROR и завершается ошибкой WFS_ERR_CIM_CASHUNITERROR.

Коды ошибок:

  • WFS_ERR_CIM_CASHUNITERROR – логическое состояние кассеты WFS_CIM_STATCUFULL.

  • WFS_ERR_CIM_NOITEMS – подающий карман пуст, пересчитывать нечего, банкнота слисталась, но не попала на датчики.

  • WFS_ERR_CIM_SHUTTERNOTCLOSED – во время выполнение команды шаттер был открыт.

WFS_CMD_CIM_CASH_IN_END

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

Коды ошибок:

  • WFS_ERR_CIM_NOITEMS – приемный карман (эскроу) пуст или открытие шаттера во время транзакции приема. Транзакция будет закрыта со статусом WFS_CIM_CIOK.

WFS_CMD_CIM_CASH_IN_ROLLBACK

Команда закрывает активную транзакцию приема наличных. Никаких механических действий по возврату принятых наличных не выполняется. Далее для возврата банкнот необходимо будет открыть шаттер (см. Отмена внесения наличных).

Коды ошибок:

  • WFS_ERR_CIM_NOITEMS – открытие шаттера во время транзакции приема.

WFS_CMD_CIM_OPEN_SHUTTER

Команда открывает шаттер. Команду следует подавать для возврата принятых банкнот. Алгоритм управления шаттером описан в разделе Отмена внесения наличных. В режиме оператора команда WFS_CMD_CIM_OPEN_SHUTTER открывает шаттер. Открытие шаттера сбрасывает счетчики активной транзакции приема.

Возможные значения поля lpfwPosition:

  • WFS_CIM_POSNULL;

  • WFS_CIM_POSOUTBOTTOM.

lpfwPosition = NULL игнорируется.

Коды ошибок:

  • WFS_ERR_SOFTWARE_ERROR – ошибка конфигурации драйвера.

  • WFS_ERR_CIM_EXCHANGEACTIVE – активна сессия замены кассет.

  • WFS_ERR_CIM_UNSUPPOSITION – неподдерживаемое значение поля lpfwPosition.

  • WFS_ERR_CIM_SHUTTEROPEN – шаттер уже открыт. Не является ошибкой.

  • WFS_ERR_CIM_INVALID_DATA – во входных параметрах передан неизвестный идентификатор позиции. Не удалось открыть шаттер.

  • WFS_ERR_SHUTTERNOTOPEN – не удалось открыть шаттер.

WFS_CMD_CIM_CLOSE_SHUTTER

Команда закрывает шаттер. Команду следует подавать после события WFS_SRVE_CIM_ITEMSTAKEN (см. События). Алгоритм управления шаттером описан в разделе Отмена внесения наличных.

Возможные значения поля lpfwPosition:

  • WFS_CIM_POSNULL;

  • WFS_CIM_POSOUTBOTTOM.

lpfwPosition = NULL игнорируется.

Коды ошибок:

  • WFS_ERR_SOFTWARE_ERROR – ошибка конфигурации драйвера.

  • WFS_ERR_CIM_EXCHANGEACTIVE – активна сессия замены кассет.

  • WFS_ERR_CIM_UNSUPPOSITION`` – неподдерживаемое значение поля lpfwPosition.

  • WFS_ERR_CIM_SHUTTERCLOSED – шаттер уже закрыт. Не является ошибкой.

  • WFS_ERR_CIM_INVALID_DATA – во входных параметрах передан неизвестный идентификатор позиции. Не удалось закрыть шаттер.

WFS_CMD_CIM_SET_CASH_UNIT_INFO

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

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

  • bAppLock.

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

WFS_CMD_CIM_START_EXCHANGE

Команда используется для старта сессии замены кассет (инкассации). Команда закрывает шаттер, если он был открыт со стороны ПО ПроАТМ.

Значения входных параметров:

  • fwExchangeType=WFS_CIM_EXBYHAND;

  • usCount=1;

  • lpusCUNumList – первый элемент должен быть равен 1.

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

WFS_CMD_CIM_END_EXCHANGE

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

Значения входных параметров:

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

  • ulCount=0;

  • ulCashInCount=0;

  • noteNumberList пустой;

Команда позволяет установить только нулевые счетчики. Не поддерживается изменение структуры кассет, изменение валют и номиналов, порогов ulMaximum/ulMinimum.

WFS_CMD_CIM_RESET

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

Если значения входных параметров команды – NULL, то устройство складирует банкноты, при их наличии, и перезагружается.

Значения входных параметров:

  • usNumber:

    • 0 – оставить банкноты без перемещения;

    • 1 – переместить банкноты в кассету №1.

  • lpRetractArea – игнорируется.

  • fwOutputPosition – WFS_CIM_POSNULL (обнаруженные банкноты остаются в исходном состоянии).

Команда выполняет следующие аппаратные действия:

  • Перезагрузка модуля CCM.

  • По возможности производится сброс ошибок устройства.

Программные действия:

  • Генерация события WFS_SRVE_CIM_MEDIADETECTED (см. События).

  • Закрытие активной транзакции приема наличных (для версии CEN/XFS 3.10).

  • Закрытие активной сессии замены кассет (для версии CEN/XFS 3.10).

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

При складировании банкнот учет статистики реализуется следующим образом:

  1. Если транзакция приема наличных активна – как распознанные в количестве равном последним пересчитанным (аналогично команде WFS_CMD_CIM_CASH_IN_END).

  2. Если транзакция приема наличных не активна – как нераспознанные (с индексом 0) в количестве равном последним пересчитанным.

Коды ошибок:

  • WFS_ERR_SOFTWARE_ERROR – ошибка конфигурации драйвера.

  • WFS_ERR_CIM_EXCHANGEACTIVE – активна сессия замены кассет (для CEN/XFS 3.02 и ниже).

  • WFS_ERR_CIM_CASHINACTIVE – активна сессия приема наличных (для CEN/XFS 3.02 и ниже).

  • WFS_ERR_CIM_UNSUPPOSITION – неподдерживаемое значение поля fwOutputPosition.

  • WFS_ERR_CIM_INVALIDCASHUNIT – неподдерживаемое значение поля usNumber, возвращается в ответ на lpResetln: NULL.

  • WFS_ERR_HARDWARE_ERROR – аппаратная ошибка выполнения команды. Не удалось перезагрузить модуль CCM/складировать банкноты/актуализировать статус устройства.

  • WFS_ERR_CIM_CASHUNITERROR – ошибка при невозможности складировать во время операции сброса.

События

  • WFS_SRVE_CIM_ITEMSINSERTED – генерируется только для подающего кармана при выполнении команд приема наличных.

  • WFS_SRVE_CIM_ITEMSPRESENTED – генерируется для приемного кармана и кармана отбраковки.

  • WFS_SRVE_CIM_ITEMSTAKEN – генерируется для приемного кармана и кармана отбраковки в фоновом режиме.

Поддерживаются также события WFS_USRE_CIM_CASHUNITTHRESHOLD, WFS_SRVE_CIM_CASHUNITINFOCHANGED, WFS_SRVE_CIM_MEDIADETECTED, WFS_EXEE_CIM_INSERTITEMS, WFS_EXEE_CIM_INPUTREFUSE.