Skip to content

skokov3812/encrypted-smiley-secure-protocol

Repository files navigation

encrypted-smiley-secure-protocol

FOSSA Status

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('encrypted-smiley-secure-protocol')

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('encrypted-smiley-secure-protocol')

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.

License

FOSSA Status