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?
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:
https://docklight.de/download/Docklight_Scripting.zip
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 fullmo.de - a Microchip PIC based communication gateway running a custom ASCII protocol via USB HID.
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 fullmo.de - 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:
USBHID:4D8:F708
(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.:
USBHID:4D8:F708
(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.:
USBHID:\\?\hid#vid_04d8&pid_f708&mi_01#8&8121c84&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}
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):
USBHID:4D8:F708:P
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>
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.
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.
USBHID:4D8:F708
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)
Example:
USBHID:4D8:3F:P,64,1
Extended Format 2:
USBHID:<hid path>
Example:
USBHID:\\?\hid#vid_04d8&pid_f708&mi_01#9&2cebf0a4&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}
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:
DL.SetAppearance(<appearance>)
<appearance>: a combination of the following letters:
L - Send/Receive lists visible
E - Script Editor visible
Examples:
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.
Example:
PROXY:10001
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
WildcardAnythingButExample.ptp
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.
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:
PIPE:mynamedpipe
(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!
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.
USBHID:4D8:F708
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)
Example:
USBHID:4D8:3F:P,64,1
Extended Format 2:
USBHID:<hid path>
Example:
USBHID:\\?\hid#vid_04d8&pid_f708&mi_01#9&2cebf0a4&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}
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:
DL.SetAppearance(<appearance>)
<appearance>: a combination of the following letters:
L - Send/Receive lists visible
E - Script Editor visible
Examples:
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.
Example:
PROXY:10001
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
WildcardAnythingButExample.ptp
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.
Comments
Post a Comment