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

Get a List of Available Devices
Send a Command to a Specific (single) Device
Printer Description Block

"How to" Guides

How to print a simple document
How to use an EFT terminal to request funds

Javascript

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.

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.

Field	Name	Description
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. 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.
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)
f114		Driver Name
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
Extended Information
f200-f299		For 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.

Field	Name	Description	Used By
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
f121	URL		Printer
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
f			EFTPOS

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

Command	Description	Applies too
		Receipt	Document	CashDrawer	EFTPOS
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
102	Settlement Enquiry				Y
103	Settlement Cutover				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.

Field	Name	Description	Used By
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
f598	ProcessingType	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
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.

Field	Description
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

APPT

Field	Type	Description
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

APPD

Conformance Set 'A' - Simple Line Printing

Field

Type

Description

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.

#	Description
0	Text node
1	Paragraph





10	Table Header
11	Table Row
12	Table Cell

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

Vertical alignment

f130

Select Font face name

f131

Conformance Set 'B' - Font Selection

Field	Type	Description
		Set font face
		Bold, colour, italic

Conformance Set 'C' - Colour Capabilities

Field	Type	Description

Conformance Set 'D' - Extended Text Handling

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

Conformance Set 'E' - Image Handling

Field	Type	Description

Conformance Set 'F' - Retail Specific

Field	Type	Description
		Print a barcode
		Encode a magstripe card

Conformance Set '' -

Field	Type	Description

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