DeviceAccess is a program that silently runs as a service on a machine and allows HTTP access to devices, such as printers and cash drawers. Primarily this is intended to allow tethered web browsers such as PDAs and tablets access to a range of devices that are not normally available.
Security is included in the system, and generally device access is only opened to a subset of users/network nodes.
The system works by allocating a unique identifier to every device, which can be used to reference that device regardless of how the host system changes the naming over time. Commands, such as print, open drawer or perform EFT funds request are directed to individual devices.
Some options can be directed generally and the system will decide the best device for use. An example is printing product or address labels, the client typically is not concerned which printer is used, just that it happens. This can save client applications from isolating which device should be used, but this can still be used in needed.
Available API Calls
- Get a List of Available Devices
- Send a Command to a Specific (single) Device
- Printer Description Block
"How to" Guides
- Include DeviceAccess.js into your web page
- Call DeviceAccessInit() to verify the connection. This can be done asynchronously via setTimeout() or similar technique.
Devices are controlled and operated by sending a command packet to them. This packet describes the intent of what you want to do, such as printing a receipt or opening the cash drawer.
Identifying the target device
The target device for the operation is given in f101. This should be one of the following
- A generic name, such as receipt, drawer, eftpos etc, which identifies the broad target device, but allows the server to select the exact device.
- An operational name, such as "deliverylabel", which is used when you wish to perform an action and have no real concern about how or where; allowing the server to select the best method.
- A physical device name when you wish to direct the command to a specific device.
Often, an application wishes to interact with a device to perform an action, but is not concerned with the exact internals of that operation. For example you may wish to print a delivery label for "Jane and Bob", but don't want to concern yourself with the specifics of where, media type, page layout and other details.
The DeviceAccess library supports these operational commands by defining specific command packets for these operations. You simply build a command packet and send this to the server to execute.
<DATI> <f8>localsystem.print.format</f8> // Code for delivery label <f100>142</f100> // Shipping address <f110_s>Jane and Bob|15 Here and There Street|Kelburn</f110_s> // Number of boxes, typically causes "box 1 of 3" type text and prints multiple copies <f115>3</f115> </DATI>
Low Level - Requesting Device List
A list of devices served on a host can be queried using the bucket localsystem.device.list
This bucket returns an ARAY of subpackets, where each packet is defined using the same schema but the type of the packet reflects the underlying device. A printer is returned in an 'AGPR' packet, while an eftpos terminal is returned in a 'EGEF' packet. Both of these packets contain fields based on the same schema.
|f101||ShortCode||Internal Device shortcode. A technical name that can be used to access an individual device.
These values are not designed for human use, although will be readable.
The following shortcodes are predefined as aliases which can be used by applications that just wish to select a device, rather than a specific device.
|f105||DevType||Type of device. 1=Printer, 2=Eftpos, 3=Cash Drawer|
|f110||Name of Printer Queue on System. Name of EFT Provider, Name of Cash Drawer|
|f111||Port printer uses on system|
|f112||PRINTER_INFO attributes (technical)|
|f115||Estimated Printer type (technical) mask|
|f116||Estimated Printer Type Name, Values are "Epson TM88-IV" etc|
|f117||Estimated Printer type. 1=Receipt Printer 2=Label Printer 3=Id/Credit Card Printer, 4=Document Printer|
|f200-f299||For printers, returns the conformance sets adhered too. (See section on printing)|
Response: Showing two printers
<ARAY> <AGPR> <f105>1</f105> <f110>Zebra LP2824</f110> <f101>Printer.0.0</f101> <f114>Zebra LP2824</f114> <f115>2</f115> <f116>Zebra LP2824</f116> <f117>2</f117> <f140>0</f140> <f141>0</f141> </AGPR> <AGPR> <f105>1</f105> <f110>TM88</f110> <f101>Printer.2.2</f101> <f114>EPSON TM-T88IV ReceiptE4</f114> <f115>1</f115> <f116>Epson TM-T88IV</f116> <f117>1</f117> <f140>0</f140> <f141>0</f141> </AGPR> </ARAY>
Low Level - Controlling Individual DevicesIndividual devices are controlled or made to perform an action with a DATI to localsystem.device.command
When writing to this bucket, you MUST set the target shortcode (f101 from localsystem.device.list) in f101, this is used to select the target device to execute the command.
|f101||ShortCode||ShortCode of device to execute this command||All|
|f105||DevType||Type of device. 1=Printer, 2=Eftpos, 3=Cash Drawer||All|
|f110||Command||Action to perform, such as print or open. This is a numeric value taken from the list below||All|
|f111||RefCode||Callers reference code (optional) used to identify this specific transaction. This allows you to request the status of a call later if communication is lost||All|
|f140||PurchAmt||Sets the primary amount of the EFT transaction, ie how much funds are requested. The format is NNNN.CC where NNNN is the "dollar" amount in numeric digits only. This is followed by a single dot or comma and then any optional "cents"||EFTPOS|
|f141||CashAmt||Sets the amount of Cash Out requested for eftpos fund requests.||EFTPOS|
|f142||EftRefCode||Reference Code to use for this transaction. This is the reference code sent to the EFT terminal and is rarely set specifically.||EFTPOS|
|f143||DisableAC||Account types to disable, if possible||EFTPOS|
|SubPackets||Extended device specific information||Several|
The overall command to be executed MUST be set in f110, with values taken from the following list:
|1||Open Cash Drawer||Y|
|2||Print a document or other output. Information to be printed is supplied in a sub-packet APPT||Y||Y|
|3||Reserved. Do not use. Print a document or other output. Information is supplied as a URL||Y||Y|
|4||Perform a visible test, such as printing a test page, changing display, or other such function depending on the device.||Y||Y||Y|
|100||Reserved for EFT terminals. Do not use.||Y|
|101||Perform an EFT logon process if required.||Y|
|104||Swipe Loyalty Card only||Y|
|110||Request Payment. Starts a payment request sequence with the customer.||Y|
The response packet will be of type QDNE, with the following fields.
|f500||Status||Overall Status of request -1=error; 0=pending/unknown; 1=complete/ok; 2=complete/failed||All|
|f511||RefCode||Transaction RefCode (f111) that was supplied as part of the request||All|
|f540||PurchAmt||Amount of money received||Eftpos|
|f541||CashAmt||Amount of cash out to be issued||Eftpos|
Some devices can process in different ways for the same command. This field returns information about how the device
is being used to process the command. It is a series of pipe seperated (case insensitive) keywords.
|f599||ResultMsg||Human readable technical result. Typically includes a technical description of failure root cause||All|
Low Level Packet Structure - Printing
Printers may indicate conformance levels to a field level by specifying the range of fields supported or not. If a field list is not provided, all fields are assumed intact.
Syntax N,Field-List eg <f200>M,!120-121</f200> We support Level A, but not f120 or f121. N can have the values 'Y' (full support) 'M' Majority support, unlikely to have material problems or 'S' some support, but wish to avoid this unless understood. 'N' no support.
A printer that has a ribbon with only red/black might use 'S' for the colour capabilities, indicating no real support, but there is some potential.
|f200||Conformance set 'A' Line Printing|
|f201||Conformance set 'B' Font Selection|
|f202||Conformance set 'C' Colour Capabilities|
|f202||Conformance set 'D' Extended Text Handling|
At the lowest level, DeviceAccess is responding to a HTTP POST transaction to the URL /GNAP/DATI?8=localsystem.device.command
|APPD||Subpacket||A series of command blocks to add text and images to the printed output.|
|f120||s||A Job name, an optional short descriptive text of what is being printed. Used in lists of printed jobs, identifying reprints and other user level functions.|
|f121||E||Number of copies to print. Not yet supported|
|f130-f139||Varies||Set default job font. See identically numbered fields in APPD packet for details|
Conformance Set 'A' - Simple Line Printing
|f100||String||A sequence of text to be printed|
|f101||Character||Positioning control. Can have the values 'L', 'C' or 'R' for left, center or right aligned on page.|
|f102||0/1||No advance flag. Normally after each piece of text is output, an internal line counter moves the cursor position to the next line. Setting this field to "1" indicates that this block of text should not advance the line counter. This would be used where you wish to print 2 or more pieces of text on the same line (such as a left and right aligned title). Set the NoAdvance flag on the first text drawn, so that the second appears on the same line. The last piece of text to be drawn on that line should not set this flag.|
|f103||Number||Node type. An indicator specifying
what type of information is contained in this node.
|f120||String||Define a column in a table. The string provides an optional column heading.|
|f121||Number||Set the column width to a size (width) rather than allowing the system to decide.|
|Advance vertically with whitespace|
|f150||Draw a line across the page|
|f130||s||Select Font face name|
Conformance Set 'B' - Font Selection
|Set font face|
|Bold, colour, italic|
Conformance Set 'C' - Colour Capabilities
Conformance Set 'D' - Extended Text Handling
|Text overflow actions, truncate, wrap, smaller font, overrun|
|Reverse colour (white on black)|
Conformance Set 'E' - Image Handling
Conformance Set 'F' - Retail Specific
|Print a barcode|
|Encode a magstripe card|
Conformance Set '' -
How to Print
How to Control EFTPOS Terminals
Request a list of EFT devices
Server will will respond with 0 or more EFT capable devices in AGEF packets. The server may easily return multiple devices so you must support selection of which terminal is to be used.
Create an XML as shown
<DATI> <f8>localsystem.device.command</f8> <f101>Eft.Debug.0</f101> // Set to ShortCode of actual Device <f110_E>101</f110_E> // Code 101 is EFT Logon request </DATI>Send the XML packet to http://...server.../gnap/DATI
Create an XML as shown
<DATI> <f8>localsystem.device.command</f8> <f101>Eft.Debug.0</f101> // Set to ShortCode of actual Device <f110_E>110</f110_E> // Code 110 is EFT payment request <f111>MyTxn.1</f111> // My transaction reference <f140>9.95</f140> // Amount </DATI>Send the XML packet to http://...server.../gnap/DATI
The Server response will be <QERR> if there is a failure to even start the transaction, or <QDNE> when the transaction is completed or in progress. Check the value of f500 in this QDNE packet, looking for a status of other than pending. You can continue to poll the server by sending the exact same packet again, the server takes this as an indication to return the result rather than start a new transaction.
<QDNE> <f500>0</f500> // f500=0 means still processing <f511>MyTxn.1</f511> // My transaction reference </QDNE>