Retail:Hardware and Peripherals Installation
Introduction
The Openbravo Commerce Cloud is designed to be platform agnostic and therefore to support a wide range of hardware and operating systems. To help you choose the best for your business you first need to understand the architecture. Then you need to look at your specific situation and budget.
Architectural Overview
There is one centralized, real-time database that serves both the back office and the store-level Web POS GUI. The Openbravo instance (that manages this database) is deployed on a server that can sit on-site or in a cloud. For more detailed information on the different deployment options, see the System Administration Guide.
Now the user will operate Openbravo Commerce Cloud always through a browser. There are two different GUIs that use the same Openbravo instance but are intended for different users, hardware and usage.
- The back office. This is the Openbravo 3 user interface. It is optimized for large screens and superior productivity featuring grids, forms, tabs and workspaces.
- The Web POS. This is the store-level user interface that is optimized for touch and mobile devices. It is light, fast and extremely user friendly. Technically, the Web POS is just another window to Sales Orders.
Terminals that are connected to peripherals such as printers, need to run a small web application, the so-called Hardware Manager (HWM) to control those. The HW Manager does not have an end-user GUI and runs in the background.
On what hardware do I access the back office?
To use the back office web interface of Openbravo 3 any modern office system would work. See the Client sections of the Openbravo System_Requirements for details.
On what hardware do I access Web POS?
To use Web POS there is a lot more to choose from: Tablets smartphones, POS systems, all-in-one systems and desktops.
To see the recommended specifications of the hardware and software to run Web POS go to the Hardware and Peripherals Guide .
On what hardware do I run the Hardware Manager?
For the Web POS cash register terminal you would typically choose a desktop or laptop computer because it needs to run the Hardware Manager if you want to connect to peripherals such as receipt printers, customer displays, cash drawers, scales and payment devices. The Hardware Manager is a tiny web server. It runs on any computer that runs Java and it does not need a display. So called headless computers that come in a small housing are a good option as they can be easily hidden below the checkout desk. See below for detailed instructions on installing the Hardware Manager.
In the Peripherals section of the Hardware and Peripherals Guide you can find the recommended and supported devices.
 | Note: Always make sure to test the hardware and devices you plan to use before deploying. |
