16-bit relative USB mouse support

[wareya]

Related area

Gaming Mouse

Hardware specification

ESP32-S2

Is your feature request related to a problem?

I'm making a gaming mouse using an ESP32-S2-DevKitM-1U. Modern gaming mice all report at 1000hz with 16 bits of motion per frame.

The HID USB mouse implementation only support 8 bits of motion data per frame: https://github.com/espressif/arduino-esp32/blob/master/libraries/USB/src/USBHIDMouse.cpp

At 125hz and 800dpi, this limits the max tracking speed to 0.5 meters per second. At 1000hz, it's 4 meters per second, which sounds like a lot, but isn't enough for game genres that involve very fast flicking. At higher DPIs, the max tracking speed is reduced; 800dpi isn't really enough to run a HiDPI monitor any more, so "silly" DPIs like 1600, 3200, etc. are increasingly common.

TinyUSB doesn't seem to have a report type for 16-bit mice out of the box, but someone seems to have gotten it working anyway: hathach/tinyusb#366

Describe the solution you'd like

Add a second class that uses 16-bit motion deltas and a proper report descriptor.

Describe alternatives you've considered

Overclocking above 1000hz (e.g. to 8000hz) only works on "High-Speed" USB devices, not "Full-Speed" as is usually used for keyboards and mice.

Additional context

No response

I have checked existing list of Feature requests and the Contribution Guide

• I confirm I have checked existing list of Feature requests and Contribution Guide.

[wareya]

This header file works with the 3.0.0-a version of the ardunio esp32 support library:

#include <USB.h>
#include <USBHID.h>
#include <USBHIDMouse.h>

#define TUD_HID_REPORT_DESC_MOUSE16(...) \
  HID_USAGE_PAGE ( HID_USAGE_PAGE_DESKTOP      )                   ,\
  HID_USAGE      ( HID_USAGE_DESKTOP_MOUSE     )                   ,\
  HID_COLLECTION ( HID_COLLECTION_APPLICATION  )                   ,\
    /* Report ID if any */\
    __VA_ARGS__ \
    HID_USAGE      ( HID_USAGE_DESKTOP_POINTER )                   ,\
    HID_COLLECTION ( HID_COLLECTION_PHYSICAL   )                   ,\
      HID_USAGE_PAGE  ( HID_USAGE_PAGE_BUTTON  )                   ,\
        HID_USAGE_MIN   ( 1                                      ) ,\
        HID_USAGE_MAX   ( 5                                      ) ,\
        HID_LOGICAL_MIN ( 0                                      ) ,\
        HID_LOGICAL_MAX ( 1                                      ) ,\
        /* Left, Right, Middle, Backward, Forward buttons */ \
        HID_REPORT_COUNT( 5                                      ) ,\
        HID_REPORT_SIZE ( 1                                      ) ,\
        HID_INPUT       ( HID_DATA | HID_VARIABLE | HID_ABSOLUTE ) ,\
        /* 3 bit padding */ \
        HID_REPORT_COUNT( 1                                      ) ,\
        HID_REPORT_SIZE ( 3                                      ) ,\
        HID_INPUT       ( HID_CONSTANT                           ) ,\
      HID_USAGE_PAGE  ( HID_USAGE_PAGE_DESKTOP )                   ,\
        /* X, Y position [-32767, 32767] */ \
        HID_USAGE       ( HID_USAGE_DESKTOP_X                    ) ,\
        HID_USAGE       ( HID_USAGE_DESKTOP_Y                    ) ,\
        HID_LOGICAL_MIN_N ( 0x8001, 2                            ) ,\
        HID_LOGICAL_MAX_N ( 0x7fff, 2                            ) ,\
        HID_REPORT_COUNT( 2                                      ) ,\
        HID_REPORT_SIZE ( 16                                     ) ,\
        HID_INPUT       ( HID_DATA | HID_VARIABLE | HID_RELATIVE ) ,\
        /* Verital wheel scroll [-127, 127] */ \
        HID_USAGE       ( HID_USAGE_DESKTOP_WHEEL                )  ,\
        HID_LOGICAL_MIN ( 0x81                                   )  ,\
        HID_LOGICAL_MAX ( 0x7f                                   )  ,\
        HID_REPORT_COUNT( 1                                      )  ,\
        HID_REPORT_SIZE ( 8                                      )  ,\
        HID_INPUT       ( HID_DATA | HID_VARIABLE | HID_RELATIVE )  ,\
      HID_USAGE_PAGE  ( HID_USAGE_PAGE_CONSUMER ), \
       /* Horizontal wheel scroll [-127, 127] */ \
        HID_USAGE_N     ( HID_USAGE_CONSUMER_AC_PAN, 2           ), \
        HID_LOGICAL_MIN ( 0x81                                   ), \
        HID_LOGICAL_MAX ( 0x7f                                   ), \
        HID_REPORT_COUNT( 1                                      ), \
        HID_REPORT_SIZE ( 8                                      ), \
        HID_INPUT       ( HID_DATA | HID_VARIABLE | HID_RELATIVE ), \
    HID_COLLECTION_END                                            , \
  HID_COLLECTION_END

