|
Serial and
USB Macros |
|||||||||
Introduction
Some pointer device controllers recognise commands and these are used to set the controllers into certain states or to modify the firmware settings. Commands can also be sent to retrieve current settings. It may also be necessary to initialise a controller to a certain state before generating coordinate packet information. Some controllers respond to the commands to indicate the status or success of the requested command, others do not. If a controller is initialised by a UPDD macro the initialisation status of a controller is shown in the DCU Status dialog.
Macro Definition
In UPDD Version 3, macros are defined in the Driver Control Utility (DCU), Advanced tab, Macros. When the macro option is selected the macro editor dialog is shown to allow the macro command strings to be viewed, updated or defined as required.
Selecting the 'default' option will restore the initialisation string to its default value.
In UPDD Version 4 macros will be defined in the Advanced Console. When the macro option is selected the macro editor dialog is shown to allow the macro command strings to be viewed, updated or defined as required.
Version 4 Image to follow.
Macro execution
Macro commands can be invoked at various times, as described below:
Controller start
Issued each time the driver controller interface starts, ie at driver startup. The driver is re-started when DCU settings are changed (and the Apply or OK button is selected), calibration is initiated, or when the re-initialisation option is selected in the DCU Status dialog.
Controller stop
Issued each time the driver controller interface stops, ie at driver shutdown. The driver is stopped when DCU settings are changed (and the Apply or OK button is selected) or calibration is initiated. Issued prior to terminating communication with the controller.
Driver load
Issued whenever the driver loads. This is usually when the system starts but under NT an administrator may stop and start the driver without stopping the system.
Driver unload
Issued whenever the driver unloads. This is usually, when the system shuts down but under NT an administrator may stop and start the driver without stopping the system.
Firmware
A special macro generated by the Firmware page for controllers with firmware support. This macro is read only. It is executed only as part of one of the above macros, if the [FIRM] directive is encountered.
Macro Commands
When the macros are processed spaces are ignored, except in ASCII mode. Characters are sent to the output port as they are read, unless they are part of an ack/nak string or a macro command. All macro commands are entered between square brackets, ie [command].
|
Command |
Description |
||
|
// |
denotes comment line - Only supported from version 2.07 eg // this is a comment |
||
|
[HEX] |
denotes that the characters that follow are pairs of hex characters separated by commas. This is the default mode. The mode remains in effect until the end of the string, or until [ASCII] macro command is encountered. E.g. [HEX]01,02,03 |
||
|
[ASCII] |
denotes that the characters that follow are ASCII characters. The mode remains in effect until the end of the string, or until [HEX] macro command is encountered. E.g. [ASCII]ABC |
||
|
[CR] |
send a carriage return (hex 0D) to the output port. |
||
|
[LF] |
send a line feed (hex 0A) to the output port. |
||
|
[END] |
denotes the end of an |
||
|
[ |
the characters that follow from an |
||
|
[NAK text] |
the characters
that follow from a NAK string. They are read and stored. If the NAK string is
read whilst waiting for an |
||
|
[DTR n] |
where n = 0 or 1. E.g.[DTR 1] sets the DTR line active (high). [DTR 0] sets the DTR line inactive (low). |
||
|
[RTS n] |
where n = 0 or 1. E.g.[RTS 1] sets the RTS line active (high). [RTS 0] sets the RTS line inactive (low). CTS and DSR are input lines and thus cannot be set in a macro |
||
|
[WAIT nnnn] |
pause for the specified number of milliseconds. |
||
|
[BREAK n] |
sets the UART break line to the value of n (0 or 1). |
||
|
[FIRM] |
Execute the firmware macro. |
||
|
[DELAY nnnn] |
There is a send macro API command. The Delay macro sets the delay between bytes send during macro playback. The default is 20ms, and it is rounded to the nearest 20 ms. |
||
|
[USB] |
[USB type=xxxxxxx dir=OUT bits=0 req=0 val=xx idx=0]. The USB macro directive initiates a USB vendor request. It is followed by data to send (if any), and terminated by an [END] directive. The various subfields are described below: |
||
|
|
type |
Indicates the transfer type. It may be any of the following: |
|
|
|
|
DEVICE |
Indicates a vendor-defined request for a USB device. |
|
|
|
INTERF |
Indicates vendor-defined request for an interface on a USB device. |
|
|
|
ENDPOINT |
Indicates a vendor-defined request for an endpoint, in an interface, on a USB device. |
|
|
|
OTHER |
Indicates a vendor-defined request for a device-defined target. |
|
|
dir |
Indicates the transfer direction. It can only take the following value:- |
|
|
|
|
OUT |
Indicates a transfer from host to device. |
|
|
bits |
Specifies the (hex) value of the URB field "ReservedBits". |
|
|
|
req |
Specifies the (hex value) of the vendor defined request code. |
|
|
|
val |
Specifies the (hex) value of the URB field "Value". |
|
|
|
idx |
Specifies the device-defined identifier if the request is for an endpoint, interface, or device-defined target. Otherwise, Index must be 0. |
|
|
|
As of updd 4.1.3 we now support writing data to USB endpoint 2 using macros. An example macro is shown. USB request arguments (value, index etc) are irrelevant in this context and are ignored if specified. [USB type=EP2 len=4]12 47 00 81[END] Currently this is only available for endpoint 2. The hardware interface is presently only supported for Windows. |
||
|
[MODE] |
[MODE baud,parity,databits,stopbits]. Changes com port setup. Used on devices that switch speed during initialisation. E.g.[MODE 9600,N,8,1] baud can be any valid baud rate parity can be N / O / E (none, odd, even) databits can be 7 or 8 stopbits can be 1 or 2 alternatively any value can be "*" - meaning use the defined hardware setting. E.g. [MODE *,*,8,1], means get baud and parity setting from the DCU hardware settings and set databits=8, stopbits=1. This macro only applies to serial controllers. Using this for any other type of connection will result in a "not supported" macro status. We recommend that for macros that change controller speed, the "operating speed" of the controller be set in the hardware settings, and the alternate speed be set at the start of the macro. By finishing up with [MODE *,*,*,*] the controller operating speed is reflected in the DCU hardware dialog. Doing this the other way round could lead to confusion. Eg a controller initially set to 1200,N,7,1 but eventually operates at 9600,N,8,1 could have 1200,N,7,1 in the hardware settings, and use [MODE 9600,N,8,1] in the macro. We would recommend setting 9600,N,8,1 in the DCU Hardware settings, then changing to 1200,N,7,1 then the initialisation sequence and 9600,N,8,1 in the macro. |
||
Example
Example macro initialisation strings
Example 1 - Send string 0x01, 0x02, 0x03 to controller, no response expected.
01,02,03
Example 2 - Send string 0x01, 0x02, 0x03 to controller, controller response with 0x04, no response within 1 second indicates fail.
01,02,03[
Example 3 - Pulse CTS high for 100 milliseconds to reset controller, controller reponds within 0.5 seconds with hex 00 then send init string CR LF, controller responds with 0x01 for OK, 0x02 for low battery or 0x03 for general failure.
[CTS 1][WAIT 100][CTS 0][
Example 4 - The following example macro sends a device request (0) to the default pipe with a value 3C, waits 150 ms, then sends device request 1 - value 2C with some associated data.
[USB type=DEVICE dir=OUT bits=0 req=0 val=3C idx=0]
[END]
[WAIT 150]
[USB type=DEVICE dir=OUT bits=0 req=1 val=23 idx=0]
01,02 [ASCII]Start[CR][LF][HEX]
[END]
Contact
For further information or technical assistance please email the technical support team at technical@touch-base.com