@toopago/essp

eSSP

Node.JS library Encrypted Smiley ® Secure Protocol (eSSP, SSP)

Supported devices: NV9USB, NV10USB, BV20, BV50, BV100, NV200, SMART Hopper, SMART Payout, NV11

const sspLib = require('@toopago/essp');

let eSSP = new sspLib({
    id: 0x00,
    debug: false,
    timeout: 3000,
    fixedKey: '0123456701234567'
});

Methods

All methods use Promise

• eSSP.open('COM1') - Connect device
• eSSP.close() - Disconnect device
• eSSP.initEncryption() - Initializing Diffie-Hellman key exchange and enable encryption
• eSSP.enable() - Enable device and start listen events
• eSSP.disable() - Disable device and stop listen events
• eSSP.command('COMMAND_NAME') - Execute command and get answer

Command

eSSP.command('GET_SERIAL_NUMBER')
.then(result => {
    console.log('Serial number:', result.info.serial_number)
    return;
})

See all supported commands

Event

eSSP.on('READ_NOTE', result => {
    console.log(result)
})

See all supported events

Example

const sspLib = require('@toopago/essp');

let eSSP = new sspLib({
    id: 0,
    debug: false,
    timeout: 3000,
    fixedKey: '0123456701234567'
});

eSSP.on('OPEN', () => {
    console.log('open');

    eSSP.command('SYNC')
    .then(() => eSSP.command('HOST_PROTOCOL_VERSION', { version: 6 }))
    .then(() => eSSP.initEncryption())
    .then(() => eSSP.command('GET_SERIAL_NUMBER'))
    .then(result => {
        console.log('SERIAL NUMBER:', result.info.serial_number)
        return;
    })
    .then(() => eSSP.enable())
    .then(result => {
        if(result.status == 'OK'){
            console.log('Device is active')
        }
		return;
    })
})

eSSP.on('NOTE_REJECTED', result => {
    console.log('NOTE_REJECTED', result);

    eSSP.command('LAST_REJECT_CODE')
    .then(result => {
        console.log(result)
    })
})

eSSP.open('COM1');

Supported Commands:

Command name	Option Required	Encryption Required	Description
RESET		optional	Command to instruct the slave to perform a hard reset at any point within its operational status.
SET_CHANNEL_INHIBITS	yes	optional	Variable length command, used to control which channels are enabled.
DISPLAY_ON		optional	Use this command to re-enabled a disabled bezel illumination function (using the Display Off command).
DISPLAY_OFF		optional	This command will force the device bezel to not be illuminated even if the device is enabled.
SETUP_REQUEST		optional	The device responds with an array of data the format of which depends upon the device, the dataset installed and the protocol version set.
HOST_PROTOCOL_VERSION	yes	optional	Set version of the protocol that is implemented on the host
POLL		optional	The poll command returns the list of events that have occurred within the device since the last poll.
REJECT_BANKNOTE		optional	A command to reject a note held in escrow in the banknote validator.
DISABLE		optional	The peripheral will switch to its disabled state, it will not execute any more commands or perform any actions until enabled, any poll commands will report disabled.
ENABLE		optional	Send this command to enable a disabled device.
GET_SERIAL_NUMBER		optional	This command returns the unique factory programmed serial number of the device.
UNIT_DATA		optional	Returns: Unit type, Firmware Version, Country Code, Value Multiplier, Protocol Version.
CHANNEL_VALUE_REQUEST		optional	Returns channel value data for a banknote validator.
CHANNEL_SECURITY_DATA		optional	The command returns the security settings of the channels
CHANNEL_RE_TEACH_DATA		optional	This is a vestigial command and may be deprecated in future versions.
SYNC		optional	A command to establish communications with a slave device.
LAST_REJECT_CODE		optional	Returns a single byte that indicates the reason for the last banknote reject.
HOLD		optional	This command may be sent to BNV when Note Read has changed from 0 to >0 (valid note seen) if the user does not wish to accept the note with the next command. This command will also reset the 10-second time-out period after which a note held would be rejected automatically, so it should be sent before this time-out if an escrow function is required.
GET_FIRMWARE_VERSION		optional	Returns the firmware version
GET_DATASET_VERSION		optional	Returns the dataset version of the device.
GET_ALL_LEVELS		optional	Use this command to return all the stored levels of denominations in the device (including those at zero level).
GET_BAR_CODE_READER_CONFIGURATION		optional	Returns the set-up data for the device bar code readers.
SET_BAR_CODE_CONFIGURATION	yes	optional	This command allows the host to set-up the bar code reader(s) configuration on the device. Possible value: enable[none/top/bottom/both] numChar[min:6 max:24]
GET_BAR_CODE_INHIBIT_STATUS		optional	Command to return the current bar code/currency inhibit status.
SET_BAR_CODE_INHIBIT_STATUS	yes	optional	Sets up the bar code inhibit status register.
GET_BAR_CODE_DATA		optional	Command to obtain last valid bar code ticket data, send in response to a Bar Code Ticket Validated event.
SET_REFILL_MODE	yes	optional	A command sequence to set or reset the facility for the payout to reject notes that are routed to the payout store but the firmware determines that they are un-suitable for storage.
PAYOUT_AMOUNT	yes	yes	A command to set the monetary value to be paid by the payout unit.
SET_DENOMINATION_LEVEL	yes	optional	A command to increment the level of coins of a denomination stored in the hopper.
GET_DENOMINATION_LEVEL	yes	optional	This command returns the level of a denomination stored in a payout device.
COMMUNICATION_PASS_THROUGH		optional	Used with SMART Hopper only. This command sets USB pass through mode.
HALT_PAYOUT		yes	A command to stop the execution of an existing payout.
SET_DENOMINATION_ROUTE	yes	optional	This command will configure the denomination to be either routed to the cashbox on detection or stored to be made available for later possible payout. Possible value: route[payout/cashbox]
GET_DENOMINATION_ROUTE		yes	This command allows the host to determine the route of a denomination.
FLOAT_AMOUNT	yes	optional	A command to float the hopper unit to leave a requested value of money, with a requested minimum possible payout level. All monies not required to meet float value are routed to cashbox.
GET_MINIMUM_PAYOUT		yes	A command to request the minimum possible payout amount that this device can provide
EMPTY_ALL		yes	This command will direct all stored monies to the cash box without reporting any value and reset all the stored counters to zero.
SET_COIN_MECH_INHIBITS	yes	optional	This command is used to enable or disable acceptance of individual coin values from a coin acceptor connected to the hopper.
GET_NOTE_POSITIONS		optional	This command will return the number of notes in the Note Float and the value in each position.
PAYOUT_NOTE		optional	The Note Float will payout the last note that was stored.
STACK_NOTE		optional	The Note Float will stack the last note that was stored.
FLOAT_BY_DENOMINATION	yes	yes	A command to float (leave in device) the requested quantity of individual denominations.
SET_VALUE_REPORTING_TYPE	yes	optional	This will set the method of reporting values of notes.
PAYOUT_BY_DENOMINATION	yes	yes	A command to payout the requested quantity of individual denominations.
SET_COIN_MECH_GLOBAL_INHIBIT	yes	optional	This command allows the host to enable/disable the attached coin mech in one command rather than by each individual value with previous firmware versions.
SET_BAUD_RATE	yes	optional	Set the communication speed with the device.
GET_BUILD_REVISION		optional	A command to return the build revision information of a device.
SET_HOPPER_OPTIONS	yes	optional	The host can set the following options for the SMART Hopper.
GET_HOPPER_OPTIONS		optional	This command returns option described in SET_HOPPER_OPTIONS command.
SMART_EMPTY		yes	Empties payout device of contents, maintaining a count of value emptied.
CASHBOX_PAYOUT_OPERATION_DATA		optional	Can be sent at the end of a SMART Empty, float or dispense operation.
CONFIGURE_BEZEL	yes	optional	This command allows the host to configure a supported BNV bezel.
POLL_WITH_ACK		yes	A command that behaves in the same way as the POLL command but with this command, the specified events (see table below) will need to be acknowledged by the host using the EVENT_ACK command. The events will repeat until the EVENT_ACK command is sent and the BNV will not allow any further note actions until the event has been cleared by the EVENT_ACK command.
EVENT_ACK		yes	This command will clear a repeating Poll ACK response and allow further note operations.
GET_COUNTERS		optional	A command to return a global note activity counter set for the slave device.
RESET_COUNTERS		optional	Resets the note activity counters described in Get Counters command to all zero values.
COIN_MECH_OPTIONS	yes	optional	The host can set the following options for the SMART Hopper.
DISABLE_PAYOUT_DEVICE		optional	All accepted notes will be routed to the stacker and payout commands will not be accepted.
ENABLE_PAYOUT_DEVICE	yes	optional	A command to enable the attached payout device for storing/paying out notes.
SET_FIXED_ENCRYPTION_KEY	yes	yes	A command to allow the host to change the fixed part of the eSSP key.
RESET_FIXED_ENCRYPTION_KEY		optional	Resets the fixed encryption key to the device default.

Example commands with options:

