Quick search

TUIO Input Provider

TUIO is the de facto standard network protocol for the transmission of touch and fiducial information between a server and a client. To learn more about TUIO (which is itself based on the OSC protocol), please refer to http://tuio.org – The specification should be of special interest.

Configure a TUIO provider in the config.ini

The TUIO provider can be configured in the configuration file in the [input] section:

# name = tuio,<ip>:<port>
multitouchtable = tuio,

Configure a TUIO provider in the App

You must add the provider before your application is run, like this:

from kivy.app import App
from kivy.config import Config

class TestApp(App):
    def build(self):
        Config.set('input', 'multitouchscreen1', 'tuio,')
        # You can also add a second TUIO listener
        # Config.set('input', 'source2', 'tuio,')
        # Then do the usual things
        # ...
class kivy.input.providers.tuio.TuioMotionEventProvider(device, args)[source]

Bases: kivy.input.provider.MotionEventProvider

The TUIO provider listens to a socket and handles some of the incoming OSC messages:

  • /tuio/2Dcur
  • /tuio/2Dobj

You can easily extend the provider to handle new TUIO paths like so:

# Create a class to handle the new TUIO type/path
# Replace NEWPATH with the pathname you want to handle
class TuioNEWPATHMotionEvent(MotionEvent):
    def __init__(self, id, args):
        super(TuioNEWPATHMotionEvent, self).__init__(id, args)

    def depack(self, args):
        # In this method, implement 'unpacking' for the received
        # arguments. you basically translate from TUIO args to Kivy
        # MotionEvent variables. If all you receive are x and y
        # values, you can do it like this:
        if len(args) == 2:
            self.sx, self.sy = args
            self.profile = ('pos', )
        self.sy = 1 - self.sy
        super(TuioNEWPATHMotionEvent, self).depack(args)

# Register it with the TUIO MotionEvent provider.
# You obviously need to replace the PATH placeholders appropriately.
TuioMotionEventProvider.register('/tuio/PATH', TuioNEWPATHMotionEvent)


The class name is of no technical importance. Your class will be associated with the path that you pass to the register() function. To keep things simple, you should name your class after the path that it handles, though.

static create(oscpath, **kwargs)[source]

Create a touch event from a TUIO path

static register(oscpath, classname)[source]

Register a new path to handle in TUIO provider


Start the TUIO provider


Stop the TUIO provider

static unregister(oscpath, classname)[source]

Unregister a path to stop handling it in the TUIO provider


Update the TUIO provider (pop events from the queue)

class kivy.input.providers.tuio.Tuio2dCurMotionEvent(device, id, args)[source]

Bases: kivy.input.providers.tuio.TuioMotionEvent

A 2dCur TUIO touch.

class kivy.input.providers.tuio.Tuio2dObjMotionEvent(device, id, args)[source]

Bases: kivy.input.providers.tuio.TuioMotionEvent

A 2dObj TUIO object.