Requesting HID Reports with Pico-PIO-USB

[hexad]

I tried connecting a mouse to a pico.
However i was unable to parse the scroll wheel. One person suggested that I should perform a HID request beforehand, in order to find out what bytes to target.
I used USB Device Viewer on Windows, and I saw that the USB mouse actually contains 3 HID Devices.

So, is it possible to dynamically scan all HID interfaces and find which one has the wheel, middle mouse button, left and right mouse buttons, and X/Y mouse movement, with PIO-USB?

Please help me, because I am hitting the wall for about one month now and i don't know not only, if it is even possible.
Could you please answer, or at least point out to resource - a forum or discord server or something that someone can help?

Thanks a lot and kind regards.

[braxlan]

I guess you are using TinyUSB in C with Pico-PIO-USB as a USB host.

There are two things you must do to get started:

• Get the report descriptors and parse them to find out how to interpret the reports coming from the mouse in report mode (this has a very steep learning curve). This will also help you find out which interface actually sends the information you need.
• Set the device to report mode to actually get reports in report mode. TinyUSB uses boot protocol mode as default which does not contain scroll wheel information (if you take it very strict). You can change the behaviour of TinyUSB to set report mode as default.

Read the file tinyusb/src/class/hid/hid_host.h and the HID host examples to find out more.

[hexad]

@braxlan Thank you for your answer!
I am a USB newbie and I am still struggling to make sense of all of this.

I have one question about your second bullet point. Since TinyUSB will be used in a Device Mode, in order to act like a device on the PC.
Then shouldn't the USB report descriptor be handled by Pico-PIO-USB?

[braxlan]

I am also quite new to USB and I guess it is quite normal to struggle at the beginning. My knowledge might only be one step ahead of yours.

I have one question about your second bullet point. Since TinyUSB will be used in a Device Mode, in order to act like a device on the PC.

That depends on your setup. Maybe you can give us more details, which MCU you use and what you connect to where? From what you write, I guess you have the Pico's PHY (its "USB connector") running in device mode connected to a PC, while you use Pico-PIO-USB in host mode and connect your mouse to it.

Then shouldn't the USB report descriptor be handled by Pico-PIO-USB?

Yes and no. TinyUSB handles the report descriptor with Pico-PIO-USB acting like a PHY. So think of Pico-PIO-USB just replacing a physical USB controller with a software (which is exactly what it does).

But to come back to your initial question, looks like I forgot the most easy and straightforward solution: Just set your mouse to report protocol mode and cross your fingers the report format equals the boot protocol format, but with an additional 4th Byte containing the wheel coordinate information as a signed value (signed char to be precise). I just tested it and I guess it should work with the majority of mice. It did not work with my wireless keyboard though. So parsing the report descriptor still is the most secure way to do it.

[hexad]

@braxlan Once again, thank you for taking the time to address me, because it's very hard to get people to mentor me for this issue.

What i want to do is capture the mouse X/Y movement, left/middle/right buttons, potential extra buttons AND scroll wheel and log them to the PC via serial.

I am using a raspberry pi pico. Together with TinyUSB (in device mode), in order to relay the messages via serial, and with Pico-PIO-USB, in order to receive the mouse data.

This is a repo that does this with keyboard and mouse: https://github.com/TheLowSpecPC/pico_device_and_host_updated/issues
And this is a repo that does the same but with the Arduino core - instead of the pico-sdk: https://github.com/hexad/RP2040-PIO-USB-Host

All of these suffer the same issue. That the scroll wheel does not work. Because all these examples don't parse the HID descriptor, and just rely on hardcoding the positions of the mouse's input.

So in the previous setup that I described, since it's PIO-USB that talks to the mouse, it's PIO-USB that has to request the HID Descriptor? Since TinyUSB is talking to the PC....

I have two more questions:

1. You said this:

Just set your mouse to report protocol mode and cross your fingers the report format equals the boot protocol format, but with an additional 4th Byte containing the wheel coordinate information as a signed value (signed char to be precise). I just tested it and I guess it should work with the majority of mice.

Wow! Do you have a working example of this so I can test it? If yes, I would be so grateful!

2. In your HID-Remapper, project, is there perhaps a HID-Descriptor parsing portion inside that I can take a look at? Because in my opinion, Pico-PIO-USB has a documentation problem, and I can't seem to find how to do the things that I know have to be done.

Thanks again!

[braxlan]

