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.

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 . For information about receiving unsolicited data from the device, see .

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.

Connection MMS communication between the host and the device consists of Messages, which are independent of connection type. 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 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:

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

How to Use Apple iAP2 Connections (iAP2 Only)

This section provides information about developing an iOS app that interfaces with the device via the USB connector using iPod Accessory Protocol (iAP2). For sample code and other supporting materials, see SDKs & Tools

To develop host software for an iOS host that connects to the device, you must know the following device properties, which are specified by the purchaser when ordering, and loaded by the manufacturer:

• Apple iAP2 AppBundleID, also known as the SDK Protocol, usually in the form of a reverse DNS string unique to the host software developer or the device purchaser.

The host software should initiate a connection to the device using the iOS SDK’s ExternalAccessory Framework (for sample code, see Apple’s EADemo app). Upon establishing the connection, the host can begin exchanging data with the device.

This section provides information about developing software for a Bluetooth® LE-capable host that needs to communicate with the device using Bluetooth® Low Energy (Bluetooth® LE). The device acts as a Bluetooth® LE server/peripheral, and the host acts as a client/central.

About GATT Characteristics

Messages are exchanged with the device using a service named “DynaFlex”. The UUID for this service is:

0c ba 14 b7 ff 24 47 b0 be 09 26 44 05 38 53 0c 

in big endian order. This service contains the following characteristics.

Messages are sent to the device using a characteristic named “Message From Host”. The UUID for this service is

47 f0 5f fa 59 09 49 69 bc 57 25 0d 47 e8 74 e5 

in big endian order. This characteristic supports the Write Request Attribute PDU Method. The value of this characteristic has a variable length. The maximum length is 244 bytes. The host must have performed secure connections pairing with the device before the device will allow it to write to this characteristic.

Messages are sent to the host using a characteristic named “Message To Host”. The UUID for this service is

in big endian order. This characteristic only supports the Handle Value Notification Attribute PDU Method. The value of this characteristic has a variable length. The maximum length is 244 bytes. The host must have secure connections pairing with the device before the device will send notifications on this characteristic. The host must also enable notifications to be sent from this characteristic before the device will start sending messages on it.

Messages are exchanged with these characteristics using the DynaFlex Bluetooth® LE protocol. This protocol is described in the next section.

This protocol was designed to meet the following goals:

• Exchange messages with the device.

• Maximize throughput.

• Allow the side receiving a message to detect if a message is partially or completely dropped.

Bluetooth® LE attribute protocol transmits data in protocol data units (PDUs). The maximum size of a PDU is determined by the maximum transmission unit (MTU) agreed on between the host and the device. The MTU is typically set to the minimum of the host and device’s ATT_MTU size. DynaFlex’s ATT_MTU size is 247 bytes. Most host’s ATT_MTU sizes are larger than 247 bytes, so the MTU size agreed on between most hosts and DynaFlex’s is 247 bytes. Since application messages can be much larger than 247 bytes, application messages need to be able to be sent using multiple PDUs. Note that the minimum ATT_MTU allowed for all hosts and devices is 23 bytes. To maximize throughput, all messages should be sent using the maximum MTU size possible. This protocol allows large application messages to be sent using multiple PDUs. The protocol format for sending and receiving messages is the same for both the host and device. The only difference is the characteristic used. Since the attribute opcode and attribute handle use 3 bytes of the MTU size the attribute value length for the message from host and message to host characteristics is limited to 247 - 3 = 244 bytes.

When a PDU is received in the application layer, it is guaranteed to be correct since Bluetooth® LE does error detection and retries in the lower layers. However, PDUs can be completely dropped if the device goes out of range of the host or bad interference occurs. So host applications should be written with appropriate error detection and handling to account for these potential drops.

The following is the definition of each byte of a characteristic’s value for the DynaFlex Bluetooth® LE protocol:

• The first byte of the characteristic value is the message counter for every PDU. The message counter should be zero for the first message sent after every new BLE connection is established and should increase by one after sending every message. If its’ value is 0xff before it increments, it should have a value of zero after incrementing. All PDUs of a single message should have the same value for the message counter. The side receiving the message can use this counter to help detect if some PDUs of a message or if an entire message is dropped. The message counter for the message from host direction should be completely independent from the message counter for the message to host direction.

• The second byte of the characteristic value is the PDU counter for every PDU. The PDU counter should be zero for the first PDU of a message sent and should increase by one after sending every PDU of that message. If its’ value is 0xff before it increments, it should have a value of one instead of zero after incrementing. This is because the value of zero is reserved to always be used for the first PDU of a message. If the device receives a PDU counter of zero while it is still expecting more PDUs for an existing message, it shall discard any message that it is currently receiving and start receiving the new message. The first PDU of a message has a different protocol format than the remaining PDUs. The side receiving the message shall use this counter to help detect if some PDUs of a message are dropped. The PDU counter for the message from host direction should be completely independent from the PDU counter for the message to host direction.

The following is an example of sending two application messages in a row where the first 9-byte message fits into a single PDU and the second 512-byte message requires 3 PDUs.

This section provides information about developing software for a host to communicate via a TCP/IP network with MMS products connected to a wireless LAN access point. In this arrangement, the host and device exchange messages as peers using the bidirectional WebSocket protocol. For details about the WebSocket Protocol, formally IETF RFC 6455, see and .

For information about SDKs and sample code that can wrap the protocol and speed up development, see .

Before the device and host can communicate using the wireless LAN (WLAN) connection, the device must first be configured to connect to a WLAN access point. For details about configuring the device, see the device’s Installation and Operation Manual or supporting documentation included with the device.

After the device has been successfully configured for WLAN communication, whenever the device powers on or resets, it attempts to connect to the configured access point. If it is configured to use DHCP, it contacts a DHCP server to acquire a dynamic IP address and register its Hostname to the DNS server, otherwise it uses its configured static IP address. It then opens a WebSocket server listener port, and waits for a host to establish a connection using a WebSocket handshake. If any notification events occur before the host completes the handshake and establishes a connection, the device does not send the corresponding notifications, and it does not buffer while it waits for a host to establish a connection.

DynaFamily readers connect to a host over USB or Bluetooth LE. The MMS command set is identical over either transport — how you frame and send commands doesn't change — so the connection choice is about the device and your use case, not your integration code. Wired USB is simplest for fixed, attended setups; Bluetooth LE suits portable and mobile deployments (on the readers that support it, such as the DynaFlex II Go).

In This Section

Once connected, head to , or the for the command set.