Digitizer HID interface : absolute coordinates for mouse cursor (#12851)

* Add digitizer HID interface for setting the mouse cursor position at
absolute screen coordinates. Tested on Pro Micro, Proton C and
Blackpill.

* Update docs/feature_digitizer.md

Co-authored-by: Ryan <fauxpark@gmail.com>

* Update tmk_core/protocol/usb_descriptor.c

Co-authored-by: Ryan <fauxpark@gmail.com>

* Add missing copyrights
Add V-USB support

* Add support for digitizer dedicated endpoint for lufa and chibios.
Fix formatting issues
Move digitizer_task definition to the feature's base implementation file

* Run cformat on modified files

* Change digitizer report usage to Digitizer instead of Pen to avoid
pointer disappearing on Windows.

* Update tmk_core/protocol/vusb/vusb.c

Co-authored-by: Ryan <fauxpark@gmail.com>

* Run cformat from docker image

* Remove send_digitizer from host_driver_t and instead rely on the
declaration being the interface to the implementation in each
HW-specific usb implementation.

* Fix build : send_digitizer shouldn't be static in vusb and add
weak-linkage implementation for tests without usb implementation

* Change digitizer user interface to match pointing device's

* Update documentation with new API

Co-authored-by: a-chol <nothing@none.com>
Co-authored-by: Ryan <fauxpark@gmail.com>

6 files changed, 226 insertions, 5 deletions

diff --git a/tmk_core/protocol/chibios/main.c b/tmk_core/protocol/chibios/main.c
index 199741594a..e41d6ff195 100644
--- a/tmk_core/protocol/chibios/main.c
+++ b/tmk_core/protocol/chibios/main.c
@@ -65,6 +65,7 @@ void    send_keyboard(report_keyboard_t *report);
 void    send_mouse(report_mouse_t *report);
 void    send_system(uint16_t data);
 void    send_consumer(uint16_t data);
+void    send_digitizer(report_digitizer_t *report);
 
 /* host struct */
 host_driver_t chibios_driver = {keyboard_leds, send_keyboard, send_mouse, send_system, send_consumer};
diff --git a/tmk_core/protocol/chibios/usb_main.c b/tmk_core/protocol/chibios/usb_main.c
index e5edd74dcb..cc282e6a9b 100644
--- a/tmk_core/protocol/chibios/usb_main.c
+++ b/tmk_core/protocol/chibios/usb_main.c
@@ -316,6 +316,9 @@ typedef struct {
 #ifdef JOYSTICK_ENABLE
             usb_driver_config_t joystick_driver;
 #endif
+#if defined(DIGITIZER_ENABLE) && !defined(DIGITIZER_SHARED_EP)
+            usb_driver_config_t digitizer_driver;
+#endif
         };
         usb_driver_config_t array[0];
     };
@@ -360,6 +363,14 @@ static usb_driver_configs_t drivers = {
 #    define JOYSTICK_OUT_MODE USB_EP_MODE_TYPE_BULK
     .joystick_driver = QMK_USB_DRIVER_CONFIG(JOYSTICK, 0, false),
 #endif
+
+#if defined(DIGITIZER_ENABLE) && !defined(DIGITIZER_SHARED_EP)
+#    define DIGITIZER_IN_CAPACITY 4
+#    define DIGITIZER_OUT_CAPACITY 4
+#    define DIGITIZER_IN_MODE USB_EP_MODE_TYPE_BULK
+#    define DIGITIZER_OUT_MODE USB_EP_MODE_TYPE_BULK
+    .digitizer_driver = QMK_USB_DRIVER_CONFIG(DIGITIZER, 0, false),
+#endif
 };
 
 #define NUM_USB_DRIVERS (sizeof(drivers) / sizeof(usb_driver_config_t))
@@ -930,6 +941,23 @@ void send_consumer(uint16_t data) {
 #endif
 }
 
+void send_digitizer(report_digitizer_t *report) {
+#ifdef DIGITIZER_ENABLE
+#    ifdef DIGITIZER_SHARED_EP
+    osalSysLock();
+    if (usbGetDriverStateI(&USB_DRIVER) != USB_ACTIVE) {
+        osalSysUnlock();
+        return;
+    }
+
+    usbStartTransmitI(&USB_DRIVER, DIGITIZER_IN_EPNUM, (uint8_t *)report, sizeof(report_digitizer_t));
+    osalSysUnlock();
+#    else
+    chnWrite(&drivers.digitizer_driver.driver, (uint8_t *)report, sizeof(report_digitizer_t));
+#    endif
+#endif
+}
+
 /* ---------------------------------------------------------
  *                   Console functions
  * ---------------------------------------------------------
diff --git a/tmk_core/protocol/lufa/lufa.c b/tmk_core/protocol/lufa/lufa.c
index 4ac079e168..8ddb8b1c4b 100644
--- a/tmk_core/protocol/lufa/lufa.c
+++ b/tmk_core/protocol/lufa/lufa.c
@@ -142,9 +142,7 @@ static void    send_keyboard(report_keyboard_t *report);
 static void    send_mouse(report_mouse_t *report);
 static void    send_system(uint16_t data);
 static void    send_consumer(uint16_t data);
-host_driver_t  lufa_driver = {
-    keyboard_leds, send_keyboard, send_mouse, send_system, send_consumer,
-};
+host_driver_t  lufa_driver = {keyboard_leds, send_keyboard, send_mouse, send_system, send_consumer};
 
 #ifdef VIRTSER_ENABLE
 // clang-format off
@@ -525,6 +523,11 @@ void EVENT_USB_Device_ConfigurationChanged(void) {
     /* Setup joystick endpoint */
     ConfigSuccess &= Endpoint_ConfigureEndpoint((JOYSTICK_IN_EPNUM | ENDPOINT_DIR_IN), EP_TYPE_INTERRUPT, JOYSTICK_EPSIZE, 1);
 #endif
+
+#if defined(DIGITIZER_ENABLE) && !defined(DIGITIZER_SHARED_EP)
+    /* Setup digitizer endpoint */
+    ConfigSuccess &= Endpoint_ConfigureEndpoint((DIGITIZER_IN_EPNUM | ENDPOINT_DIR_IN), EP_TYPE_INTERRUPT, DIGITIZER_EPSIZE, 1);
+#endif
 }
 
 /* FIXME: Expose this table in the docs somehow
@@ -983,6 +986,23 @@ void virtser_send(const uint8_t byte) {
 }
 #endif
 
+void send_digitizer(report_digitizer_t *report) {
+#ifdef DIGITIZER_ENABLE
+    uint8_t timeout = 255;
+
+    if (USB_DeviceState != DEVICE_STATE_Configured) return;
+
+    Endpoint_SelectEndpoint(DIGITIZER_IN_EPNUM);
+
+    /* Check if write ready for a polling interval around 10ms */
+    while (timeout-- && !Endpoint_IsReadWriteAllowed()) _delay_us(40);
+    if (!Endpoint_IsReadWriteAllowed()) return;
+
+    Endpoint_Write_Stream_LE(report, sizeof(report_digitizer_t), NULL);
+    Endpoint_ClearIN();
+#endif
+}
+
 /*******************************************************************************
  * main
  ******************************************************************************/
diff --git a/tmk_core/protocol/usb_descriptor.c b/tmk_core/protocol/usb_descriptor.c
index 7a4a790315..099964ae56 100644
--- a/tmk_core/protocol/usb_descriptor.c
+++ b/tmk_core/protocol/usb_descriptor.c
@@ -158,6 +158,53 @@ const USB_Descriptor_HIDReport_Datatype_t PROGMEM SharedReport[] = {
 #    endif
 #endif
 
+#ifdef DIGITIZER_ENABLE
+#    ifndef DIGITIZER_SHARED_EP
+const USB_Descriptor_HIDReport_Datatype_t PROGMEM DigitizerReport[] = {
+#    elif !defined(SHARED_REPORT_STARTED)
+const USB_Descriptor_HIDReport_Datatype_t PROGMEM SharedReport[] = {
+#        define SHARED_REPORT_STARTED
+#    endif
+    HID_RI_USAGE_PAGE(8, 0x0D),      // Digitizers
+    HID_RI_USAGE(8, 0x01),           // Digitizer
+    HID_RI_COLLECTION(8, 0x01),      // Application
+#    ifdef DIGITIZER_SHARED_EP
+        HID_RI_REPORT_ID(8, REPORT_ID_DIGITIZER),
+#    endif
+        HID_RI_USAGE(8, 0x20),       // Stylus
+        HID_RI_COLLECTION(8, 0x00),  // Physical
+            // Tip Switch (1 bit)
+            HID_RI_USAGE(8, 0x42),   // Tip Switch
+            HID_RI_LOGICAL_MINIMUM(8, 0x00),
+            HID_RI_LOGICAL_MAXIMUM(8, 0x01),
+            HID_RI_REPORT_SIZE(8, 0x01),
+            HID_RI_REPORT_COUNT(8, 0x01),
+            HID_RI_INPUT(8, HID_IOF_VARIABLE),
+            // In Range (1 bit)
+            HID_RI_USAGE(8, 0x32),  // In Range
+            HID_RI_INPUT(8, HID_IOF_VARIABLE),
+            // Padding (6 bits)
+            HID_RI_REPORT_COUNT(8, 0x06),
+            HID_RI_INPUT(8, HID_IOF_CONSTANT | HID_IOF_VARIABLE),
+
+            // X/Y Position (4 bytes)
+            HID_RI_USAGE_PAGE(8, 0x01),     // Generic Desktop
+            HID_RI_LOGICAL_MAXIMUM(16, 0x7FFF),
+            HID_RI_REPORT_SIZE(8, 0x10),
+            HID_RI_REPORT_COUNT(8, 0x01),
+            HID_RI_UNIT(8, 0x33),           // Inch, English Linear
+            HID_RI_UNIT_EXPONENT(8, 0x0E),  // -2
+            HID_RI_USAGE(8, 0x30),          // X
+            HID_RI_INPUT(8, HID_IOF_VARIABLE),
+            HID_RI_USAGE(8, 0x31),          // Y
+            HID_RI_INPUT(8, HID_IOF_VARIABLE),
+        HID_RI_END_COLLECTION(0),
+    HID_RI_END_COLLECTION(0),
+#    ifndef DIGITIZER_SHARED_EP
+};
+#    endif
+#endif
+
 #if defined(SHARED_EP_ENABLE) && !defined(SHARED_REPORT_STARTED)
 const USB_Descriptor_HIDReport_Datatype_t PROGMEM SharedReport[] = {
 #endif
@@ -227,6 +274,7 @@ const USB_Descriptor_HIDReport_Datatype_t PROGMEM SharedReport[] = {
         HID_RI_OUTPUT(8, HID_IOF_CONSTANT),
     HID_RI_END_COLLECTION(0),
 #endif
+
 #ifdef SHARED_EP_ENABLE
 };
 #endif
@@ -921,6 +969,46 @@ const USB_Descriptor_Configuration_t PROGMEM ConfigurationDescriptor = {
         .PollingIntervalMS      = USB_POLLING_INTERVAL_MS
     }
 #endif
+
+#if defined(DIGITIZER_ENABLE) && !defined(DIGITIZER_SHARED_EP)
+    /*
+     * Digitizer
+     */
+    .Digitizer_Interface  = {
+        .Header = {
+            .Size               = sizeof(USB_Descriptor_Interface_t),
+            .Type               = DTYPE_Interface
+        },
+        .InterfaceNumber        = DIGITIZER_INTERFACE,
+        .AlternateSetting       = 0x00,
+        .TotalEndpoints         = 1,
+        .Class                  = HID_CSCP_HIDClass,
+        .SubClass               = HID_CSCP_NonBootSubclass,
+        .Protocol               = HID_CSCP_NonBootProtocol,
+        .InterfaceStrIndex      = NO_DESCRIPTOR
+    },
+    .Digitizer_HID = {
+        .Header = {
+            .Size               = sizeof(USB_HID_Descriptor_HID_t),
+            .Type               = HID_DTYPE_HID
+        },
+        .HIDSpec                = VERSION_BCD(1, 1, 1),
+        .CountryCode            = 0x00,
+        .TotalReportDescriptors = 1,
+        .HIDReportType          = HID_DTYPE_Report,
+        .HIDReportLength        = sizeof(DigitizerReport)
+    },
+    .Digitizer_INEndpoint = {
+        .Header = {
+            .Size               = sizeof(USB_Descriptor_Endpoint_t),
+            .Type               = DTYPE_Endpoint
+        },
+        .EndpointAddress        = (ENDPOINT_DIR_IN | DIGITIZER_IN_EPNUM),
+        .Attributes             = (EP_TYPE_INTERRUPT | ENDPOINT_ATTR_NO_SYNC | ENDPOINT_USAGE_DATA),
+        .EndpointSize           = DIGITIZER_EPSIZE,
+        .PollingIntervalMS      = USB_POLLING_INTERVAL_MS
+    },
+#endif
 };
 
 /*
@@ -1059,6 +1147,13 @@ uint16_t get_usb_descriptor(const uint16_t wValue, const uint16_t wIndex, const
                     Size    = sizeof(USB_HID_Descriptor_HID_t);
                     break;
 #endif
+#if defined(DIGITIZER_ENABLE) && !defined(DIGITIZER_SHARED_EP)
+                case DIGITIZER_INTERFACE:
+                    Address = &ConfigurationDescriptor.Digitizer_HID;
+                    Size    = sizeof(USB_HID_Descriptor_HID_t);
+
+                    break;
+#endif
             }
 
             break;
@@ -1109,6 +1204,12 @@ uint16_t get_usb_descriptor(const uint16_t wValue, const uint16_t wIndex, const
                     Size    = sizeof(JoystickReport);
                     break;
 #endif
+#if defined(DIGITIZER_ENABLE) && !defined(DIGITIZER_SHARED_EP)
+                case DIGITIZER_INTERFACE:
+                    Address = &DigitizerReport;
+                    Size    = sizeof(DigitizerReport);
+                    break;
+#endif
             }
 
             break;
diff --git a/tmk_core/protocol/usb_descriptor.h b/tmk_core/protocol/usb_descriptor.h
index 867e549b4f..0f0c78f66c 100644
--- a/tmk_core/protocol/usb_descriptor.h
+++ b/tmk_core/protocol/usb_descriptor.h
@@ -135,6 +135,13 @@ typedef struct {
     USB_HID_Descriptor_HID_t   Joystick_HID;
     USB_Descriptor_Endpoint_t  Joystick_INEndpoint;
 #endif
+
+#if defined(DIGITIZER_ENABLE) && !defined(DIGITIZER_SHARED_EP)
+    // Digitizer HID Interface
+    USB_Descriptor_Interface_t Digitizer_Interface;
+    USB_HID_Descriptor_HID_t   Digitizer_HID;
+    USB_Descriptor_Endpoint_t  Digitizer_INEndpoint;
+#endif
 } USB_Descriptor_Configuration_t;
 
 /*
@@ -180,6 +187,10 @@ enum usb_interfaces {
 #if defined(JOYSTICK_ENABLE)
     JOYSTICK_INTERFACE,
 #endif
+
+#if defined(DIGITIZER_ENABLE) && !defined(DIGITIZER_SHARED_EP)
+    DIGITIZER_INTERFACE,
+#endif
     TOTAL_INTERFACES
 };
 
@@ -226,7 +237,7 @@ enum usb_endpoints {
 #        if STM32_USB_USE_OTG1
 #            define CONSOLE_OUT_EPNUM CONSOLE_IN_EPNUM
 #        else
-    CONSOLE_OUT_EPNUM = NEXT_EPNUM,
+    CONSOLE_OUT_EPNUM   = NEXT_EPNUM,
 #        endif
 #    else
 #        define CONSOLE_OUT_EPNUM CONSOLE_IN_EPNUM
@@ -259,6 +270,19 @@ enum usb_endpoints {
     JOYSTICK_OUT_EPNUM    = NEXT_EPNUM,
 #    endif
 #endif
+
+#ifdef DIGITIZER_ENABLE
+#    if !defined(DIGITIZER_SHARED_EP)
+    DIGITIZER_IN_EPNUM = NEXT_EPNUM,
+#        if STM32_USB_USE_OTG1
+    DIGITIZER_OUT_EPNUM = DIGITIZER_IN_EPNUM,
+#        else
+    DIGITIZER_OUT_EPNUM = NEXT_EPNUM,
+#        endif
+#    else
+#        define DIGITIZER_IN_EPNUM SHARED_IN_EPNUM
+#    endif
+#endif
 };
 
 #ifdef PROTOCOL_LUFA
@@ -284,5 +308,6 @@ enum usb_endpoints {
 #define CDC_NOTIFICATION_EPSIZE 8
 #define CDC_EPSIZE 16
 #define JOYSTICK_EPSIZE 8
+#define DIGITIZER_EPSIZE 8
 
 uint16_t get_usb_descriptor(const uint16_t wValue, const uint16_t wIndex, const void** const DescriptorAddress);
diff --git a/tmk_core/protocol/vusb/vusb.c b/tmk_core/protocol/vusb/vusb.c
index 98cebf6012..485b20c900 100644
--- a/tmk_core/protocol/vusb/vusb.c
+++ b/tmk_core/protocol/vusb/vusb.c
@@ -292,6 +292,14 @@ static void send_consumer(uint16_t data) {
 #endif
 }
 
+void send_digitizer(report_digitizer_t *report) {
+#ifdef DIGITIZER_ENABLE
+    if (usbInterruptIsReadyShared()) {
+        usbSetInterruptShared((void *)report, sizeof(report_digitizer_t));
+    }
+#endif
+}
+
 /*------------------------------------------------------------------*
  * Request from host                                                *
  *------------------------------------------------------------------*/
@@ -510,8 +518,46 @@ const PROGMEM uchar shared_hid_report[] = {
     0x95, 0x01,                //   Report Count (1)
     0x75, 0x10,                //   Report Size (16)
     0x81, 0x00,                //   Input (Data, Array, Absolute)
-    0xC0                       // End Collection
+    0xC0,                      // End Collection
+#endif
+
+#ifdef DIGITIZER_ENABLE
+    // Digitizer report descriptor
+    0x05, 0x0D,                 // Usage Page (Digitizers)
+    0x09, 0x01,                 // Usage (Digitizer)
+    0xA1, 0x01,                 // Collection (Application)
+    0x85, REPORT_ID_DIGITIZER,  //   Report ID
+    0x09, 0x22,                 //   Usage (Finger)
+    0xA1, 0x00,                 //   Collection (Physical)
+    // Tip Switch (1 bit)
+    0x09, 0x42,  //     Usage (Tip Switch)
+    0x15, 0x00,  //     Logical Minimum
+    0x25, 0x01,  //     Logical Maximum
+    0x95, 0x01,  //     Report Count (1)
+    0x75, 0x01,  //     Report Size (16)
+    0x81, 0x02,  //     Input (Data, Variable, Absolute)
+    // In Range (1 bit)
+    0x09, 0x32,  //     Usage (In Range)
+    0x81, 0x02,  //     Input (Data, Variable, Absolute)
+    // Padding (6 bits)
+    0x95, 0x06,  //     Report Count (6)
+    0x81, 0x03,  //     Input (Constant)
+
+    // X/Y Position (4 bytes)
+    0x05, 0x01,        //     Usage Page (Generic Desktop)
+    0x26, 0xFF, 0x7F,  //     Logical Maximum (32767)
+    0x95, 0x01,        //     Report Count (1)
+    0x75, 0x10,        //     Report Size (16)
+    0x65, 0x33,        //     Unit (Inch, English Linear)
+    0x55, 0x0E,        //     Unit Exponent (-2)
+    0x09, 0x30,        //     Usage (X)
+    0x81, 0x02,        //     Input (Data, Variable, Absolute)
+    0x09, 0x31,        //     Usage (Y)
+    0x81, 0x02,        //     Input (Data, Variable, Absolute)
+    0xC0,              //   End Collection
+    0xC0               // End Collection
 #endif
+
 #ifdef SHARED_EP_ENABLE
 };
 #endif