@braxlan Once again, thank you for taking the time to address me, because it's very hard to get people to mentor me for this issue.

I had the same problem so I'm glad if I can help! For me it turned out that AI is a good mentor to explain things. But be careful and double check all the information it gives!

What i want to do is capture the mouse X/Y movement, left/middle/right buttons, potential extra buttons AND scroll wheel and log them to the PC via serial.

Okay. I guess by "serial" you mean the serial connection via USB aka "CDC" as used in the example below.

I am using a raspberry pi pico. Together with TinyUSB (in device mode), in order to relay the messages via serial, and with Pico-PIO-USB, in order to receive the mouse data.

Okay, this is a common setup.

This is a repo that does this with keyboard and mouse: https://github.com/TheLowSpecPC/pico_device_and_host_updated/issues And this is a repo that does the same but with the Arduino core - instead of the pico-sdk: https://github.com/hexad/RP2040-PIO-USB-Host

Hmm, looks like the first example is a modified version of this TinyUSB example:

https://github.com/hathach/tinyusb/tree/master/examples/dual/host_hid_to_device_cdc/src

I better leave my hands off the Arduino example, because I am more familiar with plain C.

The first example neither calls tuh_hid_set_protocol() nor tuh_hid_set_default_protocol() which means the connected devices will remain in HID boot protocol mode (or to be exact, will be set from HID report protocol mode to HID boot protocol mode during initialization, because report mode is the standard for HID devices when initialized). If a mouse is connected and follows the HID boot protocol precisely, it will never send the wheel coordinates in the 4th Byte, because HID boot protocol mode (for mouse) only has 3 Bytes. Some might still send the 4th byte, the ones I've tested didn't.

All of these suffer the same issue. That the scroll wheel does not work. Because all these examples don't parse the HID descriptor, and just rely on hardcoding the positions of the mouse's input.

Yes, they rely on the fixed report from the HID boot protocol, which does not need a report descriptor, because it uses a standard report descriptor with fixed positions of the data, which is part of the USB standard.

So in the previous setup that I described, since it's PIO-USB that talks to the mouse, it's PIO-USB that has to request the HID Descriptor? Since TinyUSB is talking to the PC....

As I said, you have running TinyUSB in both device and host mode at the same time, but you use the hardware USB controller of the Pico in device mode, while you use the software PIO-USB in host mode.

I have two more questions:

1. You said this:

Just set your mouse to report protocol mode and cross your fingers the report format equals the boot protocol format, but with an additional 4th Byte containing the wheel coordinate information as a signed value (signed char to be precise). I just tested it and I guess it should work with the majority of mice.

Wow! Do you have a working example of this so I can test it? If yes, I would be so grateful!

I am working on a project, but haven't made it available publicly yet. I will do so once it works the way I want it. However, you can do the following changes to the first example you listed:

Add static variables before function definitions:

static uint8_t daddr;
static uint8_t idx;
static bool report_mode_set = true;

Add the callback which is called after the device is properly mounted (does not need a prototype):

tuh_mount_cb (uint8_t daddr)
{
  (void) daddr; // We don't use it here
  report_mode_set = false;
}

Note that tuh_mount_cb() is called after tuh_hid_mount_cb() has returned for all HID instances of the device! You could use report_mode_set = false; within tuh_hid_mount_cb() instead, but then calling tuh_hid_set_protocol() from the main loop (see below) would fail much more often because TinyUSB might still be initializing the device in the meantime.

Add this to tuh_hid_mount_cb():

idx = instance;
daddr = dev_addr;

Add this to the main loop:

if(!report_mode_set)
{
  // Set HID instance to report protocol mode
  // This might fail if there is some ongoing transfer, so we try it until it is successful:
  if(tuh_hid_set_protocol(daddr, idx, HID_PROTOCOL_REPORT)) report_mode_set = true;
}

I haven't tested all of this, but it should work. Keep in mind that this is not a very elegant but simple and (hopefully) easy to understand solution, which should do the job.

An alternative would be to call tuh_hid_set_default_protocol() at some point, but I have no experience where exactly to call it that it works in the end. If properly called, TinyUSB will initialize connected devices in the desired HID protocol mode.

2. In your HID-Remapper, project, is there perhaps a HID-Descriptor parsing portion inside that I can take a look at? Because in my opinion, Pico-PIO-USB has a documentation problem, and I can't seem to find how to do the things that I know have to be done.