SET_CHANNEL_INHIBITS

eSSP.command('SET_CHANNEL_INHIBITS', {
    channels: [1,1,1,0,0,0,0,0] // channel 1-3 enable
})

HOST_PROTOCOL_VERSION

eSSP.command('HOST_PROTOCOL_VERSION', {
    version: 6
})

SET_BAR_CODE_CONFIGURATION

eSSP.command('SET_BAR_CODE_CONFIGURATION', {
    enable: 'top',    // none|top|bottom|both
    numChar: 6        // min:6  max:24
})

SET_BAR_CODE_INHIBIT_STATUS

eSSP.command('SET_BAR_CODE_INHIBIT_STATUS', {
    currencyRead: true,
    barCode: true
})

SET_REFILL_MODE

eSSP.command('SET_REFILL_MODE', {
    mode: 'on' // on|off|get
})

PAYOUT_AMOUNT

eSSP.command('PAYOUT_AMOUNT', {
    amount: 10000,
    country_code: 'RUB',
    test: false
})

SET_DENOMINATION_LEVEL

eSSP.command('SET_DENOMINATION_LEVEL', {
    value: 1,
    denomination: 10000,
    country_code: 'RUB'
})

GET_DENOMINATION_LEVEL

eSSP.command('GET_DENOMINATION_LEVEL', {
    amount: 100,
    country_code: 'RUB'
})

SET_DENOMINATION_ROUTE

eSSP.command('SET_DENOMINATION_ROUTE', {
    route: 'payout', // payout|cashbox
    value: 10000,
    country_code: 'RUB'
})

GET_DENOMINATION_ROUTE

eSSP.command('GET_DENOMINATION_ROUTE', {
    isHopper: false, // true/false
    value: 10000,
    country_code: 'RUB'
})

FLOAT_AMOUNT

eSSP.command('FLOAT_AMOUNT', {
    min_possible_payout: 1000,
    amount: 10000,
    country_code: 'RUB',
    test: false
})

SET_COIN_MECH_INHIBITS

eSSP.command('SET_COIN_MECH_INHIBITS', {
    amount: 100,
    inhibited: true
})

FLOAT_BY_DENOMINATION

eSSP.command('FLOAT_BY_DENOMINATION', {
    value: [
        {
            number: 1,
            denomination: 10000,
            country_code: 'RUB'
        }, {
            number: 1,
            denomination: 50000,
            country_code: 'RUB'
        }
    ],
    test: false
})

SET_VALUE_REPORTING_TYPE

eSSP.command('SET_VALUE_REPORTING_TYPE', {
    reportBy: 'channel' // value|channel
})

PAYOUT_BY_DENOMINATION

eSSP.command('PAYOUT_BY_DENOMINATION', {
    value: [
        {
            number: 1,
            denomination: 10000,
            country_code: 'RUB'
        }, {
            number: 1,
            denomination: 50000,
            country_code: 'RUB'
        }
    ],
    test: false
})

SET_COIN_MECH_GLOBAL_INHIBIT

eSSP.command('SET_COIN_MECH_GLOBAL_INHIBIT', {
    enable: true
})

SET_BAUD_RATE

eSSP.command('SET_BAUD_RATE', {
    baudrate: 9600, // 9600|38400|115200
    reset_to_default_on_reset: true
})

SET_HOPPER_OPTIONS

eSSP.command('SET_HOPPER_OPTIONS', {
    payMode: true,
    levelCheck: true,
    motorSpeed: true,
    cashBoxPayAcive: true
})

CONFIGURE_BEZEL

eSSP.command('CONFIGURE_BEZEL', {
    RGB: '0000ff', // RGB in hex
    volatile: true
})

COIN_MECH_OPTIONS

eSSP.command('COIN_MECH_OPTIONS', {
    ccTalk: false
})

ENABLE_PAYOUT_DEVICE

// for Payout
eSSP.command('ENABLE_PAYOUT_DEVICE', {
    REQUIRE_FULL_STARTUP: true,
    OPTIMISE_FOR_PAYIN_SPEED: true
})

// for NV11
eSSP.command('ENABLE_PAYOUT_DEVICE', {
    GIVE_VALUE_ON_STORED: true,
    NO_HOLD_NOTE_ON_PAYOUT: true
})

SET_FIXED_ENCRYPTION_KEY

eSSP.command('SET_FIXED_ENCRYPTION_KEY', {
    fixedKey: '0000000000000000'
})

Supported Events:

