Adapter - Sankyo Dispenser
This page describes version 2.0.2 of the adapter.
Overview
This adapter controls a Sankyo dispenser device using the Kiosk Router.
The card dispenser device is connected to a serial port on the Kiosk Client. The Serial2TCP Windows service must be configured to connect to the Kiosk Router and to communicate with the serial port the dispenser is connected to.
The settings for Serial2TCP SerialPort need to be set as follows: BaudRate: 115200 (highest available) Parity: even StopBits: 1
Supported Dispensers
The following dispenser models are supported:
- SCT0M0-0130
- SCT0M0-2161
The model of the device is specified in the adapter properties under "model".
- 0130 = the device is a SCT0M0-0130
- 2161 = the device is a SCT0M0-2161
Connection Information
The adapter connects to Kiosk Router using information specified in the adapter properties.
- The URL to the Kiosk Server such as https://kioskserver:8080.
- The Kiosk position name the device is connected to.
- The router token specified in Serial2TCP on the device.
- The client certificate and private key for the adapter to connect.
- This is available in Kiosk Admin under UIP Adapter Connection in Connection Settings.
The Kiosk position name and router token together make a unique key to match the adapter and Serial2TCP running on the client.
Properties
| Name | Display | Is Required | Comments | Type | Default Value | Maximum Value | Minimum Value | Maximum Length | Minimum Length |
|---|---|---|---|---|---|---|---|---|---|
| routerUrl | Kiosk Server URL | True | The URL to connect to the Kiosk Server (e.g https://address:8080). | string | 1024 | 1 | |||
| kioskPosition | Kiosk Position | True | The name of the kiosk position the device is on. | string | 128 | 1 | |||
| routerToken | routerToken | True | The token defined on the device side. | string | 128 | 1 | |||
| clientCertificate | clientCertificate | True | The adapter client certificate (PEM format). | string | |||||
| clientPrivateKey | clientPrivateKey | True | The private key for the adapter client certificate (PEM format). | string | |||||
| model | Sankyo Dispenser Model | False | 0130=Sankyo-0130, 2161=Sankyo-2161. The default is 2161 | string | 2161 | 4 | |||
| initOption | Dispenser Initialization Option | False | Sets state of the dispenser if a card is present while initializing. (0-Move to Gate, 1-Recycle Bin, 3-Do Nothing, 4-Same as 0 + Recycle Counter, 5-Same as 1 + Recycle Counter, 6-Same as 3 + Recycle Counter) (Default=3) | integer | 3 | 6 | 0 | ||
| initShutter | Perform Shutter Test | False | Dispenser performs open/close test of shutter during initialization if checked. Not performed if Dispenser Initialize Option is 3. | boolean | true | ||||
| externalEncoder | Use an external encoder | False | Use the non generic encoder if checked else use the generic encoder | boolean | false | ||||
| cardType | Card Type | False | Currently supported card types. (1-Mifare Classic 1K, 2- Mifare Ultralight C, 3-Mifare Classic 4K, 7-Generic Type A, 8-Generic Type B) Default is Mifare Classic 1K. | integer | 1 | 8 | 1 | ||
| masterKey | Master Authentication Key | False | Key used for authorizing card reading and writing functions. When using Mifare Classic Authentication the Master Key is only used for authenticating sectors 0-15. Upper sectors on 4k cards require the use of the manual Load Key command. | password | 32 | ||||
| keyOption | Use Master Key for Mifare Classic Authentication. | True | Controls whether the Master Key is used or loaded for Classic Authentication. 0-Never, 1-Use A, 2-Use B, 3-Load A, 4-Load B. To load: define Master Key, select load option=> save config,=>restart adapter, select use option => save config. | integer | 0 | 4 | 0 |
Commands
Accept Card With Timeout. (acceptWithTimeout)
Sets the dispenser to accept a card for specified amount of time.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| timeout | Timeout Timer | Sets the amount of time for the dispenser to wait and accept a card. (0-30) seconds. Defaults to 30 if left blank. | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| status | The current status result of the command. | string |
Mifare Classic Read or Write (classic)
Authenticates and reads or writes data to a Mifare Classic card. If card data exceeds 16 bytes it will attempt to write to the following blocks of that sector.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| sector | Sector | The sector on the card to write the data to. Acceptable values are 0-15. | True | string |
| blocks | Block(s) | Acceptable values are 0-3. When writing card data, if the data is more than 16 bytes additional data will be written to blocks succeeding the block specified. If reading a sector, multiple blocks can be listed separated by commas. | True | string |
| keyType | Key Type | Identifies one of 2 keys assignable to a sector. Possible values are 0 and 1. 0=key A, 1=key B. Blank attempts to use Master Key from adapter configuration and will only be successful if the key option was loaded per helptext and currently set to Use. | False | string |
| cardData | Card Data | The hexadecimal string of data to write to the specified sector of the card. Limited to 128 characters(sector Max) if starting with block 0. If left blank, a read is performed on the specified blocks. | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| commStatus | The status returned from the Communication Board. | string |
| status | The current status result of the command. | string |
| cardData | The hexadecimal string of data returned from the card during a read. | string |
Deactivate Card (deactivateCard)
Signals the Contactless Communication Board to deactivate the card by cutting off the carrier.
Response Properties
| Name | Description | Type |
|---|---|---|
| status | The current status result of the command. | string |
Disable Accept (disableGate)
Disables the exit slot from accepting cards.
Response Properties
| Name | Description | Type |
|---|---|---|
| status | Status result of the command. | string |
Enable Accept (enableGate)
Enables the exit slot to accept a card until it is disabled, or the Move Card From Hopper command is used. When card is inserted into exit slot, the card is automatically moved to the communications board.
Response Properties
| Name | Description | Type |
|---|---|---|
| status | Status result of the command. | string |
From Hopper to Encoder (fromHopper)
Moves a card from the hopper to the communications board. Disables Accept Enabled if Accept Enabled is set.
Response Properties
| Name | Description | Type |
|---|---|---|
| status | Status result of the command. | string |
Monitor Gate (gateMonitor)
Monitors the gate for card removal when a card is presented.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| timer | Timeout Timer | The amount of time to wait for the card to be removed. (1-30) seconds. Left blank assumes 30 seconds. | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| status | The current status result of the command. | string |
Read CCB Software Version (getCCBSoftwareVersion)
Returns the program number and software version information for the contactless communication board.
Response Properties
| Name | Description | Type |
|---|---|---|
| programNumber | The program number assigned to the software installed on the contactless communication board. | string |
| version | The version of software installed on the contactless communication board. | string |
| status | The current status result of the command. | string |
Read Dispenser Software Version (getDispenserSoftwareVersion)
Returns the program number and software version information for the dispenser.
Response Properties
| Name | Description | Type |
|---|---|---|
| programNumber | The program number assigned to the software installed on the dispenser. | string |
| version | The version of software installed on the dispenser. | string |
| status | The current status result of the command. | string |
Get Status (getStatus)
Gets the current status of the dispenser device.
Response Properties
| Name | Description | Type |
|---|---|---|
| status | Status result of the command. | string |
| cardHopperLow | The card hopper is low on cards. | string |
| cardHopperEmpty | The card hopper does not have any cards left. Please, add more cards. | string |
| cardAtGate | The card is present at the exit slot and is ready for the user to take. | string |
| cardAtCCB | There is a card on the Contactless Communication Board. | string |
| rejectStackerHasCards | The reject-stacker contains cards. | string |
Get Serial Number (getUID)
Signals the Contactless Communication Board to activate the card within and return the UID gathered from the card.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| timer | Timeout Timer | The number of milliseconds the Contactless Communication Board repeatedly attempts to activate the card. (000-999). Default = 100. | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| cardType | The type of card detected during activation. | string |
| cardTypeId | The type ID of the cards currently used in the dispenser determined by the Card Type setting in the property settings of the adapter. | string |
| uid | The unique identifier of the card detected during activation. | string |
| status | The current status result of the command. | string |
Hospitality Encode Card (hospitalityEncode)
Command used to encode cards using data provided by the hospitality door lock systems.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| lockSystem | Lock System | Indicate the lock system used by the hospitality site. (1-3) 1-AssaAbloy, 2-Salto, 3-Dormakaba. | True | string |
| cardData | Card Data | Card data provided by the Lock System for writing to the card. | True | string |
| authKey | Authorization Key | The string representation of a hexadecimal value of the key used to password protect sectors. Does not apply to the Dormakaba Lock System. | False | string |
| keyType | Authorization Key Type | Key Type to use for the Authorization Key. Possible values are 0 and 1. 0=key A, 1=key B. Left blank will attempt to use Door Lock default. | False | string |
| transportKey | Transport Key | The Key value the system will attempt to use for a card that has never been used by the lock system. If left blank, the value 'FFFFFFFFFFFF' will be used. | False | string |
| transportKeyType | Transport Key Type | Key Type to use for the Transport Key. Possible values are 0 and 1. 0=key A, 1=key B. Left blank will default to 0. | False | string |
| sectors | Sectors | The sectors on the card to write the data to. In the case of the Salto Lock System if more than one sector is used, separate the specified sectors with a comma. | False | string |
| block | Block | The starting block of the sector to write hospitality data to. Acceptable values are 0-3. Left blank assumes 0. | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| commStatus | The status returned from the Communication Board. | string |
| status | The current status result of the command. | string |
Initialize Ultralight C Card (initializeUltra)
Command used to initialize new Ultralight C cards or change the existing key. Command requires adapter configuration card type to be set to Ultralight C.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| page | Start Page | The first page on the card to require authentication after the key is updated. All subsequent pages are also password protected. Acceptable values (3-30). Default = 3. | False | string |
| oldKey | Existing Key | A 32 character hexidecimal string that is the currently the key used by the card. The value is: 49454D4B41455242214E4143554F5946 when shipped from factory. | True | string |
| newKey | New Key | The desired 32 character hexidecimal string to use as the authentication key for the card. | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| commStatus | The status returned from the Communication Board. | string |
| status | The current status result of the command. | string |
Load Keys (loadKey)
Stores keys in the non-volatile memory of the Contactless Communication Board to use with Mifare Classic authentication. Changes made by this command will be overwritten if a Master Key is defined and the adapter is restarted.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| keyType | Key Type | Identifies one of 2 key types assignable to a sector. Possible values are 0 and 1. 0 = key type A and 1= key type B. | True | string |
| authKey | Authorization Key | The string representation of the 6 byte hexadecimal value of the authorization key to store on the assigned sector of the Contactless Communication Board. | True | string |
| sectors | Sector(s) | The sector or sectors that will use the Key Value for authentication. Multiple sectors listed must be separated by commas. Acceptable values are 0-15. Leaving blank will load the Key Value for sectors 0-15. | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| commStatus | The status returned from the Communication Board. | string |
| status | The current status result of the command. | string |
Eject To Gate (move2Gate)
Moves card from communication board to the exit gate slot.
Response Properties
| Name | Description | Type |
|---|---|---|
| status | Status result of the command. | string |
Capture To Recycle Bin (move2Recycle)
Moves a card from the communications board to the recycle bin.
Response Properties
| Name | Description | Type |
|---|---|---|
| status | Status result of the command. | string |
Read Recycled Card Count (recycleCountGet)
Returns the recycled card count value. Only applicable when appropriate initialization option is set.
Response Properties
| Name | Description | Type |
|---|---|---|
| count | The card recycle count value. | string |
| status | The current status result of the command. | string |
Set Recycled Card Count (recycleCountSet)
Sets the recycled card count to a value. Only applicable when appropriate initialization option is set.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| count | Recycle Count | Sets the value of card-recycling counter. (0-99) Left blank assumes 0. | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| status | The current status result of the command. | string |
Reset Card (resetCard)
Resets the Contactless IC card.
Response Properties
| Name | Description | Type |
|---|---|---|
| status | The current status result of the command. | string |
Retrieve Card (retrieveCard)
Retrieves card left at the gate to the communications board.
Response Properties
| Name | Description | Type |
|---|---|---|
| status | Status result of the command. | string |
Mifare Transfer (transfer)
Increments or decrements the source block value by the change value and transfers the value to the destination block and sector.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| change | Increment or Decrement | Increment or decrement during the transfer. 0 - Increment, 1 - Decrement. | True | string |
| sourceSector | Source Sector | The sector where the data currently resides. Acceptable values are 0-15. | True | string |
| sourceBlock | Source Block | The block where the data currently resides. Acceptable values are 0-3. | True | string |
| destinationSector | Destination Sector | The sector to which the data will transfered. Acceptable values are 0-15. | True | string |
| destinationBlock | Destination Block | The block to which the data will be transferred . Acceptable values are 0-3. | True | string |
| changeValue | Change Value | The hexadecimal string representation of the 4 bytes to decrement or increment the source value. | True | string |
| keyType | Key Type | Identifies one of 2 keys assignable to a sector. Possible values are 0 and 1. 0=key A, 1=key B. Blank attempts to use Master Key from adapter configuration and will only be successful if the key option was loaded per helptext and currently set to Use. | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| commStatus | The status returned from the Communication Board. | string |
| status | The current status result of the command. | string |
Card Type AB Communication (typeABCommunication)
Used to send and recieve data from ISO/IEC14443 part 4 protocol Type A and B RFID cards.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| data | C-APDU Data | The ISO/IEC14443 part 4 protocol APDU data to be written to the card. | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| data | The ISO/IEC14443 part 4 protocol APDU data returned from the card. | string |
| status | The current status result of the command. | string |
Ultralight C Read or Write (ultralight)
Command used to read and write to ultralight cards.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| page | Start Page | The page used to start reading or writing data to the Ultralight card. Acceptable write pages (0-47). Acceptable read pages (0-43). | True | string |
| data | Card Data | The hexidecimal string of data to be written to the card. Card read is assumed if left blank. | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| commStatus | The status returned from the Communication Board. | string |
| data | The data returned from the card read. Returns 4 pages of data (16 bytes) including the start page. | string |
| status | The current status result of the command. | string |
Events
Connected (connectedEvent)
The connection to the dispenser device has been established.
No properties defined
Card Holding Event (cardHoldingEvent)
A card is at the exit slot's holding position.
No properties defined
Card Removed Event (cardRemovedEvent)
A card was removed from the exit slot's holding position.
No properties defined
Card At the CCB Event (cardReadyEvent)
A card is at the CCB and is ready to read.
No properties defined
Hopper Low Event (stackerLowEvent)
The card hopper level is low.
No properties defined
Hopper Empty Event (stackerEmptyEvent)
The card hopper is empty.
No properties defined
Communications Board Initialized (communicationsBoardInitializedEvent)
The Contactless Communications Board was successfully initialized.
No properties defined
Malfunction Event (malfunctionEvent)
The dispenser device has a mechanical issue or a card is jammed.
Event Properties
| Name | Display | Description | Type |
|---|---|---|---|
| errCode | Error Code | The error code returned by the dispenser device. | string |
| errDetail | Error Detail | The detailed error information. | string |
Release History
| Version | Type | Description | Tracking # | Date |
|---|---|---|---|---|
| 2.0.1 | Initial | First release in the Adapter Type store. | NAP-22853 | 2023-07-31 |
| 2.0.2 | Feature | Added support for model 2161 | NAP-27492 | 2024-03-29 |