I am not the owner of the HID-Remapper project so I don't deserve any credits here, but I follow it because it is really nicely done and an inspiration to my own project! It has a report descriptor parser, but for me it is quite hard to understand.

Regarding a report descriptor parser I am also at the point of finding a solution. I found a really helpful source how to deal with this as a starting point:
https://docs.kernel.org/hid/hidintro.html

It also hives some hints of existing parsers/libs which we could use.

Thanks again!

You're welcome! I hope it helps!

[hexad]

First of all, thank you so so much!
You provided info that I was searching many months, in a quick code review. I cannot express how grateful I am.

I didn't know that the original code used the mouse in a USB Boot Mode. I know that in this mode, scroll wheel buttons do not work!

But i have a question regarding this:

As I said, you have running TinyUSB in both device and host mode at the same time, but you use the hardware USB controller of the Pico in device mode, while you use the software PIO-USB in host mode.

How is that possible? I know that software PIO-USB is host mode, to talk with the mouse, but how is the TinyUSB in both device and host mode at the same time?
Isn't this impossible to do? I thought that the TinyUSB can either be in device or host mode.
Isn't TinyUSB used in device mode, in the hardware USB controller?

The second question involves the code you posted. First of all, once again, thank you so much for this!
But let's say I implement your code successfully.
Does this mean that there is no need for the HID Descriptor parsing anymore?
And will your code cover extra buttons that the mouse may have? (Because some mouses besides the obvious X/Y, left/middle/right button and scroll wheel, have extra buttons)

Finally, I have to add it would be great of we had a library or functions for HID Descriptor parsing.
Just today, I came across a nice reference.
It's USB in a nutshell.
https://www.beyondlogic.org/usbnutshell/usb1.shtml
There is also a pdf form if you google its name. It's only 11 pages long.
Perhaps you already know this document, or perhaps it's too basic information for you.

Either way, I had to share, especially after all the help you have given me.
Thanks again!

[braxlan]

First of all, thank you so so much! You provided info that I was searching many months, in a quick code review. I cannot express how grateful I am.

You're welcome!

I didn't know that the original code used the mouse in a USB Boot Mode. I know that in this mode, scroll wheel buttons do not work!

To be precise: The wheel itself does not work, but if the wheel also has a button function, it still might work as the third mouse button, but without scrolling function.

But i have a question regarding this:

As I said, you have running TinyUSB in both device and host mode at the same time, but you use the hardware USB controller of the Pico in device mode, while you use the software PIO-USB in host mode.

How is that possible? I know that software PIO-USB is host mode, to talk with the mouse, but how is the TinyUSB in both device and host mode at the same time? Isn't this impossible to do? I thought that the TinyUSB can either be in device or host mode. Isn't TinyUSB used in device mode, in the hardware USB controller?

It absolutely is possible. If you analyze the first example, you can see it has two files called main_device.c and main_host.c, which already indicates that they are acting in device and host mode. If you look into them, you will find that one contains a call of tud_task() and the other a call of tuh_task() in their main loops. tu stands for TinyUSB and d or h for device and host respectively. It would also be possible to have both calls in the same main loop. Also if you look at tusb_config.h you can see that it contains settings for both device and host mode. So you might ask, why are the functions split into two main loops? If you look closer, you can see that one of the main loops (core1_main()) is running in host mode on a second core and handles all of the PIO USB functionality which is common practice for PIO USB, because it deserves its own core because of its resource usage.

Another story is to have more than one instance of each device or host mode running at the same time, which seems to be complicated at the current state of development of TinyUSB iirc.

The second question involves the code you posted. First of all, once again, thank you so much for this! But let's say I implement your code successfully. Does this mean that there is no need for the HID Descriptor parsing anymore? And will your code cover extra buttons that the mouse may have? (Because some mouses besides the obvious X/Y, left/middle/right button and scroll wheel, have extra buttons)

No. The code I supplied is super simple in the way it ignores report descriptors from the start and just guesses the mice connected use a report descriptor, which equals the boot protocol for the first three bytes and has the wheel coordinate information stored in the 4th byte. It totally depends on the mice connected and which report descriptor they use. This said, you cannot rely on it working for any connected mouse. If you want more than three buttons and x/y coordinates, the one and only way to make it work for any mouse is to set it to report mode and parse its report descriptor to find out the report format and map it accordingly.

