USB HID Support on Pico!

[gfwilliams]

Posted at 2015-05-29 by @gfwilliams

I've finally managed to add USB HID support on the Pico. An experimental binary for it should be here in an hour or two.

It's taken most of last and this week to work my way around ST's USB drivers, and they now don't bare much relation to the originals at all :(

So... How do you use it?

// Simple mouse
E.setUSBHID({
  reportDescriptor : [
  0x05,   0x01,
  0x09,   0x02,
  0xA1,   0x01,
  0x09,   0x01,

  0xA1,   0x00,
  0x05,   0x09,
  0x19,   0x01,
  0x29,   0x03,

  0x15,   0x00,
  0x25,   0x01,
  0x95,   0x03,
  0x75,   0x01,

  0x81,   0x02,
  0x95,   0x01,
  0x75,   0x05,
  0x81,   0x01,

  0x05,   0x01,
  0x09,   0x30,
  0x09,   0x31,
  0x09,   0x38,

  0x15,   0x81,
  0x25,   0x7F,
  0x75,   0x08,
  0x95,   0x03,

  0x81,   0x06,
  0xC0,   0x09,
  0x3c,   0x05,
  0xff,   0x09,

  0x01,   0x15,
  0x00,   0x25,
  0x01,   0x75,
  0x01,   0x95,

  0x02,   0xb1,
  0x22,   0x75,
  0x06,   0x95,
  0x01,   0xb1,

  0x01,   0xc0 ]
});

function mouse(x,y,b) {
  E.sendUSBHID([b&7,x,y,0]);
}

// Now save, unplug USB and re-plug it

mouse(20,20,0); // moves mouse diagonally down

// Simple Keyboard

E.setUSBHID({
  reportDescriptor : [
        0x05, 0x01,          // Usage Page (Generic Desktop),
        0x09, 0x06,          // Usage (Keyboard),
        0xA1, 0x01,          // Collection (Application),
        0x75, 0x01,          //   Report Size (1),
        0x95, 0x08,          //   Report Count (8),
        0x05, 0x07,          //   Usage Page (Key Codes),
        0x19, 0xE0,          //   Usage Minimum (224),
        0x29, 0xE7,          //   Usage Maximum (231),
        0x15, 0x00,          //   Logical Minimum (0),
        0x25, 0x01,          //   Logical Maximum (1),
        0x81, 0x02,          //   Input (Data, Variable, Absolute), ;Modifier byte
        0x95, 0x01,          //   Report Count (1),
        0x75, 0x08,          //   Report Size (8),
        0x81, 0x03,          //   Input (Constant),                 ;Reserved byte
        0x95, 0x05,          //   Report Count (5),
        0x75, 0x01,          //   Report Size (1),
        0x05, 0x08,          //   Usage Page (LEDs),
        0x19, 0x01,          //   Usage Minimum (1),
        0x29, 0x05,          //   Usage Maximum (5),
        0x91, 0x02,          //   Output (Data, Variable, Absolute), ;LED report
        0x95, 0x01,          //   Report Count (1),
        0x75, 0x03,          //   Report Size (3),
        0x91, 0x03,          //   Output (Constant),                 ;LED report padding
        0x95, 0x06,          //   Report Count (6),
        0x75, 0x08,          //   Report Size (8),
        0x15, 0x00,          //   Logical Minimum (0),
        0x25, 0x68,          //   Logical Maximum(104),
        0x05, 0x07,          //   Usage Page (Key Codes),
        0x19, 0x00,          //   Usage Minimum (0),
        0x29, 0x68,          //   Usage Maximum (104),
        0x81, 0x00,          //   Input (Data, Array),
        0xc0                 // End Collection
  ]
});

  // 1 = modifiers
  // 2 = ?
  // 3..8 = key codes currently down

var KEY = {
  A           : 4 ,
  B           : 5 ,
  C           : 6 ,
  D           : 7 ,
  E           : 8 ,
  F           : 9 ,
  G           : 10,
  H           : 11,
  I           : 12,
  J           : 13,
  K           : 14,
  L           : 15,
  M           : 16,
  N           : 17,
  O           : 18,
  P           : 19,
  Q           : 20,
  R           : 21,
  S           : 22,
  T           : 23,
  U           : 24,
  V           : 25,
  W           : 26,
  X           : 27,
  Y           : 28,
  Z           : 29
};

