2 - Connection Types
eDynamo| Secure Card Reader Authenticator | Programmer’s Manual (COMMANDS)
Page 23 of 245 (
D998200115-17
)
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
, 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
, 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
. 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
in section
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
in section
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
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
documentation specifies these special cases if they exist.
(Extended Commands Only)
