USB Macro

Utility to demo USB requests via UPDD.

UPDD can send and receive data to and from UPDD supported devices.

To interface with a USB device the driver has to construct and issue a USB request.

A USB request may be issued to a touch controller for many different reasons and are used for a range of controller specific requests. Typical examples could be to initialise the device (e.g. to set a multi-touch capable device into multi touch mode), send firmware commands to update internal settings or send firmware commands to retrieve settings.

Although at the lowest level a USB request is issued, these requests could be initiated at a user level, say via a driver’s API, or even defined mnemonically such as a UPDD Macro which is interpreted by the driver to construct the relevant USB request.

Developers using our driver often seek advice on how best to interface with a USB controller and to help satisfy these queries we have written a USB request utility and posted the source code and run-time on our web site here.

To run the utility under Windows download the compressed file and extract the USBMacro.exe, qtcore4.dll and qtgui4.dll files to the UPDD folder (normally c:\program files\UPDD).

The utility allows you to simply define and execute UPDD Macros which in the source code ultimately invokes the UPDD API TBApiSendMacroSynchronous to issue the USB request. This API is available in UPDD 4.1.10 (build 2367 and above – June 2012). Prior to the introduction of this macro there was TBApiSendMacro and TBApiSendData. TBApiSendMacro is now obsolete and we recommend that TbApiSendData only be used for serial devices (sending to a USB device uses a fixed USB request which may or may not be accepted by the controller)

When invoked the UPDD shows this simple dialog:

The top field allows for the manual entry and edit of a USB macro(s). These macros can also be constructed using the Wizard dialog as shown:

This dialog can be used to construct a UPDD Macro which in turn will issue the USB request and thus defines the specific components that compromise a USB request (we use Windows tags – which are not always the same tags as referenced in the USB specifications!)

For detailed information about the various components defined in the USB request block please refer to this link. Although the utility can be used to construct any USB request you will need to have knowledge of the USB request that can be handled by the specific touch controller and what responses, if any, are returned. This information should be available from the touch manufacturer or hopefully published in their controller documentation. If you have a driver or diagnostic tool that sends these requests you can always use a USB trace utility, such as USBlyzer, to trace the requests as they are issued and then replicate the request in the macro wizard.

If data is to be sent or received as part of the USB request the ‘Device to Host’ setting indicates the direction.

When disabled the data is being sent from the host computer to the device and will show a flags=0 in the macro. The data is entered in the ‘Data (Hex)’ field (with a space between each hex byte) and the length is automatically calculated.
When enabled, it will show a flags=1 entry in the macro and the Length byte indicates the amount of data to be returned from the device.

Data received data back from the host is displayed in the display area at the bottom of the main dialog. Once the USB request is issued the response data may be returned in a number of ways:

By delivering data on the interrupt endpoint.
By accepting a subsequent USB request (device to host) and delivering the response in the data part of the response. You would typically construct two macros; one to issue the USB request requesting the data and one to receive the data.
By utilizing a single request (device to host) and delivering the response in the data part of the response, with the host to controller data being in the request packet (e.g. value).

In this example the Wizard has been used to construct a macro to enable Multi-touch in a specific multi-touch device:

USB request UPDD macro structure	Same request as issued by HID driver in Windows 7 and traced by USBlyzer

The USBlyzer shows the USB standard tags for the various settings. The UPDD definition uses Windows tag names, the relationship being as follows:

USB tag	Wizard tag	Macro tag
Request Type	Request Type	USB type
RequestTypeReservedBits	Bits	bits
Request	Request	req
Value	Value	val
Index	Index	idx
TransferBufferLength	Length	len
TransferFlags	Device to Host	flags

Select OK in the Wizard to place the Macro in the macro field. Macros listed here can be manually edited as required.

The macro is executed and the USB request is issued to the first UPDD supported device as shown:

Limitations

Although the TBApiSendMacroSynchronous is a synchronous operation due to the use of legacy code in the driver to deliver the USB request the USB request block is not accessable and therefore any returned information from the request is not available for display.

It is our intention to replace the above API call with a new function such that the USB request block is accessible and exposed at the API level.

Examples

ELO Smartset controller

The firmware ‘Filter’ command is documented thus: Unused bytes are padded with Hex ‘00’.

The ELO documentation also gives some clues as to the USB requested needed. For this particular controller you issue a USB Request to request data and then a second request to retrieve the data, as shown:

With some ELO controllers we have found that you need to issue the retrieval macro a number of times to clear out erroneous data from the controller before issuing further firmware commands.

Hampshire Tsharc controller

The firmware ‘Return Vendor ID’ command is documented thus:

For this particular controller you issue a USB Request to request data and then a second request to retrieve the data, as shown: