# Draft - Connection Types

iDynamo 5 Gen III connects to iOS products via a USB-C or Lighting to USB-C cable.

### How to Use Apple iAP2 Connections <a href="#toc183604097" id="toc183604097"></a>

This section provides information about developing an iOS app that interfaces with the device via the Lightning or USB connector using iPod Accessory Protocol 2 (iAP2).  For sample code and other supporting materials, see DYNAMAX / EDYNAMO / UDYNAMO / ADYNAMO / IDYNAMO / KDYNAMO / SDYNAMO / TDYNAMO SDK FOR IOS (WEB), 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:

* protocolString, 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 project must include the protocolString in its .plist file before compiling.  Spelling, including punctuation and capitalization, must exactly match the protocolString of the device.

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

## USB Communications <a href="#toc156981754" id="toc156981754"></a>

### USB Interface

This USB device conforms to the USB specification revision 2.0 and Human Interface Device (HID) class specification version 1.11.  The device is set up as a full-speed, high-powered USB device that draws power from the USB bus.  iDynamo5 Gen III identifies itself to the USB host with MagTek’s vendor ID 0x0801 and Product ID (PID) of 0x0020. All USB enumeration will include the device serial number.

#### About USB Reports

HID reports used by the host can be divided into two types:

* Feature Reports, which the host uses to send commands to the device and receive responses using Get Feature and Set Feature.
* Input Reports are used by the device to send unsolicited notifications to the host when the device’s state changes, or to send asynchronous responses to the host when a command completes.  The device commonly uses input reports when reporting card swipes, device events, or when a command takes more time for the device to process than is reasonable for the host to wait on a blocking call for the device to acknowledge completion.

#### USB Keyboard Emulation

A device in KB mode identifies itself to the USB host as a keyboard and transmits data to the host as ASCII as though it is being typed by a person on an actual keyboard.  It does this by mapping each of the possible ASCII characters in the stream to keystrokes.  To send an ASCII character to the host, the device looks up the ASCII character in the key and retrieves a combination of a single Key Usage which is a unique value assigned to every keyboard key, and a Key Modifier Byte and sends them to the host.  The key modifier byte modifies the meaning of the key usage ID, by indicating whether any combination of the right or left Ctrl, Shift, Alt or GUI keys \[as defined by Universal Serial Bus (USB) Device Class Definition for Human Interface Devices (HID)] are pressed at the same time as the key usage ID.

The device transmits ASCII 0 to 31 and 127 as their equivalent control code combinations.  For example, for a carriage return value 13 (0x0D), the device appears to the host as a keyboard where a person very quickly presses and holds the Ctrl key, then presses the M key, then releases both keys.

When the keymap contains a Key Usage ID and Key Modifier Byte of 0xFF for the ASCII value the device wants to send, the device uses Alt ASCII code keystrokes instead of key map values, meaning it simulates holding down the Alt key on a keyboard and typing the three-digit decimal value of the ASCII character it wants to send.  For example, to transmit the ASCII character ‘?’ (063 decimal in the ASCII table), the device sends keypad ‘0’ combined with the Left Alt key modifier, then keypad ‘6’ combined with the Left Alt key modifier, then keypad ‘3’ combined with the Left Alt key modifier.

**Commands and Responses**

Feature reports are used to send commands and receive responses, even when KB mode is active.

**Notifications (RFU)**

### Table - Notification in KB mode

<table data-header-hidden><thead><tr><th width="203.3333740234375"></th><th width="81"></th><th width="91.33331298828125"></th><th width="102.33331298828125"></th><th></th></tr></thead><tbody><tr><td>Description</td><td> </td><td>Type</td><td>Txt Len</td><td>Notes</td></tr><tr><td>Message ID = “N001”</td><td>Clear</td><td>ASCII</td><td>4</td><td>Notification Msg ID in KB mode</td></tr><tr><td>Notification Length</td><td>Clear</td><td>HEX</td><td>4</td><td>Notification Length</td></tr><tr><td>Notification</td><td>Clear</td><td>Hex</td><td>var</td><td>Notification in ASCII-Hex</td></tr></tbody></table>

### USB HID Protocol

This section defines how the device communicates with the host over the USB HID interface.

#### HID Packeting

The data transmitted in commands, responses, and notifications can be substantial, with a size limit of 64 kilobytes (64K bytes). However, the USB HID interface utilized by V5 restricts messages to 64 bytes. Therefore, to accommodate larger messages, we employ specific methods to segment them into multiple 64-byte packets. The segmentation approach varies depending on the message type to ensure compatibility with legacy V5. Below is the core structure of a USB HID packet.

### Table - HID Packet Definition

<table data-header-hidden><thead><tr><th width="127"></th><th width="93.66668701171875"></th><th width="156.33331298828125"></th><th></th></tr></thead><tbody><tr><td>Data Offset</td><td>ID</td><td>Complete Data Len</td><td>Data Segment</td></tr><tr><td>2 bytes</td><td>2 bytes</td><td>2 bytes</td><td>varies</td></tr></tbody></table>

#### Sending USB HID Messages to the Host

