Help/Control/HIDDeviceService.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <title></title>
   7 <meta name="Generator" content="Cocoa HTML Writer">
   8 <meta name="CocoaVersion" content="824.42">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #0019b7}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #a71e12; min-height: 12.0px}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #a71e12}
  18 p.p9 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #326f17}
  19 span.s1 {font: 12.0px Helvetica}
  20 span.s2 {color: #0019b7}
  21 span.s3 {font: 9.0px Monaco}
  22 span.s4 {font: 9.0px Monaco; color: #0019b7}
  23 span.s5 {font: 12.0px Helvetica; color: #000000}
  24 span.s6 {color: #000000}
  25 span.s7 {color: #326f17}
  26 span.s8 {color: #a71e12}
  27 span.Apple-tab-span {white-space:pre}
  28 </style>
  29 </head>
  30 <body>
  31 <p class="p1"><b>HIDDeviceService</b></p>
  32 <p class="p2"><br></p>
  33 <p class="p3"><b>A Service that provides access to Human Interface Devices like joysticks and gamepads.</b></p>
  34 <p class="p2"><br></p>
  35 <p class="p3">It is advised to use <a href="GeneralHID.html"><span class="s2">GeneralHID</span></a> instead, which wraps the HIDDeviceService functionality, and produces crossplatform compatible code.</p>
  36
  37 <p class="p2"><br></p>
  38 <p class="p3">This service was mainly designed to use gamepads as control input. The name is derived from the mac osx specifications.<span class="Apple-converted-space"> </span></p>
  39 <p class="p3">The HIDDeviceService handles all the primitive calls. HIDDevice only stores information about a device and holds an array of HIDElements, which store information about the controllers of the device.</p>
  40 <p class="p3">A HIDDevice's information consists out of:<span class="Apple-converted-space"> </span></p>
  41 <p class="p3"><span class="Apple-tab-span">     </span>the manufacturer, the product, the usage, the vendorID, the productID and the locID.</p>
  42 <p class="p3"><span class="Apple-tab-span">     </span>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.</p>
  43 <p class="p3">A HIDDeviceElement's information consists out of:<span class="Apple-converted-space"> </span></p>
  44 <p class="p3"><span class="Apple-tab-span">     </span>the type, the usage, the cookie, the minimum and the maximum value.</p>
  45 <p class="p3"><span class="Apple-tab-span">     </span>the cookie is a number that can be used to identify an element of a device.</p>
  46 <p class="p2"><span class="Apple-tab-span">     </span></p>
  47 <p class="p3">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 MIDIIn).</p>
  48 <p class="p3">To set up an eventloop follow these steps:</p>
  49 <p class="p3"><span class="Apple-tab-span">     </span>1. initialize the service by calling:</p>
  50 <p class="p2"><span class="Apple-tab-span">     </span></p>
  51 <p class="p4"><span class="s1"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span><span class="s2">HIDDeviceService.</span>buildDeviceList;</p>
  52 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  53 <p class="p3"><span class="s3"><span class="Apple-tab-span">    </span></span>2. now the information about the devices can be found:</p>
  54 <p class="p2"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  55 <p class="p3"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="s4">(</span></p>
  56 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="s2">HIDDeviceService</span>.devices.do({<span class="s2">arg</span> dev;</p>
  57 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>[dev.manufacturer, dev.product, dev.vendorID, dev.productID, dev.locID].postln;</p>
  58 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>dev.elements.do({<span class="s2">arg</span> ele;</p>
  59 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>[ele.type, ele.usage, ele.cookie, ele.min, ele.max].postln;</p>
  60 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>});</p>
  61 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>});</p>
  62 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="s2">)</span></p>
  63 <p class="p5"><span class="Apple-tab-span">     </span></p>
  64 <p class="p3"><span class="s3"><span class="Apple-tab-span">    </span></span>3. the device needs to be queued, that means that the eventloop actually uses this device to push values.<span class="Apple-converted-space"> </span></p>
  65 <p class="p2"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  66 <p class="p4"><span class="s1"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span><span class="s2">HIDDeviceService</span>.devices.at(0).queueDevice;</p>
  67 <p class="p5"><span class="Apple-tab-span">     </span></p>
  68 <p class="p3"><span class="s3"><span class="Apple-tab-span">    </span></span>4. 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.</p>
  69 <p class="p2"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  70 <p class="p3"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="s4">(</span></p>
  71 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="s2">HIDDeviceService</span>.action_({<span class="s2">arg</span> productID, vendorID, locID, cookie, val;</p>
  72 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>[productID, vendorID, locID, cookie, val].postln;</p>
  73 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>});</p>
  74 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>)</p>
  75 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  76 <p class="p3"><span class="Apple-tab-span">     </span>5. start the eventloop:</p>
  77 <p class="p2"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  78 <p class="p6"><span class="s5"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span>HIDDeviceService.<span class="s6">runEventLoop;</span></p>
  79 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  80 <p class="p3"><span class="s3"><span class="Apple-tab-span">    </span></span>6. stop the eventloop:</p>
  81 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  82 <p class="p6"><span class="s6"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span>HIDDeviceService.<span class="s6">stopEventLoop;</span></p>
  83 <p class="p2"><br></p>
  84 <p class="p2"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  85 <p class="p2"><br></p>
  86 <p class="p3"><b>buildDeviceList(usagePage, usage)</b></p>
  87 <p class="p2"><br></p>
  88 <p class="p3">It is also possible to search for devices in other usage pages. (look in the class file)</p>
  89 <p class="p3">the default is: page: GenericDesktop usage: Joystick. if a nil is passed in all devices are listed.</p>
  90 <p class="p2"><br></p>
  91 <p class="p2"><br></p>
  92 <p class="p3">//HIDDeviceServis by jan trutzschler v. falkenstein</p>
  93 <p class="p2"><br></p>
  94 <p class="p3"><b>deviceSpecs</b></p>
  95 <p class="p3"><span class="Apple-tab-span">     </span>you can add to the classvar deviceSpecs the specs of your device.</p>
  96 <p class="p3"><span class="Apple-tab-span">     </span>the key used has to be the <b>product name</b> derived from the device info.</p>
  97 <p class="p2"><span class="Apple-tab-span">     </span></p>
  98 <p class="p2"><br></p>
  99 <p class="p3">here is a collection of specs:</p>
 100 <p class="p7"><br></p>
 101 <p class="p8">//wingman</p>
 102 <p class="p4">(</p>
 103 <p class="p9"><span class="s2">HIDDeviceService</span><span class="s6">.deviceSpecs.put(</span>'WingMan Action Pad'<span class="s6">,<span class="Apple-converted-space"> </span></span></p>
 104 <p class="p6"><span class="s6"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span>IdentityDictionary<span class="s6">[</span></p>
 105 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\a</span> -&gt; 0, <span class="s7">\b</span>-&gt; 1, <span class="s7">\c</span>-&gt; 2,</p>
 106 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\x</span>-&gt; 3, <span class="s7">\y</span>-&gt; 4, <span class="s7">\z</span>-&gt; 5,</p>
 107 <p class="p8"><span class="s6"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span><span class="s7">\l</span><span class="s6">-&gt; 6, </span>//front left</p>
 108 <p class="p8"><span class="s6"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span><span class="s7">\r</span><span class="s6">-&gt; 7, </span>//front right</p>
 109 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\s</span>-&gt; 8,<span class="Apple-converted-space"> </span></p>
 110 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\mode</span>-&gt; 9,</p>
 111 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\xx</span>-&gt; 10,<span class="Apple-tab-span">        </span><span class="Apple-tab-span">    </span></p>
 112 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\yy</span>-&gt; 11,<span class="Apple-tab-span">        </span><span class="Apple-tab-span">    </span></p>
 113 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\slider</span>-&gt; 12,</p>
 114 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\hat</span>-&gt; 13</p>
 115 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>])</p>
 116 <p class="p4">)</p>
 117 <p class="p8">//cyborg</p>
 118 <p class="p4">(</p>
 119 <p class="p8"><span class="s2">HIDDeviceService</span><span class="s6">.deviceSpecs.put(</span><span class="s7">\cyborg</span><span class="s6">,<span class="Apple-converted-space">  </span></span>//not the right product name yet, so this doesn't work.</p>
 120 <p class="p6"><span class="s6"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span>IdentityDictionary<span class="s6">[</span></p>
 121 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\trig</span> -&gt; 0, <span class="s7">\a</span>-&gt; 1, <span class="s7">\b</span> -&gt; 2, <span class="s7">\c</span> -&gt; 3,</p>
 122 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\f1</span>-&gt; 4, <span class="s7">\f2</span>-&gt; 5, <span class="s7">\f3</span>-&gt; 6, <span class="s7">\f4</span> -&gt; 7,</p>
 123 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\l</span> -&gt; 8, <span class="s7">\r</span> -&gt; 9, <span class="s8">// arrow buttons</span></p>
 124 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\hu</span> -&gt; 10, <span class="s7">\hl</span> -&gt; 11, <span class="s7">\hr</span> -&gt; 12, <span class="s7">\hd</span> -&gt; 13, <span class="s8">// hat positions</span></p>
 125 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\x</span> -&gt; 14, <span class="s7">\y</span> -&gt; 15, <span class="s7">\z</span> -&gt; 16, <span class="s8">// axes</span></p>
 126 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\slider</span>-&gt; 17,</p>
 127 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="s7">\hat</span>-&gt; 18</p>
 128 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>]);</p>
 129 <p class="p4">)</p>
 130 <p class="p5"><br></p>
 131 <p class="p5"><br></p>
 132 <p class="p5"><br></p>
 133 <p class="p2"><br></p>
 134 </body>
 135 </html>