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.
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:
- public String getPrinterName();
Returns the printer name that will be displayed in the printer tab of the POS Hardware Manager UI.
- public String getPrinterDescription();
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.
- public JComponent getPrinterComponent();
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.
- public void reset();
Initializes the driver. This method is invoked from the POS Hardware Manager UI when executing the action Reset printers.
- public void beginReceipt();
Indicates that a new receipt is going to be printed. It corresponds with the xml start tag <ticket>.
- public void printImage(BufferedImage image);
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.
- public void printBarCode(String type, String position, String code);
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.
- public void beginLine(int iTextSize);
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
- public void printText(int iStyle, String sText);
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.
- public void endLine();
Indicates that the line started with the method beginLine() is complete. Corresponds with the xml end tag </line>.
- public void endReceipt();
Indicates that the receipt started with the method beginReceipt() is complete. Corresponds with the xml end tag </ticket>.
- public void openDrawer();
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:
- public String getFiscalName();
Returns the fiscal name that will be displayed in the fiscal printer tab of the POS Hardware Manager UI.
- public String getFiscalDescription();
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.
- public JComponent getFiscalComponent();
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.
- public void reset() throws HardwareException;
Initializes the driver. This method is invoked from the POS Hardware Manager UI when executing the action Reset printers.
- public void test() throws HardwareException;
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.
- public void beginReceipt(String type, String cashier) throws HardwareException; and public void beginReceipt(String type, String cashier, String invNumber, String taxNumber, String vatNumber, String name, String address) throws HardwareException;
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.
- public void printLine(String sproduct, double dprice, double dunits, int taxinfo) throws HardwareException; and public void printLine(String sproduct, double dprice, double dunits, int taxinfo, double discount) throws HardwareException;
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.
- public void printMessage(String style, String smessage) throws HardwareException;
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.
- public void printDiscount(double discount) throws HardwareException;
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.
- public void printServiceCharge(double amount) throws HardwareException;
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.
- public void printTotal(int paymentId, String paymentName, double amount) throws HardwareException;
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.
- public void endReceipt() throws HardwareException;
Indicates that the fiscal receipt started with the method beginReceipt() is complete. Corresponds with the xml end tag </fiscal>.
- public void printCashManagement(int paymentId, String paymentName, double amount) throws HardwareException;
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.
- public void printZReport() throws HardwareException;
Prints a fiscal Z report. It corresponds with the xml tag <fiscalzreport/>.
- public void printXReport() throws HardwareException;
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:
- public String getDisplayName();
Returns the customer display name that will be displayed in the printer tab of the POS Hardware Manager UI.
- public String getDisplayDescription();
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.
- public JComponent getDisplayComponent();
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.
- public void writeVisor(String sLine1, String sLine2); and public void writeVisor(int animation, String sLine1, String sLine2);
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.
- public void clearVisor();
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:
- public String getScaleName();
Returns the scale name that will be displayed in the scale tab of the POS Hardware Manager UI.
- public String getScaleDescription();
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.
- public JComponent getScaleComponent();
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.
- public Double readWeight() throws ScaleException;
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:
- public String getName();
Returns the payment device name that will be displayed in the payment tab of the POS Hardware Manager UI.
- public String getDescription();
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.
- public JComponent getComponent();
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.
- public PaymentResult execute(PaymentRequest params);
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:
- int type. The transaction type code. It has the following possible values: TYPE_SALE for sales transactions, TYPE_REFUND for refund transactions, or TYPE_VOID to void a previous transaction.
- String transactionID. The related transaction identifier for transactions of type TYPE_REFUND or TYPE_VOID.
- String terminalID The terminal identifier that requests this transaction.
- String currency. The currency code of this transaction. It must follow the ISO 4217 standard. For example EUR for Euro currency, USD for USA Dollar currency.
- BigDecimal amount. The amount to transact.
- JSONObject properties. Extra properties as parameters for this transaction.
The java type com.openbravo.pos.payment.PaymentResult has the following properties:
- int result'. The transaction result code. It has the following possible values: RESULT_SUCCESS, RESULT_AUTHORIZATION_FAIL or RESULT_ERROR.
- String resultCode. The native result code returned by the payment device.
- String resultMessage. The native result message returned by the payment device.
- String transactionID. The transaction identifier for the transaction. This identifier can be used in next transactions to reference it.
- String authorizationID. The authorization identifier for the transaction.
- PaymentRequest request. The original payment request.
- JSONObject properties. Extra properties returned for this transaction.
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:
- public String getName();
Returns the RFID device name that will be displayed in the RFID tab of the POS Hardware Manager UI.
- public String getDescription();
Returns the description that will be displayed in the RFID tab of the POS Hardware Manager UI.
- public JComponent getComponent();
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.
- public WebsocketCreator getRFIDWebSocketCreator();
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:
- public synchronized void onClose();
This method is called when the connection is closed.
- public void onError();
This method is called when an error occurs.
- public void onConnect();
This method is called when the connection is established.
- public void onMessage(String message);
This method in called every time a message is received through the WebSocket.