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
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
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
Description
Type
Txt Len
Notes
Message ID = “N001”
Clear
ASCII
4
Notification Msg ID in KB mode
Notification Length
Clear
HEX
4
Notification Length
Notification
Clear
Hex
var
Notification in ASCII-Hex
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
Data Offset
ID
Complete Data Len
Data Segment
2 bytes
2 bytes
2 bytes
varies
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
Command
Parameter Data Len
Parameter Data
2 bytes
2 bytes
0-64k bytes
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
Packet Data Len
(Includes all subsequent field lengths)
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
Packet Data Len
(Includes all subsequent field lengths)
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
Length
Field Name
Description
0..1
Partial Data Length
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.
2..3
Data Offset
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.
4..5
Notification Identifier
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.
6..7
Complete Data Length
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.
8..n
Data
May contain part or all the notification data. The size of this field is contained in the Partial Data Length field.
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
Length
Field Name
Description
1
Partial Data Length
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.
2
Data Offset
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.
2
Reserved
Set to 0000
2
Complete Data Length
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.
Varies
Data
May contain part or all the data. The size of this field is contained in the Partial Data Length field.
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
Start
Message Type
Message Len
Message
End
0xC0
1 byte
2 bytes
Length varies
0xC0
Last updated