Help/Control/GeneralHID.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="949.46">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.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: 9.0px Monaco; min-height: 12.0px}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco; min-height: 12.0px}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica; min-height: 14.0px}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 14.0px Helvetica}
  18 p.p9 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000}
  19 p.p10 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
  20 span.s1 {font: 18.0px Helvetica}
  21 span.s2 {color: #0000bf}
  22 span.s3 {text-decoration: underline ; color: #0000bf}
  23 span.s4 {color: #0000bf}
  24 span.s5 {color: #0000bf}
  25 span.Apple-tab-span {white-space:pre}
  26 </style>
  27 </head>
  28 <body>
  29 <p class="p1"><span class="s1"><b>GeneralHID<span class="Apple-tab-span">       </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></b></span><b>A uniform class to access HID devices<span class="Apple-converted-space"> </span></b><span class="s1"><b><span class="Apple-tab-span">    </span></b></span></p>
  30 <p class="p2"><br></p>
  31 <p class="p1"><b>Inherits from: </b><a href="../Core/Object.html"><span class="s2"><b>Object</b></span></a></p>
  32 <p class="p3"><br></p>
  33 <p class="p1">GeneralHID is a cross platform wrapper for accessing HID devices. Currently the MacOSX and Linux HID support has been wrapped. Some of the code is inspired by the GUI wrapper.</p>
  34 <p class="p2"><br></p>
  35 <p class="p1"><b>It is advised to use this class instead of the platform specific classes:</b> <a href="HIDDeviceService.html"><span class="s2">HIDDeviceService</span><span class="s3"> (on MacOSX)</span></a> and <a href="../Linux/LID.html"><span class="s2">LID</span><span class="s3"> (on Linux)</span></a></p>
  36 <p class="p1">There are intermediate "bridge" classes <span class="s2">MXHID</span> (on MacOSX) and <span class="s2">GLID</span> (on Linux), which should not be used directly, but their names will show up in the output of some of the methods of <span class="s2">GeneralHID</span>.</p>
  37 <p class="p2"><br></p>
  38 <p class="p4"><b>Some outstanding issues</b></p>
  39 <p class="p2"><br></p>
  40 <p class="p1">This class is not completely finished yet. Common slot numbers across platforms are not yet guaranteed. On Windows there is not yet a proper implementation available, but you can use HID Server from <a href="http://ixi-software.net/content/backyard.html">Ixi's backyard</a>, which comes with classes which are compatible with GeneralHID.</p>
  41 <p class="p2"><br></p>
  42 <p class="p4"><b>Creation / Class Methods</b></p>
  43 <p class="p5"><br></p>
  44 <p class="p6"><b><span class="Apple-tab-span">  </span>*scheme , *current</b></p>
  45 <p class="p6"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>Get the current scheme</p>
  46 <p class="p7"><b><span class="Apple-tab-span">  </span></b></p>
  47 <p class="p6"><b><span class="Apple-tab-span">  </span>*scheme.id , *current.id</b></p>
  48 <p class="p6"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>Get the current scheme ID</p>
  49 <p class="p7"><b><span class="Apple-tab-span">  </span></b></p>
  50 <p class="p6"><b><span class="Apple-tab-span">  </span>*buildDeviceList</b></p>
  51 <p class="p6"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>Look for all connected devices and build a device list. This returns the devicelist as an Array.</p>
  52 <p class="p7"><b><span class="Apple-tab-span">  </span></b></p>
  53 <p class="p6"><b><span class="Apple-tab-span">  </span>*deviceList</b></p>
  54 <p class="p6"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>Returns the device list if it has already been built before.</p>
  55 <p class="p7"><b><span class="Apple-tab-span">  </span></b></p>
  56 <p class="p6"><b><span class="Apple-tab-span">  </span>*postDevices</b></p>
  57 <p class="p6"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>Posts a readable list of devices.</p>
  58 <p class="p7"><b><span class="Apple-tab-span">  </span></b></p>
  59 <p class="p6"><b><span class="Apple-tab-span">  </span>*postDevicesAndProperties</b></p>
  60 <p class="p6"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>Posts a readable list of devices and their properties.</p>
  61 <p class="p7"><b><span class="Apple-tab-span">  </span></b></p>
  62 <p class="p6"><b><span class="Apple-tab-span">  </span>*startEventLoop( arg rate=0.005 )</b></p>
  63 <p class="p6"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>Start the eventloop with a update rate (or rather update time in seconds). (Note: this is only really needed on MacOSX, but for crossplatform code you should include it in your code).</p>
  64 <p class="p7"><b><span class="Apple-tab-span">  </span></b></p>
  65 <p class="p6"><b><span class="Apple-tab-span">  </span>*stopEventLoop</b></p>
  66 <p class="p6"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>Stop the eventloop.</p>
  67 <p class="p7"><b><span class="Apple-tab-span">  </span></b></p>
  68 <p class="p6"><b><span class="Apple-tab-span">  </span>*eventLoopIsRunning</b></p>
  69 <p class="p6"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>Check status of eventloop.</p>
  70 <p class="p7"><b><span class="Apple-tab-span">  </span></b></p>
  71 <p class="p6"><b><span class="Apple-tab-span">  </span>*findBy( vendorID, productID, locID, versionID )</b></p>
  72 <p class="p6"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>Find a device by its vendorID (manufacturer), productID (product identifier as given by manufacturer), locID (identifier for the physical connection to your computer, and versionID (a version of the product, as given by the manufacturer).</p>
  73 <p class="p7"><b><span class="Apple-tab-span">  </span></b></p>
  74 <p class="p7"><b></b><br></p>
  75 <p class="p8"><b>Further information:</b></p>
  76 <p class="p1"><b>See </b><a href="GeneralHIDDevice.html"><span class="s2">GeneralHIDDevice</span></a> for a documentation of the methods to access an HID device.</p>
  77 <p class="p1"><b>See </b><a href="GeneralHIDSpec.html"><span class="s4">GeneralHIDSpec</span></a> for a documentation of how to access slots by name, instead of numbers.</p>
  78 <p class="p8"><b>Example</b></p>
  79 <p class="p3"><br></p>
  80 <p class="p9">// General structure to access a device</p>
  81 <p class="p9">// Look for the devices that are attached:</p>
  82 <p class="p10"><span class="s5">GeneralHID</span>.buildDeviceList;</p>
  83 <p class="p9">// Get the list of devices:</p>
  84 <p class="p10">d = <span class="s5">GeneralHID</span>.deviceList;</p>
  85 <p class="p9">// Check which devices have been found:</p>
  86 <p class="p10"><span class="s5">GeneralHID</span>.postDevices;</p>
  87 <p class="p9">// Pick the 6th device and open it and create an instance of it:</p>
  88 <p class="p10">a = <span class="s5">GeneralHID</span>.open( d[5] )</p>
  89 <p class="p9">// Get info on the device:</p>
  90 <p class="p10">a.info;</p>
  91 <p class="p9">// if you want to automatically find the device when you restart you can use the GeneralHID.findBy method. To get the arguments you should use for this function, you can use:</p>
  92 <p class="p10">a.info.findArgs;</p>
  93 <p class="p9">// this outputs for my Impact gamepad:</p>
  94 <p class="p10">[ 1973, 786, usb-0000:00:1d.0-1/input0, 272 ]</p>
  95 <p class="p9">// close the device, as we will reopen it in the next lines</p>
  96 <p class="p10">a.close;</p>
  97 <p class="p9">// if we know which device we want, we can find it:</p>
  98 <p class="p10">b = GeneralHID.findBy( 1973, 786, "usb-0000:00:1d.0-1/input0", 272 );</p>
  99 <p class="p9">// if you do not care about the version or the location, you can also do:</p>
 100 <p class="p10">b = GeneralHID.findBy( 1973, 786 );</p>
 101 <p class="p9">// or if you do not even care about the productID</p>
 102 <p class="p10">b = GeneralHID.findBy( 1973 );</p>
 103 <p class="p9">// you can then open it by:</p>
 104 <p class="p10">a = GeneralHID.open( b )</p>
 105 <p class="p9">// Start eventloop:</p>
 106 <p class="p10"><span class="s5">GeneralHID</span>.startEventLoop</p>
 107 <p class="p9">// Get the capabilities of the device in a readable format:</p>
 108 <p class="p10">a.caps;</p>
 109 <p class="p9">// there are different types of slots:<br>
 110 // button (type 1), has only on/off (1/0) states<br>
 111 // relative (type 2), counts up or down (scrollwheel for example)<br>
 112 // absolute (type 3), continuous value between 0 and 1<br>
 113 // some other may show up on Linux ( Syn (type 0) and Miscellaneous (type 4), but these are generally not very useful).</p>
 114 <p class="p9">// See if data is coming in:</p>
 115 <p class="p10">a.debug_( true );</p>
 116 <p class="p9">// Stop it:</p>
 117 <p class="p10">a.debug_( false );</p>
 118 <p class="p9">// Debugging can be turned on for each slot individually, if necessary:<br>
 119 //(IBM trackpoint)</p>
 120 <p class="p10">a.slots[1].at( 272 ).debug_( true );</p>
 121 <p class="p9">// (external mouse on macbook pro)</p>
 122 <p class="p10">a.slots[3][1].debug_(true);</p>
 123 <p class="p9">(external mouse on ibm thinkpad)</p>
 124 <p class="p10">a.slots[2][1].debug_(true);</p>
 125 <p class="p9">// Turn it off again: // (IBM trackpoint)</p>
 126 <p class="p10">a.slots[1].at( 272 ).debug_( false );</p>
 127 <p class="p9">//(external mouse on macbook pro)</p>
 128 <p class="p10">a.slots[3][48].debug_(false);</p>
 129 <p class="p9">//(external mouse on ibm thinkpad)</p>
 130 <p class="p10">a.slots[3][1].debug_(false);</p>
 131 <p class="p3"><br></p>
 132 <p class="p9">// You can also create a generic gui to see what is coming in:</p>
 133 <p class="p10">a.makeGui;</p>
 134 <p class="p3"><br></p>
 135 <p class="p9">// The current value of a slot can be checked:</p>
 136 <p class="p10">a.slots[1].at( 272 ).value;<br>
 137 a.slots[2].at( 1 ).value;<br>
 138 a.slots[3][1].value</p>
 139 <p class="p9">//If the slot is an LED, you can set the value:</p>
 140 <p class="p10">a.slots[11][0].value = 1;<br>
 141 a.slots[11][0].value = 0;</p>
 142 <p class="p3"><br></p>
 143 <p class="p9">// Actions can be mapped to each slot individually.</p>
 144 <p class="p10">a.slots[1].at( 272 ).action_( { "hello".postln; } );<br>
 145 a.slots[1].at( 273 ).action_( { "hi".postln; } );<br>
 146 a.slots[3].at( 1 ).action_( { "hi".postln; } );</p>
 147 <p class="p9">with an input to the function</p>
 148 <p class="p10">a.slots[3].at( 1 ).action_( { |v| "hi, my value is ".post; v.value.postln; } );<br>
 149 a.slots[1].at( 272 ).action_( { |v| "hi, my value is ".post; v.value.postln; } );</p>
 150 <p class="p3"><br></p>
 151 <p class="p9">To stop the action, assign it to an empty function.</p>
 152 <p class="p10">a.slots[1].at( 272 ).action_( {} );<br>
 153 a.slots[1].at( 273 ).action_( {} );<br>
 154 a.slots[3].at( 1 ).action_( {} );</p>
 155 <p class="p3"><br></p>
 156 <p class="p9">// you can access slots, by giving them a key:</p>
 157 <p class="p10">a.add( \lx, [3,0] );</p>
 158 <p class="p10">a[\lx].debug_( true );</p>
 159 <p class="p9">// the last item in the output array, now shows the key</p>
 160 <p class="p10">a[\lx].debug_( false );</p>
 161 <p class="p9">// save the spec for future use:</p>
 162 <p class="p10">a.spec.save( "Impact_help" );</p>
 163 <p class="p9">// find a spec defined previously for this device:</p>
 164 <p class="p10">c = a.findSpec;</p>
 165 <p class="p9">// set it:</p>
 166 <p class="p10">a.setSpec( c[0] );</p>
 167 <p class="p9">// more info on this in the [GeneralHIDSpec] helpfile</p>
 168 <p class="p9">// If the server is running you can create a control bus for the HID data to go to, so that a synth can immediately read the data:</p>
 169 <p class="p10">s = Server.local.boot;</p>
 170 <p class="p9">// To create the bus:</p>
 171 <p class="p10">a.slots[1].at( 272 ).createBus( s ); a.slots[2].at( 8 ).createBus( s );</p>
 172 <p class="p3"><br></p>
 173 <p class="p10">SynthDef( \hidbus_help, { |out=0,amp=0|<br>
 174 Out.ar( out, SinOsc.ar( 300, 0, 0.01*amp.abs ) );<br>
 175 }).load( s );<br>
 176 )</p>
 177 <p class="p10">x = Synth.new( \hidbus_help );<br>
 178 x.map( \amp, a.slots[2].at( 8 ).bus );<br>
 179 x.free;</p>
 180 <p class="p3"><br></p>
 181 <p class="p10">( // a nicer version:<br>
 182 SynthDef( \hidbus_help, { |out=0,amp=0,amp2=0|<br>
 183 Out.ar( out, SinOsc.ar( 300, 0, 0.01*amp.abs.lag( 0.1 ) * amp2.lag(0.01,0.99) ) );<br>
 184 }).load( s );<br>
 185 )</p>
 186 <p class="p10">x = Synth.new( \hidbus_help );<br>
 187 x.map( \amp, a.slots[2].at( 8 ).bus );<br>
 188 x.map( \amp2, a.slots[1].at( 272 ).bus );<br>
 189 x.free;</p>
 190 <p class="p3"><br></p>
 191 <p class="p10">( // an even nicer version:<br>
 192 SynthDef( \hidbus_help, { |out=0,freqadd=0,amp=0|<br>
 193 Out.ar( out, SinOsc.ar( 300 + (freqadd.lag(0.2,1)*40), 0, 0.2*amp.lag(0.01,0.99) ) );<br>
 194 }).load( s );<br>
 195 )</p>
 196 <p class="p10">x = Synth.new( \hidbus_help );<br>
 197 x.map( \freqadd, a.slots[2].at( 8 ).bus );<br>
 198 x.map( \amp, a.slots[1].at( 272 ).bus );<br>
 199 x.free;</p>
 200 <p class="p3"><br></p>
 201 <p class="p9">// To free the bus:</p>
 202 <p class="p10">a.slots[1].at( 272 ).freeBus;<br>
 203 a.slots[2].at( 8 ).freeBus;<span class="Apple-converted-space"> </span></p>
 204 <p class="p9">// Close the device after use:</p>
 205 <p class="p10">a.close;</p>
 206 <p class="p10"><span class="s5">GeneralHID</span>.stopEventLoop</p>
 207 <p class="p3"><br></p>
 208 </body>
 209 </html>