The device makes data available to the host using one or more Input Reports over a USB Interrupt IN pipe. The host will poll the device at the configured Polling Interval to see if Input Reports are ready.  The device must respond to polls with a USB NAK when no Input Reports are available.

* Data Messages sent by the device use Input Report ID 0x01.
* Notification Messages sent by the device use Input Report ID 0x02.

#### Receiving USB Data from the Host

The host sends commands using a Set Feature Report and sends a Get Feature Report to the device to retrieve a synchronous response when appropriate.  Feature reports use report ID 0x01.

The host should send both Feature Report types using the default Control pipe using a blocking call to the operating system’s native USB libraries.  The device NAKs the Status page of a Set Feature Report until it finishes the requested operation, and if it does not respond, the operating system will generally time out and report failure.  This method ensures that as soon as the device has fulfilled the command request embedded in the Set Feature Report, the host software can immediately call a follow-up Get Feature Report to retrieve the command.

In very rare cases, the host may simply send a Get Feature Report directly without a preceding Set Feature Report.  The Commands documentation specifies these special cases if they exist.

#### Command Packets

Commands are sent to the device using USB Set Feature Reports using Report ID 1.

### Table - Standard Command Format

<table data-header-hidden><thead><tr><th width="127.6666259765625"></th><th width="200"></th><th></th></tr></thead><tbody><tr><td>Command</td><td>Parameter Data Len</td><td>Parameter Data</td></tr><tr><td>2 bytes</td><td>2 bytes</td><td>0-64k bytes</td></tr></tbody></table>