function tap(key) {
  E.sendUSBHID([0,0,key,0,0,0,0,0]);
  setTimeout(function() { E.sendUSBHID([0,0,0,0,0,0,0,0]); }, 10);
}

function type(txt, callback) {
  if (!txt.length) return;
  var int = setInterval(function() {
    tap(KEY[txt[0]]);
    txt = txt.substr(1);
    if (!txt.length) clearInterval(int);
  }, 20);
}

// Now save, unplug USB and re-plug it

type("HELLOWORLD");

I'll make these all into libraries when it's ready for a proper release, but it's quite usable even now :)

[gfwilliams]

Posted at 2015-05-29 by @gfwilliams

Just to add, the keyboard stuff is shamefully ripped off the Teensy 3 USB library - there must be a better source of USB report descriptors, but I can't find one :(

[gfwilliams]

Posted at 2015-05-29 by @gfwilliams

Just to add, at the moment this will only work if you power the pico from a battery, and then plug into USB after. It's an easy fix, I just forgot to do it before posting this

[gfwilliams]

Posted at 2015-06-04 by @gfwilliams

With USB, when you plug a device in it's 'enumerated' - the host computer asks it what it is and what it can do. So to tell the PC it's a mouse, Espruino has to know to do that at the time it's plugged in.

When HID is enabled, Espruino actually enumerates as a HID device and a COM port, so you can still communicate with it just like before - including changing the USB HID code on the fly. Only if you want to change what it enumerates as, you have to unplug and re-plug it.

I've already tweaked the code so that Espruino can appear as a USB HID device even when it's plugged straight in without a battery, but there are some really strange compilation issues. Sometimes it works fine, and sometimes it only receives the first 2 characters of anything you send it - so right now it's not something I can release!

[gfwilliams]

Posted at 2015-06-04 by @gfwilliams

:) Looks like it's as easy as googling for it: https://forums.obdev.at/viewtopic.php?t=2559

In case the link goes down:

/* declare a digitzer device generated with HID Descriptor tool */
/* 4 buttons (reports only 3 for compatibility), absolute pointer , normally generates X/Y valus of max. 15 bits    
 * this represents an absolute pointer device with a resolution of 0.1 mm (2972 dots on a 29,7 cm tablet)
 * to the OS . 
*/
PROGMEM char usbHidReportDescriptor[60] = {
    0x05, 0x01,                    // USAGE_PAGE (Generic Desktop)
    0x09, 0x02,                    // USAGE (Mouse)
    0xa1, 0x01,                    // COLLECTION (Application)
    0x09, 0x01,                    //   USAGE (Pointer)
    0xa1, 0x00,                    //   COLLECTION (Physical)
    0x05, 0x09,                    //     USAGE_PAGE (Button)
    0x19, 0x01,                    //     USAGE_MINIMUM (Button 1)
    0x29, 0x03,                    //     USAGE_MAXIMUM (Button 3)
    0x15, 0x00,                    //     LOGICAL_MINIMUM (0)
    0x25, 0x01,                    //     LOGICAL_MAXIMUM (1)
    0x95, 0x03,                    //     REPORT_COUNT (3)
    0x75, 0x01,                    //     REPORT_SIZE (1)
    0x81, 0x02,                    //     INPUT (Data,Var,Abs)
    0x95, 0x01,                    //     REPORT_COUNT (1)
    0x75, 0x05,                    //     REPORT_SIZE (5)
    0x81, 0x03,                    //     INPUT (Cnst,Var,Abs)
    0x05, 0x01,                    //     USAGE_PAGE (Generic Desktop)
    0x09, 0x30,                    //     USAGE (X)
    0x09, 0x31,                    //     USAGE (Y)
    0x35, 0x00,                    //     PHYSICAL_MINIMUM (0)
    0x46, 0x9d, 0x0b,              //     PHYSICAL_MAXIMUM (2973)
    0x15, 0x00,                    //     LOGICAL_MINIMUM (0)
    0x26, 0x9d, 0x0b,              //     LOGICAL_MAXIMUM (2973)
    0x65, 0x11,                    //     UNIT (SI Lin:Distance)
    0x55, 0x0e,                    //     UNIT_EXPONENT (-2)
    0x75, 0x10,                    //     REPORT_SIZE (16)
    0x95, 0x02,                    //     REPORT_COUNT (2)
    0x81, 0x02,                    //     INPUT (Data,Var,Abs)
    0xc0,                          //   END_COLLECTION
    0xc0                           // END_COLLECTION
};

