How to create a description file for an HID device

Extension

Introduction

The functionality of MKtl relies on descriptions of the devices to be used. For many controllers, there are already descriptions available, but your preferred device may not be among them.

This Tutorial first shows simple examples of HID interfaces, by emulating them within SuperCollider, and then describes how to create a description file for your interface.

• Simple element
• Write a description file and explore an HID device
• HID device info
• HID Initialisation messages

Simple element

An element for an HID device looks in general like this:(key: 'bt_1', 'hidUsage': 1, 'hidUsagePage': 9, 'elementType': 'button', 'ioType': 'in', 'spec': \hidBut )

hidUsage and hidUsagePage are the keys that identify the control from the device - these keys are crossplatform compatible. The ioType can be \in or \out. Examples of input elements are mouse axes, joystick axes, and buttons. Examples of output elements are LEDs on the device, or forcefeedback or rumble (e.g. on gamepads).

Here is an example of an output element:(key: \rumble_l, 'hidUsage': 187, 'hidUsagePage': 1, 'elementType': 'rumble', 'ioType': 'out', spec: \lin255 )

Some HID devices that do not use common elements, or have ill-defined HID descriptors built into the hardware, will have a hidUsage and hidUsagePage that is not unique. In that case the automatic generation of a description file will return an element that looks like this:(key: 'b1', 'hidElementID': 1, 'elementType': 'button', 'ioType': 'in', 'spec': \hidBut )

Instead of hidUsage and hidUsagePage we have an identifier hidElementID. This identifier may not be cross platform compatible, as different operating systems may list the order of elements differently. However, on the same operating system, it should always be the same, and thus usable with caution. See also: Working with HID, HIDUsage.

Write a description file and explore an HID device

For HID devices, you can automatically generate a description file, as the device reports what it's inputs and outputs are.m.createDescriptionFile;

