This file describes the support Kino have for using "Jog Shuttles" for
input. Jog/Shuttles are devices made especially for working with streams of
data, such as Video or Audio.

----------------------------------------------------------------------
* Contents

- What devices are supported
- How to use the Jog/Shuttle devices
- Hotplug support
- Troubleshooting
- The old/obsolete jogshuttle.c driver


----------------------------------------------------------------------
* What devices are supported

Kino supports (at least) two different jogshuttle input devices. The
most commonly used by the kino developers is the "Contour ShuttlePro",
but the "Sony PCDA-J1/A USB Jog Shuttle" controller has also been
known to work at some point. Both are USB units.

As of kino version 0.6.2, the default method of supporting jogshuttles is
through the Linux kernel HID driver which is part of any recent kernel.
Before version 0.6.2, a custom driver distributed with kino was used. It is
suspected that using HID may break support for the Sony controller -
information about the custom driver is included at the end of this document.

Benefits of using the HID driver includes easy loading with hotplug (most
distributions will load the necessary driver when you plug in the controller
- you may have to "modprobe evdev" in some cases). Also, any controller
supported by the Linux HID driver should work with kino. (Preference
mapping untested for other controllers than the Contour Shuttle Pro).

In theory, Kino should work with any (usb) Jog/Shuttle devices that supports
the USB HID v1.10 Pointer profile. If you use Kino succesfully with a device
other than the Contour Shuttle Pro, please let the kino developers know what
device and what your experience was by mailing the Kino developer list on 
Kino-dev@lists.sourceforge.net


----------------------------------------------------------------------
* How to use the Jog/Shuttle devices

If you have a working USB system (e.g. an USB mouse is connected and works),
you should be able to simply plug in the Jog/Shuttle device. This should
append something like the following to your systems log (/var/log/messages
most often):

Dec 10 19:40:59 localhost kernel: hub.c: new USB device 00:1f.2-1, assigned address 3
Dec 10 19:40:59 localhost kernel: input1: USB HID v1.10 Pointer [Contour Design ShuttlePRO] on usb1:3.0

The exact text and number of messages may wary. At this point, some systems
needs to load the "evdev" driver. You can do this, as root, by issuing the
command
#modprobe evdev

Your system can be set up to do this automatically - it is outside the scope
of this document to explain how to do this.

Now you can start Kino, go to File|Preferences|Jog/Shuttle. You need to tick
on "Enable Jog/Shuttle input" and provide a path to your device. (Typically
"/dev/input/event0"). Restart Kino for the changes to take effect.

At this point you should have Jog/Shuttle support in Kino. You can use the
preferences dialog to change the mappings between the buttons and actions in
Kino.


----------------------------------------------------------------------
* Hotplug support

If your systems supports usb hotpluggin and you have the program
update-usb.usermap, you can configure kino to get a notification when
you insert a supported usb Jog/Shuttle.

You can do this, by configuring kino like this:
./configure --with-hotplug-script-dir=/etc/hotplug/usb \
  --with-hotplug-usermap-dir=/usr/lib/hotplug/kino/

After you have installed kino, you then need to run:

$update-usb.usermap

You can test that this work by inserting your Jog/Shuttle device and
look for lines like these in /var/log/messages:

/etc/hotplug/usb.agent: Setup hid for USB product b33/10/100
/etc/hotplug/usb.agent: Setup kino-jogshuttle for USB product b33/10/100
/etc/hotplug/usb.agent: Module setup kino-jogshuttle for USB product b33/10/100


----------------------------------------------------------------------
* Troubleshooting

If you have trouble getting your Jog/Shuttle to work, please send a bug
report to Kino-dev@lists.sourceforge.net . Make sure to include information
about what device your are trying to get to work, your distribution, kernel
version (the output of uname -a), and relevant log information. 
