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

Retail:Developers Guide/How-to/How to create a new device driver

Contents

Introduction

The POS Hardware Manager supports out of the box the most common receipt printers, fiscal printers, customer displays, scales and payment devices. But if you need to support a different device, the POS Hardware Manager provides a plugin architecture that allows you to develop and package in a java .jar file the support for new devices without having to recompile or modify the POS Hardware Manager code. This guide explains how to create and install new plugins for new devices.

Installing a POS Hardware Manager plugin

A POS Hardware Manager plugin is a java library packaged as a .jar file with a defined structure that allows the POS Hardware manager to discover and instantiate the drivers implemented in the plugin.

To install a POS Hardware manager plugin you only need to drop the .jar file into the subfolder libext/ located in the folder where the POS Hardware Manager is deployed. When started, the POS Hardware Manager, will find in all .jar files located in libext/ for plugins.

The POS Hardware Manager plugin structure

To recognise the drivers implementation in a POS Hardware Manager plugin, the project must use the following structure:

For receipt printers, fiscal printers, customer displays and scales, in the folder META-INF/services must go a text file with the name com.openbravo.pos.service.HardwareService. This file has to include a line with the full class name of the java class in your project that implements the java interface com.openbravo.pos.service.HardwareService This implementation will be used by the POS Hardware Manager to discover the device drivers implemented in the plugin. This plugin architecture is based on the service provider utilities included in the jvm. You can see how it works in detail in the ServiceLoader class API document.

The class that implements the interface com.openbravo.pos.service.HardwareService includes the following methods:

public DeviceDisplay getDisplay(String type, HardwareConfig hwconfig) throws Exception;
public DevicePrinter getPrinter(String type, HardwareConfig hwconfig) throws Exception;
public DeviceScale getScale(String type, HardwareConfig hwconfig) throws Exception;
public DeviceFiscalPrinter getFiscal(String type, HardwareConfig hwconfig) throws Exception;

For payment devices, it is similar, in the folder META-INF/services must go a text file with the name com.openbravo.pos.service.PaymentService. This file has to include a line with the full class name of the java class in your project that implements the java interface com.openbravo.pos.service.PaymentService

The class that implements the interface com.openbravo.pos.service.PaymentService includes the following method:

public DevicePayment getPayment(String type, HardwareConfig hwconfig) throws Exception;

The implementation of these methods must return null if you do not support the hardware device identified in the parameter type or a new java class instance that implements the driver expected by the method.

The second parameter contains the configuration information needed to instantiate the driver.

For example if your plugin includes a new receipt printer driver it should be configured in the openbravohw.properties this way:

machine.printer = sampleprinter:param1,param2

With this configuration your method getPrinter() will be invoked with the value sampleprinter in the parameter type and the values param1 and param2 in the hwconfig paramater. To know more about how the configuration of the POS Hardware Manager works, go through the Hardware and Peripherals Guide document.

Sample plugin project in Eclipse

Receipt printer drivers implementation

To create a new receipt printer driver you must create a java class that implements the interface com.openbravo.pos.printer.DevicePrinter. The methods of this interface follow closely the document specification for receipt printers described in the The receipt printer language document.

The methods to implement are:

Returns the printer name that will be displayed in the printer tab of the POS Hardware Manager UI.

Returns the description that will be displayed in the printer tab of the POS Hardware Manager UI. This description should show the configuration parameters used to instantiate the printer driver.

Returns null if there is no UI associated with the printer driver. If this method returns an instance of JComponent it will be displayed in the printer tab of the POS Hardware Manager UI.

Initializes the driver. This method is invoked from the POS Hardware Manager UI when executing the action Reset printers.

Indicates that a new receipt is going to be printed. It corresponds with the xml start tag <ticket>.

Indicates the driver to print an image. It corresponds with xml tag <image/> and is invoked only inside a receipt, between beginReceipt() and endReceipt() invocations.

Indicates the printer to print a barcode. It corresponds with the xml tab <barcoce/> and is invoked only inside a receipt, between beginReceipt() and endReceipt() invocations.

The recommended barcode types to implement are EAN13 or CODE128 but more barcode types can be implemented if your receipt printer supports it.

The position parameter indicates where to place the text that identifies the barcode and can be none, no text is printed, or bottom the text is printed bellow the barcode graphic.

The parameter code indicates the barcode to encode and print.