... but yes, I'll try and remember to put that in as another module.

[gfwilliams]

Posted at 2015-06-04 by @gfwilliams

Yes, it can be zero - it's just whether buttons are pressed or not. I'll put definitions in the modules, but it's 1=left, 2=right, 4=middle - a bit like dealing with low-level GUI events tends to be :)

I think at some point the modules will need a bit of tidying - for instance making sure you can actually print a line of text to the Keyboard.

As a fun aside, you can now do something like this:

var kb = require("USBKeyboard");

var data = [];

setInterval(function() {
  if (data.length>=40) data = data.slice(-39);
  data.push(E.getTemperature());
}, 1000);

function outputData() {
  var i = 0;
  function outputLine() {
    if (i>=data.length) return;
    var s = data[i++].toFixed(2)+",\n";
    kb.type(s, outputLine);
  }
  outputLine();
}

setWatch(outputData, BTN, {debounce:100,repeat:true, edge:"rising"});

I'll post a link to the latest version in a bit

[gfwilliams]

Posted at 2015-06-04 by @gfwilliams

Ok, updated firmware is here now

USB HID documentation and examples at http://www.espruino.com/USB

[gfwilliams]

Posted at 2015-06-05 by @gfwilliams

This build still needs external Battery or just the save()?

Just save() this time, but I think you figured that out? :)

can one grab and use the console's serial port on the Espruino side for that so that data sent to the USB modem dev on the host would end up in some serial buffer on the Pico?

Yes, you just need to move the console out the way and then you can do what you want:

LoopbackA.setConsole(); // or you can put it on Serial1 if you want?
USB.on('data',function(d) { ... });

USBTablet

Ok, I'll update the module. Very interesting that a plug in device can crash the UI! :o

As you say, I doubt the clipping/offset is anything Pico-related - the data sent from the Pico obviously doesn't have anything done to it (it works fine on Linux), so I wonder whether your Macs have some kind of 'calibration' that's applied?

Very strange about the keyboard example and the context menu - I actually tried that on a Mac and it worked great.

the physical minimum/maximum value ... don't seem to have any effect

Interesting - so it's just the logical values? To be honest I didn't read it properly and assumed they were X and Y.

[gfwilliams]

Posted at 2015-06-05 by @gfwilliams

Just to add - I'm interested how people get on in Windows. I don't know if it's the ST VCP drivers grabbing the device to themselves, but I didn't have any luck with it.

[gfwilliams]

Posted at 2015-06-08 by @gfwilliams

Is it possible to configure this to do "RawHID"?

It should be possible to send 'RawHID' now - I think you can basically just copy the device descriptor from the Teensy's code. Receiving would require a bit more work though - it's possible in the future, but right now I want to get the current HID implementation working well first.

mouse doesn't appear to work at all on any of the 3 test boxes.

Are these all Windows? Do you get any errors reported, or any devices shown in the device manager?

[gfwilliams]

Posted at 2015-06-25 by @gfwilliams

What do you mean about 'looking more like known ones'? If you can get the HID Descriptor of a device you want to emulate, you should just be able to copy it... Or do you mean changing the device name that gets reported?

I don't think anyone asked about hiding the serial port so far? It wasn't on my list of things to do. Is it causing you problems having it there, or are you looking at putting it inside something and want to hide the fact that it's actually an Espruino?

[gfwilliams]

Posted at 2015-06-25 by @gfwilliams

What type of HID device are you having problems with?

My understanding is that something like Windows will load drivers for one reported interface even if it doesn't know anything about the other one. It's definitely been the case with other products (like the Nucleo boards, where even without drivers you still get the mass storage interface).

But you're saying that even if you install the ST drivers that'll handle the virtual COM port, the second you enable HID as well, VCP stops working too?

