[[cha:shuttlexpress]]

= ShuttleXpress

== Description

shuttlexpress is a non-realtime HAL component that interfaces Contour
Design’s ShuttleXpress device with LinuxCNC’s HAL.

If the driver is started without command-line arguments, it will probe
all /dev/hidraw* device files for ShuttleXpress devices, and use all
devices found. If it is started with command-line arguments, it will
only probe the devices specified.

The ShuttleXpress has five momentary buttons, a 10 counts/revolution
jog wheel with detents, and a 15-position spring-loaded outer wheel that
returns to center when released.

[WARNING]
=====
The ShuttleXpress device has an internal 8-bit counter for the current
jog-wheel position. The shuttlexpress driver can not know this value
until the ShuttleXpress device sends its first event. When the first
event comes into the driver, the driver uses the device’s reported
jog-wheel position to initialize counts to 0.

This means that if the first event is generated by a jog-wheel move,
that first move will be lost.

Any user interaction with the ShuttleXpress device will generate an event,
informing the driver of the jog-wheel position. So if you (for example)
push one of the buttons at startup, the jog-wheel will work fine and
notice the first click.
=====


== Setup

The shuttlexpress module needs read permission to the /dev/hidraw*
device files. This can be accomplished by adding a file
/etc/udev/rules.d/99-shuttlexpress.rules, with the following contents:

----
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0b33", ATTRS{idProduct}=="0020", MODE="0444"
----

The LinuxCNC Debian package installs an appropriate udev file
automatically, but if you are building LinuxCNC from source and are not
using the Debian packaging you'll need to install this file by hand.


== Pins

'shuttlexpress.<DeviceNumber>.button-<ButtonNumber>' (bit out)::

    The ShuttleXpress has five buttons around the outside of the device,
    numbered 0 through 4.  0 is the counter-clockwise-most button, 4 is
    the clockwise-most button.  These pins are True (1) when the button
    is pressed.

'shuttlexpress.<DeviceNumber>.button-<ButtonNumber>-not' (bit out)::

    These pins have the inverse of the button state, so they're True
    (1) when the button is not pressed.

'shuttlexpress.<DeviceNumber>.counts' (s32 out)::

    Accumulated counts from the jog wheel (the inner wheel).

'shuttlexpress.<DeviceNumber>.spring-wheel-s32' (s32 out)::

    The current deflection of the spring-wheel (the outer wheel).
    It’s 0 at rest, and ranges from -7 at the counter-clockwise extreme
    to +7 at the clockwise extreme.

'shuttlexpress.<DeviceNumber>.spring-wheel-f' (float out)::

    The current deflection of the spring-wheel (the outer wheel).
    It’s 0.0 at rest, -1.0 at the counter-clockwise extreme, and
    +1.0 at the clockwise extreme. (The ShuttleXpress device reports
    the spring-wheel position as an integer from -7 to +7, so this pin
    reports only 15 discrete values in it’s range.)

