Skip to main content

Debugging USB HID applications

UPDATED 2016-06: See our latest extensions and USB HID related fixes for Windows 10.

Did you design a custom USB HID device and wonder why you cannot test its application protocol with the same ease as serial COM (RS232, ..) or network TCP connections? 

Well we did, too, along with quite a few of our users. So it was high time to get this feature off the wishlist and into the software. See the Docklight FAQ - USB HID, or download the new software directly from here:

While we are still on our way to a concise and fully documented implementation, we found the current V2.0.200 version already very useful for our own projects with - a Microchip PIC based communication gateway running a custom ASCII protocol via USB HID.

How to use

Docklight Scripting V2.0.200 can connect to your custom HID device via the VID (vendor ID) and PID (product ID) code, if you use the following communication channel syntax:


(here for a device with VID 4D8 and PID F708.)

If you have several devices with the same VID/PID, you can also use the full Windows USB device path, e.g.:


The HID output in Docklight is report-based by default. I.e. each input report will generate a new Docklight time stamp and print the original HID report data, including the report ID as the first byte, if > 0. Here is how this could look in HEX format:
11.02.2014 07:55:41.486 [TX] - 01 02 56 0D
11.02.2014 07:55:41.490 [RX] - 01 0F 76 30 31 2E 30 30 2E 30 31 2E 33 35 32 00 0D 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

(The report ID is zero here and does not show up in the RX data. The returned data frame has 64 bytes size.)

Too much information? 

In many cases you do not want to deal with the original 64-byte report frames, but focus on the actual application layer protocol. Docklight Scripting offers a second mode for this (payload / protocol data mode):


It will not generate a time stamp for every input report. The report ID (if used) is dropped, along with all trailing zero fill bytes. The same protocol as above could then be shown as:
11.02.2014 07:59:44.609 [TX] - <SOH><STX>V<CR>
11.02.2014 07:59:44.612 [RX] - <SOH><SI>v01.00.01.352<NUL><CR>

Now we're talking! You can even spot an implementation flaw on the device side immediately: the stray zero byte before the <CR> of the version string.

Work in Progress

The USB HID support in Docklight Scripting V2.0.200 is certainly not complete, and most notably lacks a basic enumerator/browser for the HID devices on your PC. So any feedback and suggestions are highly appreciated!

Other Useful Additions

Oh, and there is more - you can also use Docklight Scripting V2.0.200 as a basic Windows Named Pipes client, using the following channel syntax:


(Thanks, Scott, for the initiative and the helpful feedback - much appreciated.) 

We added a few other tricks, too, including TCP proxy behavior (for TCP monitoring where one side is server, one side is client), file dialogs, using channel alias names for improved readability, two-channel send via script command, a.s.o. See the readme.txt release notes, as also listed below. 

These are experimental additions we did not design out completely, and we did not commit yet to add them as standard features for the V2.1 release. But we feel the experimental implementations are already very helpful in many lab applications. So please don't hesitate to write us about any problems within your environment, or any additional suggestions. As in the past, we are committed to come up with the most reliable and practical solution for the official update. 

Thanks again for all the helpful input so far!

Marco Flachmann and Oliver Heggelbacher
- The Docklight Developers -

Docklight Scripting V2.0.200 (03/2014) Customer Support Version

New features and functions:
- Experimental USB HID support
  Use the following channel syntax for USB HID Input / Output channel access
  USBHID:<vendorId>:<productId>  e.g.
  Extended Format 1: 
  USBHID:<vendorID Hex>:<product ID Hex>:<reportFormat>,<tx report size>,<tx report ID>
  <reportFormat>   : Use "P" for receiving the payload data only, and ignoring the original 
report boundaries and report ID. Zero fill bytes at the end of an report are also ignored.
  <tx report size> : if > 0, use a this block size for output, instead of the full report size
  <tx report ID>   : use this report ID for output (default = 0)
  Extended Format 2: 
  USBHID:<hid path>
  Use the full USB device path if you have more than one device with the same VID / PID
  See the \USBHID_Example folder for an example project.
- Experimental "Named Pipes Client" support: 
  Use the following channel syntax for a client connection to an existing Named Pipe: 
  PIPE:MyNamedPipe        - standard read/write access
  PIPEREAD:MyOutboundPipe - access a pipe that was created using PIPE_ACCESS_OUTBOUND on 
                            the server side and is read-only for the client (Docklight).
  PIPEWRITE:MyInboundPipe - access a pipe that was created using PIPE_ACCESS_INBOUND on 
                            the server side.
  See also the additional screenshots. 
  NOTE: Docklights uses 8 bit ASCII or byte data processing always. Plain text applications 
  with servers that receive and send 16 bit UNICODE strings will not work unless you manually 
  create Docklight Send Sequences with 16 bit encoded strings. 
  See the \NamedPipe_Example folder for an example project.
- Experimental FileInput/FileOutput Additions:
  1) <resultingPath> = FileInput.Dialog([<caption>,] [<defaultPath>])
     shows a "File Open" dialog and return the chosen path in <resultingPath>, or empty string, if aborted. 
  2) <resultingPath> = FileOutput.Dialog([<caption>,] [<defaultPath>])
     shows a "File Save" dialog. 
  3) FileInput.FileExists(<myFilePath>) or FileOutput.FileExists(<myFilePath>)
     returns True, if <myFilePath> exists
  See the \FileDialog_Example folder for an example.  

- Experimental DL.SetAppearance command: 
  <appearance>: a combination of the following letters: 
  L - Send/Receive lists visible
  E - Script Editor visible
  DL.SetAppearance ""  ' show communication window only (no Script Editor, no Send/Receive Sequence lists)
  DL.SetAppearance "L" ' show communication window and Send/Receive sequence lists, but no script editor
  DL.SetAppearance     ' show everything (default, same as <appearance> = "LE")

- Experimental DL.DirectSend command: 
  success = DL.DirectSend(<channelNo>, <data> [, <representation>])
  Allows two-channel-send or advanced data forwarding applications. 
  See the DirectSend_Example\forwardWithHeader.pts example script for more information and documentation. 

- Experimental "PROXY:<tcpPort>" syntax for TCP server mode. 
  Second channel will be opened/closed according to the connection accepted by the server channel.
  If the second channel forcefully closes a connection, the PROXY channel drops its connection, too.

- Channel Alias: The new settings in the Project Settings -> Comm. Filter tab allow to label the
  two data direction according to your needs, instead of hard to distinguish default labels 
  like TAP0 / TAP1.

- Experimental "Anything but this Character" wildcard. 
  Not available through a menu / keyboard shortcut,  use the 
  for copying into own sequences.

Fixes and Improvements: 
- Faster RTF (colored text) formatting, especially with text that contains a lot of color changes. 
- More readable and more up-to-date fonts and layout
- Improved display overload handling, e.g. when RTF formatting still takes too long. Docklight does
  not freeze, but switch to Plain Text Mode automatically and indicate a warning. 
- Fixed #include bug: "Script preprocessor error: Duplicate Include for same file" appeared,
  even for unique include paths. 
- Fixed bug: For "RS485 Transceiver Control - Set RTS high while sending", XON/XOFF was enabled, too.