It could potentially be some issue with Espruino's Device Qualifier. At the moment it seems to do the totally standard thing of saying 'each interface defines what it is', but I guess it's possible that for no-driver operation it should instead be saying 'I'm a mouse'.

It's a hard one - if you can find out what needs changing I can have a go at implementing it, but I have a lot of work on at the moment so I can't spend days implementing stuff just because it might save you a bit of time.

You can always compile your own version of the NEW_USB branch - instructions are on GitHub. Once you're doing that you can tweak the device descriptors just by changing this file - to the point where you could even pull out the USB CDC interface.

[gfwilliams]

Posted at 2015-07-16 by @gfwilliams

You'd have to send the code, save() it, then unplug and re-plug - did you do that?

Espruino can only add new USB devices when it connects to USB - but after it's done that then you can dynamically change the code as usual.

(It also works without save() if you just keep Espruino powered with something like a battery)

I finally merged the USB code into the master branch, so for an up to date build you can just use one of the latest builds, like this one. The build you have should still work though.

[gfwilliams]

Posted at 2015-07-16 by @gfwilliams

And you're using the updated firmware from my last post, and the code that you posted above?

Because I tried that just now and it works great. Just booted a mac up and it works on that too.

[gfwilliams]

Posted at 2015-07-17 by @gfwilliams

@loopmasta upgraded :) I changed the version numbering so 1vXX is a main release (or an old one!) and 1vXX.YY is Y git commits after the release of version 1vXX

I'm not personally doing USB Midi right now, but if you can find the magic USB descriptor for it, it should be pretty easy to get working.

[gfwilliams]

Posted at 2015-07-17 by @gfwilliams

Actually just took a quick look at this, and it seems that USB MIDI isn't a HID device after all (at least looking at this code), which means a report descriptor may not be enough.

If that's the case I'm afraid you might be out of luck - it'd require changes to Espruino to let you specify the whole config descriptor. I hadn't done that because it's actually very device specific (setting endpoints and suchlike) and it also contains stuff to do with the USB com port as well.

[gfwilliams]

Posted at 2015-07-22 by @gfwilliams

Actually I just found the problem - it was with the USBKeyboard module, not USB HID itself.

If you try uploading your code again now it should probably work fine.

[gfwilliams]

Posted at 2015-07-22 by @gfwilliams

What changed between times?

If you were using the firmware I posted above both times, it shouldn't have affected the way Espruino enumerates (just what happens when you press the button).

[gfwilliams]

Posted at 2015-07-22 by @gfwilliams

Yes, I think there may be some problem when repeatedly writing USB HID code to Espruino (it doesn't happen when I upload normal bits of JS, but recently I've had similar problems when trying to update USB HID code).

[gfwilliams]

Posted at 2015-07-22 by @gfwilliams

Ok, thanks - I just had a try and noticed this too.

Has anyone actually had any luck with Windows at any point, for Mouse or Keyboard?

I wonder if it's to do with the descriptor not being right, or is just because the ST com port drivers are somehow 'grabbing' the whole device. I guess there must be some kind of debug info available in windows.

Sigh. This is why I hate doing anything remotely platform specific - not that HID actually should be!

[gfwilliams]

Posted at 2015-07-22 by @gfwilliams

Hmm. That log isn't hugely helpful - I wonder what the problem starting actually was, as it doesn't seem to say much more than had a problem starting.?

What happens if you now use one of the older builds (that had the device subclass set as a mouse) with the example code for the mouse? Does it work any better?

[gfwilliams]

Posted at 2015-07-22 by @gfwilliams

Yeah, maybe not bad with their driver, but it probably claims the whole device. I'll have to look into doing a custom inf file like MicroPython does.

This build would probably work ok - it's the one just before I changed the HID details.

[gfwilliams]

Posted at 2015-07-23 by @gfwilliams

@Jean-Philippe_Rey Thanks, that's a good point - and there's also usb_desc.c:129 (not sure why those details are specified twice?). I wonder if setting it to 0 would affect enumeration when it was just a CDC device.

I'm actually having troubles with the build at the moment (sometimes it works, sometimes the build doesn't enumerate at all when using HID) so it's proving hard to test.

[gfwilliams]

