1  [[cha:shuttle]]
 2  
 3  = Shuttle
 4  
 5  == Description
 6  
 7  Shuttle is a non-realtime HAL component that interfaces Contour Design’s
 8  ShuttleXpress and ShuttlePRO devices with LinuxCNC’s HAL.
 9  
10  If the driver is started without command-line arguments, it will probe
11  all /dev/hidraw* device files for Shuttle devices, and use all devices
12  found. If it is started with command-line arguments, it will only
13  probe the devices specified.
14  
15  The ShuttleXpress has five momentary buttons, a 10 counts/revolution
16  jog wheel with detents, and a 15-position spring-loaded outer wheel that
17  returns to center when released.
18  
19  The ShuttlePRO has 13 momentary buttons, a 10 counts/revolution jog
20  wheel with detents, and a 15-position spring-loaded outer wheel that
21  returns to center when released.
22  
23  [WARNING]
24  =====
25  The Shuttle devices have an internal 8-bit counter for the current
26  jog-wheel position. The shuttle driver can not know this value until the
27  Shuttles device sends its first event. When the first event comes into
28  the driver, the driver uses the device’s reported jog-wheel position
29  to initialize counts to 0.
30  
31  This means that if the first event is generated by a jog-wheel move,
32  that first move will be lost.
33  
34  Any user interaction with the Shuttle device will generate an event,
35  informing the driver of the jog-wheel position. So if you (for example)
36  push one of the buttons at startup, the jog-wheel will work fine and
37  notice the first click.
38  =====
39  
40  
41  == Setup
42  
43  The shuttle driver needs read permission to the /dev/hidraw*
44  device files. This can be accomplished by adding a file
45  /etc/udev/rules.d/99-shuttle.rules, with the following contents:
46  
47  ----
48  SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0b33", ATTRS{idProduct}=="0020", MODE="0444"
49  SUBSYSTEM=="hidraw", ATTRS{idVendor}=="05f3", ATTRS{idProduct}=="0240", MODE="0444"
50  ----
51  
52  The LinuxCNC Debian package installs an appropriate udev file
53  automatically, but if you are building LinuxCNC from source and are not
54  using the Debian packaging you'll need to install this file by hand.
55  
56  
57  == Pins
58  
59  All HAL pin names are prefixed with the type of device followed by
60  the index of the device (the order in which the driver found them),
61  for example "shuttlexpress.0" or "shuttlepro.2".
62  
63  '<Prefix>.button-<ButtonNumber>' (bit out)::
64  
65      These pins are True (1) when the button is pressed.
66  
67  '<Prefix>.button-<ButtonNumber>-not' (bit out)::
68  
69      These pins have the inverse of the button state, so they're True
70      (1) when the button is not pressed.
71  
72  '<Prefix>.counts' (s32 out)::
73  
74      Accumulated counts from the jog wheel (the inner wheel).
75  
76  '<Prefix>.spring-wheel-s32' (s32 out)::
77  
78      The current deflection of the spring-wheel (the outer wheel).
79      It’s 0 at rest, and ranges from -7 at the counter-clockwise extreme
80      to +7 at the clockwise extreme.
81  
82  '<Prefix>.spring-wheel-f' (float out)::
83  
84      The current deflection of the spring-wheel (the outer wheel).
85      It’s 0.0 at rest, -1.0 at the counter-clockwise extreme, and +1.0 at
86      the clockwise extreme. (The Shuttle devices report the spring-wheel
87      position as an integer from -7 to +7, so this pin reports only 15
88      discrete values in it’s range.)