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

[espruino-discuss]

Posted at 2015-05-29 by @allObjects

Great to see this coming along and to be here now!

[espruino-discuss]

Posted at 2015-05-30 by the1laz

Awesome news, looking forward to getting my Pico to try this on!

[espruino-discuss]

Posted at 2015-06-04 by Stev

That's pretty neat.

Since I am missing the critical USB know-how: we have to enter some kind of HID mode which then will be reset when plugged in without power from the battery, or is this just another USB channel in parallel to the serial port?

Can this already be revoked in software or is the current way to toggle it by having it started up before plugging (HID settings active) or not (pure console mode)?

As I said, no idea on the "mode" model right now, but eager to try out.

Great addition to the Pico's dongle form factor.

[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!

[espruino-discuss]

Posted at 2015-06-04 by Stev

Ok, that would be cool. Though the hick-ups seem to get closer to "on every char" :)

"While you're at it"(TM), is there a way to have an absolute pointer device, too. Don't know if that's a mode/param of the mouse mode or a separate one.

Cheers
Stev

[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.

[espruino-discuss]

Posted at 2015-06-04 by Stev

Hoped it would be more work :)

To make up for that:

What's b (or first array param) in sendUSBHID() in the mouse example (or the general content of that data stream array for certain HID modes)? Or just: can this be zero for the absolute pointing device as well?

[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

[espruino-discuss]

Posted at 2015-06-04 by Stev

Ah, so good. Especially with the module and tablet. This build still needs external Battery or just the save()?

Nice link at the end. Lots of tinkering options :)

As a backchannel, eg for a software on the host, reporting certain state values, 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? I remember switching console from back then, but I don't know if that's still possible. I could of course set vars via the console via JS, but it would nice to define limited protocol on the board side.

[espruino-discuss]

Posted at 2015-06-04 by Stev

The tablet example keeps logging me out of my Mac :) Probably kills's the UI.
From a quick search it seems that the values in the HID setup should be signed numbers while the module uses unsigned ones for the physical and logical limits. Those might just not be looked at in the relative mouse example (which works fine :).

The kb example triggers the context menu. Haven't looked at that module, though, yet.

[espruino-discuss]

Posted at 2015-06-04 by Stev

Hm, lost my prepared comment in the editor ;/ Again...

I changed the report descriptor in the USBTablet module to signed values (0xFF, 0x7f) for the logical maximum and changed the send function accordingly. Which seems to work.

However I see some offset of my monitors origin (about 2500..2600 logical units) for top and left, resulting in a clipped circle. This only occurs on one of our Macs, on another with less clipping, on another without (just the vertical values are clipped due to the difference in height vs width in pixels). Just to make clear that this might not be the fault of the Pico when it occurs. Might be some kind of touch pad or multi monitor setup that triggers that. Can't say.

However, the physical minimum/maximum value only seem to be information on the theoretical input device behind it. They don't seem to have any effect (like a movable and scalable value window, as one might expect). At least on the mac without any tablet driver they seem not to be taken into account.

[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-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.

[espruino-discuss]

Posted at 2016-05-20 by @yerpj

Hi,

Does anyone managed to get the VCP+HID class enumeration on Windows?
I came accross a document that explains how to enumerate a composite device.
Is anyone working on this those days?

[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?

[espruino-discuss]

Posted at 2016-05-20 by @yerpj

OK I had a look at the different descriptors (Device desc, Config desc, Interface desc, Endpoint desc, ...) as well as the stmcdc.INF, and it appears that I am completely lost. I can't figure out if 2 configuration descriptors are used (one for each interface) or if only one configuration descriptor is used, thus enclosing both interfaces. I am not familiar enough with that USB stuff to pretend I will find a solution, but I read this (old) post where they managed to enumerate a VCP/HID device with an STM32.

I will continue to try to understand all that stuff anyway.

[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.

[espruino-discuss]

Posted at 2016-05-24 by DrAzzy

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

Do we have a way to get a telnet terminal on a wifi connected Espruino yet? That's a solution (for certain values of solution). Or setConsole and a TTL serial adapter...

[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).

[espruino-discuss]

Posted at 2016-06-04 by @yerpj

It seems that on Windows, if there is more than one interface descriptor within a configuration descriptor, the latter should include a IAD (Interface Association Descriptor).

[Device Descriptor]
[ConfigDescriptor]
[Interface Association Descriptor]
[Interface Descriptor] (1)
[EndPoints Descriptors and so on..]
[Interface Descriptor] (2) 
[EndPoints Descriptors and so on..]   

I don't see any IAD in usbd_cdc_hid.c. Maybe this could do the trick in order to allow windows to enumerate this CDC-HID config.

That said, I don't know if IAD are recognized in Linux and macOS

I am exploring USB enumeration with STM32F4DISCO. I will give feedback here in case of positive results.

[espruino-discuss]

Posted at 2016-06-04 by @yerpj

I just found a working example of dual CDC (2 COM ports) on a stm32F103 HERE. This example may help.

[espruino-discuss]

Posted at 2016-06-04 by @yerpj

I also found a tool from Texas Instruments, helping to generate composite descriptors as well as corresponding .INF files. Unfortunately, this tool is focused on MSP430, but the generated descriptors are written as C structures, so they may be of any help for comparing with current descriptors for CDC-HID in 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.

[espruino-discuss]

Posted at 2016-09-26 by Eugen

Hi
are there any changes with HID-support for Windows?
Need that feature and ready to try digging into INF files, if this is the only solution.

[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.

[espruino-discuss]

Posted at 2023-06-10 by Potados

Hi!
I understand this is a closed issue, but I searched a web for a whole day and couldn't find an answer.

I'm looking for a solution to make the pico a dedicated USB HID keyboard.

I'm currently working on an environment where serial communication(including VCP) is blocked(also prohibited), so the pico needs to pretend to be a just a keyboard, without VCP capability.

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.

Developing being a nightmare is not a problem for me. Is there a way to achieve it?
Thank you.

[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