Setup of Self-Service Kiosk

Introduction

Self-Service Kiosk or r_keeper_SelfServiceTerminal_7 is a system enabling the customer to independently select dishes and pay for the order using a bank card. It can also be called a kiosk, a self-service terminal, and a self-service cash register.

System Requirements

To ensure that the r_keeper_SelfServiceTerminal_7 operates properly you need the following components:

• OS: MS Windows Server 2008 or later, or MS Windows Vista/7/8/8.1/10 Professional
• r_keeper version 7.5.4.218 or later

Block Diagram of r_keeper_SelfServiceTerminal_7

Distribution Package

This product is available at FTP: ftp://ftp.ucs.ru/rk7/INSTALL/RK7_Kiosk/

Licensing

r_keeper_SelfServiceTerminal_7 demands a license starting  with version 1.0.1.6 . There are two types of licenses for this product:

• License supporting the order payment function

• License not supporting the order payment function.

The license will be linked to a virtual key generated by r_keeper 7 cash server which is to be licensed for at least zero stations.

License Verification Mechanism:

• While working, SelfOrderService.exe requests the license from the l.ucs.ru license server from time to time
• If the license response for this computer is correct, the computer continues operating
• If the license response is incorrect, i.e. no license is found, an error message is displayed and the kiosk remains in such a state until a valid license is obtained.

The LicReq.exe app is used to generate a license request code. The app is launched from the SelfOrderService.exe working directory.

To generate a request code, take the following steps:

• Launch the r_keeper 7 cash server that will be operating with the Kiosk

• Set up the cash server connection in the SelfOrderService.ini configuration file. It is enough to fill in the CashServer parameter in the [XMLIntf] section.

  [XMLIntf]
  ; the cash server's XML interface address.
  CashServer=127.0.0.1:8787

• Launch the LicReq.exe app.
  If there is no connection with the cash server, the app will generate an error message: Restaurant Code Unidentified.

• If the cash server connection is successful, the app will show a request to enter the dealer ID and password

• Enter the current dealer ID and password and click Login. After this the app's main window will open

• To generate a license request, select the used key — physical or virtual — and click Generate license request. A generated license request will appear in the Request field

• Save the generated request and perform the standard licensing procedure using the l.ucs.ru license server.
• If you need to delete the virtual key which is used to generate the request, click Delete key.

Manager Station Settings

XML Interface

To ensure the interaction between the Kiosk and r_keeper 7 cash server, you need to add and configure the XML interface:

1. Go to Service > Stations and Devices select the cash server or create a new one
2. Add the XML Interface for Windows in the cash server properties in the Drivers tab
3. Specify the Port parameter in the attributes of the added XML interface in the Options section — the value of this parameter will be used for Kiosk server setup
   
4. Then, link the added interface to the logical one. To do so, go to Service > Interfaces and create a copy of the existing XML interface. The interface should use ITcpXML.dll. Open the Library Files section, select the cash server, and add the previously created XML interface
   
5. Reboot the cash server

Starting version 0.7.0, an r_keeper_SelfServiceTerminal_7 (RKeeperKiosk.exe) client interacts with the cash server directly using the HTTP protocol. Take the following steps to set up the protocol:

1. In Service > Manager Station > Object Privileges, create a new rule for the HTTP Access object
2. In Service > Stations and Devices, select the cash server used for linking with the Kiosk
3. Set the previously created HTTP Access privilege for all parameters in the cash server properties in the HTTP Rights section
4. Set up the HTTP connection parameters in the cash server properties in the HTTP Server section, where:
   • HTTP Bind Address — the network interface's IP address for binding the HTTP protocol. If you leave it blank, it will listen using all available interfaces
   • Use Free Listen Port — disable the option
   • HTTP Data Port — the HTTP protocol's binding port. It is also specified in the \app\settings.xml.
     
5. In Personnel > Employees, select or create an employee, for example, Kiosk, for the XML-Editing role to use in the kiosk connection settings and specify the employee's password
6. In the role properties of this employee, in the Manager Restrictions section, open the Object Privileges parameter and choose the previously created HTTP Access privilege
   

7. Specify the <user>...</user> и <password>...</password> parameters in the \App\settings.xml kiosk client configuration file in the <xmlinterface>...<xmlinterface> section:

   <xmlinterface>
   <host>127.0.0.1</host>
   <port>5252</port>
   <user>HTTPUSER</user>
   <password>1</password>

Equipment Support

The kiosk's hardware is supported only by r_keeper 7 cash register and/or third-party bank card authorization software — none of the kiosk's modules needs to directly interact with the peripheral equipment.

You need to add a new printing station before setting up the equipment:

