IDTECH VersaKey IDKA-2331 User manual

USER MANUAL
VersaKey
with
USB-HID Reader Interface
INTERFACE REFERENCE
80074503-001-A
Copyright © 2006, International Technologies & systems Corporation. All rights reserved.
Page 1 of 11

Copyright © 2006, International Technologies & systems Corporation. All rights reserved.
Page 2 of 11
Please see the VersaKey Quick Start Manual for the following information:
FCC WARNING STATEMENT
FCC COMPLIANCE STATEMENT
CE STANDARDS
LIMITED WARRANTY
The information contained herein is provided to the user as a convenience. While every
effort has been made to ensure accuracy, ID TECH assumes no responsibility, for its use,
nor for any infringements on patents or other rights of third parties that may result from its
use. ID TECH is not responsible for damages that might occur because of errors or
omissions, including any loss of profit or other commercial damage. The specifications
described herein were current at the time of publication, but are subject to change at any
time without notice.
ID TECH is a registered trademark of International Technologies & Systems Corporation.
Spectrum and Value through Innovation are trademarks of International Technologies &
Systems Corporation.
ID TECH
10721 Walker Street
Cypress, CA 90630
[phone]
ISO 9001-2000

VersaKey with USB-HID Reader Interface
TABLE OF CONTENTS
1.0 Introduction..............................................................................................................................4
2.0 The HID interface, General Information.................................................................................4
2.1 Installation..................................................................................................................................4
2.2 Operation...............................................................................................................................5
3.0 The HID interface, Technical Information .............................................................................5
3.1 Data Structure ...........................................................................................................................6
3.2 Format Data Structure...............................................................................................................6
3.4 IDTECH format..........................................................................................................................7
3.5 Descriptor Tables ......................................................................................................................7
Device Descriptor............................................................................................................................7
Configuration Descriptor..................................................................................................................8
Interface Descriptor.........................................................................................................................8
HID Descriptor.................................................................................................................................8
End Pointer Descriptor....................................................................................................................9
Report Descriptor, (ID TECH Setting).............................................................................................9
4.0 HID Usages.............................................................................................................................10
4.1 IDTECH format reader usage page 0xff00..............................................................................10
4.3 Mag-Tek format reader usage page 0xff00.............................................................................11
4.2 Commands and responses......................................................................................................11
Copyright © 2006, International Technologies & systems Corporation. All rights reserved.
Page 3 of 11

VersaKey with USB-HID Reader Interface
1.0 Introduction
The scope of this document pertains specifically to USB VersaKey keyboards with
MagStripe readers, where the keyboard & reader USB interfaces are of two different
device classes. The keyboard interface is a typical USB Keyboard; the MagStripe
reader interface is USB-HID. The data transmitted for both is over the single
keyboard communication cable.
This document provides two sections of information. The first section is general
information of the USB interfaces, the reader, and its operation in the VersaKey
keyboard. The second section provides technical information for the reader USB-
HID interface. The second section is typically for applications programmers needing
information to develop software applications.
A demo program with its source code is available, written in Visual Basic, and
operates with the reader using the standard Windows HID API. Visit the ID TECH
website: www.idtechproducts.com
2.0 The HID interface, General Information
Some VersaKey product models provide an integral MagStripe reader having a
USB-HID communication interface. The reader is a “vendor defined HID device”
so that a direct communication path can be established with an application.
The reader conforms to the USB Human Interface Device (HID) Class
specification Version 2.0. Host applications designed for the latest versions of
Windows 98, Me, 2000, XP can easily communicate to the reader using standard
Windows API calls.
The reader conforms to ISO/IEC 7811 standards. The reader is compatible with
personal computers or device with a USB interface.
2.1 Installation
There are two separate USB communications interfaces using the single
keyboard communication cable. Connect the VersaKey USB cable to a host
USB port. The keyboard interface is “plug-n-play” and the keyboard functions
immediately after the cable is connected. The reader has an independent USB-
HID communication interface; some set-up may be required.
Copyright © 2006, International Technologies & systems Corporation. All rights reserved.
Page 4 of 11

