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

tabpage string

• Publisher - The tabpage that the control is on.
• Subscriber - (Optional, populated from topic name)

control string

• Publisher - The control name.
• Subscriber - (Optional, populated from topic name)

x int16

• Publisher - The x position of the control (in pixels).
• Subscriber - X position to move the control to. A value of 0 leaves the control in place.

y int16

• Publisher - The y position of the control (in pixels).
• Subscriber - Y position to move the control to. A value of 0 leaves the control in place.

width uint16

• Publisher - The width of the control (in pixels).
• Subscriber - New control width. A value of 0 will leave the control at it's current width.

height uint16

• Publisher - The height of the control (in pixels).
• Subscriber - New control height. A value of 0 will leave the control at it's current height.

visible string

• Publisher - The visibility of the control.
• Subscriber - Sets the visibility of the control.
  • "" (Empty string) Leaves the visibility unchanged.
  • "True" or "False" will change the visibility of the control.

color string

• Publisher - The color of the control
• Subscriber - Set the new control color.
  • Possible colors are ["red", "green", "blue", "yellow", "purple", "gray", "orange"].
  • Leaving the field empty ("") will leave the color unchanged.

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

LED

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]

• Publisher - An array representing the bottom and top values of the control.
• Subscriber - No Subscriber.

value float32

• Publisher - No Publisher.
• Subscriber - Value to set the LED to.
  • A value less than range[0] turns the LED off (0%)
  • A value greater than range[1] turns the LED on (100%)
  • A value between range[0] and range[1] varies the brightness.

z bool

• Publisher - No Publisher
• Subscriber - No Subscriber

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

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.

• Outline - Place an outline around the label
• Background - Fill in the background of the label
• Size - Change the font size of the label

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

• Publisher - No Publisher.
• Subscriber - The string to display on the label

Push and Toggle Buttons

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.

• Local feedback off - The state of the control can only be set via the OSC interface. Local touches will still be registered, but the control will not change state.

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]

• Publisher - An array representing the bottom and top values of the control.
• Subscriber - No Subscriber.

value float32

• Publisher - Current value of the control
• Subscriber - Value to set the LED to.
  • A value less than range[0] turns the button off
  • A value greater than range[0] turns the button on

z bool

• Publisher - True if the control is being touched, False otherwise
• Subscriber - No Subscriber

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.

• Local feedback off - The state of the control can only be set via the OSC interface. Local touches will still be registered, but the control will not change state.
• Exclusive mode (multitoggle only) - Only one toggle button can be "on" at a time. Pressing a different button will toggle all other buttons to the "off" position.

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]

• Publisher - An array representing the bottom and top values of the control.
• Subscriber - No Subscriber.

dimension uint16[2]

• Publisher - The x and y dimensions of the array.
• No Subscriber

value float32[x*y]

• Publisher - sent when the control is interacted with, an array representing the state of all of the buttons in the control.
• Subscriber - The value to set the control to.

  • The array is indexed by x, and then by y. In a 3x5 array, this means that the bottom-left button will be value[0], bottom middle will be value[1], bottom right will be value[2], the left-most in the second row will be value[3], and so forth.

z bool

• Publisher - set to True when the control is being touched, reverts to False when the control is no longer touched.
• No Subscriber

Faders and Rotary

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.

• Centered - Starts the control at the midpoint of the range.
• Inverted - Inverts the maximum and minimum values of the range.
• Reponse - Alters the tactile response of the control
  • Absolute - The control moves to the point it is touched.
  • Relative - The control moves with the relative motion of the touch.

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]

• Publisher - An array representing the bottom and top values of the control.
• Subscriber - No Subscriber.

value float32

• Publisher - sent when control is interacted with. The value of the current position of the control.
• Subscriber - The value to set the control to.

z bool

• Publisher - set to True when the control is being touched, reverts to False when the control is no longer touched.
• No Subscriber.

Multifaders

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

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]

• Publisher - An array representing the bottom and top values of the control.
• Subscriber - No Subscriber.

dimension uint16

• Publisher - The number of faders in the multifader control
• Subscriber - No Subscriber.

values float32[dimension]

• Publisher - sent when control is interacted with. The value of the current position of the control.
• Subscriber - Sends the entire array to the device.

z bool

• Publisher - set to True when the control is being touched, reverts to False when the control is no longer touched.
• No Subscriber.

Encoder

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]

• Publisher - An array representing the bottom and top values of the control.
• Subscriber - No Subscriber.

value float32

• Publisher - sent when control is interacted with.

  • range[0] when the control is moved counterclockwise.

  • range[1] when the control is moved clockwise.

• Subscriber - No Subscriber

z bool

• Publisher - set to True when the control is being touched, reverts to False when the control is no longer touched.
• No Subscriber

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]

• Publisher - An array representing the bottom and top values of the control.
  • Both the x and y dimension have the same range.
• Subscriber - No Subscriber.

x float32

• Publisher - sent when control is interacted with.
• Subscriber - Update the x position of the control

y float32

• Publisher - sent when control is interacted with.
• Subscriber - Update the y position of the control.

z bool

• Publisher - set to True when the control is being touched, reverts to False when the control is no longer touched.
• No Subscriber

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]

• Publisher - An array representing the bottom and top values of the control.
  • Both the x and y dimension have the same range.
• Subscriber - No Subscriber.

x float32[5]

• Publisher - sent when control is interacted with.
• Subscriber - Update the x position of the control

y float32[5]

• Publisher - sent when control is interacted with.
• Subscriber - Update the y position of the control.

z bool[5]

• Publisher - set to True when the control is being touched, reverts to False when the control is no longer touched.
• No Subscriber