HelpSource/Classes/LID.schelp

   1 class:: LID
   2 summary:: Linux Input Device
   3 categories:: Platform>Linux, External Control>HID
   4 related:: Classes/GeneralHID, Classes/HIDDeviceService
   5
   6 description::
   7 This class provides a way to access devices in the linux input
   8 layer, which supports many input devices (mouse, keyboard,
   9 joystick, gamepad, tablet) and busses (serial, PS/2, USB).
  10
  11 See link::#examples:: below for documentation-by-example.
  12
  13 note::
  14 It is advised to use link::Classes/GeneralHID:: instead, which wraps the link::Classes/HIDDeviceService:: functionality, and produces crossplatform compatible code.
  15 ::
  16
  17 examples::
  18 subsection:: Opening a device
  19
  20 Input devices are accessed through device nodes, typically
  21 /dev/input/event[0-9]. When using a userspace daemon like udev,
  22 meaningful names can be assigned to devices.
  23
  24 raw device name:
  25 code::
  26 d = LID("/dev/input/event4");
  27 ::
  28
  29 symbolic device name
  30 code::
  31 d = LID("/dev/input/trackball");
  32 ::
  33
  34 device name relative to LID.deviceRoot
  35 code::
  36 d = LID("gamepad");
  37 ::
  38
  39 build a list of the available devices:
  40 code::
  41 LID.buildDeviceList
  42 ::
  43 buildDeviceList builds a table of the devices found in LID.deviceRoot+"/event", trying to open all that it finds, looking up its name and closing them again. The result is returned and can later be accessed by LID.deviceList.
  44 You can query another name than "/event" by passing an argument. (the search will be: LID.deviceRoot++"/"++name++"*")
  45 code::
  46 LID.buildDeviceList( "mouse" );
  47 ::
  48 Note:: this is likely to give the info that the devices could not be opened, as "mouse" uses another interface (you can of course access mice via the "event" interface) ::
  49
  50 Note:: if you cannot open the devices at all, please look in the helpfile for: Linux_udev_setup ::
  51
  52 subsection:: Querying device information
  53 code::
  54 d.info;
  55 d.info.name;
  56 d.info.vendor.asHexString(4);
  57 d.info.product.asHexString(4);
  58 ::
  59
  60 subsection:: Querying device capabilities
  61 Device capabilities are reported as event type and event code mappings. Event type and event code constants can be found in /usr/include/linux/input.h
  62 code::
  63 d.caps;
  64 d.dumpCaps;
  65 ::
  66
  67 subsection:: Event actions (raw events)
  68 The device's 'action' instance variable can be used for event notifications. it is passed the event type, code and current value.
  69 code::
  70 (
  71 d.action = { | evtType, evtCode, evtValue |
  72         [evtType.asHexString(4), evtCode.asHexString(4), evtValue].postln
  73 }
  74 )
  75
  76 d.action = nil;
  77 ::
  78 If a device is detached LID will detect this, and close the device. It will execute a closeAction, which can be defined by the user:
  79 code::
  80 d.closeAction = { "device was detached".postln; };
  81 ::
  82
  83 subsection:: Event actions (raw slot events)
  84
  85 When 'action' is nil, actions can be bound to specific events.
  86 code::
  87 (
  88 d.slot(0x0001, 0x0120).action = { | slot |
  89         [slot.type.asHexString(4), slot.code.asHexString(4), slot.rawValue].postln;
  90 }
  91 )
  92 ::
  93 Relative slots can have deltaActions:
  94 code::
  95 d.slot(0x0002, 0x0001).deltaAction = { | slot |
  96         [slot.type.asHexString(4), slot.code.asHexString(4), slot.delta].postln;
  97 }
  98 )
  99 ::
 100
 101 subsection:: Device specs
 102 Device specs are mappings between event codes and symbolic control
 103 names. New specs can be added to LID.specs via LID>>*register.
 104
 105 code::
 106 // Add a mouse device spec for a Logitech trackball
 107 LID.register('Logitech Trackball', LID.mouseDeviceSpec);
 108
 109 // Add a custom device spec for a Logitech gamepad
 110 (
 111 LID.register('Logitech WingMan RumblePad', (
 112         // key
 113         rumble: #[0x0001, 0x0102],      // rumble (toggles ff)
 114         mode: #[0x0001, 0x0103],        // mode (switches h and l)
 115         a: #[0x0001, 0x0120],           // button a
 116         b: #[0x0001, 0x0121],           // button b
 117         c: #[0x0001, 0x0122],           // button c
 118         x: #[0x0001, 0x0123],           // button x
 119         y: #[0x0001, 0x0124],           // button y
 120         z: #[0x0001, 0x0125],           // button z
 121         l: #[0x0001, 0x0126],           // left front button
 122         r: #[0x0001, 0x0127],           // right front button
 123         s: #[0x0001, 0x0128],           // button s
 124         // abs
 125         lx: #[0x0003, 0x0000],          // left joystick x
 126         ly: #[0x0003, 0x0001],          // left joystick y
 127         rx: #[0x0003, 0x0005],          // right joystick x
 128         ry: #[0x0003, 0x0006],          // right joystick y
 129         hx: #[0x0003, 0x0010],          // hat x
 130         hy: #[0x0003, 0x0011],          // hat y
 131         slider: #[0x0003, 0x0002]       // slider
 132 ));
 133 )
 134 ::
 135
 136 subsection:: Event actions (symbolic slot events)
 137
 138 When a device spec was registered for a given device name, slot
 139 actions can be assigned by using the symbolic control name.
 140 code::
 141 d[\a].action = { | slot | [\a, slot.value].postln };
 142 ::
 143 There is also a default keyboard device spec.
 144 code::
 145 (
 146 LID.keyboardDeviceSpec.keys.do { | key |
 147         d[key].action = { | slot | [key, slot.value].postln }
 148 }
 149 )
 150 ::
 151
 152 subsection:: LED's
 153 some devices have LEDs which can be turned on and off. These show up
 154 with d.caps as events of type 0x0011
 155 code::
 156 d = LID("/dev/input/event0");
 157 // LED's can be turned on:
 158 d.setLEDState( 0x0, 1 )
 159 // (LED 0x0 should be available on any keyboard)
 160 // and off:
 161 d.setLEDState( 0x0, 0 )
 162 d.close;
 163
 164 // setLEDState( evtCode, evtValue ): value should be 1 or 0
 165 ::
 166
 167 subsection:: Grabbing devices
 168 Given proper permissions, devices can be grabbed to prevent use in
 169 other applications (including X). Be careful when grabbing mouse or
 170 keyboard!
 171 code::
 172 d[\b].action = { d.ungrab };
 173 d.grab;
 174
 175 d.isGrabbed;
 176 ::
 177
 178 subsection:: Closing devices
 179 code::
 180 d.close;
 181 LID.closeAll;
 182 ::
 183