Finally, I have to add it would be great of we had a library or functions for HID Descriptor parsing. Just today, I came across a nice reference. It's USB in a nutshell. https://www.beyondlogic.org/usbnutshell/usb1.shtml There is also a pdf form if you google its name. It's only 11 pages long. Perhaps you already know this document, or perhaps it's too basic information for you.

Nice find! As I am also still learning, any document helping me to learn is welcome!

Either way, I had to share, especially after all the help you have given me. Thanks again!

Again, you're welcome! For me it is also a good chance to validate my current knowledge.

And by the way, don't forget to close this issue when your question(s) has/have been answered.

[hexad]

Thank you once again.. I am really, really grateful for your answers...

Does this code only have problems when the mouse is involved (due to the boot protocol)?
Are keyboards working completely fine, relaying all data to the PC?
Or this HID Descriptor parsing has to be applied to keyboards as well?

Also, you said this:

one of the main loops (core1_main()) is running in host mode on a second core and handles all of the PIO USB functionality which is common practice for PIO USB

So PIO-USB is not run standalone, but TinyUSB has to be run as a wrapper?

Is this situation with two TinyUSB instances (one as a host, one as a device) ideal for what I want to do?
As a reminder, I want to parse data from the mouse (PIO-USB) and send them to the pc via serial with TinyUSB.

Do I have to have both these files?

Sorry that I ask, it's just this revelation came as a surprise to me, that I thought dogmatically that TinyUSB has to have only one functino - either as device, or as host.

So what is doing right now exactly? Is the inclusion of both functions necessary?

If I had to implement a report descriptor parsing, would TinyUSB still be involved?
Or just PIO-USB?
In both case, which would be the correct file, or loop to implement this?

Anyway, maybe this is not the correct place for Q&A, or maybe I have tired you.
Is there a place when I can discuss such things?
Perhaps a discord server or something?

Thank you so much, once again!

[braxlan]

Does this code only have problems when the mouse is involved (due to the boot protocol)? Are keyboards working completely fine, relaying all data to the PC? Or this HID Descriptor parsing has to be applied to keyboards as well?

If you have a standard keyboard without any special keys like media keys or the like, you don't need to set it to report mode. Keyboard boot protocol allows 6-KRO and 8 modifier keys to be pressed at the same time.

Also, you said this:

one of the main loops (core1_main()) is running in host mode on a second core and handles all of the PIO USB functionality which is common practice for PIO USB

So PIO-USB is not run standalone, but TinyUSB has to be run as a wrapper?

I don't know how exactly this constellation is called, but PIO-USB is not able to run standalone. If I got it right, it is meant to run with TinyUSB, at least the examples rely on TinyUSB.

Is this situation with two TinyUSB instances (one as a host, one as a device) ideal for what I want to do? As a reminder, I want to parse data from the mouse (PIO-USB) and send them to the pc via serial with TinyUSB.

Yes, if you want to have serial via USB, this is ideal and common practice. An alternative would be to use the native USB port of your Pico in host mode and use the serial I/O pins instead of serial over USB for output.

Do I have to have both these files?

Not really, you could merge both files into one if you prefer. However, you need the contents of both files if you want to preserve the functionality it offers.

Sorry that I ask, it's just this revelation came as a surprise to me, that I thought dogmatically that TinyUSB has to have only one functino - either as device, or as host.

So what is doing right now exactly? Is the inclusion of both functions necessary?

As written above, if you want to preserve the functionality, you need to keep both functions unless you want to use the native USB as a host.

If I had to implement a report descriptor parsing, would TinyUSB still be involved? Or just PIO-USB? In both case, which would be the correct file, or loop to implement this?

TinyUSB will still be involved if you do not want to change to another library. I would implement the descriptor parsing on the core running the device task (the core not running PIO-USB) to keep the other core free for PIO-USB resources. However, you need to get the descriptor on the host side, there's no way around it. I'm very unsure how the cores can communicate, maybe it is even necessary to run the parser on the host (PIO-USB) core because of memory access restrictions.

Anyway, maybe this is not the correct place for Q&A, or maybe I have tired you. Is there a place when I can discuss such things? Perhaps a discord server or something?

What about doing a fork of the code you want to use as a basis and allow issues and/or discussions in your fork? I think that would be the best place for further discussions.

Thank you so much, once again!

You're welcome!

[hexad]

Thank you once more!
I researched what you told me and consulted ChatGPT as well. I have some distinctions that I think will be helpful to you as well:

As for the interaction of Pico-PIO-USB with TinyUSB, this is what it said:

PIO-USB is independent of TinyUSB.
However, the examples often use TinyUSB in parallel, especially to:
Run as a USB device (e.g., sending HID or serial to PC),
Reuse TinyUSB HID parser or descriptor structures,
Make use of the TinyUSB device stack, because PIO-USB is host only.

As far as where to use the HID Descriptor parser (host-device. TinyUSB or PIO-USB), this is what it told me:

TinyUSB can run in device or host mode, but not both on the same USB controller simultaneously.
HID report descriptor parsing requires host mode logic, but not necessarily hardware interaction once the data is received.

Finally, I asked it what would be the best strategy for me. I laid out three strategies:
Extract and Use TinyUSB's HID Parser Standalone
Temporarily Run TinyUSB in Host Mode (on Core 0), Parse HID Descriptor, Then Reboot into Device Mode
Use TinyUSB (only for parsing) on PIO-USB side (Core 1), then activate device mode on Core 0

It laid out that my best option would be to:

Use PIO-USB alone on one core to perform:
Device enumeration
HID descriptor request (raw)
Feed the raw descriptor to a standalone version of TinyUSB’s hid_parser.c/.h
Parse and identify positions of X/Y, wheel, buttons etc.
Forward data to Core 0, which is running TinyUSB as a device (serial or HID) to the PC

Of course, I am not so sure if this will turn out to be as easy at it described it to be. But I will give it a shot!

[braxlan]

Thank you once more! I researched what you told me and consulted ChatGPT as well. I have some distinctions that I think will be helpful to you as well:

As for the interaction of Pico-PIO-USB with TinyUSB, this is what it said:

PIO-USB is independent of TinyUSB.

Yes.

However, the examples often use TinyUSB in parallel, especially to:
Run as a USB device (e.g., sending HID or serial to PC),
Reuse TinyUSB HID parser or descriptor structures,
Make use of the TinyUSB device stack, because PIO-USB is host only.

At least the last sentence is wrong: PIO-USB supports both host and device modes, look at its GitHub starting page. But as far as I know the device mode is broken in the current implementation.

As far as where to use the HID Descriptor parser (host-device. TinyUSB or PIO-USB), this is what it told me:

TinyUSB can run in device or host mode, but not both on the same USB controller simultaneously.

This makes sense, because a USB (OTG) controller can only act either as a host or a device at the same time, so this is not a special limitation of TinyUSB but a hardware limitation.

HID report descriptor parsing requires host mode logic, but not necessarily hardware interaction once the data is received.

This also makes sense, because once you've got the descriptor, you can parse it whenever you want, even if the device is not connected anymore.

Finally, I asked it what would be the best strategy for me. I laid out three strategies: Extract and Use TinyUSB's HID Parser Standalone Temporarily Run TinyUSB in Host Mode (on Core 0), Parse HID Descriptor, Then Reboot into Device Mode Use TinyUSB (only for parsing) on PIO-USB side (Core 1), then activate device mode on Core 0

To me it is not clear what the three different strategies you mentioned are. Also it is not clear which part is running as host and which as device. You can use both the hardware USB controller and PIO-USB as host and device (however PIO-USB device mode recently seems to be broken, see above). Changing roles of a controller or PIO-USB would require you to reconnect devices and host, which would enforce another reboot and may break strategies unless you use an external power for your MCU.

It laid out that my best option would be to:

Use PIO-USB alone on one core to perform:
Device enumeration
HID descriptor request (raw)

So PIO-USB would be running as host.

Feed the raw descriptor to a standalone version of TinyUSB’s hid_parser.c/.h

The "parser" (tuh_hid_parse_report_descriptor()) will only help you to split/convert the report descriptor into an array, but that's already it, you'll have to manage the rest yourself. And the file hid_parser.c/.h does not exist (anymore), that's why I said it is necessary to validate AI output.

Parse and identify positions of X/Y, wheel, buttons etc.
Forward data to Core 0, which is running TinyUSB as a device (serial or HID) to the PC

Of course, I am not so sure if this will turn out to be as easy at it described it to be. But I will give it a shot!

This is exactly the setup and strategy we were discussing before, with the difference that the report would be parsed on core 1 instead of core 0. The hardest part still is to adapt to different report descriptors and fetch the relevant parts of the report.