hid2osc manual

About

The hid2osc application reads values from devices that meet the HID (Human Interface Device) specification (most mice and joysticks) and outputs those values as OSC (Open Sound Control). OSC can be used to control various applications.

Running it

Run hid2osc from the command line or by double clicking it. On the first launch the application creates a configuration file with entries for all connected HID devices. To see what the application actually spits out you can use an OSC monitor like dumpOSC, http://www.cnmat.berkeley.edu/OpenSoundControl/dumpOSC.html . Hid2osc to OSC sends by default over 5000, so tell dumpOSC from the command line to listen on port 5000 ( dumpOSC 5000 )

Configuring it

By editing the configuration file you can specify for each HID device which OSC addresses it should send to and which UDP ports it should use. The configuration file gets generated when the application is first launched and is adapted each time a "not yet configured" HID device is recognized. Once hid2osc has added an entry for the device in its configuration file you can tweak the device. Hid2osc needs to be restarted to make the edited configuration active.
N.B. Editing XML should be done very carefully, because invalid XML might make the application fail to launch.

The configuration file can be found here : "~/Library/Preferences/KWlive/hid2osc.xml" and it looks a bit like this:

<?xml version="1.0" ?>
<devicelist>
    <destination address="127.0.0.1" port="5000" />
    <destination address="127.0.0.1" port="5001" />
    <device name="USB Mouse" active="false" required="false" id="454164480" typeid="12872960" oscname="mouse1">
        <!--<destination address="127.0.0.1" port="5000" />-->
        <element name="Mouse" oscaddress="/HID/mouse1/Mouse" />
        <element name="Pointer" oscaddress="/HID/mouse1/Pointer" />
        <element name="Button #1" oscaddress="/HID/mouse1/Button1" fixedvalue="0.25" />
        <element name="Button #2" oscaddress="/HID/mouse1/Button2" />
        <element name="Button #3" oscaddress="/HID/mouse1/Button3" />
        <element name="X-Axis" oscaddress="/HID/mouse1/X-Axis" />
        <element name="Y-Axis" oscaddress="/HID/mouse1/Y-Axis" />
        <element name="Wheel" oscaddress="/HID/mouse1/Wheel" />
        <element name="Motion Wakeup" oscaddress="/HID/mouse1/MotionWakeup" />
    </device>
    <device name="Trackpad" active="true" required="false" id="50397184" typeid="371712" oscname="trackpad1">
        <!--<destination address="127.0.0.1" port="5000" />-->
        <element name="Mouse" oscaddress="/HID/trackpad1/Mouse" />
        <element name="Pointer" oscaddress="/HID/trackpad1/Pointer" />
        <element name="X-Axis" oscaddress="/HID/trackpad1/X-Axis" />
        <element name="Y-Axis" oscaddress="/HID/trackpad1/Y-Axis" />
        <element name="Button #1" oscaddress="/HID/trackpad1/Button1" />
    </device>
</devicelist>

the configuration file explained

• "outer" destination address :
  this address is used as destination address for all devices that don't have destination address defined within the device tag. You can add as many destinations as you want. The current configuration makes the application send using both port 5000 as port 5001

• device :
  for each unique device type a device tag gets created. Device types generally are unique by "model", the application cannot distinguish between two devices that have the same manufacturer and model, since most manufacturers use serial numbers. When two devices of the same model are connected hid2osc will make two configurations. The first configuration is used for the first device found. The order might change when you, for instance, switch the USB connectors.
  • typeid : used for matching the found device with the config.... DON'T EDIT
  • active : (true,false) define whether hid2osc should send data from this device
  • required: (true,false) define whether hid2osc should not launch when a device cannot be found
  • oscname: used for distinguishing multiple devices of the same model... GENERALLY DON'T EDIT

• "inner" destination address :
  this address is used as destination address for this device only. You can add as many destinations as you want. The destinations specified here overrule the general destination. The current configuration makes no use of this option, since the "inner" destination tags are "uncommented".

• element :
  generally each knob, button or continuous controller on a device is an element. For each element you can specify which address its data should be send to
  • name : used for matching the element with the config.... DON'T EDIT
  • oscaddress : specify the desired OSC address here.
  • fixedvalue (optional): make hid2osc always send the same fixed value for this element. Usefull for button arrays (i.e. dancemat).
  • nr (optional): some HID devices use "pages" of elements, with on each page the same elements (names). You can add a "page" nr to distinguish them.

Convince yourself the OSC addresses are valid when you edit them, the initially generated address addresses are always valid and based upon the device its name. Look here http://www.cnmat.berkeley.edu/OpenSoundControl/ for a specification of the protocol.

---