VersaKey with USB-HID Reader Interface
The first time the keyboard is plugged into a specific USB port, the MagStripe
reader is recognized as a separate device, and Windows presents a pop-up
dialog box. The pop-up box guides one through the process of installing the HID
device driver for the reader. After this process is completed once, Windows no
longer request this process as long as the device is plugged into the same USB
port. The device driver that Windows installs for this device is a driver used for
HID devices and it is part of the Windows operating system. Most Windows
systems finds the drivers needed without additional prompts. In some cases, the
Windows system needs to know the location of the drivers.
2.2 Operation
The keyboard and reader operate as outlined in the VersaKey Quick Start
Manual, Part Number: 80074502-001.
Although, the reader communication data interface is separate, the reading
operation remains the same. The card data is accepted into the Windows
system USB HID input report where the card data can be used by a specific card
operations application. Card data is not mixed with the keyboard character
information.
3.0 The HID interface, Technical Information
The reader conforms to the USB specification revision 2.0. This device also
conforms to the Human Interface Device (HID) class specification version 2.0. The
reader communicates to the host as a vendor defined HID device. The details
about how the card data and commands are structured into HID reports follow later
in this section. The latest versions of the Windows operating systems, Windows 98,
Me, 2000, and XP all come with a standard Windows USB HID driver. Windows
applications that communicate to this reader can be easily developed. These
applications can communicate to the reader using standard windows API calls that
communicate to the reader using the standard Windows USB HID driver. These
applications can be easily developed using compilers such as Microsoft’s Visual
Basic or Visual C++. A demonstration program and its source code, written in
Visual Basic, that communicates with this reader is available. This demo program
can be used to test the reader and it can be used as a guide for developing other
applications.
Developers should become familiar with the HID specification and the USB
specification before attempting to communicate with the reader. This document
assumes the developer is familiar with these specifications. Specifications can be
downloaded free from www.usb.org.
Copyright © 2006, International Technologies & systems Corporation. All rights
reserved.
Page 5 of 11

VersaKey with USB-HID Reader Interface
This is a full speed USB reader. The reader has a number of programmable
configuration properties. These properties are stored in non-volatile EEPROM
memory. These properties can be configured at the factory or by the end user. The
reader has an adjustable endpoint descriptor polling interval value that can be set
to any value in the range of 1ms to 255ms. This property can be used to change
the speed of the card data transfer rate.
3.1 Data Structure
The USB HID Reader supports the ID TECH data Structure with an EEPROM
setting.
USB HID Data Format Setting:
Setting A: ID TECH Data Format (Default setting) Product ID: 0500
When the reader is initially plugged in, the Firmware reads the "Data Format
Setting" from EEPROM and send current Product ID in enumeration. Each time
after changing the "Data Format Setting", the firmware saves the setting to
EEPROM then re-do the enumeration process. (On occasion, the reader needs to
be disconnected and connected again to switch the data format.)
3.2 Format Data Structure
Offset Usage Name .
0 T1 decode status
1 T2 decode status
2 T3 decode status
3 T1 data length
4 T2 data length
5 T3 data length
6 Card encode type
7, 8 Total Output Length
9-508 Output Data
In this approach, the reader keeps all of the ID TECH data editing and other
features like preamble, postamble, etc. The output data is always 500 bytes;
the "Total Output Length" field indicates the valid data length in the output
data.
Copyright © 2006, International Technologies & systems Corporation. All rights reserved.
Page 6 of 11

VersaKey with USB-HID Reader Interface
3.4 IDTECH format
T1, T2 or T3 decode status: 0 for no error, 1 for error
T1, T2 or T3 Data Length: Each byte value indicates how many bytes of decoded
card data are in the track data field. This value is set to zero if there was no data
on the track or if there was an error decoding the track. The track data includes all
data string starting with the start sentinel and ending with the end sentinel.
Card Encode Type:
Value Encode TypeDescription
0 ISO/ABA ISO/ABA encode format
1 AAMVA AAMVA encode format
2 CADL California Driver License
3 Blank The card is blank
4 Other The card has a non-standard format.
For example, ISO/ABA track 1 format on track 2
3.5 Descriptor Tables
Device Descriptor
Field Value Description
Length 12
Des type 01
bcd USB 10 01
Device Class 03
Sub Class 00 Unused
Device Protocol 00 Unused
Max Packet Size 20 32 bytes
VID CD 0A
PID 00 05
/ 10 05 With ID TECH Structure With MagTech Structure
BCD Device Release 00 01
i-Manufacture 01
i-Product 02
i-Serial-Number 00
# Configuration 01
Copyright © 2006, International Technologies & systems Corporation. All rights reserved.
Page 7 of 11

