How to Use USB Connections
These USB devices conform to the USB specification revision 1.1. They also conform to the Human Interface Device (HID) class specification version 1.1. This document assumes the audience is familiar with USB HID class specifications, which are available at http://www.usb.org/ MagTek strongly recommends becoming familiar with that standard before trying to communicate with the device directly via USB.
These devices are full-speed, high-powered USB devices that draw power from the USB bus they are connected to. They enter and wake up from Suspend mode when directed to do so by the USB host. They do not support remote wakeup.
When connecting via USB, MMS devices connect to the USB host as a vendor-defined Human Interface Device.
MMS devices identify themselves to the host with MagTek’s vendor ID 0x0801.
DynaFlex products report as Product ID (PID) 0x2020
DynaProx products report as Product ID (PID) 0x2023
DynaFlex II Go report as Product ID (PID) 0x2024.
Details for exchanging messages with the device are provided in the sections that follow.
About USB Reports, Usages, Usage Pages, and Usage IDs
All USB HID devices send and receive data using Reports. Each report may contain several sections, called Usages, each of which has its own unique four-byte (32-bit) identifier. The two most significant bytes of a usage are called the usage page, and the two least significant bytes are called the usage ID. Vendor-defined HID device usages must have a usage page in the range 0xFF00 - 0xFFFF, and it is common practice for related usage IDs share the same usage page. For these reasons, all usages for MMS devices use vendor-defined usage page 0xFF00, Magnetic Stripe Reader.
HID reports used by the host can be divided into two types:
Output Reports, which the host uses to send messages (such as commands) to the device.
Input Reports, which the device uses to send messages (such as responses and unsolicited notifications) to the host.
For information about using output reports to send command messages to / receive response messages from the device, see section 2.1.3 How to Send Command Requests Using the USB Connection. For information about receiving unsolicited data from the device, see section 2.1.4 How to Receive Data Using the USB Connection (HID Only).
How to Connect to a Device Using the USB Connection
The steps for a host to connect to the device using the USB connector are the same as connecting to any USB HID device, and are platform specific. The general steps regardless of platform are as follows:
Enumerate the USB devices connected to the host.
Locate the desired device by PID.
Open the USB connection.
Read the report descriptor.
Begin listening for incoming reports, and sending data using outgoing reports.
How to Send Command Requests Using the USB
Connection MMS communication between the host and the device consists of Messages, which are independent of connection type and are documented in section 2.7. This section focuses specifically on how to use the device’s USB HID connection to transmit a Command to the host by composing and sending a Request Message, then listening for and interpreting the corresponding Response Message.
When the device is connected to the host via USB, the host sends one or more Output Reports to the device to send the requests for commands, and listens / waits for the device to send one or more Input Reports containing a response. All reports use Usage Page 0xFF00, Usage ID 0x20, and no Report ID (which some platform libraries present to the calling software as Report ID 0x00).
The host may send Output Reports by using either the default Control pipe or the Interrupt OUT pipe using a blocking call to the platform’s USB libraries. The device ACKs all Output Reports immediately. Upon detecting the ACK for the last Output Report in the message stream, the host software can immediately begin listening for one or more follow-up Input Reports containing the device’s response.
Some messages defined in section 2.7 may exceed the maximum packet length allowed by USB HID. For this reason, MMS implements a packetizing scheme the host must use when it composes Output Reports to send commands, and when it decomposes Input Reports to receive responses. The host should follow this general sequence to send a request and receive a response:
Determine Report Payload Length
Examine the device’s Report Descriptor to determine what payload length the device expects for an Output Report (operating system libraries may refer to this length as the “Report Length” or “Report Count”). MMS devices using USB HID generally use a payload length of 64 bytes.
If the message length fits the Single Packet payload length of 62 bytes, wrap the message in the Single Packet format shown in Table 4.
If the message length does not fit the Single Packet payload length, wrap the message in the format of a single Multi-Packet Head, followed by zero or more Multi-Packet Middles as necessary, followed by one Multi-Packet Tail, as shown in Table 5, Table 6, and Table 7. If necessary, the host can cancel in the middle of a Multi-Packet message using the Multi-Packet Cancel packet shown in Table 8.
Send Packets and Wait for ACKs
For each packet, send an Output Report to the device, and wait for the device to ACK the output report USB packet. Upon ACK, either send the next packet in the sequence (if any), or begin listening for an Input Report containing the device’s response message (see How to Receive Data Using the USB Connection (HID Only)). If an ACK does not arrive, time out and assume the command needs to be started again.
Reassemble Response
Strip wrappers off the device’s response in exactly the same way you constructed the command (using either Single Packet format or Multi-Packet format), and recompose the response message. Be sure to assemble the packets in the correct order using Packet Number, and to truncate the padding based on Message Length or Remaining Message Length.
Table - Single Packet Format
0
Packet Type
0x00 = Single Packet
1
Message Length
Message length, denoted as N
2..N+1
Message
Message exactly from section 2.7
N+2..63
Padding, if needed
0x00
Table - Multi-Packet Head Format
0
Packet Type
0x01 = Multi-packet Head
1..4
Message Length
Total message length before decomposing into packets, denoted as N. If 62 or less, use Single Packet Format.
5..63
Message Part
First 59 bytes of message from section 2.7
Table - Multi-Packet Middle Format
0
Packet Type
0x02 = Multi-Packet Middle
1..2
Packet Number
0x0001 = First Multi-Packet Middle 0x0002 = Second Multi-Packet Middle Etc. up to 0xFFFF
3..63
Message Part
Next 61 bytes of message from section 2.7
Table - Multi-Packet Tail Format
0
Packet Type
0x03 = Multi-Packet Tail
1
Remaining Message Length
Number of bytes of the message that are being transmitted in this final packet, denoted as n.
2..n+1
Message Part
Final n bytes of message exactly as described in section 2.7
n+2..63
Padding, if needed
0x00
Table - Multi-Packet Cancel Format
0
Packet Type
0x04 = Multi-Packet Cancel
1..2
Reason for Cancel
0x0000 = General
3..63
Padding
0x00
How to Receive Data Using the USB Connection (HID Only)
MMS devices use the same mechanism to send Response messages to host commands and to send unsolicited Notifications to the host when events occur, such as device state changes or user interactions.
When the device communicates with the host as a vendor-defined HID device, it sends messages to the host via an Input Report, which it sends to the host using the USB Interrupt IN pipe. Per the USB HID standard, the host polls the device on a regular Polling Interval to see if the device has input reports available to send. If the device does not, it responds to the host’s poll with a USB NAK.
The host software should always be listening for Input Reports from the device containing notification messages and command response messages. Assembling and parsing the incoming message is the same in both cases, but notification messages, which are generally unpredictable, need to be routed to different handlers than responses, which are generally anticipated after sending a command. All input reports use Usage Page 0xFF00, Usage ID 0x20. Because MMS devices only implement one input report, the input report they send to the host does not include an Input Report ID (which some operating system libraries present to the calling software as Input Report ID 0x00), in accordance with the USB HID specification.
Some response and notification messages defined in section 2.7 may exceed the maximum packet length allowed by USB HID. If the message can’t fit into one packet, the device sends multiple packets, each containing partial message data using the same message packet structures described in the Multi-Packet tables above.
Upon receiving an input report, the host can determine the size of message packet Input Reports by looking at the HID report descriptor. The host can locate a specific data element in the report by finding the corresponding Usage and interpreting its contents as binary data. Because MMS devices use a single usage to hold the Input Report contents, unlike devices that divide the Input Report contents into length-delimited Usages, the host software can hard-code its method of finding the packet data; it is not necessary for the host software to examine the Report Descriptor for information about separate data elements’ offsets upon receiving a packet.
The host should follow this general sequence to process incoming Input Reports:
Detect Packet Format
Interpret the blob of data according to tables to determine whether the incoming message is in single packet format or multi-packet format. If it is using multi-packet format:
Continue buffering the message and processing incoming packets until the last packet of the message arrives.
Assemble the full message. Be sure to assemble the packets in the correct order using the Packet Number, and to truncate the padding based on Message Length or Remaining Message Length.
Last updated