Event name	Description
OPEN	Port open
CLOSE	Port close
READ_NOTE	A note is in the process of being scanned by the device (channel 0) or a valid note has been scanned and is in escrow (channel N)
CREDIT_NOTE	A note has passed through the device, past the point of possible recovery and the host can safely issue its credit amount.
NOTE_REJECTING	The note is in the process of being rejected from the validator.
NOTE_REJECTED	The note has been rejected from the validator and is available for the user to retrieve.
NOTE_STACKED	The note has exited the device on the host side or has been placed within its note stacker.
SAFE_NOTE_JAM	The note is stuck in a position not retrievable from the front of the device (user side).
UNSAFE_NOTE_JAM	The note is stuck in a position where the user could possibly remove it from the front of the device.
DISABLED	The device is not active and unavailable for normal validation functions.
STACKER_FULL	The banknote stacker unit attached to this device has been detected as at its full limit
FRAUD_ATTEMPT	The device has detected an attempt to tamper with the normal validation/stacking/payout process.
BAR_CODE_TICKET_VALIDATED	A validated barcode ticket has been scanned and is available at the escrow point of the device.
CASHBOX_REPLACED	A device with a detectable cashbox has detected that it has been replaced.
CASHBOX_REMOVED	A device with a detectable cashbox has detected that it has been removed.
NOTE_CLEARED_TO_CASHBOX	At power up, a note was detected as being moved into the stacker unit or host exit of the device.
NOTE_CLEARED_FROM_FRONT	At power-up, a note was detected as being rejected out of the front of the device.
NOTE_PATH_OPEN	The device has detected that its note transport path has been opened.
COIN_CREDIT	A coin has been detected as added to the system via the attached coin mechanism.
CASHBOX_PAID	This is given at the end of a payout cycle.
INCOMPLETE_FLOAT	The device has detected a discrepancy on power-up that the last float request was interrupted (possibly due to a power failure).
INCOMPLETE_PAYOUT	The device has detected a discrepancy on power-up that the last payout request was interrupted (possibly due to a power failure).
NOTE_STORED_IN_PAYOUT	The note has been passed into the note store of the payout unit.
DISPENSING	The device is in the process of paying out a requested value.
TIME_OUT	The device has been unable to complete a request.
FLOATED	The device has completed its float command and the final value floated to the cashbox is given in the event data.
FLOATING	The device is in the process of executing a float command and the value paid to the cashbox at the poll time is given in the event data.
HALTED	This event is given when the host has requested a halt to the device.
JAMMED	The device has detected that coins are jammed in its mechanism and cannot be removed other than by manual intervention.
DISPENSED	The device has completed its pay-out request.
BAR_CODE_TICKET_ACKNOWLEDGE	The bar code ticket has been passed to a safe point in the device stacker.
NOTE_HELD_IN_BEZEL	Reported when a dispensing note is held in the bezel of the payout device.
NOTE_DISPENSED_AT_POWER-UP	Reported when a note has been dispensed as part of the power-up procedure.
NOTE_STACKING	The note is being moved from the escrow position to the host exit section of the device.
NOTE_PAID_INTO_STORE_AT_POWER-UP	Reported when a note has been detected as paid into the payout store as part of the power-up procedure.
NOTE_PAID_INTO_STACKER_AT_POWER-UP	Reported when a note has been detected as paid into the cashbox stacker as part of the power-up procedure.
NOTE_TRANSFERED_TO_STACKER	Reported when a note has been successfully moved from the payout store into the stacker cashbox.
NOTE_FLOAT_ATTACHED	Reported when a note float unit has been detected as removed from its validator.
NOTE_FLOAT_REMOVED	Reported when a note float unit has been detected as removed from its validator.
PAYOUT_OUT_OF_SERVICE	This event is given if the payout goes out of service during operation.
COIN_MECH_RETURN_PRESSED	The attached coin mechanism has been detected as having is reject or return button pressed.
COIN_MECH_JAMMED	The attached coin mechanism has been detected as having a jam.
EMPTIED	The device has completed its Empty process in response to an Empty command from the host.
EMPTYING	The device is in the process of emptying its content to the system cashbox in response to an Empty command.
COIN_MECH_ERROR	The attached coin mechanism has generated an error.
INITIALISING	This event is given only when using the Poll with ACK command.
CHANNEL_DISABLE	The device has had all its note channels inhibited and has become disabled for note insertion.
SMART_EMPTIED	The device has completed its Smart Empty command.
SMART_EMPTYING	The device is in the process of carrying out its Smart Empty command from the host.
ERROR_DURING_PAYOUT	Returned if an error is detected whilst moving a note inside the SMART Payout unit.
JAM_RECOVERY	The SMART Payout unit is in the process of recovering from a detected jam.