Sending commands to the device over a packeted interface (maximum parameter size is 64k (0xFFFF). Standard command format gets broken down into packets for interfaces that do not support unlimited length messages. This is compatible with the V5 extended command protocol.

The number ranges shown in packets assume the interface is USB with a maximum message size of 64 bytes.

### Table - USB HID Command Packet

| Header | <p>Packet Data Len</p><p>(Includes all subsequent field lengths)</p> | Data Offset | Command | Full Parameter Data Len | Partial Parameter Data |
| ------ | -------------------------------------------------------------------- | ----------- | ------- | ----------------------- | ---------------------- |
| 0x49   | 1 Byte (6-58)                                                        | 2 bytes     | 2 bytes | 2 bytes                 | 0-52 bytes             |

The Command and Parameter Data length fields stay the same for all packets.  Each packet will contain one segment of parameter data up to 52 bytes.  The data offset indicates which portion of the parameter data is contained within this packet.

If the required Parameter Data is 52 bytes or shorter, the host can send the entire command using a single command packet.  If the Parameter Data is longer than 52 bytes, the host should split the data into multiple packets of 52 or fewer bytes and send multiple command packets.  Assuming 52-byte packets, the first packet the host sends should specify Data Offset = 0, the next packet should specify Data Offset = 52, and so on, until the host has sent all the Parameter Data.  The device’s response to each packet contains either an extended command result code or a standard result code for the command that was sent:

A packet with Data Offset = 0 is considered the start of a new command.  If there are still packets pending from a previous command, then that command is cleared, and all data received is erased.

The device will respond to packets with a 0x0B,0x00 when it expects additional packets (i.e., the length of parameter data received is less than the full parameter data length).  When all data has been received, then the device will respond with a packet starting with 0x0A and include the response message for the command.

ACK Packet … Send next packet.

Result Code 0x0B - Protocol Request Pending indicates the device is buffering the incoming data and expects the host to send subsequent packets.

### Table - Device to Host – Send next packet.

| Packet Result | Data Len |
| ------------- | -------- |
| 0x0B          | 0x00     |

### Table - Device to Host – Last packet received and Response

| Pkt Response | Data Len | Response                  |
| ------------ | -------- | ------------------------- |
| 0x0A         | 1 byte   | First portion of response |

Error due to invalid or missing data or due to a timeout while the device is waiting for more packets.

### Table - Error Invalid or Missing Data

| Packet Result | Data Len |
| ------------- | -------- |
| 0x02          | 0x00     |

#### Response Packets

Response messages are generated after executing a command and made available to the host as a feature report with the report ID set to 1.  The host uses the USB Get Feature Report to receive the response or a portion. The following should be compatible with V5 extended responses.

### Table - Standard Response Message Format (aka Extended Response in V5)

| Return Code | Response Data Len | Response Data |
| ----------- | ----------------- | ------------- |
| 2-bytes     | 2-bytes           | 0...n bytes   |

After the host receives the initial response packet, it’s up to the host to collect the data and send 0x4A commands to get more response packets until all data has been received.

### Table - USB HID Response Packet

| Header | <p>Packet Data Len</p><p>(Includes all subsequent field lengths)</p> | Data Offset | Response Code | Full Response Data Len | Partial Response Data |
| ------ | -------------------------------------------------------------------- | ----------- | ------------- | ---------------------- | --------------------- |
| 0x0A   | 1 Byte (6-58)                                                        | 2 bytes     | 2 bytes       | 2 bytes                | 0-52 bytes            |

### Table - Host to Device – Send next packet of Response.

| Send Next Packet Command | Data Len |
| ------------------------ | -------- |
| 0x4A                     | 0x00     |

#### Notifications

Notification messages with a data size longer than 52 bytes will need to be split into multiple packets to accommodate the USB HID interface. Notifications are made available to the host as one or more USB Input Reports with the report ID set to 2.

### Table - Notification Packets

<table data-header-hidden><thead><tr><th width="103"></th><th width="186.66668701171875"></th><th></th></tr></thead><tbody><tr><td>Length</td><td>Field Name</td><td>Description</td></tr><tr><td>0..1</td><td>Partial Data Length</td><td>The length of the Data field contained in the current message.  This field is in big endian format.  If this value is not equal to the Complete Data Length, the device is sending the notification using multiple packets.</td></tr><tr><td>2..3</td><td>Data Offset</td><td>The offset position in bytes within the entire assembled notification where the first byte of the current packet’s Data field is located.  This field is in big endian format.  The first byte of the entire notification’s Data is at offset zero.</td></tr><tr><td>4..5</td><td>Notification Identifier</td><td><mark style="color:$danger;">The type of notification being sent. This field is in big endian format. In many cases, two-byte notification identifiers are assigned such that the high byte indicates a group of related commands, and the low byte specifies a command within that group.</mark></td></tr><tr><td>6..7</td><td>Complete Data Length</td><td>The total length of data for the entire notification message, summing all Partial Data Lengths for multiple packets.  This field is in big endian format.  If this value is not equal to the Partial Data Length of the current packet, the device is sending the data using multiple packets.</td></tr><tr><td>8..n</td><td>Data</td><td>May contain part or all the notification data.  The size of this field is contained in the Partial Data Length field.</td></tr></tbody></table>

#### Data

Data messages are another type of asynchronous communication and handled in the same manner as a notification, except the report ID is set to 1.

### Table - Data Message Packets

<table data-header-hidden><thead><tr><th width="92.33331298828125"></th><th width="191"></th><th></th></tr></thead><tbody><tr><td>Length</td><td>Field Name</td><td>Description</td></tr><tr><td>1</td><td>Partial Data Length</td><td>The length of the Data field contained in the current message.  This field is in big endian format.  If this value is not equal to the Complete Data Length, the device is sending the data using multiple packets.</td></tr><tr><td>2</td><td>Data Offset</td><td>The offset position in bytes within the entire assembled notification where the first byte of the current packet’s Data field is located.  This field is in big endian format.  The first byte of the entire Data message is at offset zero.</td></tr><tr><td>2</td><td>Reserved</td><td>Set to 0000</td></tr><tr><td>2</td><td>Complete Data Length</td><td>The total length of data for the entire data message, summing all Partial Data Lengths for multiple packets.  This field is in big endian format.  If this value is not equal to the Partial Data Length of the current packet, the device is sending the data using multiple packets.</td></tr><tr><td>Varies</td><td>Data</td><td>May contain part or all the data.  The size of this field is contained in the Partial Data Length field.</td></tr></tbody></table>

### iOS SLIP Format

When connected to an iOS host, the device communicates over what appears to be a simple bidirectional serial line transferring binary data. To manage serial communications, we utilize an old method called SLIP (Serial Line Internet Protocol).  This allows the addition of message control characters and a method to distinguish between control and data.

#### Message Identification

Each message is prefixed by a one-byte message type followed by a two-byte message length. The possible types are:

* 00 - Data (Data is ASCII text to be compatible with KB emulation output)
* 02 - Notification
* 04 - Response
* 05 – Command

### Table - Message with iOS prefix

| Message Type | Message Len | Message       |
| ------------ | ----------- | ------------- |
| 1 byte       | 2 bytes     | Length varies |

#### Processing a Message Using SLIP

Messages are framed before and after with a byte value of 0xC0.  Because this value can also appear as part of the data message, a few 2-byte sequences are added to distinguish between control and data bytes. The sender modifies the outgoing data, and the receiver translates the incoming data back to the original message. Conversion can be done on the fly during the sending and receiving processes.

* Assemble message.
* Add message type and length to the beginning of the message.
* Replace any bytes with value 0xDB with bytes 0xDB 0xDD.
* Replace any bytes with value 0xC0 with bytes 0xDB 0xDC.
* Start and end the message with bytes 0xC0.

### Table - Message with SLIP framing

<table data-header-hidden><thead><tr><th width="92.33331298828125"></th><th width="100.33331298828125"></th><th width="116.3333740234375"></th><th width="136.33331298828125"></th><th></th></tr></thead><tbody><tr><td>Start</td><td>Message Type</td><td>Message Len</td><td>Message</td><td>End</td></tr><tr><td>0xC0</td><td>1 byte</td><td>2 bytes</td><td>Length varies</td><td>0xC0</td></tr></tbody></table>

```
SLIP example 
Message 01 DB C0 05 S
LIP C0 01 DB DD DB DC 05 C0
```


---

# Agent Instructions: 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:

```
GET https://developer.magtek.com/hardware/card-readers/magnetic-stripe-readers/idynamo-5-gen-iii/draft-documents/5-6-26-draft-of-programmers-manual-commands/draft-connection-types.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.