> For the complete documentation index, see [llms.txt](https://developer.magtek.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.magtek.com/hardware/card-readers/mms-dyna-devices/dynaflex-ii-ped/documentation/developers-manuals/dynaflex-ii-ped-programmers-manual/connection-types.md). # Connection Types 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/ ](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: {% stepper %} {% step %} ### Choose Command Choose the command to invoke from section 6 Commands. {% endstep %} {% step %} ### Construct Request Construct the command request message using the Request table in the command documentation. For a deeper explanation of the contents of request tables, see section 2.7. {% endstep %} {% step %} ### Determine Length Determine the complete length of the command request message. {% endstep %} {% step %} ### 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. {% endstep %} {% step %} ### 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. {% endstep %} {% step %} ### 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. {% endstep %} {% step %} ### Parse Response Parse the final response message using the Response table in the documentation for the command. {% endstep %} {% endstepper %} ## Table - Single Packet Format
Byte OffsetField NameField Value
0Packet Type0x00 = Single Packet
1Message LengthMessage length, denoted as N
2..N+1MessageMessage exactly from section 2.7
N+2..63Padding, if needed0x00
## Table - Multi-Packet Head Format
Byte OffsetField NameField Value
0Packet Type0x01 = Multi-packet Head
1..4Message LengthTotal message length before decomposing into packets, denoted as N. If 62 or less, use Single Packet Format.
5..63Message PartFirst 59 bytes of message from section 2.7
## Table - Multi-Packet Middle Format
Byte OffsetField NameField Value
0Packet Type0x02 = Multi-Packet Middle
1..2Packet Number0x0001 = First Multi-Packet Middle 0x0002 = Second Multi-Packet Middle Etc. up to 0xFFFF
3..63Message PartNext 61 bytes of message from section 2.7
## Table - Multi-Packet Tail Format
Byte OffsetField NameField Value
0Packet Type0x03 = Multi-Packet Tail
1Remaining Message LengthNumber of bytes of the message that are being transmitted in this final packet, denoted as n.
2..n+1Message PartFinal n bytes of message exactly as described in section 2.7
n+2..63Padding, if needed0x00
## Table - Multi-Packet Cancel Format
Byte OffsetField NameField Value
0Packet Type0x04 = Multi-Packet Cancel
1..2Reason for Cancel0x0000 = General
3..63Padding0x00
### 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: {% stepper %} {% step %} ### Register Listener Register a listener with the operating system USB library to have the relevant Input Reports routed to the host software for processing. {% endstep %} {% step %} ### Retrieve Usage Data When an Input Report arrives, knowing from section 2.1.1 that the device uses Usage Page 0xFF00, and knowing the desired data is found in the usage with Usage ID 0x0020, call the platform’s USB SDK to retrieve the data from Usage 0xFF000020 in the input report. {% endstep %} {% step %} ### 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. {% endstep %} {% step %} ### Determine Message Type Determine the message type and message ID and parse it according to the corresponding Response table or Notification table in section 2.7. {% endstep %} {% step %} ### Route Message Route the fully composed message to the appropriate handler. {% endstep %} {% endstepper %} ### About Wireless LAN (WLAN) Connections 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 [http://websocket.org](http://websocket.org/). For information about SDKs and sample code that can wrap the protocol and speed up development, see section 1.3 About SDKs and Sample Code. ### How to Connect to a Device Using the Wireless LAN (WLAN) Connection 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. If you wish to test the device’s network connection before writing any code, you may choose to use the echo tool at [https://www.websocket.org/echo.html](https://www.websocket.org/echo.htmlhttps://websocket.org/tools/websocket-echo-server), which allows a WebSocket capable browser to connect directly to a local IP address and port to perform a simple echo operation. To connect to the device, the host software must follow these steps: {% stepper %} {% step %} ### Know WebSocket Parameters Know the WebSocket connection / handshake parameters: * /host/ is the device’s IP address or IP name (if DNS is in use). By default, when using DHCP, the device registers its Hostname as its IP name. Suggest using the Hostname df-device serial number to keep each server unique. See the serial number label on the back of the device. * /port/ is the port the device’s WebSocket server is listening on. Per the WebSocket standard, if the host does not specify a port, the connection assumes the default (port 80 for non-secure WebSocket, port 443 for secure WebSocket). For these devices, use the default port. * /resource name/, /protocols/, and /extensions/ are not required because the device only communicates with a single host and uses binary WebSocket frames. * /origin/ is not required per the WebSocket standard, because the host software is not a web browser. * /secure/ is recommended. {% endstep %} {% step %} ### Client Connections As a WebSocket server, the device can be configured to accept up to four client connections at a time. {% endstep %} {% step %} ### Establish Handshake Establish a connection using a standard WebSocket handshake. {% endstep %} {% step %} ### Keep Connection Open Leave the connection open to listen for incoming WebSocket messages as binary WebSocket frames. {% endstep %} {% step %} ### Session End The device will automatically disconnect from the client at the end of a session. See Command 0x1F03 - Extend Session (Session Management Only) for more details. {% endstep %} {% step %} ### Ping and Connection Monitoring Spawn a process to send a WebSocket ping across the connection on a reasonable interval (such as 5 seconds) to make sure the connection is still alive. Note that WebSocket protocol keeps ping / pong and binary message traffic separate, so there is not a risk of collision between MMS messages and a ping. Upon detecting the connection is no longer functioning (such as during power interruptions, wireless interference or out-of-range, network outage, etc.), take appropriate action such as: * Resetting the state of all host-side operations in process * Reporting the connection state and recommended troubleshooting procedures to the operator * Attempting to re-establish the connection {% endstep %} {% endstepper %} ### How to Send Commands Using the Wireless LAN (WLAN) Connection To send a command to the device using the WLAN connection: {% stepper %} {% step %} ### Ensure Open WebSocket Make sure there is an open WebSocket connection. See How to Connect to a Device Using the Wireless LAN (WLAN) Connection for details. {% endstep %} {% step %} ### Choose Command Choose the command to invoke from section 6 Commands. {% endstep %} {% step %} ### Construct Request Construct the command request message using the Request table in the command documentation. For a deeper explanation of the contents of request tables, see section 2.7. {% endstep %} {% step %} ### Transmit Message Transmit the full command request using the binary WebSocket message type (binary frames). {% endstep %} {% step %} ### Listen for Response Listen for the device’s response, which will also come in as a binary WebSocket message type. {% endstep %} {% step %} ### Validate Message Make sure the incoming message is the expected response, not an asynchronous notification. {% endstep %} {% step %} ### Parse Response Parse the final response message using the Response table in the documentation for the command. {% endstep %} {% endstepper %} ### How to Receive Data Using the Wireless LAN (WLAN) Connection 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. The host software should always be listening for notification messages, and should listen for command response messages after sending a command. Receiving 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. The host should follow this general sequence to process notification messages incoming via WebSocket protocol: {% stepper %} {% step %} ### Ensure Open WebSocket Make sure there is an open WebSocket connection. See How to Connect to a Device Using the Wireless LAN (WLAN) Connection for details. {% endstep %} {% step %} ### Route/Parse Message After a WebSocket message arrives, determine the message type and message ID and route / parse it according to the corresponding Response table or Notification table in section 2.7. {% endstep %} {% endstepper %} ### 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 1000007353 MAGTEK UNIVERSAL SDK FOR MMS DEVICES ( iOS ), available from MagTek. 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.magtek.com/hardware/card-readers/mms-dyna-devices/dynaflex-ii-ped/documentation/developers-manuals/dynaflex-ii-ped-programmers-manual/connection-types.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.