Indicates a new text line is going to be printed. It corresponds with the xml start tag <line> and is invoked only inside a receipt, between beginReceipt() and endReceipt() invocations.

The values for the iTextSize parameter can be:

0: Normal size
2: Double height
3: Double width
4: Double height, double width

Indicates the text to be printed inside a text line. It corresponds with the xml tag <text/> and is invoked only inside a line, between beginLine() and endLine() invocations.

The values for the iStyle parameter can be:

0: Plain text
1: Bold
2: Underlined
3: Bold and underlined

The sText parameter indicates the text to print.

Indicates that the line started with the method beginLine() is complete. Corresponds with the xml end tag </line>.

Indicates that the receipt started with the method beginReceipt() is complete. Corresponds with the xml end tag </ticket>.

Indicates the receipt printer to send the signal that opens the cash drawer. Corresponds with the xml tag <opendrawer/>.

Fiscal printer drivers implementation

To create a new fiscal printer driver you must create a java class that implements the interface com.openbravo.pos.printer.DeviceFiscalPrinter. The methods of this interface follow closely the document specification for fiscal printers described in the The fiscal receipt printer language document.

The methods to implement are:

Returns the fiscal name that will be displayed in the fiscal printer tab of the POS Hardware Manager UI.

Returns the description that will be displayed in the fiscal printer tab of the POS Hardware Manager UI. This description should show the configuration parameters used to instantiate the printer driver.

Returns null if there is no UI associated with the printer driver. If this method returns an instance of JComponent it will be displayed in the fiscal printer tab of the POS Hardware Manager UI.

Initializes the driver. This method is invoked from the POS Hardware Manager UI when executing the action Reset printers.

Tests the driver. This implementation should print a test receipt in the fiscal printer. This method is invoked from the POS Hardware Manager UI when executing the action Test printers.

Indicates that a new fiscal receipt is going to be printed. It corresponds with the xml start tag <fiscalreceipt>.

The parameter type indicates the fiscal document type. The possible values are:

nonfiscal: Defines a non fiscal document not registered in the fiscal memory of the device.
fiscal: Defines a fiscal document. This is the value that must be used for regular receipts given to customers when selling goods.
invoice: Defines a fiscal invoice. this is the value that must be used when it is needed to provide an invoice to the customer when selling goods.

The parameter cashier defines the cashier that created the receipt.

The parameter invnumber is only for fiscal documents of type invoice. Defines the invoice number.

The parameter taxnumber is only for fiscal documents of type invoice. Defines the tax identifier of the customer.

The parameter vatnumber is only for fiscal documents of type invoice. Defines the VAT identifier of the customer.

The parameter name is only for fiscal documents of type invoice. Defines the name of the customer.

The parameter address is only for fiscal documents of type invoice. Defines the address of the customer.

Indicates to print a new line. It corresponds with the xml tag <line/> and is invoked only inside a receipt, between beginReceipt() and endReceipt() invocations.

The parameter sproduct defines the product name.

The parameter dprice defines the unit price.

The parameter dunits define the units.

The parameter taxinfo defines the tax identifier for this line.

The parameter discount defines the percentage discount applied for this line. If negative is a discount, if positive an extra charge. By default is 0.

Indicates to print a message. It corresponds with the xml tag <message/> and is invoked only inside a receipt, between beginReceipt() and endReceipt() invocations.

The parameter style defines the style for the text message. The possible values are:

normal. Prints the message with no styles. It is the default value.
bold. Prints the message in bold.
italic. Prints the message in italic.
underline. Prints the message underlined.
doublewidth. Prints the message with double width typeface.
doubleheight. Prints the message with double height typeface.

The parameter smessage defines the text to print.

Adds a percentage discount to the total of the receipt. It corresponds with the xml tag <totaldiscount/> and is invoked only inside a receipt, between beginReceipt() and endReceipt() invocations.

The parameter discount defines the percentage to apply to the total of the receipt. If negative is a discount, if positive an extra charge.

Adds an service charge to the total of the receipt. It corresponds with the xml tag <servicecharge/> and is invoked only inside a receipt, between beginReceipt() and endReceipt() invocations.

The parameter amount defines the service charge to apply to the total of the receipt. If negative is a discount, if positive an extra charge.