Posted at 2015-07-23 by @gfwilliams

Hmm, no luck I'm afraid.

In usbd_cdc_hid.c it turns out the 2 you see if actually the USB version number. I just added comments to it:

/* USB Standard Device Descriptor */
__ALIGN_BEGIN static const uint8_t USBD_CDC_HID_DeviceQualifierDesc[USB_LEN_DEV_QUALIFIER_DESC] __ALIGN_END =
{
  USB_LEN_DEV_QUALIFIER_DESC,    // bLength
  USB_DESC_TYPE_DEVICE_QUALIFIER,// bDescriptorType
  0x00,  // bcdUSB lo
  0x02,  // bcdUSB hi
  0x00,  // bDeviceClass
  0x00,  // bDeviceSubClass
  0x00,  // bDeviceProtocol
  0x40,  // bMaxPacketSize0
  0x01,  // bNumConfigurations
  0x00,  // bReserved
};

But usb_desc.c did have the problem. Sadly that didn't help matters though :(

[gfwilliams]

Posted at 2015-08-03 by @gfwilliams

Yeah, I'll try and fix that problem today hopefully. My guess is it's to do with the changes to RAM size rather than anything specifically to do with USB HID.

[gfwilliams]

Posted at 2016-05-20 by @gfwilliams

When HID is enabled, it is a composite device already... The issue seems to be that Windows still seems to require an 'inf' file for it (much like it does for normal VCP devices). All other OSes (Mac, Linux, Android) seem happy with it as-is. Usually that inf file is in the ST driver pack that you have to install before you start using Espruino - but it only mentions VCP - not the HID stuff at all.

The only solution I'd found to get it working driverless on Windows appeared to be for me to add the option to disable the virtual COM port and have just the HID device - but that means trying to develop HID stuff on Windows would be a nightmare, so it wasn't desperately high priority.

But if you can figure out some way of tweaking the descriptor such that it does actually work then I'd be very happy to include it :)

I guess if you found a VCP+HID composite device that does work without drivers then we could compare the descriptors and see what was different?

[gfwilliams]

Posted at 2016-05-23 by @gfwilliams

You could compare with what's here: https://github.com/espruino/Espruino/blob/master/targetlibs/stm32usb/usbd_cdc_hid.c#L181

But it seems like there might be some USB debug tools for Windows, and those might be the best place to start? They might give some clue as to what Windows thinks is wrong.

[gfwilliams]

Posted at 2016-05-24 by @gfwilliams

Yes, a USB-TTL adaptor would work fine - it defaults to B6/B7 when USB isn't connected anyway, no there's not even a need for setConsole.

You can implement telnet over WiFi with a few lines of JS, it's just not built-in yet (as the existing WiFi driver uses a JS library, so would have problems if you wanted to totally reset Espruino).

[gfwilliams]

Posted at 2016-06-06 by @gfwilliams

Thanks - that's interesting... It could well be an IAD is needed.

Maybe with the TI tool (or an example for ST) we can compare the descriptors that are generated.

It might just be that a few extra bytes need adding to that descriptor to get it working.

[gfwilliams]

Posted at 2016-09-26 by @gfwilliams

Hi, I'm afraid there haven't been any changes with it recently. If you're able to figure out what it is about the descriptor that windows doesn't like (there might be some USB debug tools?) then I'm more than happy to make the relevant changes as well :)

Also, Zadig might be worth a try? It's possible it'll be able to force the driver installation.

[gfwilliams]

Posted at 2023-06-12 by @gfwilliams

Right now to manage it you'd have to build your own version of Espruino with the descriptor offering just HID and not CDC. The relevant bit of code is https://github.com/espruino/Espruino/blob/master/targetlibs/stm32usb/usbd_cdc_hid.c#L191C1-L321 and you'd have to cut the CDC bit out so it looked a bit more like https://github.com/STMicroelectronics/STM32CubeF7/blob/master/Middlewares/ST/STM32_USB_Device_Library/Class/HID/Src/usbd_hid.c#L135C37-L186

Building itself is not too hard - in fact as long as GitHub actions are enabled, when you fork the Espruino repo and make a change the firmware is built automatically! Or for local dev see https://github.com/espruino/Espruino/blob/master/README_Building.md