HelpSource/Classes/HIDDeviceService.schelp

   1 class:: HIDDeviceService
   2 summary:: provides access to Human Interface Devices like joysticks and gamepads
   3 related:: Classes/LID, Classes/GeneralHID, Classes/HIDDevice
   4 categories:: External Control>HID
   5
   6 description::
   7 It is advised to use link::Classes/GeneralHID:: instead, which wraps the HIDDeviceService functionality, and produces crossplatform compatible code.
   8
   9 This service was mainly designed to use gamepads as control input. The name is derived from the mac osx specifications.
  10
  11 The HIDDeviceService handles all the primitive calls. link::Classes/HIDDevice:: only stores information about a device and holds an array of HIDElements, which store information about the controllers of the device.
  12
  13 A link::Classes/HIDDevice::'s information consists out of:
  14 the manufacturer, the product, the usage, the vendorID, the productID and the locID.
  15 The last three are used to identify the device. The vendorID and the productID are static for each device, the locID depends on the (usb) port the device is connected to.
  16
  17 A link::Classes/HIDDeviceElement::'s information consists out of:
  18 the type, the usage, the cookie, the minimum and the maximum value.
  19 The cookie is a number that can be used to identify an element of a device.
  20
  21 ClassMethods::
  22
  23 private::initClass, prbuildDeviceList, prbuildElementList, prGetElementListSize, prreleaseDeviceList, pr_runEventLoop, pr_stopEventLoop, prHidAction, prReadError
  24
  25 method::buildDeviceList
  26 It is also possible to search for devices in other usage pages (look in the class file). The default is: page: GenericDesktop usage: Joystick. If a nil is passed in all devices are listed.
  27
  28 method::deviceSpecs
  29 You can add to the classvar deviceSpecs the specs of your device. The key used has to be the product name derived from the device info. Here is a collection of specs:
  30 code::
  31 //wingman
  32 (
  33 HIDDeviceService.deviceSpecs.put('WingMan Action Pad',
  34         IdentityDictionary[
  35                 \a -> 0, \b-> 1, \c-> 2,
  36                 \x-> 3, \y-> 4, \z-> 5,
  37                 \l-> 6, //front left
  38                 \r-> 7, //front right
  39                 \s-> 8,
  40                 \mode-> 9,
  41                 \xx-> 10,
  42                 \yy-> 11,
  43                 \slider-> 12,
  44                 \hat-> 13
  45         ]);
  46 )
  47 //cyborg
  48 (
  49 HIDDeviceService.deviceSpecs.put(\cyborg,  //not the right product name yet, so this doesn't work.
  50         IdentityDictionary[
  51                 \trig -> 0, \a-> 1, \b -> 2, \c -> 3,
  52                 \f1-> 4, \f2-> 5, \f3-> 6, \f4 -> 7,
  53                 \l -> 8, \r -> 9, // arrow buttons
  54                 \hu -> 10, \hl -> 11, \hr -> 12, \hd -> 13, // hat positions
  55                 \x -> 14, \y -> 15, \z -> 16, // axes
  56                 \slider-> 17,
  57                 \hat-> 18
  58         ]);
  59 )
  60 ::
  61
  62 Examples::
  63
  64 There are two ways of getting values from the device: One is to poll a value, the other one is to start an eventloop that pushes every new value into the language and calls an action (like link::Classes/MIDIIn::).
  65 To set up an eventloop follow these steps:
  66 numberedList::
  67 ## initialize the service by calling:
  68 code::
  69 HIDDeviceService.buildDeviceList;
  70 ::
  71 ## now the information about the devices can be found:
  72 code::
  73 (
  74 HIDDeviceService.devices.do({arg dev;
  75         [dev.manufacturer, dev.product, dev.vendorID, dev.productID, dev.locID].postln;
  76         dev.elements.do({arg ele;
  77                 [ele.type, ele.usage, ele.cookie, ele.min, ele.max].postln;
  78         });
  79 });
  80 )
  81 ::
  82 ## the device needs to be queued, that means that the eventloop actually uses this device to push values.
  83 code::
  84 HIDDeviceService.devices.at(0).queueDevice;
  85 ::
  86 ## set an action that is called by the incoming events. In addition to the value the events also deliver the productID, the vendorID and the locID of the device and the cookie of the element.
  87 code::
  88 (
  89 HIDDeviceService.action_({arg productID, vendorID, locID, cookie, val;
  90         [productID, vendorID, locID, cookie, val].postln;
  91 });
  92 )
  93 ::
  94 ## start the eventloop:
  95 code::
  96 HIDDeviceService.runEventLoop;
  97 ::
  98 ## stop the eventloop:
  99 code::
 100 HIDDeviceService.stopEventLoop;
 101 ::
 102 ::