[Documentation] [TitleIndex] [WordIndex

TouchOSC Controls Reference

Below is a listing of the available controls in the TouchOSC interface. Also included is a detail of what parameters are sent and received via the Default Tabpage Handler included in touchosc_bridge.

For the most accurate and up-to-date information about the TouchOSC application, it is best to consult the official documentation on hexler.net

TouchOSC is Copyright 2008-2011 R.J. Fischer. The following document explains how ROS can work with the existing TouchOSC application.

In the below document, Publisher and Subscriber are used to mark the behavior of the touchosc_bridge DefaultTabpageHandler. If you are writing your own handler, it is best to consult the TouchOSC documentation linked above.

If a particular field is marked with No Publisher or No Subscriber, it means that that particular field will not be published, or cannot be update via the ROS subscriber. This typically means that it is a property of the control that may only be set via the TouchOSC Editor. All cases of this have been noted below in the documentation.

Common Properties

All controls share common properties that may be set via OSC. These are detailed below. These are set in the touchosc_msgs/CommonProperties message. The message is designed so that the default constructor for the message (all zeros and empty strings) will leave the control unmodified.

Listing

Control Naming

It is best to name controls with ROS-compliant names.

  1. First character is an alpha character ([a-z|A-Z])
  2. Subsequent characters can be alphanumeric ([0-9|a-z|A-Z]), or underscores (_)

Additionally, TouchOSC and touchosc_bridge do not support control or tabpage names with forward slash (/) or asterisk (*).

tabpage string

control string

x int16

y int16

width uint16

height uint16

visible string

color string

Additionally, with all controls, setting the frame_id in the header to a valid client IP address will send the message to only that client.

Valid Control Sizes and Positions

Device and Orientation

Minimum X

Maximum X

Minimum Y

Maximum Y

Maximum Width

Maximum Height

iPod Vertical

0

320

0

440

320

440

iPod Horizontal

0

480

0

280

480

280

iPad Vertical

0

770

0

980

770

980

iPad Horizontal

0

1020

0

720

1020

720

Control Position and Sizing

Placing controls at maximum values will cause them to be outside of the viewing area on screen. Use care when setting control positions and sizes via the ROS Subscriber.

Additionally, controls may be placed on the tab bar at the top of the screen, but this is generally regarded poor practice.

LED

LEDs in 7 Colors LEDs Dimmed

The LED is a receive-only control. LED control Publishers and Subscribers will be registered with the touchosc_msgs/ScalableControl message.

Listing

In addition to the std_msgs/Header and touchosc_msgs/CommonProperties, this control includes:

range float32[2]

value float32

z bool

Battery and Clock

Battery and Clock

The battery and clock display will show the amount of battery life remaining and local time on the device. Neither control send data, and only respond to common properties.

Listing

The battery and clock both subscribe to the touchosc_msgs/TouchOSC_Common message. This is a standard ROS std_msgs/Header message and a TouchOSC <<MsgLink(touchosc_msgs/CommonProperties>> message.

Label

Label

The label control allows for text to be sent to the screen of the device. Currently, only center justification is possible.

In the TouchOSC Editor, there are additional configurations for labels.

Listing

Label controls Publish and Subscribe to touchosc_msgs/Label messages. In addition to the std_msgs/Header and touchosc_msgs/CommonProperties, this control includes:

value string

Push and Toggle Buttons

Push and Toggle

Push buttons send the top of their set range message when pressed, and then go back to the bottom of their set range when released.

Toggle buttons will toggle to the top of their set range when pressed, and then go back to the bottom of their set range when released. Both push and toggle buttons send a z-message when the user is pressing them.

In the TouchOSC Editor, there are additional configurations for push and toggle buttons.

Listing

Push and Toggle buttons Publish and Subscribe to touchosc_msgs/ScalableControl messages. In addition to the std_msgs/Header and touchosc_msgs/CommonProperties, this control includes:

range float32[2]

value float32

z bool

Multipush and Multitoggle

Multipush and MultiToggle

Multipush and Multitoggle controls are functionally identical to the PUsh and Toggle controls with the exception that they are stored in an array.

In the TouchOSC Editor, there are additional configurations for multipush and multitoggle buttons.

Maximum array size

The largest multibutton or multitoggle array size is 16x16 (256 buttons).

Listing

Multipush and and multitoggle buttons Publish and Subscribe to touchosc_msgs/MultiButton messages. In addition to the std_msgs/Header and touchosc_msgs/CommonProperties, this control includes:

range float32[2]

dimension uint16[2]

value float32[x*y]

z bool

Faders and Rotary

Faders Rotary Knobs

Faders and rotary knobs provide a continuous range of values between the top and bottom of the set range. Both fader and rotary controls send z-messages when the control is being touched.

In the TouchOSC Editor, there are additional configurations for faders and rotary knobs.

Listing

Fader and Rotary controls Publish and Subscribe to touchosc_msgs/ScalableControl messages. In addition to the std_msgs/Header and touchosc_msgs/CommonProperties, this control includes:

range float32[2]

value float32

z bool

Multifaders

Multifader

Multifader controls are much like the fader control, but in an array.

Maximum array size

The largest multifader array size is 64 faders.

Listing

Multifader controls Publish and Subscribe to touchosc_msgs/MultiFader messages. In addition to the std_msgs/Header and touchosc_msgs/CommonProperties, this control includes:

range float32[2]

dimension uint16

values float32[dimension]

z bool

Encoder

Encoder Knob

A "wheel" control that sends it's high value when rotated clockwise and low value when rotated clockwise.

Listing

Encoder controls Publish and Subscribe to touchosc_msgs/ScalableControl messages. In addition to the std_msgs/Header and touchosc_msgs/CommonProperties, this control includes:

range float32[2]

value float32

z bool

XY Pad

XY Pad

The XY Pad control provides a two-dimensional track of touches on the control surface. Also, messages can be sent to move the cursor around the extents of the XY Pad.

Listing

XY Pad controls Publish and Subscribe to touchosc_msgs/XYPad messages. In addition to the std_msgs/Header and touchosc_msgs/CommonProperties, this control includes:

range float32[2]

x float32

y float32

z bool

Multi XY Pad

Multi XY Pad

The MultiXY Pad is like the XY Pad control, but can register up to 5 touches within the control area.

Unlike the XY control, the MultiXY cannot move the cursor based on incoming data.

The x, y, and z arrays in the message are populated in the order that touches are registered. Likewise, since touches are tracked, touches from the "middle" of the array may be removed.

For instance, the first three touches are registered in positions [0, 1, 2]. If the second touch is lifted from the surface, then the values in position 1 will zero out.

Listing

Multi XY Pad controls Publish and Subscribe to touchosc_msgs/MultiXYPad messages. In addition to the std_msgs/Header and touchosc_msgs/CommonProperties, this control includes:

range float32[2]

x float32[5]

y float32[5]

z bool[5]


2022-05-28 13:05