AML KDT750 series User manual

For models:
KDT750-XXXX

KDT750 APL Guide
PRE-1
Revision History
September 2008 - Initial revision
November 2008 - Add POST documentation, reformat and restructure

KDT750 APL Guide
PRE-2
© 2009 American Microsystems, Ltd. All rights reserved.
American Microsystems, Ltd. reserves the right to make changes in specifications and other
information contained in this document without prior notice, and the reader should in all
cases consult American Microsystems, Ltd. to determine whether any such changes have
been made. The information in this publication does not represent a commitment on the
part of American Microsystems, Ltd.
American Microsystems, Ltd. shall not be liable for technical or editorial errors or omissions
contained herein; nor for incidental or consequential damages resulting from the furnishing,
performance, or use of this material.
This document contains proprietary information which is protected by copyright.
All rights are reserved. No part of this document may be photocopied, reproduced or trans-
lated into another language without the prior written consent of American Microsystems,
Ltd.
American Microsystems, Ltd.
2190 Regal Parkway • Euless, TX 76040
Phone [phone] • Fax [phone]
www.amltd.com

KDT750 APL Guide
PRE-3
Table of Contents
About This Document
Introduction
Chapter Descriptions
Chapter 1 – Getting Started
Transaction Overview
Protocol Overview
AML Price Lookup Protocol
APL via TCP
APL via HTTP
Chapter 2 – AML Price Lookup Protocol
Transaction Overview
General Data Format
Lookup Request from Client to Server
Client to Server Event Names
Example APL Client to Server Events
Lookup Reply from Server to Client
Output Pairs and Action Pairs
Special Output Pairs
Available Action Pairs
Formatting Text Output
Example Field Format Pair
Chapter 3 – Using APL Over HTTP
Overview
HTTP POST
POST Reply
URL Encoding Data
Example Transactions
Example Server Source Code
Chapter 4 – Using APL Over a TCP Socket
Overview
General Packet Format
Example Transactions
Example TCP Server Design
TCP Server Source Code

KDT750 APL Guide
PRE-4
Chapter 5 – PCDemo
Introduction to PCDemo
PCDemo Operational Loop
Command Line Interface
Local Image Slide Show
Lookup Screen
Lookup Screen Background and Error Images
Text Fields
PRC Field Font
Colors
Example PCDemo Implementation
PCDemo on the KDT750
Appendix A – APL HTTP POST Transaction Examples with Screenshots

KDT750 APL Guide
PRE-5
About this Document
Introduction
This document describes the software interface protocol and system requirements for use of the
AML Price Lookup protocol (APL) and application software.
This document is provided as PRELIMINARY ONLY and is not intended as a complete product
reference. AML reserves the right to make changes to this document and to any hardware,
software or product it describes.
Chapter Descriptions
Chapter 1 – gives brief overview of APL and its intended uses
Chapter 2 – describes the AML Price Lookup (APL) protocol, which provides communication
between AML kiosk devices and a database lookup server or some other network device
Chapter 3 – describes how to implement APL via HTTP POST
Chapter 4 – describes using APL over a raw TCP socket connection
Chapter 5 – describes the KDT750 APL client application PCDemo

KDT750 APL Guide
1 - 1
Getting Started
This chapter gives a brief overview of
APL and its intended uses.

KDT750 APL Guide
1 - 2
Theory of Operation
APL was designed as a network based protocol for use in price verification and data lookup
environments. It is tailored for use where some given input data will be sent to a network
server followed by a meaningful response. Generally, this response will be parsed into text
based fields and displayed on an AML price checking kiosk terminal such as the KDT750.
Figure 1.1 - High Level Price Checking Implementation
Communication Protocol Overview
Both the kiosk client software and the lookup server must understand a common interfacing
protocol. To allow for easy integration into existing environments and to give the maximum
functionality to AML price checking systems, APL supports two high level communication
protocol methods – HTTP forms POST and raw TCP sockets. Each of these APL methods con-
tain the ability to send and receive the same data; only the format of the request and reply
differ.
APL: AML Price Lookup Protocol
APL was designed in an effort to simplify communication between price checking clients
and database servers. Compared to other price verification protocols, APL drastically
reduces the complexity of the server side software by limiting the client-server command set
to only the necessary instructions. By simplifying the protocol down to only the bare necessi-
ties, integration time is drastically reduced.

