Docklight Scripting allows you to open HID connections to a USB or Bluetooth HID device connected to your Windows PC. You can use this connection to
•Send and receive data via Output Reports or Input Reports.
•Send and receive feature data via Set Feature Reports or Get Feature Reports.
You can access a HID device either by its Vendor ID (VID), Product ID (PID), and optional information such as Usage Page and Usage ID. Or you can use the full Windows device path string.
Preconditions
•The device is connected to your PC and ready to use.
•The device is not a standard input device such as keyboards, mice that cannot be accessed by a user application like Docklight Scripting.
•You are using Docklight Scripting V2.4.20 or higher for up-to-date HID support - see our HID FAQ at https://docklight.de/dl_faq040/ .
Performing the Test
A) Determining the Docklight Project Settings for HID
Find the Vendor ID (VID) and Product ID (PID) of the device, e.g. using the hidtest.exe utility or an alternative, as described in our HID FAQ.
Here is an example hidtest.exe output for a popular CO2 sensor (holtek-zytemp, e.g. in TFA-Dostmann AirCO2ntrol products), as used in the example project usb_hid_demo_co2monitor.
Report Descriptor: (37 bytes)
0x05, 0x0d, 0x09, 0x0e, 0xa1, 0x01, 0x09, 0x23, 0xa1, 0x02,
0x85, 0xd7, 0x09, 0x52, 0x09, 0x53, 0x15, 0x00, 0x25, 0x0a,
0x35, 0x00, 0x46, 0xcc, 0x06, 0x55, 0x0e, 0x65, 0x11, 0x75,
0x08, 0x95, 0x02, 0xb1, 0x02, 0xc0, 0xc0,
Device Found
type: 04d9 a052
path: \\?\HID#VID_04D9&PID_A052#8&393b50b7&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}
serial_number: 2.00
Manufacturer: Holtek
Product: USB-zyTemp
Release: 200
Interface: 0
Usage (page): 0x1 (0xff00)
Bus type: 1 (USB)
B) Setting the Communication Options
| 1. | Select the Tools >  Project Settings... menu |
| 2. | Select communication mode Send/Receive |
| 3. | Under Send/Receive on comm. channel, enter the correct USBHID: settings string For the above example, it is sufficient to know the Vendor ID (VID) and Product ID (PID), so you could use: USBHID:4D9:A052:I |
NOTE: See the Dialog: Project Settings - Communication sections for information on the :I option.
| 4. | For devices that appear multiple times in the device list, choose the correct device path string, or Usage Page / Usage ID. Often the device path that is intended for application access will have a Usage Page value in the "Vendor-defined" range, i.e. FF00 - FFFF. The CO2 sensor example above does not require the additional Usage Page value, but as an alternative you could use the following, more specific Comm. Channel setting: USBHID:4D9:A052:FF00:1:I or the full Windows device path: USBHID:\\?\HID#VID_04D9&PID_A052#8&393b50b7&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}:I |
NOTE: The :I again is an optional Docklight setting. It is not part of the Windows device path, which ends at the closing bracket ('}').
C) Define the Send Sequence(s) used for HID Output Reports, HID Set Feature Reports, or HID Get Feature Reports
Example: For our CO2 sensor, we use a Send Sequence definition like this:
FE | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00
The Hex FE / Decimal 254 starting value is used in :I mode as a report ID or a selector for the transfer type. Hex FE / Decimal 254 tells Docklight to use hid_send_feature_report / Windows HidD_SetFeature for this sequence data. The 00 that follows is the report ID (zero, because the device does not use numbered reports), followed by the actual report content - in our example, 8 plain zero bytes.
D) Define the Receive Sequence(s) needed to evaluate incoming data (Input Reports, Get Feature results)
Example for the CO2 sensor: The sensor does not use numbered reports, so the Docklight RX data for Input Reports does not start with a report ID. The first four bytes are actual measurement and checksum data, the last four bytes are fixed. So a Receive Sequence to capture any type of measurements could look like this:
?? | ?? | ?? | ?? | 0D 00 00 00
E) Connecting to the HID device and sending / receiving HID report data
Select Run > 
Start Communication and use the 
Send button to send your predefined report(s).
Your Docklight communication data could look like this:
After sending the "Set Feature Report":
24.01.2025 10:31:53.089 [TX] - FE 00 00 00 00 00 00 00 00 00
After the HID device starts providing data via Input Reports:
24.01.2025 10:31:53.303 [RX] - 41 00 00 41 0D 00 00 00 new telegram
