Merge pull request #931 from OferPlesser/feature/improve-ps2-mouse

Improving ps/2 mouse

3 files changed, 400 insertions, 165 deletions

diff --git a/readme.md b/readme.md
index be1510832..1f06fe79f 100644
--- a/readme.md
+++ b/readme.md
@@ -1191,7 +1191,7 @@ Please note the USB port can only supply a limited amount of power to the keyboa
 
 Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device.
 
-Then, decide whether to use USART (best), interrupts (better) or busywait (not recommended), and enable the relevant option.
+There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended).
 
 ### Busywait version
 
@@ -1316,6 +1316,116 @@ In your keyboard config.h:
 #endif
 ```
 
+### Additional Settings
+
+#### PS/2 mouse features
+
+These enable settings supported by the PS/2 mouse protocol: http://www.computer-engineering.org/ps2mouse/
+
+```
+/* Use remote mode instead of the default stream mode (see link) */
+#define PS2_MOUSE_USE_REMOTE_MODE  
+
+/* Enable the scrollwheel or scroll gesture on your mouse or touchpad */
+#define PS2_MOUSE_ENABLE_SCROLLING
+
+/* Some mice will need a scroll mask to be configured. The default is 0xFF. */
+#define PS2_MOUSE_SCROLL_MASK 0x0F
+
+/* Applies a transformation to the movement before sending to the host (see link) */
+#define PS2_MOUSE_USE_2_1_SCALING
+
+/* The time to wait after initializing the ps2 host */
+#define PS2_MOUSE_INIT_DELAY 1000 /* Default */
+```
+
+You can also call the following functions from ps2_mouse.h
+
+```
+void ps2_mouse_disable_data_reporting(void);
+
+void ps2_mouse_enable_data_reporting(void);
+
+void ps2_mouse_set_remote_mode(void);
+
+void ps2_mouse_set_stream_mode(void);
+
+void ps2_mouse_set_scaling_2_1(void);
+
+void ps2_mouse_set_scaling_1_1(void);
+
+void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution);
+
+void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate);
+```
+
+#### Fine control
+
+Use the following defines to change the sensitivity and speed of the mouse.
+Note: you can also use `ps2_mouse_set_resolution` for the same effect (not supported on most touchpads).
+
+```
+#define PS2_MOUSE_X_MULTIPLIER 3
+#define PS2_MOUSE_Y_MULTIPLIER 3
+#define PS2_MOUSE_V_MULTIPLIER 1
+```
+
+#### Scroll button
+
+If you're using a trackpoint, you will likely want to be able to use it for scrolling.
+Its possible to enable a "scroll button/s" that when pressed will cause the mouse to scroll instead of moving.
+To enable the feature, you must set a scroll button mask as follows:
+
+```
+#define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BUTTON_MIDDLE) /* Default */
+```
+
+To disable the scroll button feature:
+
+```
+#define PS2_MOUSE_SCROLL_BTN_MASK 0
+```
+
+The available buttons are:
+
+```
+#define PS2_MOUSE_BTN_LEFT      0
+#define PS2_MOUSE_BTN_RIGHT     1
+#define PS2_MOUSE_BTN_MIDDLE    2
+```
+
+You can also combine buttons in the mask by `|`ing them together.
+
+Once you've configured your scroll button mask, you must configure the scroll button send interval.
+This is the interval before which if the scroll buttons were released they would be sent to the host.
+After this interval, they will cause the mouse to scroll and will not be sent.
+
+```
+#define PS2_MOUSE_SCROLL_BTN_SEND 300 /* Default */
+```
+
+To disable sending the scroll buttons:
+```
+#define PS2_MOUSE_SCROLL_BTN_SEND 0
+```
+
+Fine control over the scrolling is supported with the following defines:
+
+```
+#define PS2_MOUSE_SCROLL_DIVISOR_H 2
+#define PS2_MOUSE_SCROLL_DIVISOR_V 2
+```
+
+#### Debug settings
+
+To debug the mouse, add `debug_mouse = true` or enable via bootmagic.
+
+```
+/* To debug the mouse reports */
+#define PS2_MOUSE_DEBUG_HID
+#define PS2_MOUSE_DEBUG_RAW
+```
+
 ## Safety Considerations
 
 You probably don't want to "brick" your keyboard, making it impossible
diff --git a/tmk_core/protocol/ps2_mouse.c b/tmk_core/protocol/ps2_mouse.c
index 82f6966e8..af971dd49 100644
--- a/tmk_core/protocol/ps2_mouse.c
+++ b/tmk_core/protocol/ps2_mouse.c
@@ -18,63 +18,99 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #include <stdbool.h>
 #include<avr/io.h>
 #include<util/delay.h>
-#include "ps2.h"
 #include "ps2_mouse.h"
-#include "report.h"
 #include "host.h"
 #include "timer.h"
 #include "print.h"
+#include "report.h"
 #include "debug.h"
+#include "ps2.h"
 
-#ifndef PS2_INIT_DELAY
-#define PS2_INIT_DELAY 1000
-#endif
+/* ============================= MACROS ============================ */
+
+#define PS2_MOUSE_SEND(command, message) \
+do { \
+   uint8_t rcv = ps2_host_send(command); \
+   if (debug_mouse) { \
+        print((message)); \
+        xprintf(" command: %X, result: %X, error: %X \n", command, rcv, ps2_error); \
+    } \
+} while(0)
+
+#define PS2_MOUSE_SEND_SAFE(command, message) \
+do { \
+    if (PS2_MOUSE_STREAM_MODE == ps2_mouse_mode) { \
+        ps2_mouse_disable_data_reporting(); \
+    } \
+    PS2_MOUSE_SEND(command, message); \
+    if (PS2_MOUSE_STREAM_MODE == ps2_mouse_mode) { \
+        ps2_mouse_enable_data_reporting(); \
+    } \
+} while(0)
+
+#define PS2_MOUSE_SET_SAFE(command, value, message) \
+do { \
+    if (PS2_MOUSE_STREAM_MODE == ps2_mouse_mode) { \
+        ps2_mouse_disable_data_reporting(); \
+    } \
+    PS2_MOUSE_SEND(command, message); \
+    PS2_MOUSE_SEND(value, "Sending value"); \
+    if (PS2_MOUSE_STREAM_MODE == ps2_mouse_mode) { \
+        ps2_mouse_enable_data_reporting(); \
+    } \
+} while(0)
+
+#define PS2_MOUSE_RECEIVE(message) \
+do { \
+   uint8_t rcv = ps2_host_recv_response(); \
+   if (debug_mouse) { \
+        print((message)); \
+        xprintf(" result: %X, error: %X \n", rcv, ps2_error); \
+    } \
+} while(0)
+
+static enum ps2_mouse_mode_e {
+    PS2_MOUSE_STREAM_MODE,
+    PS2_MOUSE_REMOTE_MODE,
+} ps2_mouse_mode = PS2_MOUSE_STREAM_MODE;
 
 static report_mouse_t mouse_report = {};
 
+static inline void ps2_mouse_print_report(report_mouse_t *mouse_report);
+static inline void ps2_mouse_convert_report_to_hid(report_mouse_t *mouse_report);
+static inline void ps2_mouse_clear_report(report_mouse_t *mouse_report);
+static inline void ps2_mouse_enable_scrolling(void);
+static inline void ps2_mouse_scroll_button_task(report_mouse_t *mouse_report);
 
-static void print_usb_data(void);
-
+/* ============================= IMPLEMENTATION ============================ */
 
 /* supports only 3 button mouse at this time */
-uint8_t ps2_mouse_init(void) {
-    uint8_t rcv;
-
+void ps2_mouse_init(void) {
     ps2_host_init();
 
-    _delay_ms(PS2_INIT_DELAY);    // wait for powering up
+    _delay_ms(PS2_MOUSE_INIT_DELAY);    // wait for powering up
 
-    // send Reset
-    rcv = ps2_host_send(0xFF);
-    print("ps2_mouse_init: send Reset: ");
-    phex(rcv); phex(ps2_error); print("\n");
+    PS2_MOUSE_SEND(PS2_MOUSE_RESET, "ps2_mouse_init: sending reset");
 
-    // read completion code of BAT
-    rcv = ps2_host_recv_response();
-    print("ps2_mouse_init: read BAT: ");
-    phex(rcv); phex(ps2_error); print("\n");
+    PS2_MOUSE_RECEIVE("ps2_mouse_init: read BAT");
+    PS2_MOUSE_RECEIVE("ps2_mouse_init: read DevID");
 
-    // read Device ID
-    rcv = ps2_host_recv_response();
-    print("ps2_mouse_init: read DevID: ");
-    phex(rcv); phex(ps2_error); print("\n");
+#ifdef PS2_MOUSE_USE_REMOTE_MODE
+    ps2_mouse_set_remote_mode();
+#else
+    ps2_mouse_enable_data_reporting();
+#endif
 
-    // send Set Remote mode
-    rcv = ps2_host_send(0xF0);
-    print("ps2_mouse_init: send 0xF0: ");
-    phex(rcv); phex(ps2_error); print("\n");
+#ifdef PS2_MOUSE_ENABLE_SCROLLING
+    ps2_mouse_enable_scrolling();
+#endif
 
-    return 0;
+#ifdef PS2_MOUSE_USE_2_1_SCALING
+    ps2_mouse_set_scaling_2_1();
+#endif
 }
 
-#define X_IS_NEG  (mouse_report.buttons & (1<<PS2_MOUSE_X_SIGN))
-#define Y_IS_NEG  (mouse_report.buttons & (1<<PS2_MOUSE_Y_SIGN))
-#define X_IS_OVF  (mouse_report.buttons & (1<<PS2_MOUSE_X_OVFLW))
-#define Y_IS_OVF  (mouse_report.buttons & (1<<PS2_MOUSE_Y_OVFLW))
-void ps2_mouse_task(void)
-{
-    enum { SCROLL_NONE, SCROLL_BTN, SCROLL_SENT };
-    static uint8_t scroll_state = SCROLL_NONE;
+void ps2_mouse_task(void) {
     static uint8_t buttons_prev = 0;
 
     /* receives packet from mouse */
@@ -82,142 +118,169 @@ void ps2_mouse_task(void)
     rcv = ps2_host_send(PS2_MOUSE_READ_DATA);
     if (rcv == PS2_ACK) {
         mouse_report.buttons = ps2_host_recv_response();
-        mouse_report.x = ps2_host_recv_response();
-        mouse_report.y = ps2_host_recv_response();
+        mouse_report.x = ps2_host_recv_response() * PS2_MOUSE_X_MULTIPLIER;
+        mouse_report.y = ps2_host_recv_response() * PS2_MOUSE_Y_MULTIPLIER;
+#ifdef PS2_MOUSE_ENABLE_SCROLLING
+        mouse_report.v = -(ps2_host_recv_response() & PS2_MOUSE_SCROLL_MASK) * PS2_MOUSE_V_MULTIPLIER;
+#endif
     } else {
         if (debug_mouse) print("ps2_mouse: fail to get mouse packet\n");
         return;
     }
-        xprintf("%ud ", timer_read());
-        print("ps2_mouse raw: [");
-        phex(mouse_report.buttons); print("|");
-        print_hex8((uint8_t)mouse_report.x); print(" ");
-        print_hex8((uint8_t)mouse_report.y); print("]\n");
 
     /* if mouse moves or buttons state changes */
-    if (mouse_report.x || mouse_report.y ||
+    if (mouse_report.x || mouse_report.y || mouse_report.v ||
             ((mouse_report.buttons ^ buttons_prev) & PS2_MOUSE_BTN_MASK)) {
-
-#ifdef PS2_MOUSE_DEBUG
-        print("ps2_mouse raw: [");
-        phex(mouse_report.buttons); print("|");
-        print_hex8((uint8_t)mouse_report.x); print(" ");
-        print_hex8((uint8_t)mouse_report.y); print("]\n");
+#ifdef PS2_MOUSE_DEBUG_RAW
+        // Used to debug raw ps2 bytes from mouse
+        ps2_mouse_print_report(&mouse_report);
 #endif
-
         buttons_prev = mouse_report.buttons;
+        ps2_mouse_convert_report_to_hid(&mouse_report);
+#if PS2_MOUSE_SCROLL_BTN_MASK
+        ps2_mouse_scroll_button_task(&mouse_report);
+#endif
+#ifdef PS2_MOUSE_DEBUG_HID
+        // Used to debug the bytes sent to the host
+        ps2_mouse_print_report(&mouse_report);
+#endif
+        host_mouse_send(&mouse_report);
+    }
+    
+    ps2_mouse_clear_report(&mouse_report);
+}
 
-        // PS/2 mouse data is '9-bit integer'(-256 to 255) which is comprised of sign-bit and 8-bit value.
-        // bit: 8    7 ... 0
-        //      sign \8-bit/
-        //
-        // Meanwhile USB HID mouse indicates 8bit data(-127 to 127), note that -128 is not used.
-        //
-        // This converts PS/2 data into HID value. Use only -127-127 out of PS/2 9-bit.
-        mouse_report.x = X_IS_NEG ?
-                          ((!X_IS_OVF && -127 <= mouse_report.x && mouse_report.x <= -1) ?  mouse_report.x : -127) :
-                          ((!X_IS_OVF && 0 <= mouse_report.x && mouse_report.x <= 127) ? mouse_report.x : 127);
-        mouse_report.y = Y_IS_NEG ?
-                          ((!Y_IS_OVF && -127 <= mouse_report.y && mouse_report.y <= -1) ?  mouse_report.y : -127) :
-                          ((!Y_IS_OVF && 0 <= mouse_report.y && mouse_report.y <= 127) ? mouse_report.y : 127);
+void ps2_mouse_disable_data_reporting(void) {
+    PS2_MOUSE_SEND(PS2_MOUSE_DISABLE_DATA_REPORTING, "ps2 mouse disable data reporting"); 
+}
 
-        // remove sign and overflow flags
-        mouse_report.buttons &= PS2_MOUSE_BTN_MASK;
+void ps2_mouse_enable_data_reporting(void) {
+    PS2_MOUSE_SEND(PS2_MOUSE_ENABLE_DATA_REPORTING, "ps2 mouse enable data reporting");
+}
 
-        // invert coordinate of y to conform to USB HID mouse
-        mouse_report.y = -mouse_report.y;
+void ps2_mouse_set_remote_mode(void) { 
+    PS2_MOUSE_SEND_SAFE(PS2_MOUSE_SET_REMOTE_MODE, "ps2 mouse set remote mode"); 
+    ps2_mouse_mode = PS2_MOUSE_REMOTE_MODE;
+}
 
+void ps2_mouse_set_stream_mode(void) { 
+    PS2_MOUSE_SEND_SAFE(PS2_MOUSE_SET_STREAM_MODE, "ps2 mouse set stream mode"); 
+    ps2_mouse_mode = PS2_MOUSE_STREAM_MODE;
+}
 
-#if PS2_MOUSE_SCROLL_BTN_MASK
-        static uint16_t scroll_button_time = 0;
-        if ((mouse_report.buttons & (PS2_MOUSE_SCROLL_BTN_MASK)) == (PS2_MOUSE_SCROLL_BTN_MASK)) {
-            if (scroll_state == SCROLL_NONE) {
-                scroll_button_time = timer_read();
-                scroll_state = SCROLL_BTN;
-            }
-
-            // doesn't send Scroll Button
-            //mouse_report.buttons &= ~(PS2_MOUSE_SCROLL_BTN_MASK);
-
-            if (mouse_report.x || mouse_report.y) {
-                scroll_state = SCROLL_SENT;
-
-                mouse_report.v = -mouse_report.y/(PS2_MOUSE_SCROLL_DIVISOR_V);
-                mouse_report.h =  mouse_report.x/(PS2_MOUSE_SCROLL_DIVISOR_H);
-                mouse_report.x = 0;
-                mouse_report.y = 0;
-                //host_mouse_send(&mouse_report);
-            }
-        }
-        else if ((mouse_report.buttons & (PS2_MOUSE_SCROLL_BTN_MASK)) == 0) {
-#if PS2_MOUSE_SCROLL_BTN_SEND
-            if (scroll_state == SCROLL_BTN &&
-                    TIMER_DIFF_16(timer_read(), scroll_button_time) < PS2_MOUSE_SCROLL_BTN_SEND) {
-                // send Scroll Button(down and up at once) when not scrolled
-                mouse_report.buttons |= (PS2_MOUSE_SCROLL_BTN_MASK);
-                host_mouse_send(&mouse_report);
-                _delay_ms(100);
-                mouse_report.buttons &= ~(PS2_MOUSE_SCROLL_BTN_MASK);
-            }
-#endif
-            scroll_state = SCROLL_NONE;
-        }
-        // doesn't send Scroll Button
-        mouse_report.buttons &= ~(PS2_MOUSE_SCROLL_BTN_MASK);
-#endif
+void ps2_mouse_set_scaling_2_1(void) {
+    PS2_MOUSE_SEND_SAFE(PS2_MOUSE_SET_SCALING_2_1, "ps2 mouse set scaling 2:1"); 
+}
 
+void ps2_mouse_set_scaling_1_1(void) {
+    PS2_MOUSE_SEND_SAFE(PS2_MOUSE_SET_SCALING_1_1, "ps2 mouse set scaling 1:1"); 
+}
 
-        host_mouse_send(&mouse_report);
-        print_usb_data();
-    }
-    // clear report
-    mouse_report.x = 0;
-    mouse_report.y = 0;
-    mouse_report.v = 0;
-    mouse_report.h = 0;
-    mouse_report.buttons = 0;
+void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution) {
+    PS2_MOUSE_SET_SAFE(PS2_MOUSE_SET_RESOLUTION, resolution, "ps2 mouse set resolution");
+}
+
+void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate) {
+    PS2_MOUSE_SET_SAFE(PS2_MOUSE_SET_SAMPLE_RATE, sample_rate, "ps2 mouse set sample rate");
 }
 
-static void print_usb_data(void)
-{
+/* ============================= HELPERS ============================ */
+
+#define X_IS_NEG  (mouse_report->buttons & (1<<PS2_MOUSE_X_SIGN))
+#define Y_IS_NEG  (mouse_report->buttons & (1<<PS2_MOUSE_Y_SIGN))
+#define X_IS_OVF  (mouse_report->buttons & (1<<PS2_MOUSE_X_OVFLW))
+#define Y_IS_OVF  (mouse_report->buttons & (1<<PS2_MOUSE_Y_OVFLW))
+static inline void ps2_mouse_convert_report_to_hid(report_mouse_t *mouse_report) {
+    // PS/2 mouse data is '9-bit integer'(-256 to 255) which is comprised of sign-bit and 8-bit value.
+    // bit: 8    7 ... 0
+    //      sign \8-bit/
+    //
+    // Meanwhile USB HID mouse indicates 8bit data(-127 to 127), note that -128 is not used.
+    //
+    // This converts PS/2 data into HID value. Use only -127-127 out of PS/2 9-bit.
+    mouse_report->x = X_IS_NEG ?
+        ((!X_IS_OVF && -127 <= mouse_report->x && mouse_report->x <= -1) ?  mouse_report->x : -127) :
+        ((!X_IS_OVF && 0 <= mouse_report->x && mouse_report->x <= 127) ? mouse_report->x : 127);
+    mouse_report->y = Y_IS_NEG ?
+        ((!Y_IS_OVF && -127 <= mouse_report->y && mouse_report->y <= -1) ?  mouse_report->y : -127) :
+        ((!Y_IS_OVF && 0 <= mouse_report->y && mouse_report->y <= 127) ? mouse_report->y : 127);
+
+    // remove sign and overflow flags
+    mouse_report->buttons &= PS2_MOUSE_BTN_MASK;
+
+    // invert coordinate of y to conform to USB HID mouse
+    mouse_report->y = -mouse_report->y;
+}
+
+static inline void ps2_mouse_clear_report(report_mouse_t *mouse_report) {
+    mouse_report->x = 0;
+    mouse_report->y = 0;
+    mouse_report->v = 0;
+    mouse_report->h = 0;
+    mouse_report->buttons = 0;
+}
+
+static inline void ps2_mouse_print_report(report_mouse_t *mouse_report) {
     if (!debug_mouse) return;
-    print("ps2_mouse usb: [");
-    phex(mouse_report.buttons); print("|");
-    print_hex8((uint8_t)mouse_report.x); print(" ");
-    print_hex8((uint8_t)mouse_report.y); print(" ");
-    print_hex8((uint8_t)mouse_report.v); print(" ");
-    print_hex8((uint8_t)mouse_report.h); print("]\n");
+    print("ps2_mouse: [");
+    phex(mouse_report->buttons); print("|");
+    print_hex8((uint8_t)mouse_report->x); print(" ");
+    print_hex8((uint8_t)mouse_report->y); print(" ");
+    print_hex8((uint8_t)mouse_report->v); print(" ");
+    print_hex8((uint8_t)mouse_report->h); print("]\n");
+}
+
+static inline void ps2_mouse_enable_scrolling(void) {
+    PS2_MOUSE_SEND(PS2_MOUSE_SET_SAMPLE_RATE, "Initiaing scroll wheel enable: Set sample rate");
+    PS2_MOUSE_SEND(200, "200");
+    PS2_MOUSE_SEND(PS2_MOUSE_SET_SAMPLE_RATE, "Set sample rate");
+    PS2_MOUSE_SEND(100, "100");
+    PS2_MOUSE_SEND(PS2_MOUSE_SET_SAMPLE_RATE, "Set sample rate");
+    PS2_MOUSE_SEND(80, "80");
+    PS2_MOUSE_SEND(PS2_MOUSE_GET_DEVICE_ID, "Finished enabling scroll wheel");
+    _delay_ms(20);
 }
 
+#define PRESS_SCROLL_BUTTONS    mouse_report->buttons |= (PS2_MOUSE_SCROLL_BTN_MASK)
+#define RELEASE_SCROLL_BUTTONS  mouse_report->buttons &= ~(PS2_MOUSE_SCROLL_BTN_MASK)
+static inline void ps2_mouse_scroll_button_task(report_mouse_t *mouse_report) {
+    static enum { 
+        SCROLL_NONE, 
+        SCROLL_BTN, 
+        SCROLL_SENT,
+    } scroll_state = SCROLL_NONE;
+    static uint16_t scroll_button_time = 0;
+
+    if (PS2_MOUSE_SCROLL_BTN_MASK == (mouse_report->buttons & (PS2_MOUSE_SCROLL_BTN_MASK))) {
+        // All scroll buttons are pressed
+
+        if (scroll_state == SCROLL_NONE) {
+            scroll_button_time = timer_read();
+            scroll_state = SCROLL_BTN;
+        }
+
+        // If the mouse has moved, update the report to scroll instead of move the mouse
+        if (mouse_report->x || mouse_report->y) {
+            scroll_state = SCROLL_SENT;
+            mouse_report->v = -mouse_report->y/(PS2_MOUSE_SCROLL_DIVISOR_V);
+            mouse_report->h =  mouse_report->x/(PS2_MOUSE_SCROLL_DIVISOR_H);
+            mouse_report->x = 0;
+            mouse_report->y = 0;
+        }
+    } else if (0 == (PS2_MOUSE_SCROLL_BTN_MASK & mouse_report->buttons)) {
+        // None of the scroll buttons are pressed 
+
+#if PS2_MOUSE_SCROLL_BTN_SEND
+        if (scroll_state == SCROLL_BTN 
+                && timer_elapsed(scroll_button_time) < PS2_MOUSE_SCROLL_BTN_SEND) {
+            PRESS_SCROLL_BUTTONS;
+            host_mouse_send(mouse_report);
+            _delay_ms(100);
+            RELEASE_SCROLL_BUTTONS;
+        }
+#endif
+        scroll_state = SCROLL_NONE;
+    }
 
-/* PS/2 Mouse Synopsis
- * http://www.computer-engineering.org/ps2mouse/
- *
- * Command:
- * 0xFF: Reset
- * 0xF6: Set Defaults Sampling; rate=100, resolution=4cnt/mm, scaling=1:1, reporting=disabled
- * 0xF5: Disable Data Reporting
- * 0xF4: Enable Data Reporting
- * 0xF3: Set Sample Rate
- * 0xF2: Get Device ID
- * 0xF0: Set Remote Mode
- * 0xEB: Read Data
- * 0xEA: Set Stream Mode
- * 0xE9: Status Request
- * 0xE8: Set Resolution
- * 0xE7: Set Scaling 2:1
- * 0xE6: Set Scaling 1:1
- *
- * Mode:
- * Stream Mode: devices sends the data when it changs its state
- * Remote Mode: host polls the data periodically
- *
- * This code uses Remote Mode and polls the data with Read Data(0xEB).
- *
- * Data format:
- * byte|7       6       5       4       3       2       1       0
- * ----+--------------------------------------------------------------
- *    0|Yovflw  Xovflw  Ysign   Xsign   1       Middle  Right   Left
- *    1|                    X movement
- *    2|                    Y movement
- */
+    RELEASE_SCROLL_BUTTONS;
+}
diff --git a/tmk_core/protocol/ps2_mouse.h b/tmk_core/protocol/ps2_mouse.h
index 27d9790d4..e11c705fc 100644
--- a/tmk_core/protocol/ps2_mouse.h
+++ b/tmk_core/protocol/ps2_mouse.h
@@ -20,15 +20,13 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 #include <stdbool.h>
 
-#define PS2_MOUSE_READ_DATA     0xEB
-
 /*
  * Data format:
  * byte|7       6       5       4       3       2       1       0
- * ----+--------------------------------------------------------------
- *    0|Yovflw  Xovflw  Ysign   Xsign   1       Middle  Right   Left
- *    1|                    X movement(0-255)
- *    2|                    Y movement(0-255)
+ * ----+----------------------------------------------------------------
+ *    0|[Yovflw][Xovflw][Ysign ][Xsign ][ 1    ][Middle][Right ][Left  ]
+ *    1|[                    X movement(0-255)                         ]
+ *    2|[                    Y movement(0-255)                         ]
  */
 #define PS2_MOUSE_BTN_MASK      0x07
 #define PS2_MOUSE_BTN_LEFT      0
@@ -39,10 +37,6 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #define PS2_MOUSE_X_OVFLW       6
 #define PS2_MOUSE_Y_OVFLW       7
 
-
-/*
- * Scroll by mouse move with pressing button
- */
 /* mouse button to start scrolling; set 0 to disable scroll */
 #ifndef PS2_MOUSE_SCROLL_BTN_MASK
 #define PS2_MOUSE_SCROLL_BTN_MASK       (1<<PS2_MOUSE_BTN_MIDDLE)
@@ -58,9 +52,77 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #ifndef PS2_MOUSE_SCROLL_DIVISOR_H
 #define PS2_MOUSE_SCROLL_DIVISOR_H      2
 #endif
+/* multiply reported mouse values by these */
+#ifndef PS2_MOUSE_X_MULTIPLIER
+#define PS2_MOUSE_X_MULTIPLIER          1
+#endif
+#ifndef PS2_MOUSE_Y_MULTIPLIER
+#define PS2_MOUSE_Y_MULTIPLIER          1
+#endif
+#ifndef PS2_MOUSE_V_MULTIPLIER
+#define PS2_MOUSE_V_MULTIPLIER          1
+#endif
+/* For some mice this will need to be 0x0F */
+#ifndef PS2_MOUSE_SCROLL_MASK       
+#define PS2_MOUSE_SCROLL_MASK           0xFF 
+#endif
+#ifndef PS2_MOUSE_INIT_DELAY
+#define PS2_MOUSE_INIT_DELAY            1000
+#endif
+
+enum ps2_mouse_command_e {
+    PS2_MOUSE_RESET = 0xFF,
+    PS2_MOUSE_RESEND = 0xFE,
+    PS2_MOSUE_SET_DEFAULTS = 0xF6,
+    PS2_MOUSE_DISABLE_DATA_REPORTING = 0xF5,
+    PS2_MOUSE_ENABLE_DATA_REPORTING = 0xF4,
+    PS2_MOUSE_SET_SAMPLE_RATE = 0xF3,
+    PS2_MOUSE_GET_DEVICE_ID = 0xF2,
+    PS2_MOUSE_SET_REMOTE_MODE = 0xF0,
+    PS2_MOUSE_SET_WRAP_MODE = 0xEC,
+    PS2_MOUSE_READ_DATA = 0xEB,
+    PS2_MOUSE_SET_STREAM_MODE = 0xEA,
+    PS2_MOUSE_STATUS_REQUEST = 0xE9,
+    PS2_MOUSE_SET_RESOLUTION = 0xE8,
+    PS2_MOUSE_SET_SCALING_2_1 = 0xE7,
+    PS2_MOUSE_SET_SCALING_1_1 = 0xE6,
+};
 
+typedef enum ps2_mouse_resolution_e {
+    PS2_MOUSE_1_COUNT_MM,
+    PS2_MOUSE_2_COUNT_MM,
+    PS2_MOUSE_4_COUNT_MM,
+    PS2_MOUSE_8_COUNT_MM,   
+} ps2_mouse_resolution_t;
+
+typedef enum ps2_mouse_sample_rate_e {
+    PS2_MOUSE_10_SAMPLES_SEC = 10,
+    PS2_MOUSE_20_SAMPLES_SEC = 20,
+    PS2_MOUSE_40_SAMPLES_SEC = 40,
+    PS2_MOUSE_60_SAMPLES_SEC = 60,
+    PS2_MOUSE_80_SAMPLES_SEC = 80,
+    PS2_MOUSE_100_SAMPLES_SEC = 100,
+    PS2_MOUSE_200_SAMPLES_SEC = 200,
+} ps2_mouse_sample_rate_t;
+
+void ps2_mouse_init(void);
 
-uint8_t ps2_mouse_init(void);
 void ps2_mouse_task(void);
 
+void ps2_mouse_disable_data_reporting(void);
+
+void ps2_mouse_enable_data_reporting(void);
+
+void ps2_mouse_set_remote_mode(void);
+
+void ps2_mouse_set_stream_mode(void);
+
+void ps2_mouse_set_scaling_2_1(void);
+
+void ps2_mouse_set_scaling_1_1(void);
+
+void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution);
+
+void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate);
+
 #endif