KDT750 APL Guide
1 - 3
APL via TCP
APL can utilize a standard raw TCP stream socket connection initiated by the client device
(KDT750) to a database server. In this method, the client opens the socket to the server,
sends the bar code data, receives a reply packet from the server and closes the connec-
tion. This reply is then parsed and the data is displayed on the LCD.
APL via TCP Features
• Fast communication with low overhead
• Simple, human readable packet format
• Extensible model for future custom enhancements
• Easily parsed with server-side scripts
• Fully functional server application source code provided
APL via HTTP
To allow for integration in environments where adding network services or opening new TCP
ports is not an option, APL can utilize the standard Hypertext Transfer Protocol's (HTTP) POST
operation. Here, APL acts as if it was a simple web client connecting to an HTTP service on
the server.
APL via HTTP POST Features
• Easily integrates into existing web server environments
• Simple web based development for server-side software
• Easily parsed with server-side scripts
• Fully functional server application source code provided

KDT750 APL Guide
2 - 1
APL
This chapter describes the AML Price
Lookup (APL) protocol, which provides
communication between AML kiosk
devices and a database lookup server or
some other network device.

KDT750 APL Guide
2 - 2
Transaction Overview
APL is a packet based, connection oriented protocol. For each lookup to the server, a new
connection is created, the request made, a reply sent and the connection destroyed.
Figure 2.1 - Typical AP Transaction
General Data Format
APL defines all messages between two devices as item/value pairs. Item/value pairs are a
collection of bytes defining a variable's name and its associated data, and are used to
communicate a variety of different actions, commands, and information between the host
and client.
Normally, the item name is separated from the value data by a standard ASCII equals (”=”)
sign. Data to the left of the equals sign is defined as the item's or action's name, whereas to
the right of the equals sign is defined as the value. The 'ITEM=VALUE' pair is normally ASCII
encoded, but depending upon the implementation, some characters may be required to
be encoded in a different format.
Here, the data is named “BAR”, and its value is “1234567890”:

KDT750 APL Guide
2 - 3
Lookup Request from Client to Server
A general request from a client device will have a single item/value pair. The ITEM (left of
equals sign) will denote the source of some event, and the VALUE (right of the equals sign)
will give the server the event's data. An event could be a user scanning a bar code with an
internal scanner, a swipe of a magnetic stripe card, a press of a pushbutton, or some other
external or internal action.
In the example given above, a bar code reader, denoted by the “BAR” ITEM was used to
scan a bar code that contained the data “1234567890”.
Client to Server Event Names
APL defines certain events that server applications should be aware of:

KDT750 APL Guide
2 - 4
Example APL Client to Server Events
A user scans a bar code with data of “1234567890” with the internal bar code reader:
A user swipes a magnetic stripe card with data of “John Doe” with the external MSR:
A user presses the left-most pushbutton on the front panel:
*Note: From left to right, the buttons on the front of
the KDT750 are conventionally called buttons A, B,
C and D. Other devices may use different
conventions.
A door bell switch connected to a digital input 2 was pressed (input going high):