Receipt Printers
Receipts are printed using a receipt printer that is connected to the computer that runs the Hardware Manager. Modern receipt printers usually come with a USB connection.
Fiscal Printers
Fiscal printers are very similar to regular receipt printers, used for control of a country's tax revenues. Currently, they are used in several countries, are certified by appropriate government body and usually comes in a form of sealed module. Like receipt printers, fiscal printers come with USB connection or serial connection and the protocol to manage fiscal printers usually differs between countries.
Barcode Scanner
The barcode scanner is directly connected via USB or Bluetooth to the tablet or computer and works as a Human Computer Input device (HCI) comparable to a keyboard. It simply generates characters that are shown in the Web POS field on the SCAN panel followed by a carriage return.
In Android devices bluetooth barcode scanners appear as an external keyboard and by default the on-screen keyboard is always hidden. If you want to use both input methods, the scanner and the onscreen keyboard, tap on the keyboard icon on the notification bar and in the dialog that appears uncheck the option "Physical keyboard". If this option does not appear you have to add another input method. Select "Configure input methods" and add a new one. This way the option "Physical keyboard" will appear and you can uncheck it.
Cash Drawers
The cash drawer is connected to the receipt printer and pops when it receives an electrical signal from the printer every time it prints. It is managed by the Hardware Manager.
Customer Displays
The customer display shows the details of items that are added to the ticket. It is connected to the computer that runs the Hardware Manager. Modern customer displays usually come with a USB connection. We need to use VCP drivers: Virtual COM port (VCP) drivers cause the USB device to appear as an additional COM port available to the PC. In this way, the Hardware Manager can access the USB display in the same way as it would access a standard COM port. Use these drivers to install the display as a USB device and assign a VCP to it.
Scales
Scales are used to weigh products that are priced by unit of weight. They are connected to the computer that runs the Hardware Manager via a serial port.
Payment devices
Payment devices are used to process payments using debit or credit cards. They can be connected to the computer that runs the Hardware Manager via a serial port or USB port.
RFID readers
| | Note: Starting from RR16Q3 |
An RFID reader is a wireless tag reader which work with radiofrequency waves. RFID Technology is based on EPC codes. These codes are 24 digit hexadecimal numbers. An EPC code is a unique identifier for a product so that means that multiple RFID codes can point to the same product.
The POS Hardware Manager
If you want to connect to peripherals such as receipt printer, customer display, cash drawer, scales and payment devices, you will need the POS Hardware Manager (HW Manager). This is a tiny web server that runs on a computer to which the peripherals are connected. The POS HW Manager has a unique URL and listens to incoming instructions from the terminals. This makes it possible to control the peripherals remotely. A sales person can use a tablet to choose and sell products to her customer walking around in the store and print the ticket on the receipt printer that is connected to the main cash register. There are plenty of creative deployment possibilities using this architecture and it is encouraged to experiment before picking a final deployment.
Installing
| | Note: In RR16Q2, the Jasper libraries have received a significant update. It is a good idea to update to this version if extensive usage of the Jasper reports is done. |
The POS HW Manager runs on any computer that runs the Java JDK. The supported version is Java 11 or higher. It is distributed in a module and consists of JAR files (Java Archive). It is launched with a batch file and it needs to run permanently to be able to receive instructions from the POS terminals to control the peripherals. The sources and executable files of the Hardware Manager are located inside the /dist folder of the module and compressed in two separate zip files (poshw-src-version.zip and poshw-version.zip). To install the Hardware Manager follow these steps:
- Unzip the HW Manager archive file on the computer you want to run it on
- Make sure the computer runs Java. If not, you can download it from the oracle site
- Open the openbravohw.properties file and modify the output devices parameters if necessary (see Following section Openbravo Hardware Configuration)
- To use a company logo on the printed receipt, upload an image called ticket-image.png into the poshw_bin_new/img folder. Make sure the image has an aspect ratio of 24:9, for example 120x45 pixels and do not use gradients or too many colors as it will not look good on the black and white print out. Best is to use solid fills and strong contrasts
- for Microsoft Windows operating system run the start.bat file. For Linux operating systems run start.sh.
- The HW Manager is started
- On the second tab of the POS HW Manager you find the web server´s URL. This is the machine-name and is determined by the operating system. Use this URL in the POS Terminal window in the back office followed by /printer or /scale. This will make Openbravo send instructions from the POS terminals to the HW Manager
- On the Printer and Scale tabs you can test and emulate the peripherals.
Openbravo Hardware Configuration
This section details how to configure the file openbravohw.properties. This configuration file is located in the root folder where POS Hardware Manager is installed.
This section describes also the devices supported out of the box by the POS Hardware Manager. More devices can be supported with plugins that must be copied to the libext/ folder located where the POS Hardware Manager is deployed. If you want to know how to develop and package new plugins that include implementation for other device drivers not included in the standard version of the POS Hardware Manager, read the How to create a new device driver developer document.
Web server
The hardware manager supports two protocols HTTP and Secure HTTP (HTTPS). Secure HTTPS is mandatory if Openbravo runs in a secure server (HTTPS) like the Openbravo On Demand deployment option because of the Same Origin Policy implemented in the supported web browsers.
To configure HTTP you must set the port that listens to the Web POS terminal requests. By default the port is 8090. If not configured or set to 0, the HTTP protocol is disabled.
In the same way, since 21Q1 release, you can configure the accessibility to the hardware manager ("allowedhost"). If you do not set any parameter, all the devices in the networks will be able to access to the hardware manager. In other case, it you want to give access only to your own device, you must set this parameter to "localhost".
## Web server ## server.port = 8090 server.allowedhost = localhost |
To configure Secure HTTP (HTTPS) you must set the secure port that listens to the Web POS terminal requests. By default the port is 8190. If not configured or set to 0, the Secure HTTP (HTTPS) protocol is disabled.
For Secure HTTP (HTTPS) It is needed also to have a signed certificate in order to be accepted by the web browser. To know more how Secure HTTP (HTTPS) works it is recommended to visit the wikipedia document HTTP Secure.
For Secure HTTP (HTTPS) the Hardware Manager includes needs a key store file that includes a certificate that is accepted by the browser used to execute Web POS. This certificate can be signed by a Certificate authority or can be a self-signed certificate. By default the path of the key store file is ssl/keystore.jks. Also it is needed the password for the key store and for the key manager. This is a sample configuration:
## Web server ## server.fqdn = localhost server.secureport = 8190 server.keystorepath = ssl/keystore.jks server.keystorepassword = <STORE_PASSWORD> server.keymanagerpassword = <KEY_PASSWORD> |
Using a certificate signed by a Certificate authority
To use a certificate signed by a Certificate authority you need a Fully qualified domain name for the machine where the Hardware Manager runs, buy a certificate for that Fully qualified domain name, import it into a keystore file and finally configure this keystore file to be used by the Hardware Manager. The detailed instructions to buy and to import a certificate for a Fully qualified domain name goes beyond this guide. You have more information about it in the wikipedia document HTTP Secure.
Using a self-signed certificate
If you do not want to use a certificate signed by a Certificate authority you need to create a self-signed certificate. Here you have all the steps needed to create a self-signed certificate and to configure the Hardware Manager and the browser with access to the Hardware Manager.
First you need to install the tools to create the self-signed certificate and the key store:
- keytool. Is the tool to manage key stores. It is included in the Oracle Java JDK or OpenJDK. To check you have it properly installed type in the command line keytool -help and press ENTER.
- openssl. Is the tool to manage certificates. For Linux machines can be installed using the distribution package management tools and for Windows machines can be downloaded from Open SSL Binaries. To check you have it installed, open the command line, type openssl version and press ENTER.
1.- Generate all the certificate files
The Hardware manager can generate all the certificate files needed automatically using keytool, openssl and the configuration file openbravohw.properties. Alternativelly, you can generate all the certificate files manually. To do it read the Generate self-signed certificate for the Hardware Manager guide.
To configure the automatic generation edit the following properties:
## Web server ## server.fqdn = localhost server.secureport = 8190 server.keystorepath = <KEYSTORE_PATH> server.keystorepassword = <STORE_PASSWORD> server.keymanagerpassword = <KEY_PASSWORD> |
Where server.fqdn is the Common Name (e.g. server FQDN or YOUR name), server.keystorepath is the location of the generated file, server.keystorepassword is the key store password and server.keymanagerpassword is the key manager password.
NOTE: The most important parameter is server.fqdn, the Common Name (e.g. server FQDN or YOUR name), that must be the hostname or IP address of the machine where the Hardware Manager is installed.
Then start the Hardware Manager and if the certificate files do not exist it will try to generate all the files needed. If the certificate files are generated successfully, the Hardware Manager will show the following information:
But if you try to access using Secure HTTP (HTTPS) an error will be displayed saying the connection is not private. It is only needed to configure the browser to complete the process.
| | Warning: Store safely the private key ca-key.pem and key store files keystore.p12 and keystore.jks, because can be used to sign new certificates accepted by the browsers you will configure later to access the Hardware Manager. |
2.- Configure the browser
To configure the browser you need to import the certificate file generated in the first step: ca-certificate.pem. Depending on the operating system and the browser the process to import the certificate is different
Windows, Linux with Google Chrome: Open the Settings page and at the end of the page select Show advanced settings. In the HTTP/SSL section press the button Manage certificates. Go to the tab Authorities and select Import. Here select the certificate file ca-certificate.pem. In the next dialog select the check box Trust this certificate for identifying web sites and accept.
OS X with Safari and Google Chrome: Double click on the certificate file ca-certificate.pem to open it. The Keychain Access tool opens the certificate and displays the certificate details. To install the certificate press on Always trust.
Android: First you need to make the certificate file ca-certificate.pem available in the Android device sending it by mail or storing it into a SD card. Once the certificate file is in the android device open Settings and go to the option Security. In the section Credential storage select Install from SD card. Select the certificate file. Add a certificate name and in Credential use select the default option VPN and apps and accept. If you do not have an screen lock method you will be requested to set one.
iOS: The simplest way is to send the certificate by mail, or to make the certificate file available in a web site inside the local network where the iOS device can browse. Then in the mail application or in the browser select the certificate file. The Install profile window will appear and press on Install. You can see the certificate installed in Settings, General, Profiles.
Finally, to verify that your browser works open the address https://<hostname>:8190 where <hostname> is the hostname or IP address of the machine where the Hardware manager is installed. If everything is installed properly, the Hardware manager home page will appear without any warning. From the Hardware manager home page you can also download the server certificate needed to configure your browser.
| | Note: The following images correspond to version RR18Q2 and greater |
Now you can configure POS terminals to use the Hardware Manager in the Hardware URL field of the POS Terminal window.
Interface
For enabling the graphical interface write true. If this property is set to true the user interface of the POS Hardware Manager is opened when running the application. This is useful for configuration and testing purposes. In production environments, usually this property is set to false and the POS Hardware Manager runs silently in the background. You can see the installed certificate in the option Trusted credentials
## Interface ## application.ui = true |
Receipt printer images
Copy the company logo image to be printed in receipts and save it into the hardware_manager_folder/img. If the subfolder is called img then you do not need to change anything in openbravohw.properties:
## Receipt printer images ## images.folder = ./img |
Third party libraries
The Hardware Manager offers the configuration possibilities to add new java libraries (.jar) files and native libraries required by plugins or for example JavaPOS drivers. There are several ways to add new java libraries and native libraries
- Folders libext/ and cpext/
Add to the folder libext/ new java .jar files required by the hardware manager and to the folder cpext/ new java .class files.
- Environment variables
| | Note: Starting from RR18Q2 |
The content of the environment variable HWMANAGER_CP will be added to the java classpath. HWMANAGER_LP will be added to the java native libraries path and HWMANAGER_OPTS will be added as custom java initialisation options.
- Profile file
| | Note: Starting from RR18Q2 |
Use profile.bat in Windows or profile.sh in Linux and MacOS to define environment variables or to execute any other configuration command before starting the Hardware Manager
Receipt Printer and cash drawer
POS Hardware Manager supports several receipt printers connected to the same terminal. Cash drawers are connected to the receipt printer and open with a printer command.
The supported printers modes are USB, Printer, Screen, Epson, Tmu220, Star, Ithaca and Surepos. Configuration for each mode is explained as follows:
| | The recommended mode for a production environment is USB or one of Epson, Tmu220, Star, Ithaca or Surepos because in these modes it is used the ESC/POS protocol and the Hardware Manager has full control of the receipt printer. Printer is not recommended because in this mode the Operating System printer driver is used and it is not possible to manage the cash drawer through it. |
USB
This is the default mode. If you have one of the printers included the list of USB supported devices, the Hardware Manager will automatically use and configure it.
The list of supported USB (also Powered USB) devices are:
- Epson TM-T88V
- Star Micronics TSP-100
From 16Q2 an onwards:
- Epson TM-T20
- Wincor TH230+
The Hardware Manager can be configured to include more USB printers. Retail:How_to_add_new_USB_devices.
To configure the USB port go to the USB configuration section.
Epson, Tmu220, Star, Ithaca, Surepos Mode
These modes are for different dialects of ESC/POS receipt printers connected to the machine using a serial port, a parallel port or any other kind of device port (like USB) that can be configured as a device file.
To configure the port go to the Serial and parallel port configuration section.
Do not install any printer driver, because the Hardware Manager connects directly to the printer. If a serial connection is chosen, by default the serial parameters are: bauds: 9600, data bits 8, stop bits 1, parity none and flow control none. If you want to configure these parameters, add after the serial port, separated by comma, the new serial port parameters. For flow control you have the following values: 0 for none, 3 for RTS/CTS and 12 for Xon/Xoff.
To test the printer is properly connected to the first serial port type:
- in Windows
type test > COM1: |
- in Linux
echo test > /dev/ttyS0 |
The Epson type is the most ESC/POS compatible protocol, but you must be sure to configure the printer to ESC/POS mode. Two modes are available serial for serial and parallel ports and file for serial, parallel and other ports.
The last option to indicate is the device port where the receipt printer is connected. NOTE: please note that in Windows, if the first serial port is selected, you need to type COM1 for serial mode and COM1: (with the two dots) for file mode.
Using Windows OS is not recommended to use a serial configuration. Use file configuration instead.
## Receipt printers ## machine.printer = epson\:serial,COM1 machine.printer.2 = tmu220\:file,/dev/ttyS0 machine.printer.3 = star\:serial,/dev/ttyS0,57600,8,1,0,0 |
Printer Mode
This mode is for receipt printers and standard printers installed as a printer in the operating system using the system driver provided by the manufacturer of the printer. If you want to use this mode, you need to type "printer" in Receipt printers section in openbravohw.properties.
| | Note: This mode cannot manage the cash drawer and the automatic cut of the paper. The system driver provided by the manufacturer might provide options to manage this functionalities. |
Then you have different options:
- (Default): the default system printer will be selected
- name_of_the_printer: you can write here the name of your printer to select it in case of having several ones
Finally, and separated by a "comma", you decide the paper type:
- receipt: it is the case for receipt printers
- standard: it is the case for "A4" paper size used in standard printers
The following shows different examples:
## Receipt printers ## machine.printer = printer\:(Default),receipt machine.printer.2 = printer\:name_of_the_printer,standard |
Depending on the receipt printer model or standard printer mode used some advanced configuration may be done to adjust the paper size used in your printer.
## Receipt printer paper ## paper.receipt.x paper.receipt.y paper.receipt.width paper.receipt.height paper.receipt.mediasizename paper.receipt.orientation paper.receipt.fontName paper.receipt.fontSize paper.receipt.lineHeight paper.receipt.imageScale |
The property fontName stands for the name of the font used.
The property fontSize stands for the size of the font used.
The property lineHeight stands for the height of each line. The distance between each text line.
The property imageScale stands for the factor images are scaled. Greater values make images bigger. For example, a value of 2.00 means that the image will be scaled by a factor of 2.00, will be doubled.
The property mediasizename stands for the paper size name to use and can be one of the followings:
Postcard, Statement, Letter, Executive, Legal A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, A10 B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10 ISOB0, ISOB1, ISOB2, ISOB3, ISOB4, ISOB5, ISOB6, ISOB7, ISOB8, ISOB9, ISOB10 EnvISOB0, EnvISOB1, EnvISOB2, EnvISOB3, EnvISOB4, EnvISOB5, EnvISOB6, EnvISOB7, EnvISOB8, EnvISOB9, EnvISOB10 C0, C1, C2, C3, C4, C5, C6 EnvPersonal, EnvMonarch, Monarch, Env9, Env10, Env11, Env15, c8x10 EnvDL, DL, EnvC0, EnvC1, EnvC2, EnvC3, EnvC4, EnvC5, EnvC6 |
The property orientation stands for the paper orientation to use and can be one of the followings:
Portrait, Landscape, Reverse_Portrait, Reverse_Landscape |
The properties x, y, width and height stands for the drawable area of the paper used. The units are defined in 1/72nds of an inch.
The default properties values for receipt printers are for Star Micronics receipt printers and are the following:
## Receipt printer paper ## paper.receipt.x=10 paper.receipt.y=287 paper.receipt.width=190 paper.receipt.height=546 paper.receipt.mediasizename=A4 paper.receipt.orientation=Portrait paper.receipt.fontName=Monospaced paper.receipt.fontSize=7 paper.receipt.lineHeight=12 paper.receipt.imageScale=0.65 |
If you have an Epson receipt printer modify the default values by the following:
## Receipt printer paper ## paper.receipt.x=10 paper.receipt.y=10 paper.receipt.width=190 paper.receipt.height=546 paper.receipt.mediasizename=A4 paper.receipt.orientation=Portrait paper.receipt.fontName=Monospaced paper.receipt.fontSize=7 paper.receipt.lineHeight=12 paper.receipt.imageScale=0.65 |
For standard printers the default properties values are defined for the A4 paper size and are the following:
## Standard printer paper ## paper.standard.x=72 paper.standard.y=72 paper.standard.width=451 paper.standard.height=698 paper.standard.mediasizename=A4 paper.receipt.orientation=Portrait paper.receipt.fontName=Monospaced paper.receipt.fontSize=7 paper.receipt.lineHeight=12 paper.receipt.imageScale=0.65 |
If you have another receipt printer or you want to set another paper size for your printer you will need to modify these values.
JavaPOS Mode
| | Note: Starting from RR18Q2 |
This mode is for receipt printer and cash drawer with a JavaPOS driver. The JavaPOS drivers for these devices must be provided by the hardware provider and be installed and configured properly in the JavaPOS jpos.xml file. In this configuration file each device is referenced with an ID. This ID is the value that will be used when configuring the Hardware Manager.
To configure the JavaPOS printer and cash drawer, open the openbravohw.properties and edit the property...
machine.printer = javapos\:PrinterID,CashDrawerID
Where PrinterID is the Java POS ID for the receipt printer and CashDrawerID is the JavaPOS ID, for the cash drawer. Only the receipt printer is mandatory, if there is no cash drawer, just omit the cash drawer ID.
There are the following properties, that are specific to JavaPOS receipt printers if it is needed to adapt the printing behaviour:
javapos.text.encoding = javapos.image.type = memory javapos.image.format = gif javapos.image.width = 400 javapos.barcode.width = 100 javapos.barcode.height = 1000 javapos.releaseaftertransaction = false
- javapos.text.encoding. Then encoding used to send literals to the printer, by default is UTF-8. You can find all the available encoding in the document https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.htmls
- javapos.image.type. The different modes used to print images using JavaPOS. Depends on the support of the JavaPOS driver it will be needed to select one or other. The available values are memory, file and map.
- javapos.image.format. The available values are gif, jpeg and bmp. Depending on the formats supported by the JavaPOS driver it will be needed to select one or other.
- javapos.image.width. Resizes the image to be adjusted to 400 points with. If there is no need to resize images or there are performance issues set to 0.
- javapos.barcode.width. Defines the width in points used to print barcodes.
- javapos.barcode.height. Defines the height in points used to print barcodes.
- javapos.releaseaftertransaction. If true the JavaPOS handler will be used and released for each receipt printed. Set it to true if the printer is used by other applications. If not, set it to false.
Screen
On screen receipt printer for configuration and testing purposes. This mode creates images of the receipts that are displayed in the tab Printer of the POS Hardware Manager.
Fiscal printer
To support fiscal printers in the POS Hardware manager there must exist an implementation of the fiscal printer protocol adaptor. These adaptors should be implemented as Openbravo modules. As an example POS Hardware manager includes support of Eltrade fiscal printers.
The POS Hardware manager can support several fiscal printers connected, and in each entry you must set the mode of the fiscal printer used and the parameters needed by the POS Hardware manager to communicate with the fiscal printer.
machine.fiscalprinter = machine.fiscalprinter.2 = machine.fiscalprinter.3 = |
Eltrade
Eltrade fiscal printers are connected to the computer using a serial port and the implementation in the POS Hardware manager works only in Windows machines. The reason is that the POS Hardware manager uses the ActiveX window to send commands to the printer.
First you need to install the Active X driver provided by Eltrade and also configure the logo and header lines of the receipt. Refer to Eltrade documentation to install properly the printer in your system.
To configure an Eltrade fiscal printer you need to set the mode eltrade in the Fiscal printers entry in openbravohw.properties, then separated by commas you need to write the serial port used and the bauds. This is an example of an Eltrade fiscal printer connected to the COM1: port at 115200 bauds.
machine.fiscalprinter = eltrade:COM1:,115200 |
Printing PDF documents
| | Note: The method apachepdfbox is available from version RR18Q2 and greater |
Printing PDF documents it is only supported for printers configured in #Printer_Mode because the Hardware Manager can only send PDF documents to installed printers in the operating system.
Printing PDF documents it is not directly managed by the Hardware Manager, depending on your printer model and the method you want to use to print PDF documents you need to configure it in the Hardware Manager configuration file, editing the property process.printpdf.The available methods are: apachepdfbox, printerpdf, desktop and terminal.
This is the default Hardware Manager configuration file with the process.print property configurated by default with the method apachepdfbox.
## Printing PDF ## process.printpdf = apachepdfbox |
apachepdfbox: This method process the PDF file using the Apache PDFBox library https://pdfbox.apache.org/. This is the default method.
printerpdf: This method sends directly the PDF document to the printer. The printer must support PDF printing.
desktop: This method uses the system PRINT action to print the PDF document. The printer used is selected by the system.
terminal: This method executes a system command to print a PDF document. You can use utilities like Adobe Acrobat, Ghostscript, ...
This system command goes in the property printpdf.terminal.command, where %1$s is the job name, %2$s for the PDF file to print, %3$s is the printer name and %4$s is the number of copies to print. For example the following configuration in Linux sends the document to the printer.
## Printing PDF ## process.printpdf = terminal printpdf.terminal.command = lp -d %3$s -n %4$s -t "%1$s" %2$s |
Printing QR Codes in the templates
| | Note: Starting from RR18Q4 |
A new functionality which allows the printing of QR Codes has been added. The configuration needed is the following:
qr.size = M qr.quality = M
- qr.size. Parameter used to define which is the size of the QR. The possible values are: S,M,L,XL. Please Note that not all the sizes are available for all the printers
- qr.quality. Parameter used to define the error correction for the QR image. The possible values are: L,M,H,Q
Customer display
Openbravo Web POS supports text customer displays of 2 lines and 20 columns. The two line limit is hard coded, so four line displays only show the first two lines, and only twenty characters long for each line.
The supported customer displays are:
USB
This is the default mode. If you have one of the customer displays included the list of USB supported devices, the Hardware Manager will automatically use and configure it.
The list of supported USB devices are:
- Logic Control LD9000
The Hardware Manager can be configured to include more USB customer displays. Retail:How_to_add_new_USB_devices.
To configure the USB port go to the USB configuration section.
Window
A new window is created and is used as a customer display. This is useful to use a monitor connected to the POS Hardware Manager machine as customer display.
Epson, Ld200, Ld9000, Surepos
Like in receipt printers these modes are for different dialects of ESC/POS customer displays connected to the machine using a serial port, a parallel port or any other kind of device port (like USB) that can be configured as a device file.
To configure the port go to the Serial and parallel port configuration section.
The customer display and a receipt printer can be connected in mode bridged. The customer display is connected to the computer and the receipt printer is connected to the customer display. In this case both share the configuration and must be configured using the same mode, port, and serial port parameters.
Do not install any driver, because the Hardware Manager connects directly to the printer.
If a serial connection is chosen, the default configuration is: bauds: 9600, data bits 8, stop bits 1 and parity none. And line in the case of receipt printers, if you want to configure these parameters, add after the serial port, separated by comma, the new serial port parameters.
Finally, in openbravohw.properties the configuration of customer display is similar to the printers, first by writing the mode selected, followed by file or serial then the port.
## Customer display ## machine.display = epson\:serial,COM1 |
As before, NOTE: please that in Windows, if the serial port is selected, you need to type COM1 for serial mode and COM1: (with the two dots) for file mode:
## Customer display ## machine.display = epson:file,COM3: |
FEC
The FEC XP-2025 visor is connected with serial port, but the connector is USB-C.
To configure the port go to the Serial and parallel port configuration section.
Do not install any driver, because the Hardware Manager connects directly to the printer.
The default configuration is: bauds: 9600, data bits 8, stop bits 1, flow controle none and parity none.
Finally, in openbravohw.properties the configuration of customer display is:
## Customer display ## machine.display = fec\:serial,COM2 |
(Select the port, COM2 is just an typical example)
Saga
The Perimatic Saga SGDP240 visor is connected with serial port, but the connector is USB
To configure the port go to the Serial and parallel port configuration section.
Do not install any driver, because the Hardware Manager connects directly to the printer.
The default configuration is: bauds: 9600, data bits 8, stop bits 1 and parity none.
Finally, in openbravohw.properties the configuration of customer display is:
Linux: (select the port, ttyUSB0 is just an typical example)
## Customer display ## machine.display = saga:file,/dev/ttyUSB0 |
Windows : (select the port, COM1 is just an typical example)
Windows 11 and later versions don´t support the COM to USB adapter drivers. Please use the Saga visor model with serial port in this version.
## Customer display ## machine.display = saga\:serial,COM1 |
JavaPOS Mode
| | Note: Starting from RR18Q2 |
Like in receipt printers this mode is for customer displays with a JavaPOS driver. In this configuration each device is referenced with an ID. This ID is the value that will be used when configuring the Hardware Manager.
To configure the the customer display, open the openbravohw.properties and edit the property...
machine.display = javapos\:DisplayID
Where DisplayID is the JavaPOS ID for the customer display.
Scale
Openbravo Web POS supports scales connected to the serial interface. Do not install any driver, because the hardware manager connects directly to the scale. The serial parameters used to connect to the scale are by default: bauds: 4800, data bits: 8, stop bits: 1 and parity: odd. But can be configured as demonstrated in the examples.
There are five modes supported:
- genericcontinuous. For scales sending information in continuous mode. The format of the returned information is configurable
- generic. For scales which work in bi-directional mode (that is, they require a command to be sent to them to force them to send weight readings back). The scale command sent and the returned weight are configurable.
- samsung. The scale command code sent is $. The weight is returned in kilos.
- dialog1. The scale command code sent is 0x05. The weight is returned in grams
- screen. Virtual scale for testing purposes. This mode returns to the application the weight selected in the "Scale" tab of the POS Hardware Manager
At this point, the suggested method is generic-continuous. We've tested throughly this method in-house, and we've verified to work with these two scale models:
- Mettler Toledo WS60M-SVE
- Cobos Precision JCP-15
This mode should work correctly with any scale that supports continuous sending of information.
Products that use the scale must be marked as scale in the properties tab of the Products panel.
## Scale ## machine.scale = screen machine.scale = samsung:serial,COM1,4800,8,1,1,0 |
Generic Continuous
This mode is designed to work with any scale which is able to send information in continuous mode. If the scale has been configured as genericcontinuous the following properties must also be configured:
- machine.scale. genericcontinuous.final. The java encoded character that indicates the end of the response
- machine.scale. genericcontinuous.pattern. The pattern used to analyse the response of the scale. It is a regular expression that follows the specification of the java Pattern class: http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html . The regular expression must have one or two groups. If there is only one group it will be interpreted as a number and will be multiplied by a factor as defined in the next property. If there are two groups the first group will be interpreted as the integer part and the second group as the decimal part.
- machine.scale. genericcontinuous.factor. The factor the number interpreted will be multiplied in the case the pattern has only one group. This is used for example if the scale returns grams and the POS has kilos as units. In this case the factor property must be set to 0.001 and if the scale pattern group returns grams, for example '1500'. After applying the factor it will return '1.500'.
Examples:
## Scale ## machine.scale = genericcontinuous:serial,/dev/ttyS0,9600,8,1,0,0 machine.scale.genericcontinuous.final = \r # Carriage return character machine.scale.genericcontinuous.pattern = ([0-9]*)\.([0-9]*) # Pattern for an scale response in kilos ## Scale ## machine.scale = genericcontinuous:serial,/dev/ttyS0,4800,8,1,0,0 machine.scale.genericcontinuous.final = \n # Line feed character machine.scale.genericcontinuous.pattern = ([0-9]*) # Pattern for an scale response in grams machine.scale.genericcontinuous.factor = 0.001 # factor to convert grams to kilos |
Generic
If the scale has been configured as generic the following properties must also be configured:
- machine.scale.generic.command. The command sent to the printer to request the weight
- machine.scale.generic.final. The java encoded character that indicates the end of the response
- machine.scale.generic.pattern. The pattern used to analyse the response of the scale. It is a regular expression that follows the specification of the java Pattern class: http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html . The regular expression must have one or two groups. If there is only one group it will be interpreted as a number and will be multiplied by a factor as defined in the next property. If there are two groups the first group will be interpreted as the integer part and the second group as the decimal part.
- machine.scale.generic.factor. The factor the number interpreted will be multiplied in the case the pattern has only one group. This is used for example if the scale returns grams and the POS has kilos as units. In this case the factor property must be set to 0.001 and if the scale pattern group returns grams, for example '1500'. After applying the factor it will return '1.500'.
Examples:
## Scale ## machine.scale = generic:serial,/dev/ttyS0,9600,8,1,0,0 machine.scale.generic.command = $ # Command sent to the printer machine.scale.generic.final = \r # Carriage return character machine.scale.generic.pattern = ([0-9]*)\.([0-9]*) # Pattern for an scale response in kilos ## Scale ## machine.scale = generic:serial,/dev/ttyS0,4800,8,1,0,0 machine.scale.generic.command = \005 # Command sent to the printer in octal machine.scale.generic.final = \n # Line feed character machine.scale.generic.pattern = ([0-9]*) # Pattern for an scale response in grams machine.scale.generic.factor = 0.001 # factor to convert grams to kilos |
Payment device
Openbravo Web POS supports payment devices connected to the serial interface or USB. Out of the box Openbravo does not provide any implementation for payment devices. If you want to use a payment device you must also install the right plugin that supports it.
In openbravohw.properties the configuration of the payment device depends on the payment device and its driver and must go in th property machine.payment.
## Payment device ## machine.payment = <devicename>:<parameters> |
RFID Devices
Two new lines have been added to openbravohw.properties:
## RFID ## #machine.rfid = embipos:COM1,3,500,255,0,0,300,1 machine.rfid = screen:,3
By default the screen device is the one enabled, but if an EmbiPOS device wants to be used you can comment this line and uncomment the previous one.
The line machine.rfid accepts 10 parameters:
- Device: Name of the device.
- Port: Name of the port in which the device is connected.
- Hardware Manager's Buffer Size: The number of tickets that tags will be stored in the Hardware Manager's Buffer, before getting removed Default: 3.
- Read Power: Default: 500.
- Q-Factor: Default: 255.
- Session: Default: 0.
- Miller Code: Default: 0.
- Reading Cicle: Default: 300.
- Channel: Default 1.
- Antenna: No Default.
If the screen device is enabled, only the Hardware Manager's Buffer Size is needed.
Once configured properly, the hardware manager itself can be used as an RFID reader through its graphical interface.
Basically there are two options:
- Send: Send an EPC (24 digit hex) to Web POS and add it to Hardware Manager's buffer.
- Reset: Reset Hardware Manager's buffer.
Sockets proxy
| | Starting from 20Q1 below functionality is available |
To establish a communication between the browser and any generic socket service, The hardware manager offers a generic proxy functionality that converts a websocket communication between the browser and the hardware manager in a socket communication between the hardware manager and a generic socket service where all messages sent via websocket by the browser are sent via socket by the hardware manager to the socket service, and all messages sent via socket by the socket service are sent by the hardware manager to the browser.
To establish a connection to a socket service using the proxy functionality you must open a websocket connection to the hardware manager using the following URL syntax, assuming https://hwm:8190 is the URL the hardware manager is listening.
https://hwm:8190/wsproxy?host=< remote-host >&port=< remote-port >&frame=< "binary" | "text" >
For example:
https://hwm:8190/wsproxy?host=192.168.1.111&port=5000&frame=text
Where:
- host is the host name or IP address of the socket service.
- port is the port of the host where the socket service is listening for new connections.
- frame is the kind of frame used in the websockets communication to send and receive data.
The following properties can be configured in the properties file:
## WebSocket proxy ## wsproxy.idletimeout = 120000 wsproxy.maxmessagesize = 0 wsproxy.connecttimeout = 5000 wsproxy.sotimeout = 1200000 wsproxy.buffersize = 102400
- wsproxy.idletimeout. Sets the idle timeout in milliseconds for the websocket connection.
- wsproxy.maxmessagesize. Maximum message size for the websocket connection. If 0 no limit is set.
- wsproxy.connecttimeout. Sets the timeout limit for connecting the the remote socket service in milliseconds.
- wsproxy.sotimeout. Sets the timeout for the socket connection in milliseconds. If 0 no timeout is set.
- wsproxy.buffersize. Maximum buffer size for the socket connection.
For development and testing you can use the Socket tab in the Hardware Manager. This tab creates a mock socket service you can use to verify the correct functionality of the web application and the websockets and can be used to simulate a real network socket service.
For development it is also useful the websockets section in the developer tools of Chrome. Here you can inspect all the traffic between the browser and the Hardware Manager.
Hardware manager window automatic registration
| | Starting from 19Q2 below functionality is available |
The Hardware Manager URL can be registered automatically in Hardware Manager window . In case, the mandatory properties of this functionality has been setted in the properties file the application will register its url while starting.
The application will call a web service that will be in charge to save the information. In order to be able to call the web service some configurations need to be done:
- User configuration: In order to work with a role related to the organization who owns the new hardware manager information, a role related to it should be stored as default at the profile user menu.
- Web service configuration: The role property “Is Web Service Enabled” should be checked in order to let the web service be called.
The following properties can be configured in the properties file:
Example:
## Auto Register HWM ## autoregister.url = http://localhost:8080/openbravo/ autoregister.store = Vall Blanca Store autoregister.user = Openbravo autoregister.pass = openbravo autoregister.preurl = https:// autoregister.posturl = :8190/printer autoregister.usehostname = true autoregister.name = Printer 1 autoregister.receiptprinter = true autoregister.pdfprinter = true |
- Url: It is the server address, it will be used to make the web service address. It is mandatory. It’s format will be the following <ServerUrl>+<Openbravo context>
- Store: It is the store search key and it’s mandatory.
- User: Openbravo user to access web service functionality. The user defined in Hardware Manager properties file must have access just for the services defined. It’s mandatory.
- Pass: Openbravo password to access web service functionality. It’s mandatory.
- Preurl: Part of the hardware manager url.
- Posturl: Part of the hardware manager url.
- Usehostname: It point out if the hardware manager url will be builded with hostname or with the ip address. It’s mandatory and its value must be true or false. If the usehostname parameter is true then the url will be build with the hostname parameter, in case its false, the url will be build with the ip address. Its format will be the following, <Autoregister.preurl> hostname or ip address <Autoregister.posturl>
- Name: Printer name. It’s mandatory.
- Receipt printer: It point out if the hardware manager can print receipts. It’s mandatory and its value must be true or false.
- Pdfprinter: It point out if the printer can print pdf documents. It’s mandatory and its value must be true or false.
FAQ
Troubleshooting
If the peripherals fail to work properly when using the Web POS GUI, the first step is to determine where the problem lies:
- Peripherals (drivers, connections, compatibility)
- Back office configuration
- HW Manager
The first thing which should be checked is whether the device itself works correctly and is correctly configured in the operating system. You should first attempt to use the device from the operating system directly, and see if it works. In case of scales, for example, you should verify that you can read weight measuring directly from the serial port. If that doesn't work, then you should contact the manufacturer.
In case the problem relies on the Hardware Manager part, a rough diagnosis can be made checking the following:
- If the HW Manager fails to start then the problem probably lies in the Java installation and settings on the local computer. The HW Manager uses Java that is deployed differently on different platforms which sometimes makes it necessary to add a path to environment variables in the operating system. This is typically the folder where the java.exe and javaw.exe files sit.
- Use the Printer and Scale tabs to test the peripherals. If output appears in the preview area but is not sent to the peripherals, then check the openbravohw.properties file to see whether the output is sent to the correct devices. For example, to use an Epson printer on the com1 port, you would use machine.printer = epson:file,com1:
- If this does not solve it, then the problem most likely lies in the peripherals itself and most probably the drivers
- If these tests do not generate any output in the preview area, then the problem most likely lies in the back office configuration.
USB configuration
USB support is based on the usb4Java libraries, if you find problems opening your USB device go to the document usb4java - FAQ.
In linux machines you need to have write permissions on the device file of the USB device you are going to use. To configure permissions to users you usually need to create a new file in /etc/udev/rules.d/ for example /etc/udev/rules.d/60-webposdevices.rules with the following content:
SUBSYSTEM=="usb",ATTR{idVendor}=="04b8",ATTR{idProduct}=="0202",MODE="0660",GROUP="openbravo"
With the USB vendor id and product id of the device connected.
To reload the rules execuint the following command:
sudo udevadm control --reload-rules
In Windows machines you must install a driver. The recommended way is tu use Zadig, an automated driver installer.
Serial and parallel port configuration
In linux machines several receipt printer and customer display manufacturers provide a system module for Linux that creates a device file like /dev/ttyUSB0 when the device is connected to an USB port.
In order for Linux to detect a USB-to-Serial device, the module ftdi_sio must be enabled in modprobe (not enabled by default in Ubuntu 14.04+ and Linux Mint Rebecca). If the device does not get mapped as /dev/ttyUSB0 right away (you can check that in /var/log/syslog), you have to manually add its ID to the config file of ftdi_sio.
For example, to create a new rule, enable ftdi_sio and add the device USB ID 0519:0007 to the ftdi_sio configuration, run:
SUBSYSTEM=="usb",ATTRS{idVendor}=="0519", ATTRS{idProduct}=="0007", RUN+="/sbin/modprobe", RUN+="/bin/sh -c 'echo 0519 0007 > /sys/bus/usb-serial/drivers/ftdi_sio/new_id'"
if it is needed to change the bauds, you need to aggregate the next line to udev rule:
KERNEL=="ttyUSB0", RUN+="/bin/stty -F /dev/ttyUSB0 19200 raw -echo"
To reload the rules execuint the following command:
sudo udevadm control --reload-rules
If it is a serial or a parallel you also need to have read and write permissions to the device file. For example with the following command you assign read and write permissions to the first parallel port.
sudo chmod 666 /dev/lp0