TUIO Interface

UPDD Commander can function as a TUIO server, that can be enabled to direct touches to a TUIO client application, and also as a TUIO client, to receive data from an independent TUIO server used to control touches on a system monitor.

TUIO Client applications are applications that have be written, or have an option, to receive touch information via the TUIO protocol.

The pathway schematic being:

Touch hardware > UPDD driver > UPDD API > UPDD Commander TUIO Server > TUIO client application > End user interaction

UPDD Commander currently only supports the TUIO 1.1 protocol, so any client implementation must be using this protocol version. UPDD Commander version 1.5.2 was updated to send the TUIO Source field along with other 'touch' related data. Data relating to objects and blobs is not passed by our TUIO server because the UPDD driver does not support devices that recognise objects or arbitrary shapes.

TUIO configuration

TUIO server can be set to run at the system wide level or at the application / group level.

You add the TUIO server using the add gesture control. Select the 'All Applications' or the desired Group or Application entry in the Application list and select the 'Add' gesture control:

This will add the TUIO server entry into the gesture list within the selected Application list entry:

Set the TUIO settings as required.

Mouse emulation consideration

The driver receives touch data from the touch hardware and posts the data on various interfaces.

UPDD Commander receives the touch data on the driver's API and then, based on the Commander's configuration, will potentially perform clicks, gestures and/or post data on the TUIO Server.

Depending on how the TUIO server is configured in Commander, the client application could receive touches via the TUIO interface and clicks (mouse emulation) and gestures.

In cases where the TUIO client only wants to receive data via TUIO you have two choices:

1. Set All Application entry to be TUIO only so Commander is not generating any click or gestures within the system and the TUIO Server is the only interface in use. Typically this would be used in a single application environment, say in a museum kiosk running a TUIO client application. In this example, click and gestures are not required by any other applications.
   
   
2. Specify the TUIO Client Application in the Commander Application list and disable inherited settings from the higher lever All Application setting so that only the TUIO server interface will be active for the application.

Both of these options are discussed below.​

TUIO Application presets

Application Presets exist to set All Applications/Default Gestures exclusively to TUIO whereby gesture functionality is disabled at the highest level and only services TUIO Clients

Having set All Applications/Default Gestures to TUIO server only as above, delete all other applications listed in the Application List.

You can also use the Preset option to set the Browser Group to work as a TUIO server within the web content UI element by switching to the 'Browser (TUIO)'  configuration:

Individual application TUIO configuration

Specifying a TUIO client application in UPDD Commander is very straight-forward:

1. Add the TUIO Client application in the Application list
2. Add the All Touches - Convert Touches to TUIO option for the application
3. Set the required application settings (defaults are likely to be OK if the Client application is running on the same computer)
4. Disable inherited settings if gestures are not required to be posted to the TUIO client application

Heartbeat

As part of the TUIO specifications each TUIO server (there can be more than one depending on the TUIO configuration) sends a periodic alive/fseq/source message at approximately one per second. These will stop if a touch screen associated with thje server becomes disabled, such as if the touch screen is disconnected.

Applications can use this to determine if touches are active for a specific monitor (s).

Settings

TUIO settings fall into two categories, application and global.

Application TUIO settings

These setting relate to the application level.

Host and server port

Defines the local IP address and post on which to transmit all touch data.

In most usage cases the TUIO server will be running locally on the same computer as the TUIO client program then a reasonable default configuration is for it to use localhost with the default TUIO IP address (127.0.0.1), port number (3333)

Advanced options

When an application is configured to run as a TUIO server there are some additional advanced options.

In the TUIO server application component select the Advanced Options... button:

Configure TUIO servers separately for each UPDD device

If required you can configure TUIO to send touches to different hosts and ports depending on which touch device it comes from, in essence running multiple TUIO servers at once. This checkbox switches between using the same TUIO host and port for all touch devices, and using different settings for each touch device. When checked, it lists each device configured in the driver and gives a field for setting its host and port. Each device does not need to have a unique TUIO host and port, and multiple devices can be configured to use the same TUIO host and port if you wish. Since most usage cases for a TUIO server is to have it running locally on the same computer that the TUIO client programs are running on, a reasonable default configuration is for it to use localhost with the default TUIO port number 3333.

TUIO touch positions

Relative to display: the positions of the TUIO cursors will be calculated using the entire area of the display, such that touches in the top-left corner of the display will have a normalized coordinate of (0,0) and touches in the bottom right corner will have normalized coordinates of (1,1).

Relative to display, dividing X axis evenly between touch devices: Similar to "Relative to display", TUIO cursor positions are calculated using the entire area of the display, but each device that is configured to use the same TUIO host and port will be scaled and translated horizontally so that it occupies a different equally-wide portion of the X axis, using the left-to-right order of the monitors as they are arranged in the system configuration.

Examples:

1. If two devices are using the same host and port, then the device that occupies the leftmost region of the system's desktop will have its TUIO cursors' X coordinates range from 0.0 to 0.5, and the device that uses the rightmost region will have its TUIO cursors' X coordinates range from 0.5 to 1.0.
2. If there are four UPDD devices, then all touches on the leftmost device will be converted to TUIO cursors where their minimum X value is 0 and their maximum X value is 0.25. The touches on the second device from the left will have a range of 0.25 to 0.5, the third device will have a range of 0.5 to 0.75, and so on.

The left to right order is determined by the system's display configuration.

Therefore, to get the proper coordinates for a TUIO device, simply define the X coordinates to a range of 0.0 to 1.0. The Y coordinates are unaffected.

This allows a single TUIO client to distinguish which TUIO cursor originated from which device.

Relative to window: the positions of the TUIO cursors will be calculated relative to the frame of the window that the touches fall within, such that touches at the top-left corner of the window will have a normalized coordinate of (0,0) and touches at the bottom-right corner will have a normalized coordinate of (1,1).

Global TUIO settings

These setting relate to the global level.

Server

These settings relate to the UPDD TUIO server and are located in the main Settings dialog, TUIO tab:

Send TUIO packets at the same rate as the UPDD

The TUIO server time stamps TUIO frames. By default this is as close as possible to 60 frames per second as per the TUIO specification. This setting can be used to transmit the frames at the same rate they are received from the driver albeit this does not conform to the TUIO specification. Any application written to retrieve frame times will also receive valid timestamps.

In our tests we achieved a UPDD TUIO data rate up to about 200 packets per second, although this speed will vary depending on hardware in use.

Send TUIO packets using WebSocket protocol in addition to UDP

This setting indicates that TUIO packets are transmitted using the WebSocket protocol in addition to the UDP protocol. This is required to satisfy Browsers using our Browser TUIO bridge implementation.

Client

These settings relate to the UPDD Commander running as a TUIO client application configured to receive data from an independent TUIO server to control touch on a specified monitor:

To activate this function, enable the ‘Receive touches from TUIO’ and specify the relevant port. Further, in a multi-monitor system, select the monitor to be controlled.

Browser considerations

Within UPDD Commander, web browsers can be configured in a number of ways:

Testing

UPDD Test has an option to Render Touches from TUIO Interface and thus acting as a TUIO client. It is for this reason UPDD Test is defined in the Application List as a separate entry such that it is configured as a TUIO Client application (as shown in the application settings example above).