KDT750 APL Guide
2 - 5
Lookup Reply from Server to Client
In response to a lookup request, the server should reply with meaningful data. In the most
basic of situations, the server will lookup the given data in a retail price database and reply
with the price of the item to be drawn on the LCD.
Figure 2.2 - Example Lookup Reply Screen
A server reply, like a client request, uses 'ITEM=VALUE' elements, but unlike the request, a
reply payload will typically contain multiple pairs. Each ITEM=VALUE pair will denote an
action that the client device should take (i.e., Turning on a digital output) or a text based
field that should be drawn on the LCD screen.
In the example lookup screen above, two output fields are present: one containing the price
(12.99) and the other containing the description (Designer Flower Pot...). The text at the top of
the screen is part of the background image and is not being actively drawn by APL.
Output Pairs and Action Pairs
Normally, in a lookup reply, the ITEM element corresponds to a text field on the screen and
the VALUE element to the text that should be displayed. Each valid element pair received
from the server will be drawn on the KDT750 LCD as a new text field. These output pairs can
have any non-restricted ITEM name as long as it contains only alpha-numeric characters.
This ITEM name is only used internally and must be unique.
A restricted ITEM name is one that is used for a special purpose action (turning on a digital

KDT750 APL Guide
2 - 6
output). These action pairs will tell the client device to act on some hardware, and will not
result in any data being drawn on the screen. A list of restricted names can be found in the
Available Action Pairs section of this document.
Special Output Pairs
Two special output names exist: “PRC” and “DES”. These output field names are predefined
with certain enhancements to allow more flexibility in “price+description” environments.
Available Action Pairs
Action pairs are' ITEM=VALUE' pairs that denote special actions or commands that the client
device should take. These element pairs will NOT be drawn on the LCD display in any way.

KDT750 APL Guide
2 - 7

KDT750 APL Guide
2 - 8
Formatting Text Output
To define a format for any given text output field, a special '@ITEM=VALUE' pair is used. The
name element will be the '@' symbol (ASCII 0x40) followed by the field name. For example,
the format name element for a 'PRC' field will be simply '@PRC'.
If no format '@ITEM=VALUE' pair exists in the packet, the client device will either ignore the
'ITEM=VALUE' pair or attempt to draw it using the following rules:
1.) If the PRC and DES fields exists, they will be drawn at their default locations with
default attributes. All other fields will be ignored.)
2.) If no PRC or DES fields exist and no fields contain '@ITEM=VALUE' pairs, the device
will draw the first two fields in the packet at the default PRC and DES locations and
discard all other field definitions.
The VALUE element will be a comma separated list of the field format variables in readable
ASCII text with all variables represented as decimal numbers:
@ITEM=<X>,<Y>,<W>,<H>,<FG>,<BG>
The available format variables are:

KDT750 APL Guide
2 - 9
Example Field Format Pair
The DES field will be located at x=70, y=200, width=500, height=150, foreground color is 0
and background of 120:

KDT750 APL Guide
3 - 1
Using APL Over HTTP
This chapter describes how to implement
APL via HTTP POST.

KDT750 APL Guide
3 - 2
Overview
HTTP (Hypertext Transfer Protocol) is the most common of all Internet protocols. Although it is
used primarily to fetch pages from web servers to display in a browser, it is actually a
general purpose transmission protocol. Since many large scale networks do not support
opening new TCP sockets but already host web based portals, APL has been designed to
use the HTTP POST method of sending and receiving data to and from a server.
HTTP POST
HTML forms already define a VALUE=ITEM style interface that works well when integrated
with APL. Following the APL guidelines, the client application will create POST data with the
appropriate request event name (BAR, INP, etc...) as a field name and the data value being
the supplied data.
For example, if an internal bar code reader was used to scan a bar code containing the
data “1234567890”, APL would post data to the server in the form of an input field named
“BAR” with a value of “1234567890”. If this data was actually coming from an HTML form, it
would have been formatted as such in HTML:
< input name="BAR" type="text" value='1234567890' />
POST Reply
The server side application or script should preform the desired action on the data and
supply a meaningful response to the user. ITEM=VALUE pairs in the reply should be sent as
plain text in the normal “ITEM=VALUE” format.
More often than not, this reply will contain multiple action or text output pairs.
When using HTTP POST, APL defines the separation between ITEM=VALUE pairs by a carriage
return or new line.
It is also important that the reply contains a valid HTTP header.
Example server reply:
Content-type: text/html
PARTNUM=P/N: 123789
@PARTNUM=200,200,240,35,35,50