View source | Discuss this page | Page history | Printable version   

Retail:Hardware and Peripherals Installation

Back to main page

Contents

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

Archi4.png

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.

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.


Bulbgraph.png   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

Bulbgraph.png   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

Bulbgraph.png   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:

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:

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:

Hardware Manager with Secure HTTP (HTTPS)

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.

Bulbgraph.png   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.

Bulbgraph.png   Note: The following images correspond to version RR18Q2 and greater
Hardware manager test page
Hardware manager status page


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

Add to the folder libext/ new java .jar files required by the hardware manager and to the folder cpext/ new java .class files.

Bulbgraph.png   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.

Bulbgraph.png   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:

Bulbgraph.png   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:

From 16Q2 an onwards:

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.

Bulbgraph.png   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:

Finally, and separated by a "comma", you decide the paper type:

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.

Drawable area

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
Bulbgraph.png   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
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

Bulbgraph.png   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

Bulbgraph.png   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

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:

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
Bulbgraph.png   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:

  1. genericcontinuous. For scales sending information in continuous mode. The format of the returned information is configurable
  2. 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.
  3. samsung. The scale command code sent is $. The weight is returned in kilos.
  4. dialog1. The scale command code sent is 0x05. The weight is returned in grams
  5. 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:

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:

  1. machine.scale. genericcontinuous.final. The java encoded character that indicates the end of the response
  2. 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.
  3. 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:

  1. machine.scale.generic.command. The command sent to the printer to request the weight
  2. machine.scale.generic.final. The java encoded character that indicates the end of the response
  3. 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.
  4. 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:

  1. Device: Name of the device.
  2. Port: Name of the port in which the device is connected.
  3. 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.
  4. Read Power: Default: 500.
  5. Q-Factor: Default: 255.
  6. Session: Default: 0.
  7. Miller Code: Default: 0.
  8. Reading Cicle: Default: 300.
  9. Channel: Default 1.
  10. 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:

RFIDIntegration4.png

Sockets proxy

Bulbgraph.png   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.

SocketsProxy.png


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:

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

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.

SocketsPanel.png

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.

WebSocketsChrome.png

Hardware manager window automatic registration

Bulbgraph.png   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:

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
  1. 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>
  2. Store: It is the store search key and it’s mandatory.
  3. 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.
  4. Pass: Openbravo password to access web service functionality. It’s mandatory.
  5. Preurl: Part of the hardware manager url.
  6. Posturl: Part of the hardware manager url.
  7. 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>
  8. Name: Printer name. It’s mandatory.
  9. Receipt printer: It point out if the hardware manager can print receipts. It’s mandatory and its value must be true or false.
  10. 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:

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:

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

Retrieved from "http://wiki.openbravo.com/wiki/Retail:Hardware_and_Peripherals_Installation"

This page has been accessed 45,201 times. This page was last modified on 19 January 2023, at 09:58. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.