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 <[email protected]>

* Update tmk_core/protocol/usb_descriptor.c

Co-authored-by: Ryan <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>
Co-authored-by: Ryan <[email protected]>

Author: 3 people

common_features.mk

@@ -695,6 +695,11 @@ ifeq ($(strip $(JOYSTICK_ENABLE)), digital)
     OPT_DEFS += -DDIGITAL_JOYSTICK_ENABLE
 endif
 
+DIGITIZER_ENABLE ?= no
+ifneq ($(strip $(DIGITIZER_ENABLE)), no)
+    SRC += $(QUANTUM_DIR)/digitizer.c
+endif
+
 USBPD_ENABLE ?= no
 VALID_USBPD_DRIVER_TYPES = custom vendor
 USBPD_DRIVER ?= vendor

docs/_summary.md

@@ -108,6 +108,7 @@
     * [Bluetooth](feature_bluetooth.md)
     * [Bootmagic Lite](feature_bootmagic.md)
     * [Custom Matrix](custom_matrix.md)
+    * [Digitizer](feature_digitizer.md)
     * [DIP Switch](feature_dip_switch.md)
     * [Encoders](feature_encoders.md)
     * [Haptic Feedback](feature_haptic_feedback.md)

docs/feature_digitizer.md

@@ -0,0 +1,35 @@
+## Digitizer
+
+The digitizer HID interface allows setting the mouse cursor position at absolute coordinates, unlike the Pointing Device feature that applies relative displacements.
+
+To enable the digitizer interface, add the following line to your rules.mk: 
+
+```makefile
+DIGITIZER_ENABLE = yes
+```
+
+In order to change the mouse cursor position from your keymap.c file, include the digitizer header : 
+
+```c
+#include "digitizer.h"
+```
+
+This gives you access to the `digitizer` structure which members allow you to change the cursor position.
+
+The coordinates are normalized, meaning there value must be set between 0 and 1. For the `x` coordinate, the value `0` is the leftmost position, whereas the value `1` is the rightmost position.
+For the `y` coordinate, `0` is at the top and `1` at the bottom.
+
+Here is an example setting the cursor in the middle of the screen:
+
+```c
+digitizer_t digitizer;
+digitizer.x = 0.5;
+digitizer.y = 0.5;
+digitizer.tipswitch = 0;
+digitizer.inrange = 1;
+digitizer_set_report(digitizer);
+```
+
+The `tipswitch` member triggers what equates to a click when set to `1`. The `inrange` member is required for the change in coordinates to be taken. It can then be set to `0` in a new report to signal the end of the digitizer interaction, but it is not strictly required.
+
+Once all members are set to the desired value, the `status` member needs its bitmask `DZ_UPDATED` to be set so the report is sent during the next main loop iteration.

keyboards/handwired/onekey/keymaps/digitizer/keymap.c

@@ -0,0 +1,38 @@
+ /* Copyright 2021 QMK 
+  * 
+  * This program is free software: you can redistribute it and/or modify 
+  * it under the terms of the GNU General Public License as published by 
+  * the Free Software Foundation, either version 2 of the License, or 
+  * (at your option) any later version. 
+  * 
+  * This program is distributed in the hope that it will be useful, 
+  * but WITHOUT ANY WARRANTY; without even the implied warranty of 
+  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
+  * GNU General Public License for more details. 
+  * 
+  * You should have received a copy of the GNU General Public License 
+  * along with this program.  If not, see <http://www.gnu.org/licenses/>. 
+  */ 
+#include QMK_KEYBOARD_H
+
+#include "digitizer.h"
+
+#include "math.h"
+
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {LAYOUT_ortho_1x1(KC_A)};
+
+uint32_t timer = 0;
+
+void matrix_scan_user() {
+    if (timer_elapsed32(timer) < 200) {
+        return;
+    }
+    
+    timer               = timer_read32();
+    digitizer_t digitizer;
+    digitizer.x         = 0.5 - 0.2 * cos(timer_read() / 250. / 6.28);
+    digitizer.y         = 0.5 - 0.2 * sin(timer_read() / 250. / 6.28);
+    digitizer.tipswitch = 0;
+    digitizer.inrange   = 1;
+    digitizer_set_report(digitizer);
+}

keyboards/handwired/onekey/keymaps/digitizer/rules.mk

@@ -0,0 +1 @@
+DIGITIZER_ENABLE = yes

quantum/digitizer.c