Adds a payment to the receipt. It corresponds with the xml tag <total/> and is invoked only inside a receipt, between beginReceipt() and endReceipt() invocations.

The parameter paymentId defines the payment identifier.

The parameter paymentName defines the name of the payment identifier.

The parameter amount defines amount paid.

Indicates that the fiscal receipt started with the method beginReceipt() is complete. Corresponds with the xml end tag </fiscal>.

Defines and prints a cash management movement for fiscal printers. It corresponds with the xml tag <cashmanagement/>.

The parameter payment defines the payment identifier. The parameter name defines the name of the payment identifier. The parameter amount defines amount paid.

Prints a fiscal Z report. It corresponds with the xml tag <fiscalzreport/>.

Prints a fiscal X report. It corresponds with the xml tag <fiscalxreport/>.

Customer display drivers implementation

To create a new customer display driver you must create a java class that implements the interface com.openbravo.pos.printer.DeviceDisplay. The methods of this interface follow closely the document specification for customer displays described in the The customer display language document.

The methods to implement are:

Returns the customer display name that will be displayed in the printer tab of the POS Hardware Manager UI.

Returns the description that will be displayed in the printer tab of the POS Hardware Manager UI. This description should show the configuration parameters used to instantiate the customer display driver.

Returns null if there is no UI associated with the customer display. If this method returns an instance of JComponent it will be displayed in the fiscal printer tab of the POS Hardware Manager UI.

Prints the values of the parameters sLine1 and sLine2 in the customer display.

The possible values for the animation parameter are:

0: Text is not animated. This is the default value.
1: Text appears from the right.
2: Text is scrolling in the display from right to left continuously.
3: Text blinks continuously.
4: Text appears behind a virtual curtain.

To help to implement the animated text you can use the utility class DeviceDisplayBase that hides the complexity of running the display animations if your customer display does not implements it natively.

Cleans the customer display.

Scale drivers implementation

To create a new scale driver you must create a java class that implements the interface com.openbravo.pos.scale.DeviceScale.

The methods to implement are:

Returns the scale name that will be displayed in the scale tab of the POS Hardware Manager UI.

Returns the description that will be displayed in the scale tab of the POS Hardware Manager UI. This description should show the configuration parameters used to instantiate the scale driver.

Returns null if there is no UI associated with the scale. If this method returns an instance of JComponent it will be displayed in the scale tab of the POS Hardware Manager UI.

Reads the weight in the scale and returns it.

Payment device driver implementation

To create a new payment device driver you must create a java class that implements the interface com.openbravo.pos.payment.DevicePayment.

The methods to implement are:

Returns the payment device name that will be displayed in the payment tab of the POS Hardware Manager UI.

Returns the description that will be displayed in the payment tab of the POS Hardware Manager UI. This description should show the configuration parameters used to instantiate the payment device driver.

Returns null if there is no UI associated with the payment device. If this method returns an instance of JComponent it will be displayed in the payment tab of the POS Hardware Manager UI.

Processes a payment. The details of the payment comes in the PaymentRequest params parameter that has the java type com.openbravo.pos.payment.PaymentRequest and must return a new instance of the java type com.openbravo.pos.payment.PaymentResult with the results of the payment transaction.

The java type com.openbravo.pos.payment.PaymentRequest has the following properties:

The java type com.openbravo.pos.payment.PaymentResult has the following properties:

RFID device driver implementation

To create a new RFID device driver you must create a java class that implements the interface com.openbravo.pos.rfid.DeviceRFID.

The methods to implement are:

Returns the RFID device name that will be displayed in the RFID tab of the POS Hardware Manager UI.

Returns the description that will be displayed in the RFID tab of the POS Hardware Manager UI.

Returns null if there is no UI associated with the RFID device. If this method returns an instance of JComponent it will be displayed in the RFID tab of the POS Hardware Manager UI.

Returns a instance of a class that implements WebSocketCreator

This class, on its createWebSocket method has to return a class that extends com.openbravo.poshw.WebSocketHandler.

The methods to override are:

This method is called when the connection is closed.

This method is called when an error occurs.

This method is called when the connection is established.

This method in called every time a message is received through the WebSocket.

Retrieved from "http://wiki.openbravo.com/wiki/Retail:Developers_Guide/How-to/How_to_create_a_new_device_driver"

This page has been accessed 10,412 times. This page was last modified on 25 April 2016, at 11:08. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.