For our optical mouse this creates a file called "edit and save me" with this content:---------- ( idInfo: "USB Optical Mouse_PixArt", protocol: 'hid', deviceName: "USB Optical Mouse_PixArt", deviceType: '___', elementTypes: [], status: ( linux: "unknown", osx: "unknown", win: "unknown" ), // hardwarePages: [1, 2, 3, 4], // deviceInfo: ( // vendorURI: 'http://company.com/products/this', // manualURI: 'http://company.com/products/this/manual.pdf', // description: , // features: [], // notes: , // hasScribble: false // ), elementsDesc: ( elements: [ // --------- input elements ---------- ( key: '_b1_', 'hidUsage': 1, 'hidUsagePage': 9, 'elementType': 'Button', 'ioType': 'in', 'spec': 'hidBut' ), ( key: '_b2_', 'hidUsage': 2, 'hidUsagePage': 9, 'elementType': 'Button', 'ioType': 'in', 'spec': 'hidBut' ), ( key: '_b3_', 'hidUsage': 3, 'hidUsagePage': 9, 'elementType': 'Button', 'ioType': 'in', 'spec': 'hidBut' ), ( key: '_X_', 'hidUsage': 48, 'hidUsagePage': 1, 'elementType': 'GenericDesktop', 'ioType': 'in', 'spec': '_X_' ), ( key: '_Y_', 'hidUsage': 49, 'hidUsagePage': 1, 'elementType': 'GenericDesktop', 'ioType': 'in', 'spec': '_Y_' ), ( key: '_Wheel_', 'hidUsage': 56, 'hidUsagePage': 1, 'elementType': 'GenericDesktop', 'ioType': 'in', 'spec': '_Wheel_' ), // --------- output elements ---------- ( key: '_b1_', 'hidUsage': 1, 'hidUsagePage': 9, 'elementType': 'Button', 'ioType': 'out', 'spec': 'hidBut' ), ( key: '_b2_', 'hidUsage': 2, 'hidUsagePage': 9, 'elementType': 'Button', 'ioType': 'out', 'spec': 'hidBut' ), ( key: '_b3_', 'hidUsage': 3, 'hidUsagePage': 9, 'elementType': 'Button', 'ioType': 'out', 'spec': 'hidBut' ), ( key: '_X_', 'hidUsage': 48, 'hidUsagePage': 1, 'elementType': 'GenericDesktop', 'ioType': 'out', 'spec': '_X_' ), ( key: '_Y_', 'hidUsage': 49, 'hidUsagePage': 1, 'elementType': 'GenericDesktop', 'ioType': 'out', 'spec': '_Y_' ), ( key: '_Wheel_', 'hidUsage': 56, 'hidUsagePage': 1, 'elementType': 'GenericDesktop', 'ioType': 'out', 'spec': '_Wheel_' ), ] ) ); --------

This is a fully working description file, with templates for all the info contributors should put into a desc file. Other than that, the main task now is to organize the reported flat list of elements into something semantically clearer, which will be easier to use in code.

Boiling that text down to the working minimum, idInfo, protocol, and elementsDesc are sufficient for a test description dict.

At the top of the elements array, we see that 4 buttons (on linux, 3 on osx) are detected, so we can give these names, and create an MKtl from that desc with just buttons:( ~mouseDesc = ( idInfo: "USB Optical Mouse_PixArt", protocol: 'hid', elementsDesc: ( elements: [ // --------- input elements ---------- ( key: 'b0', 'hidUsage': 0, 'hidUsagePage': 9, 'elementType': 'button', 'ioType': 'in', 'spec': 'hidBut' ), ( key: 'b1', 'hidUsage': 1, 'hidUsagePage': 9, 'elementType': 'button', 'ioType': 'in', 'spec': 'hidBut' ), ( key: 'b2', 'hidUsage': 2, 'hidUsagePage': 9, 'elementType': 'button', 'ioType': 'in', 'spec': 'hidBut' ), ( key: 'b3', 'hidUsage': 3, 'hidUsagePage': 9, 'elementType': 'button', 'ioType': 'in', 'spec': 'hidBut' ) ] ); ) ); // the elements have much info in common, so lets us move that to shared. // also, elementType 'Button' (as reported by HID) should be 'button' in Modality. ( ~mouseDesc = ( idInfo: "USB Optical Mouse_PixArt", protocol: 'hid', elementsDesc: ( shared: ('hidUsagePage': 9, 'elementType': 'button', 'ioType': 'in', 'spec': 'hidBut' ), elements: [ // --------- input elements ---------- ( key: 'b0', 'hidUsage': 0 ), ( key: 'b1', 'hidUsage': 1 ), ( key: 'b2', 'hidUsage': 2 ), ( key: 'b3', 'hidUsage': 3 ) ] ); ) ); // assign the desc to the mouse: m.rebuild( ~mouseDesc ); // make a gui for it m.gui; // and check the incoming data: m.trace;

In the posted messages, we can find b1, b2, b3, but not b0. While the HID reports a button 0 (on linux), nothing that we click seems to trigger b0, so it seems this is just a dummy element in the HID device. So we can adapt our description to:// the elements have much info in common, so lets us move that to shared: ( ~mouseDesc = ( idInfo: "USB Optical Mouse_PixArt", protocol: 'hid', elementsDesc: ( shared: ('hidUsagePage': 9, 'elementType': 'button', 'ioType': 'in', 'spec': 'hidBut' ), elements: [ ( key: 'b1', 'hidUsage': 1 ), ( key: 'b2', 'hidUsage': 2 ), ( key: 'b3', 'hidUsage': 3 ) ] ); ) ); // assign the desc to the mouse: m.rebuild( ~mouseDesc ); // and make a gui for it m.gui; // and check the incoming data: m.trace;

Next we refine the description by grouping the buttons into a group \bt, and giving the indiviudal buttons better names - left, right, middle, and reordering them as left, middle, right:( ~mouseDesc = ( idInfo: "USB Optical Mouse_PixArt", protocol: 'hid', elementsDesc: ( shared: ('hidUsagePage': 9, 'elementType': 'button', 'ioType': 'in', 'spec': 'hidBut' ), elements: [ ( key: \bt, elements: [ ( key: 'left', 'hidUsage': 1 ), ( key: 'middle', 'hidUsage': 3 ), ( key: 'right', 'hidUsage': 2 ) ] ) ] ); ) ); // assign the desc to the mouse: m.rebuild( ~mouseDesc ); // and check the incoming data: m.trace; // and make a gui: m.gui; m.trace( false ); m.elAt(\bt); // seems the same as we had before, but now we can do: m.elAt( \bt ); // the group of buttons // we can assign one single action for the group of buttons: m.elAt( \bt ).action = { arg ... args; args.postln; }; // this posts the args that are passed into the group function: // first the element, then up the hierarchy, so the \bt group. -> [ MKtlElement('bt_left', 'button', 'left'), MKtlElementGroup('bt', 'button', [ 'bt_left', 'bt_middle', 'bt_right' ]) ] m.elAt(\bt, \left); m.dictAt(\bt_left); m.elAt(0, \left); m.elAt(0, 0);

Then, looking back at the initially created file, we had three more elements that need a further definition, we will guess that they are the X and Y-axis of the mouse, and the mouse wheel.

Note that mouse axes and wheels usually create only relative values; that is, the number value tells you by how much the mouse was moved since its last position scan. You can use this to do a relative set on a process parameter, e.g. with the RelSet class.( ~mouseDesc = ( idInfo: "USB Optical Mouse_PixArt", protocol: 'hid', elementsDesc: ( shared: ('hidUsagePage': 9, 'elementType': 'button', 'ioType': 'in', 'spec': 'hidBut' ), elements: [ ( key: \bt, elements: [ ( key: 'left', 'hidUsage': 1 ), ( key: 'middle', 'hidUsage': 3 ), ( key: 'right', 'hidUsage': 2 ) ] ), (key: \x, 'hidUsage': 48, 'hidUsagePage': 1, 'elementType': 'mouseAxis', 'ioType': 'in' ), (key: \y, 'hidUsage': 49, 'hidUsagePage': 1, 'elementType': 'mouseAxis', 'ioType': 'in' ), (key: 'wheel', 'hidUsage': 56, 'hidUsagePage': 1, 'elementType': 'wheel', 'ioType': 'in' ) ] ) ) ); // assign the desc to the mouse: m.rebuild( ~mouseDesc ); // and check the incoming data: m.trace; // and make a gui m.gui;

With our mouse the resolution does not seem to be very good. So we make our custom specs.( ~mouseDesc = ( idInfo: "USB Optical Mouse_", protocol: 'hid', specs: ( mouseAxisPlus: [ 0.495, 0.505, \linear, 0, 0.5 ], mouseWheelPlus: [ 0.495, 0.505, \linear, 0, 0.5 ], ), elementsDesc: ( shared: ('hidUsagePage': 9, 'elementType': 'button', 'ioType': 'in', 'spec': 'hidBut' ), elements: [ ( key: \bt, elements: [ ( key: 'left', 'hidUsage': 1 ), ( key: 'middle', 'hidUsage': 3 ), ( key: 'right', 'hidUsage': 2 ) ] ), (key: \x, 'hidUsage': 48, 'hidUsagePage': 1, 'elementType': 'mouseAxis', 'ioType': 'in' ), (key: \y, 'hidUsage': 49, 'hidUsagePage': 1, 'elementType': 'mouseAxis', 'ioType': 'in' ), (key: 'wheel', 'hidUsage': 56, 'hidUsagePage': 1, 'elementType': 'wheel', 'ioType': 'in' ) ] ) ); ) // assign the desc to the mouse: m.rebuild( ~mouseDesc ); // and check the incoming data: m.trace; // and make a gui: m.gui; // cleanup: m.trace( false ); m.free;

HID device info

In the description file, an HID device needs an idInfo, which is created from the device's productName and vendorName.// dump the info the HID object has: m.mktlDevice.source.info.dump // inspect just the productName: m.mktlDevice.source.info.productName.postcs // posts: "USB Optical Mouse" // inspect vendorName: m.mktlDevice.source.info.vendorName.postcs // posts: ""

For our mouse the vendorName is left blank, apparently the vendor did not bother to list it in its device. Here is a little shortcut to create the string:m.lookupInfo.idInfo;

HID Initialisation messages

Some devices need initialisation messages to be sent before they can function properly with all their modes activated. You can define these messages in the initalisationMessages field of the device description.

For HID we do not have a usecase yet where this is needed, so we do not know yet how to format these messages. Write us if you have a usecase!