1. In the Service > Stations and Devices reference, select a restaurant and a previously created cash server
2. Add a new station of the Printing Station type
3. In the Main section of the station properties, pay attention to the Identifier parameter value. This value will be used to set up the Kiosk server.

To set up the equipment, take the following steps:

1. In the Service > Stations and Devices reference, select a previously created station
2. On the Drivers tab, add the fiscal data recorder connection interface. As a rule, it is a COM port
3. Add and set up the fiscal data recorder's driver, for example, SPARK
4. Add and set up the bank card authorization driver.

Order without Payment Mode

Since SelfOrderService version 1.0.1.12 and RKeeperKiosk version 0.0.3.14, there is a new operation mode — order without payment (Type = 3).

This mode requires another license, see the Licensing section.

The operation principle is similar to the end of the queue technology (ordering from the queue). In the order without payment mode, after saving the order the kiosk forms files in a special XML format to be further processed by the r_keeper 7 cash server.

This mode allows running the kiosk on any computer without using any specialized equipment, such as a fiscal register, PIN pad, card reader, etc.

If the order without payment mode is used, add the Mobile Fast Food Interface to the cash server to enable order processing:

1. Select the server in the Service > Stations and Devices reference
2. Add the Mobile Food Interface in the Drivers tab in the cash server properties
3. In the Options section of the interface properties, specify the DirName parameter which is the path to the directory storing saved kiosk orders
4. Set up the MCR algorithm according to the order number mask for the file to be found at the cash register
5. Add a new printer purpose, for example, Self-Service Kiosk, in Options > Printing > Printer Purpose
6. Pay attention to the Identifier parameter for the new printer purpose as you will need it to configure the PrinterPurposeIdent parameter in the kiosk server's configuration file
7. On the Printers tab of the cash station used for the kiosk, add a new printer with the parameters matching those set in the kiosk
8. Specify the newly added printer for the previously created new printer purpose in the Printer Purpose section of the restaurant properties

9. Enter and configure the Type, OrderQueueAddress, PrinterPurposeIdent, and OrderNumAsCode parameters in the SelfOrderService.ini configuration file.

   The value of the DirName parameter should be coordinated with the OrderQueueAddress parameter value in SelfOrderService.ini, the kiosk server's configuration file.

10. If necessary, fill in the LogName parameter of the interface properties, for example, for debugging or information collection purposes.

Operation Mode 4 — Order without Payment with Entrance Card Technology

This mode operates based on the license without order payment function.
The working principle is the same as for Order without Payment but with the use of Entrance Card technology.
When entering, the guest gets an identification card which can be used to make several orders on different self-service kiosk terminals, for example, at the restaurant, the play area, or the cinema. When leaving, the visitor goes to the cash desk and pays for all the orders with a single payment.
You need to edit SelfOrderService.ini to set up this operation mode.

[XMLIntf]
TwoStepsAuth = 0 — do not use two step authorization

[Settings]
Type = 4 — kiosk operation mode Oder without Payment with Entrance Card technology

Operation Mode 5 — Pay with a Card or at a Cash Desk

This mode operates based on the license supporting the order payment function.

The settings for this operation mode match those for the Pay and Print Using r_keeper Station and Order without Payment.

Settings in SelfOrderService.ini

Type = 5 — Pay with a Card or at Cash Desk operation mode.

When the order is saved at the kiosk and is later paid for at the cash desk it is recommended to use two cash servers — a kiosk at one cash server and a cash register on the other cash server, otherwise, the order could get doubled at the VDU.
Settings:

• To view orders in the XML format, create the mobileff folder in the bin/win directory and specify its path in the .ini.

OrderQueueAddress=\\PC-QA-10\mobileff — address for sending the orders in the Order without payment mode.

• If SelfOrderService.ini is used for the settings

[VDU] sectionUseVDUSpecialUnitNum=1

This parameter is needed to ensure that the kiosk order does not get doubled in VDU after payment at the cash desk.

[Settings] Section
Type3NumLength=4

The length of the order number, printed on the slip. The order number on the slip is used to pay for the order at the cash desk.

• If Settings.xml is used for the settings

<vdu>
UseVDUSpecialUnitNum>true</UseVDUSpecialUnitNum>
</vdu>
To ensure that the order does not get doubled in VDU after the payment at the cash desk.

<cashPay>
<orderNumLength>4</orderNumLength>
</cashPay>
The length of the order number printed in the slip. The order number on the slip is used to pay for the order at the cash desk.

• If several cash desks are used, make the following settings to avoid the order numbers overlapping when several orders are generated at several kiosks:

The order number should have four digits:

Settings in SelfOrderService.ini:

[Settings]
Type3NumLength=3
OrderPrefix=1
Settings in Settings.xml:

<server>
<cashPay>
<orderNumLength>3</orderNumLength>
<orderPrefix>1</orderPrefix>
</cashPay>
</server>

The orderPrefix is the new setting here: a non-negative integer within the range between 0 and 9. In the settings example above the value equals 1.

Different prefixes should be specified for kiosks working with one cash server. Then numbers from different kiosks will not overlap when paying at the cash desk.

If over ten kiosks operate with one server, the overlapping issue will appear again.

Preparing the Menu

Another obligatory condition for launching r_keeper_SelfServiceTerminal_7 is preparing the menu to be displayed at the kiosk. The r_keeper_SelfServiceTerminal_7 will not run until you configure the menu tree.

Go to Menu > Menu Tree and create catalogs (selector pages) and sub-catalogs to be displayed on the kiosk screen.

These selectors are then filled with sub-catalogs — second-level selectors. For example, the Juice, Mineral Water, and Alcohol, etc. selectors are added to the Beverages selector, while the second-level selectors are filled with menu dishes. Only dishes can be added to the second-level selectors. You cannot add combo dishes and sub-catalogs there. 

Once the tree is created, all catalogs — first level selectors — should be moved to the Initial Choice catalog which is the tree root.

To assign pictures to the dishes in the menu tree, specify the path to the dish picture catalog in the r_keeper 7 manager station. To do this, go to Options > Parameters > Installation > Large images path.

The pictures for the dishes are set up in the Self-Service/Web-Orders item of the dish properties. If there is no such item, go to Options > Parameters > Options usage and enable the Self-Service/Web-Orders parameter.

Setup of Self-Service Kiosk

Server

The self-service kiosk communicates with the cash server through the kiosk server.

SelfOrderService.exe is the main file executed by the kiosk server, and its configuration file is SelfOrderService.ini

Before launching the kiosk server, edit its configuration file. The parameter values specified below should match the r_keeper 7 data:

StationIdent — the identifier of the cash station which will generate orders
TableIdent — the identifier of the table for which the orders will be formed
WaiterIdent — the identifier of the employee generating the orders
MaketIdent — the identifier of the receipt print layout
DelReceipMaketIdent — the identifier for undoing the receipt
DefaultSelectorIdent — the identifier of the kiosk menu selector in the menu tree
Ordertype — a list of order type identifiers available for the kiosk
VoidIdent — the identifier of the reason for deleting a dish from the receipt

Application

A kiosk client is a user interaction interface featuring dish selection, order payment, and manager's functions. The kiosk client's executive files are placed in the \Арр subdirectory.

RKeeperKiosk.exe is the kiosk client's main executive file. It is launched automatically when the SelfOrderService.exe server is launched. The kiosk parameters are stored in two configuration files: configuration.xmlandsettings.xml.

The configuration.xml file contains the main parameters such as functionality, design, etc.

The settings.xml file contains server and debugging parameters.

The versions.txt file contains information about the build current version: server_version — client_version—"*theme"_current_file version.

Check the following parameters in the XML interface section of the settings.xml configuration file (they are added automatically from SelfOrderService.ini after the kiosk's first launch):

Host — cash server address
Port — cash server HTTP Port, is entered in the HTTP Server block of the cash server's properties
User — the user created for the kiosk's communication with the cash server via the HTTP protocol (http_user)
Password — user password
StationIdent — cash station identifier
TableIdent — table identifier
WaiterIdent — waiter identifier
MaketIdent — receipt layout identifier
DelReceiptMaketIdent — receipt deletion reason identifier

Manager Functions

A manager functions section has been added to the kiosk interface starting with r_keeper_SelfServiceTerminal_7 version 1.0.1.13:

• Print Report Z
• Print Report X
• Close common shift
• Close cash shift
• Delete receipt
• View licensing information
• Relaunch kiosk.

Two-step authentication is used to enter the manager section: in addition to the employee's code and password, you should enter a temporary password, generated automatically and sent to the specified e-mail address.

To set up this function, launch the LicReq.exe app as administrator and log in as a dealer.

Go to the Email Configuration tab and fill in the SMTP server connection parameters, specify  the receiver and sender addresses, and be sure to set the Use EHLO!! parameter.

Click Test settings to verify the operability — a testing letter with a temporary password will be sent to the specified e-mail address.

To enter the manager section an employee should have the Close Common Shift and Close Cash Shift rights.
To enter the manager section, do the following:

1. In the kiosk's user interface go to the Information section
2. Click on the screen's light area, first in the upper left-hand corner and then in the lower right-hand corner. The interval between the clicks should not exceed 2-3 seconds
3. Enter the employee's code, password, and the shift password, i.e. a temporary password sent to the e-mail address
4. You will get access to the manager's functions after successful authentication.

Menu Item Pictures

The kiosk supports graphic file viewing for menu items. The files should be located in the \App\Assets\Dishes subdirectory.

Localization

The current localized version of the system interface is available for automatic downloading from the localize.ucs.ru server starting with SelfOrderService version 1.0.1.71.
See the localization settings parameters in the [LNG] section of the SelfOrderService.ini configuration file.

Launching Self-Service Kiosk

To launch the kiosk, do the following:

1. Launch the cash server
2. Launch the printing station
3. Launch the SelfOrderService.exe kiosk server as administrator.

To ensure an automatic software launch:

• Set the cash server up as a service with the automatic launch mode
• Set the printing station up as a service with the automatic launch mode
• Add the SelfOrderService.exe kiosk server to the Windows StartUp — the server will automatically launch the client part and relaunch it in case of closure.

To exit the kiosk, close the SelfOrderService.exe kiosk server — a system tray icon, which will automatically close RKeeperKiosk.exe.

Updating Self-Service Kiosk

• Save the SelfOrderService.ini, App\Settings.xml and App\configuration.xml configuration files
• Copy the new build files by replacing the current files, or install the kiosk in another directory and copy the \App\assets\dishes,\App\assets\info and \App\assets\video directories from the current build
• Compare the new and old configuration files, make the necessary changes — relocate the settings from the old files or add new parameters to the current configuration files
• If necessary, check the \App\assets\theme\default\localization.xml localization file
• Regenerate the license using LicReq.exe.

Event-Related Blocking of Self-Service Kiosk

Starting with RKeeperKiosk version 0.8.4., event statuses for which you can enable or disable the kiosk blocking have been added to the configuration.xml configuration file:

<deviceState>
<!-- Shift duration has exceeded 24 hours -->
<shift24Out lock="true"/>
<!-- Paper low -->
<paperLow lock="true"/>
<!-- Out of paper -->
<paperOut lock="true"/>
<!-- Printer error -->
<paperOther lock="true"/>
<!-- Fiscal memory device almost full -->
<EKLZNearEnd lock="true"/>
<!-- Fiscal shift has exceeded 24 hours -->
<fisc24Out lock="true"/>
<!-- Fiscal data recorder unavailable -->
<fiscAvailableLock lock="true"/>
<!-- Unsent receipts intact -->
<OFDUnsendedDocsLock lock="true"/>
</deviceState>

Hot Keys

• [Ctrl + Shift + M] — return to the initial state, demo mode only
• [Ctrl + M] — return to the manager station, demo mode only
• [Ctrl + Shift + L] — generating license error, demo mode only
• [Ctrl + L] — generating a valid license, demo mode only
• [Ctrl + G] — calling a cleaner
• [Ctrl + O] — clearing an order, demo mode only
• [Ctrl + P] — deactivating selector visibility auto update, demo mode only
• [Ctrl + "-"] — selector deactivation: first you need to deactivate selector visibility automatic update — demo mode only
• [Ctrl + "+"] — selector activation: first you need to deactivate selector visibility automatic update — demo mode only
• [Ctrl + Shifr + "~"] — display clicker keypad, demo mode only
• [Ctrl + C] — hide/show mouse cursor, since r_keeper_SelfServiceTerminal_7 version 0.6.27
• [Ctrl + T] — switch on/off window on top other windows, since r_keeper_SelfServiceTerminal_7 version 0.7.2.

Launching Kiosk in Demo Mode

You can launch the r_keeper_SelfServiceTerminal_7 in a demo mode. No license is required.

There is no need to launch the cash server in this mode. The kiosk client part, RKeeperKiosk.exe, does not use the kiosk server SelfOrderService.exe  but operates with preset text data — a set of XML files.

To switch on the demo mode, set the true value for the <demo>...</demo> parameter in the settings.xml configuration file of the RKeeperKiosk.exe app.

<app><!-- Demo mode --><!-- The demo mode has an option of recording the mouse status (up, down, and move). Calling the record panel (shift + "~").
You can also save the status in a file and play from the file. -->
<demo>true</demo>
</app><!-- Managing the Screen Resolution

Description of Configuration Files

This section will be filled on an as-needed basisб as all the main parameters are described in the .INI and XML files.

settings.xml

OrderNumLength — the length of the order number printed on the slip. The order number from the slip is used for paying for the respective order at the cash desk.

SelfOrderService.ini

Type30OrderNum — this parameter shows the next order number. There is no need to change this value manually as it is done automatically.

User Guide

A User Guide for r_keeper_SelfServiceTerminal_7 in Russian is available at FTP: ftp://ftp.ucs.ru/books.