VersaKey with USB-HID Reader Interface
Configuration Descriptor
Field Value Description
Length 09
Des type 02
Total Length 22 00
No. Interface 01
Configuration Value 01
iConfiguration 00
Attributes 80 Bus power, no remove wakeup
Power 32 100 mA
Interface Descriptor
Field Value Description
Length 09
Des type 04
Interface No. 00
Alternator Setting 00
# EP 01
Interface Class 03 HID
Sub Class 00
Interface Protocol 00
iInterface 00
HID Descriptor
Field Value Description
Length 09
Des type 21 HID
bcdHID 11 01
Control Code 00
numDescriptors 01 Number of Class Descriptors to follow
DescriptorType 22 Report Descriptor
37 00 For ID TECH FormatDescriptor Length
Copyright © 2006, International Technologies & systems Corporation. All rights reserved.
Page 8 of 11

VersaKey with USB-HID Reader Interface
End Pointer Descriptor
Field Value Description
Length 07
Des Type 05 End Point
EP Addr 81 EP1 - In
Attributes 03 Interrupt
MaxPacketSize 20 00
bInterval 0A
Report Descriptor, (ID TECH Setting)
Field Value Description
06 00
FF Usage Page (MSR)
09 01 Usage(Decoding Reader)
A1 01 Collection (Application)
15 00 Logical Minimum
26 FF
00 Logical Maximum
75 08 Report Size
09 20 Usage (Tk1 Decode Status)
09 21 Usage (Tk2 Decode Status)
09 22 Usage (Tk3 Decode Status)
09 28 Usage (Tk1 Data Length)
09 29 Usage (Tk2 Data Length)
09 2A Usage (Tk3 Data Length)
09 38 Usage (Card Encode Type)
95 07 Report Count
81 02 Input (Data,Var,Abs,Bit Field)
09 30 Usage (Total Sending Length)
95 02 Report Count (2)
82 02
01 Input (Data, Var, Abs, Bit Field)
09 31 Usage (Output Data)
96 F4
01 Report Count (328*)
82 02
01 Input (Data, Var, Abs, Bit Field)
09 20 Usage (Command Message)
95 20 Report Count
B2 02
01 Feature (Data,Var, Abs, Buffered Bytes)
C0 End Collection
Copyright © 2006, International Technologies & systems Corporation. All rights reserved.
Page 9 of 11

VersaKey with USB-HID Reader Interface
4.0 HID Usages
This HID reader sends data reports. Elements of data in a report are identified by
unique identifiers called usages. The structure of the reader’s reports and the
reader’s capabilities are reported to the host in a report descriptor. The host
usually gets the report descriptor only once and after the reader is powered. The
report descriptor usages identify the reader’s capabilities and report structures.
Usages are four byte integers. Standardized usages such as usages for mice and
keyboards can be found in the HID Usage Tables document and can be
downloaded free at www.usb.org. Vendor defined usages must have a usage
page in the range 0xff00 – 0xffff. All usages for this device use vendor defined
magnetic stripe reader usage page 0xff00. The usage IDs for this device are
defined in the following table. The usage types are also listed. These usage types
are defined in the HID Usage Tables document.
4.1 IDTECH format reader usage page 0xff00
1 Decoding reader device Collection None
20 Track 1 decode status Data Input
21 Track 2 decode status Data Input
22 Track 3 decode status Data Input
28 Track 1 data length Data Input
29 Track 2 data length Data Input
2A Track 3 data length Data Input
38 Card encode type Data Input
30 Total Data Length Data Input
31 Output Data Data Input
20 Command message Data Feature
Copyright © 2006, International Technologies & systems Corporation. All rights reserved.
Page 10 of 11

VersaKey with USB-HID Reader Interface
4.3 Mag-Tek format reader usage page 0xff00
Usage ID
(Hex) Usage Name Usage Type Report Type
1 Decoding reader device Collection None
20 Track 1 decode status Data Input
21 Track 2 decode status Data Input
22 Track 3 decode status Data Input
28 Track 1 data length Data Input
29 Track 2 data length Data Input
2A Track 3 data length Data Input
30 Track 1 data Data Input
31 Track 2 data Data Input
32 Track 3 data Data Input
38 Card encode type Data Input
20 Command message Data Feature
4.2 Commands and responses
Commands and responses are exchanged with the reader using feature reports.
Commands are sent to the reader using HID class specific request Set Report ( 21
09 …). The response to a command is retrieved from the reader using HID class
specific request Get Report (A1 01 …). These requests are sent over the default
control pipe.
ID TECH
10721 Walker Street
Cypress, CA 90630-4720
[phone]
www. id-tech. net
Copyright © 2006, International Technologies & systems Corporation. All rights reserved.
Page 11 of 11