Fieldpine Logo Documentation Home  

Device Access


Jump to: Overview | Programming

Overview

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.

Programming

Available API Calls

"How to" Guides

Javascript

  1. Include DeviceAccess.js into your web page
  2. Call DeviceAccessInit() to verify the connection. This can be done asynchronously via setTimeout() or similar technique.
  3. ....

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

Operational Commands

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.

Example:

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

FieldNameDescription
f101ShortCodeInternal 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.

  • Receipt Select a receipt style printer
  • Document Select a document printer, such as an A4 desk printer
  • EFT Select an EFTPOS device
  • CashDrawer Select a Cash Drawer
  • Scanner Select barcode scanner
  • Scale Select scales
  • Pole Select a customer Pole Display
  • Display Select a customer Display screen
  • Label(NNN) Select a label printer
  • IdCard Select an Identity/Credit Card printer
The predefined values will not be returned in this field, the device specific id will always be returned.
f105DevTypeType of device. 1=Printer, 2=Eftpos, 3=Cash Drawer
f110Name of Printer Queue on System. Name of EFT Provider, Name of Cash Drawer
f111Port printer uses on system
f112PRINTER_INFO attributes (technical)
f114Driver Name
f115Estimated Printer type (technical) mask
f116Estimated Printer Type Name, Values are "Epson TM88-IV" etc
f117Estimated Printer type. 1=Receipt Printer 2=Label Printer 3=Id/Credit Card Printer, 4=Document Printer
Extended Information
f200-f299For printers, returns the conformance sets adhered too. (See section on printing)

Example

Call: http://..server../gnap/buck?3=localsystem.device.list

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 Devices

Individual 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.

FieldNameDescriptionUsed By
f101ShortCodeShortCode of device to execute this commandAll
f105DevTypeType of device. 1=Printer, 2=Eftpos, 3=Cash DrawerAll
f110CommandAction to perform, such as print or open. This is a numeric value taken from the list belowAll
f111RefCodeCallers reference code (optional) used to identify this specific transaction. This allows you to request the status of a call later if communication is lostAll
f121URLPrinter
f140PurchAmtSets 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
f141CashAmtSets the amount of Cash Out requested for eftpos fund requests.EFTPOS
f142EftRefCodeReference Code to use for this transaction. This is the reference code sent to the EFT terminal and is rarely set specifically.EFTPOS
f143DisableACAccount types to disable, if possibleEFTPOS
SubPackets Extended device specific informationSeveral
fEFTPOS

The overall command to be executed MUST be set in f110, with values taken from the following list:

CommandDescriptionApplies too
  ReceiptDocumentCashDrawerEFTPOS
1Open Cash Drawer  Y 
2Print a document or other output. Information to be printed is supplied in a sub-packet APPTYY  
3Reserved. Do not use. Print a document or other output. Information is supplied as a URLYY  
4Perform a visible test, such as printing a test page, changing display, or other such function depending on the device.YY Y
      
100Reserved for EFT terminals. Do not use.   Y
101Perform an EFT logon process if required.   Y
102Settlement Enquiry   Y
103Settlement Cutover   Y
104Swipe Loyalty Card only   Y
110Request Payment. Starts a payment request sequence with the customer.   Y

The response packet will be of type QDNE, with the following fields.

FieldNameDescriptionUsed By
f500StatusOverall Status of request -1=error; 0=pending/unknown; 1=complete/ok; 2=complete/failed All
f511RefCodeTransaction RefCode (f111) that was supplied as part of the requestAll
f540PurchAmtAmount of money receivedEftpos
f541CashAmtAmount of cash out to be issuedEftpos
f598ProcessingType 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.
  • interfaced Used by EFT subsystems to indicate that commands can be sent to pinpads, but response may not always be available and operator involvement may be needed.
All
f599ResultMsgHuman readable technical result. Typically includes a technical description of failure root causeAll

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.

FieldDescription
f200Conformance set 'A' Line Printing
f201Conformance set 'B' Font Selection
f202Conformance set 'C' Colour Capabilities
f202Conformance 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

APPT

FieldTypeDescription
APPDSubpacketA series of command blocks to add text and images to the printed output.
f120sA 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.
f121ENumber of copies to print. Not yet supported
f130-f139VariesSet default job font. See identically numbered fields in APPD packet for details

APPD

Conformance Set 'A' - Simple Line Printing

FieldTypeDescription
f100StringA sequence of text to be printed
f101Character Positioning control. Can have the values 'L', 'C' or 'R' for left, center or right aligned on page.
f1020/1No 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.
f103NumberNode type. An indicator specifying what type of information is contained in this node.
#Description
0Text node
1Paragraph
10Table Header
11Table Row
12Table Cell
f120StringDefine a column in a table. The string provides an optional column heading.
f121NumberSet the column width to a size (width) rather than allowing the system to decide.
Advance vertically with whitespace
f150Draw a line across the page
Vertical alignment
f130sSelect Font face name
f131

Conformance Set 'B' - Font Selection

FieldTypeDescription
Set font face
Bold, colour, italic

Conformance Set 'C' - Colour Capabilities

FieldTypeDescription

Conformance Set 'D' - Extended Text Handling

FieldTypeDescription
Text overflow actions, truncate, wrap, smaller font, overrun
Rotate
Vertical printing
Reverse colour (white on black)

Conformance Set 'E' - Image Handling

FieldTypeDescription

Conformance Set 'F' - Retail Specific

FieldTypeDescription
Print a barcode
Encode a magstripe card

Conformance Set '' -

FieldTypeDescription

How to Print


How to Control EFTPOS Terminals

Request a list of EFT devices

.../gnap/buck?3=localsystem.device.list&9=f100,0,eftpos

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.

Logon

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

Request Payment

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>