Generic Pointing Device (#1767)

common_features.mk

@@ -69,6 +69,10 @@ ifeq ($(strip $(FAUXCLICKY_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/fauxclicky.c
 endif
 
+ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
+	SRC += $(QUANTUM_DIR)/pointing_device.c
+endif
+
 ifeq ($(strip $(UCIS_ENABLE)), yes)
     OPT_DEFS += -DUCIS_ENABLE
     UNICODE_COMMON = yes

docs/feature_pointing_device.md

@@ -0,0 +1,47 @@
+## Pointing Device
+
+Pointing Device is a generic name for a feature intended to be generic: moving the system pointer arround.  There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and lightweight.  You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you.
+
+To enable Pointing Device, uncomment the following line in your rules.mk:
+
+```
+POINTING_DEVICE_ENABLE = yes
+```
+
+To manipulate the mouse report, you can use the following functions:
+
+* `pointing_device_get_report()` - Returns the current report_mouse_t that represents the information sent to the host computer
+* `pointing_device_set_report(report_mouse_t newMouseReport)` - Overrides and saves the report_mouse_t to be sent to the host computer
+
+Keep in mind that a report_mouse_t (here "mouseReport") has the following properties:
+
+* `mouseReport.x` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ to the right, - to the left) on the x axis.
+* `mouseReport.y` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ upward, - downward) on the y axis.
+* `mouseReport.v` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing vertical scrolling (+ upward, - downward).
+* `mouseReport.h` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing horizontal scrolling (+ right, - left).
+* `mouseReport.buttons` - this is a uint8_t in which the last 5 bits are used.  These bits represent the mouse button state - bit 3 is mouse button 5, and bit 7 is mouse button 1.
+
+When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in "pointing_device_send()", which can be overridden to avoid this behavior).  This way, button states persist, but movement will only occur once.  For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden.
+
+In the following example, a custom key is used to click the mouse and scroll 127 units vertically and horizontally, then undo all of that when released - because that's a totally useful function.  Listen, this is an example:
+
+```
+case MS_SPECIAL:
+	report_mouse_t currentReport = pointing_device_get_report();
+    if (record->event.pressed)
+    {
+        currentReport.v = 127;
+		currentReport.h = 127;
+		currentReport.buttons |= MOUSE_BTN1; //this is defined in report.h
+    }
+    else
+    {
+        currentReport.v = -127;
+        currentReport.h = -127;
+        currentReport.buttons &= ~MOUSE_BTN1;
+    }
+	pointing_device_set_report(currentReport);
+    break;
+```
+
+Recall that the mouse report is set to zero (except the buttons) whenever it is sent, so the scrolling would only occur once in each case.

quantum/pointing_device.c

@@ -0,0 +1,62 @@
+/*
+Copyright 2017 Joshua Broekhuijsen <snipeye+qmk@gmail.com>
+
+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 <stdint.h>
+#include "report.h"
+#include "host.h"
+#include "timer.h"
+#include "print.h"
+#include "debug.h"
+#include "pointing_device.h"
+
+static report_mouse_t mouseReport = {};
+
+__attribute__ ((weak))
+void pointing_device_init(void){
+    //initialize device, if that needs to be done.
+}
+
+__attribute__ ((weak))
+void pointing_device_send(void){
+    //If you need to do other things, like debugging, this is the place to do it.
+    host_mouse_send(mouseReport);
+	//send it and 0 it out except for buttons, so those stay until they are explicity over-ridden using update_pointing_device
+	mouseReport.x = 0;
+	mouseReport.y = 0;
+	mouseReport.v = 0;
+	mouseReport.h = 0;
+}
+
+__attribute__ ((weak))
+void pointing_device_task(void){
+    //gather info and put it in:
+    //mouseReport.x = 127 max -127 min
+    //mouseReport.y = 127 max -127 min
+    //mouseReport.v = 127 max -127 min (scroll vertical)
+    //mouseReport.h = 127 max -127 min (scroll horizontal)
+    //mouseReport.buttons = 0x1F (decimal 31, binary 00011111) max (bitmask for mouse buttons 1-5, 1 is rightmost, 5 is leftmost) 0x00 min
+    //send the report
+    pointing_device_send();
+}
+
+report_mouse_t pointing_device_get_report(void){
+	return mouseReport;
+}
+
+void pointing_device_set_report(report_mouse_t newMouseReport){
+	mouseReport = newMouseReport;
+}

quantum/pointing_device.h

@@ -0,0 +1,31 @@
+/*
+Copyright 2017 Joshua Broekhuijsen <snipeye+qmk@gmail.com>
+
+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/>.
+*/
+
+#ifndef POINTING_DEVICE_H
+#define POINTING_DEVICE_H
+
+#include <stdint.h>
+#include "host.h"
+#include "report.h"
+
+void pointingdevice_init(void);
+void pointing_device_task(void);
+void pointing_device_send(void);
+report_mouse_t pointing_device_get_report(void);
+void pointing_device_set_report(report_mouse_t newMouseReport);
+
+#endif

tmk_core/common/keyboard.c

@@ -63,6 +63,9 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #ifdef VISUALIZER_ENABLE
 #   include "visualizer/visualizer.h"
 #endif
+#ifdef POINTING_DEVICE_ENABLE
+#   include "pointing_device.h"
+#endif
 
 #ifdef MATRIX_HAS_GHOST
 extern const uint16_t keymaps[][MATRIX_ROWS][MATRIX_COLS];
@@ -153,6 +156,9 @@ void keyboard_init(void) {
 #ifdef FAUXCLICKY_ENABLE
     fauxclicky_init();
 #endif
+#ifdef POINTING_DEVICE_ENABLE
+    pointing_device_init();
+#endif
 #if defined(NKRO_ENABLE) && defined(FORCE_NKRO)
     keymap_config.nkro = 1;
 #endif
@@ -239,6 +245,10 @@ MATRIX_LOOP_END:
     visualizer_update(default_layer_state, layer_state, visualizer_get_mods(), host_keyboard_leds());
 #endif
 
+#ifdef POINTING_DEVICE_ENABLE
+    pointing_device_task();
+#endif
+
     // update LED
     if (led_status != host_keyboard_leds()) {
         led_status = host_keyboard_leds();