static const uint8_t rel16_mouse_report_descriptor[] = {
    TUD_HID_REPORT_DESC_MOUSE16(HID_REPORT_ID(HID_REPORT_ID_MOUSE))
};

typedef struct TU_ATTR_PACKED
{
    uint8_t buttons;
    int16_t  x;
    int16_t  y;
    int8_t  wheel;
    int8_t  pan;
} hid_mouse_report_16_t;

HIDMouseType_t HIDMouseRel16 = { HID_MOUSE_RELATIVE, rel16_mouse_report_descriptor, sizeof(rel16_mouse_report_descriptor), sizeof(hid_mouse_report_16_t) };

class USBHIDRelativeMouse16: public USBHIDMouseBase {
public:
    USBHIDRelativeMouse16(void): USBHIDMouseBase(&HIDMouseRel16) { }
    void move(int16_t x, int16_t y, int8_t wheel = 0, int8_t pan = 0) {
        hid_mouse_report_16_t report = {
            .buttons = _buttons,
            .x       = x,
            .y       = y,
            .wheel   = wheel,
            .pan     = pan
        };
        sendReport(report);
    }
    void click(uint8_t b = MOUSE_LEFT) override {
        _buttons = b;
        move(0,0);
        _buttons = 0;
        move(0,0);
    }
    void buttons(uint8_t b) override {
        if (b != _buttons) {
            _buttons = b;
            move(0,0);
        }
    }
};

Based on USBHIDMouse.cpp.

[SuGlider]

@wareya - It is already within Arduino Core 3.0.0-Alpha3. You can test it.

Looking in master branch I can see that
https://github.com/espressif/arduino-esp32/commits/master/libraries/USB/src/tusb_hid_mouse.h
has already 2 bytes for X,Y absolute mouse feature.

Check the PR from #8831

[wareya]

Absolute mouse and relative mouse support is different. This is for 16-bit relative mouse support.

[SuGlider]

Thanks for noting that. You are right. Absolute has a different report descriptor.
HID_INPUT ( HID_DATA | HID_VARIABLE | HID_ABSOLUTE ) --- HID_INPUT ( HID_DATA | HID_VARIABLE | HID_RELATIVE )

I'll work a way to add this feature.

[Parsaabasi]

Hello,

Due to the overwhelming volume of issues currently being addressed, we have decided to close the previously received tickets. If you still require assistance or if the issue persists, please don't hesitate to reopen the ticket.

Thanks.

[wareya]

If you still require assistance or if the issue persists, please don't hesitate to reopen the ticket.

This feature request is still relevant (unless someone fulfilled it without noting it here) and I do not have the permission to reopen this ticket. Implementing this feature request is also a relatively small amount of work (copy/paste a class and change some numbers), so it doesn't hold back any other work.