How To Send Commands On The Usb Connection - Magtek mDynamo Programmer's Manual

2 - Connection Types

2.1.2 How to Send Commands On the USB Connection

Because many MagneSafe V5 devices support connection types beyond USB, this documentation
abstracts host-device communication by referring to Commands, which are most often a pairing of a
Request from the host and a corresponding Response from the device This section explains how these
terms apply when using the USB HID connection.
When the device is connected to the host via USB, regardless of whether it identifies and operates as a
vendor-defined HID device or as a keyboard, the host sends a Set Feature Report to the device to send
the requests for Commands, and sends a Get Feature Report to the device to retrieve a synchronous
response when appropriate. All reports use Usage Page 0xFF00, Usage ID 0x20, and no Feature Report
ID (Extended Commands Only) or, on devices that support Extended Commands, Feature 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 response, if one is required, and that the host software will not hang on a
blocking call indefinitely.
The host should follow this general command sequence to send a request and receive a response:
1) Choose the command to invoke from section 7 Commands. Every command has a corresponding
Command Number listed in the header of its documentation section.
2) Construct a Command Request Data value using the Request table in the documentation for the
command.
3) Determine the length of the Command Request Data value, referred to as the Command Request
Data Length.
4) Examine the device's Report Descriptor to determine what payload length the device expects for a
Set Feature Report and Get Feature Report (the operating system libraries may refer to this length
as the "Report Length" or "Report Count").
5) Pad the Command Request Data value with 0x00 so the total length of the payload is consistent
with the Set Feature Report's Report Length / Report Count.
6) Construct a Set Report Structure using Table 7-1 in section 7.1 About Commands.
7) Send a Set Feature Report containing the finalized padded Set Report Structure. The call to send
the report may succeed, fail on a timeout, or fail for some other reason.
8) If the call succeeds, send a Get Feature Report to retrieve the device's response in the Get Report
Structure shown in Table 7-2 in section 7.1 About Commands.
9) Parse the Get Report Structure, and truncate the Command Response Data field to the provided
Command Response Data Length.
10) Examine the Result Code, which is a one-byte value the device sends to indicate success or the
failure mode of the command. See section 7.2 About Result Codes for more detail.
11) Parse the truncated Command Response Data field using the Response table in the documentation
for 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.
(Extended Commands Only)
mDynamo| OEM Secure Card Reader Authenticator | Programmer's Manual (COMMANDS)
Page 20 of 167 (D998200151-200)