Control of Dasher from a network socket = = = = = = = = = = = = = = = = = = = = - Seb Wills 28 September 2005 Introduction ============ The Dasher 'cursor', which determines the direction of zooming, and is indicated by a black square, is usually controlled by the mouse pointer, either through direct manipulation of the mouse or through other software (such as a gaze tracker) which controls the position of the pointer on the screen. From version 4, Dasher also allows its cursor to be controlled via messages received from another program via a UDP socket. The other program may be running on a different computer to Dasher, with cursor position information sent over a network. Socket configuration ==================== The UDP port number on which Dasher listens is configured in the Socket page of Dasher's preferences dialog. The preferences also contain a check-box to enable socket input. When selected, the cursor position is updated only by UDP packets (as specified below), and not by the mouse. To assist with diagnosing any problems you experience when using an external application to drive Dasher, there is an option in the preferences to display debugging messages. When this option is enabled, Dasher will display messages showing the contents of all messages received through the UDP port and information about how it is processing them. Under Linux, these debug messages are printed to the console (stderr); in Windows a console window is opened when you enable this option and the messages are displayed in it. Message format ============== Packets sent to Dasher's UDP port should consist of one or more lines, each terminated by a newline (0x0a) character. Each line should consist of a text label, followed by other data. Dasher ignores lines which do not start with one of two particular labels which are specified in Dasher's preferences and correspond to the X and Y coordinates. (In one-dimensional mode, only the Y coordinate is used.) If a line is read which begins with one of these labels, the text after the label (after skipping whitespace) is interpreted as an ASCII representation of a floating-point number, and is used to update the corresponding coordinate of the cursor position. An example packet might therefore look like this: XCoordinate 15.2 YCoordinate -21.2 OtherData 12s In this example, Dasher would probably be configured with "XCoordinate" as its label for the X coordinate, and "YCoordinate" for the Y Coordinate. Individual packets do not need to contain both (or either of) an X and Y coordinate value. In this example, the "OtherData" line would be ignored by Dasher. Packets may be sent as frequently as it is required to update the cursor. Since UDP does not guarantee delivery of packets, it is recommended to periodically send packets regardless of whether the values contained therein have changed. TCP support may be added in future. Coordinate transformation ========================= In Dasher's socket input preferences, you should specify the range of values that Dasher should expect to receive for each coordinate. These are used to linearly transform values received into Dasher's internal coordinate system. Assuming that you are using left-to-right writing orientation, then for the X coordinate, a value equal to the 'min' value specified in the preferences corresponds to the left-hand edge of the Dasher landscape. Ideally, 'max' corresponds to the right-hand edge, and values in-between are mapped linearly between these extremes in the obvious manner, however this is not currently (2005-11-29) the case; somebody needs to look into the various non-linearities applied to the coordinates and make socket input be treated more similarly to mouse input. For the Y coordinate, 'min' and 'max' correspond to the top and bottom of the Dasher landscape, respectively. Note that you can invert the sense of an input by swapping the values for 'min' and 'max' so that 'max' is numerically smaller than 'min'. The socket input code already inverts the sense of the X coordinate, to compensate for the fact that in Dasher's internal coordinate system, the X coordinate increases to the left, whereas most people would expect it to increase to the right. Values received which lie outside of the range between 'min' and 'max' are clipped to those values.