@@ -0,0 +1,34 @@
+/* Copyright 2021
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+#include "digitizer.h"
+
+digitizer_t digitizerReport = {.tipswitch = 0, .inrange = 0, .id = 0, .x = 0, .y = 0, .status = DZ_INITIALIZED};
+
+__attribute__((weak)) void digitizer_send(void) {
+    if (digitizerReport.status & DZ_UPDATED) {
+        host_digitizer_send(&digitizerReport);
+        digitizerReport.status &= ~DZ_UPDATED;
+    }
+}
+
+__attribute__((weak)) void digitizer_task(void) { digitizer_send(); }
+
+digitizer_t digitizer_get_report(void) { return digitizerReport; }
+
+void digitizer_set_report(digitizer_t newDigitizerReport) {
+    digitizerReport = newDigitizerReport;
+    digitizerReport.status |= DZ_UPDATED;
+}

quantum/digitizer.h

@@ -0,0 +1,41 @@
+/* Copyright 2021
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+#pragma once
+
+#include "quantum.h"
+
+#include <stdint.h>
+
+enum digitizer_status { DZ_INITIALIZED = 1, DZ_UPDATED = 2 };
+
+typedef struct {
+    int8_t  tipswitch;
+    int8_t  inrange;
+    uint8_t id;
+    float   x;
+    float   y;
+    uint8_t status : 2;
+} digitizer_t;
+
+extern digitizer_t digitizer;
+
+digitizer_t digitizer_get_report(void);
+
+void digitizer_set_report(digitizer_t newDigitizerReport);
+
+void digitizer_task(void);
+
+void host_digitizer_send(digitizer_t *digitizer);

tmk_core/common.mk

@@ -106,6 +106,19 @@ ifeq ($(strip $(NO_USB_STARTUP_CHECK)), yes)
     TMK_COMMON_DEFS += -DNO_USB_STARTUP_CHECK
 endif
 
+ifeq ($(strip $(DIGITIZER_SHARED_EP)), yes)
+    TMK_COMMON_DEFS += -DDIGITIZER_SHARED_EP
+    SHARED_EP_ENABLE = yes
+endif
+
+ifeq ($(strip $(DIGITIZER_ENABLE)), yes)
+    TMK_COMMON_DEFS += -DDIGITIZER_ENABLE
+    ifeq ($(strip $(SHARED_EP_ENABLE)), yes)
+        TMK_COMMON_DEFS += -DDIGITIZER_SHARED_EP
+        SHARED_EP_ENABLE = yes
+    endif
+endif
+
 ifeq ($(strip $(SHARED_EP_ENABLE)), yes)
     TMK_COMMON_DEFS += -DSHARED_EP_ENABLE
 endif

tmk_core/common/host.c

@@ -22,6 +22,7 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #include "host.h"
 #include "util.h"
 #include "debug.h"
+#include "digitizer.h"
 
 #ifdef NKRO_ENABLE
 #    include "keycode_config.h"
@@ -103,6 +104,24 @@ void host_consumer_send(uint16_t report) {
     (*driver->send_consumer)(report);
 }
 
+void host_digitizer_send(digitizer_t *digitizer) {
+    if (!driver) return;
+
+    report_digitizer_t report = {
+#ifdef DIGITIZER_SHARED_EP
+        .report_id = REPORT_ID_DIGITIZER,
+#endif
+        .tip     = digitizer->tipswitch & 0x1,
+        .inrange = digitizer->inrange & 0x1,
+        .x       = (uint16_t)(digitizer->x * 0x7FFF),
+        .y       = (uint16_t)(digitizer->y * 0x7FFF),
+    };
+
+    send_digitizer(&report);
+}
+
+__attribute__((weak)) void send_digitizer(report_digitizer_t *report) {}
+
 uint16_t host_last_system_report(void) { return last_system_report; }
 
 uint16_t host_last_consumer_report(void) { return last_consumer_report; }

tmk_core/common/host_driver.h

@@ -30,3 +30,5 @@ typedef struct {
     void (*send_system)(uint16_t);
     void (*send_consumer)(uint16_t);
 } host_driver_t;
+
+void send_digitizer(report_digitizer_t *report);

tmk_core/common/keyboard.c

@@ -106,6 +106,9 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #if defined(CRC_ENABLE)
 #    include "crc.h"
 #endif
+#ifdef DIGITIZER_ENABLE
+#    include "digitizer.h"
+#endif
 
 static uint32_t last_input_modification_time = 0;
 uint32_t        last_input_activity_time(void) { return last_input_modification_time; }
@@ -537,6 +540,10 @@ void keyboard_task(void) {
     joystick_task();
 #endif
 
+#ifdef DIGITIZER_ENABLE
+    digitizer_task();
+#endif
+
     // update LED
     if (led_status != host_keyboard_leds()) {
         led_status = host_keyboard_leds();

tmk_core/common/report.h

@@ -30,7 +30,8 @@ enum hid_report_ids {
     REPORT_ID_SYSTEM,
     REPORT_ID_CONSUMER,
     REPORT_ID_NKRO,
-    REPORT_ID_JOYSTICK
+    REPORT_ID_JOYSTICK,
+    REPORT_ID_DIGITIZER
 };
 
 /* Mouse buttons */
@@ -205,6 +206,17 @@ typedef struct {
     int8_t  h;
 } __attribute__((packed)) report_mouse_t;
 
+typedef struct {
+#ifdef DIGITIZER_SHARED_EP
+    uint8_t report_id;
+#endif
+    uint8_t  tip : 1;
+    uint8_t  inrange : 1;
+    uint8_t  pad2 : 6;
+    uint16_t x;
+    uint16_t y;
+} __attribute__((packed)) report_digitizer_t;
+
 typedef struct {
 #if JOYSTICK_AXES_COUNT > 0
 #    if JOYSTICK_AXES_RESOLUTION > 8

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};

tmk_core/protocol/chibios/usb_main.c

@@ -315,6 +315,9 @@ typedef struct {
 #endif
 #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
  * ---------------------------------------------------------

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
  ******************************************************************************/