1 files changed, 197 insertions, 7 deletions
diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md
index 905c2a8f9..031ee52c1 100644
--- a/docs/feature_pointing_device.md
+++ b/docs/feature_pointing_device.md
@@ -1,19 +1,205 @@
 # Pointing Device :id=pointing-device
-Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around.  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.
+Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around.  There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and hardware driven.  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:
-```makefile
+```make
 POINTING_DEVICE_ENABLE = yes
 ```
-To manipulate the mouse report, you can use the following functions:
+## Sensor Drivers
-* `pointing_device_get_report()` - Returns the current report_mouse_t that represents the information sent to the host computer
+There are a number of sensors that are supported by default. Note that only one sensor can be enabled by `POINTING_DEVICE_DRIVER` at a time.  If you need to enable more than one sensor, then you need to implement it manually.
-* `pointing_device_set_report(report_mouse_t newMouseReport)` - Overrides and saves the report_mouse_t to be sent to the host computer
+### ADNS 5050 Sensor
+To use the ADNS 5050 sensor, add this to your `rules.mk`
+```make
+POINTING_DEVICE_DRIVER = adns5050
+```
+The ADNS 5050 sensor uses a serial type protocol for communication, and requires an additional light source. 
+| Setting            | Description                                                         |
+|--------------------|---------------------------------------------------------------------|
+|`ADNS5050_SCLK_PIN` | (Required) The pin connected to the clock pin of the sensor.        |
+|`ADNS5050_SDIO_PIN` | (Required) The pin connected to the data pin of the sensor.         |
+|`ADNS5050_CS_PIN`   | (Required) The pin connected to the cable select pin of the sensor. |
+The CPI range is 125-1375, in increments of 125. Defaults to 500 CPI.
+### ADSN 9800 Sensor
+To use the ADNS 9800 sensor, add this to your `rules.mk`
+```make
+POINTING_DEVICE_DRIVER = adns9800
+```
+The ADNS 9800 is an SPI driven optical sensor, that uses laser output for surface tracking. 
+| Setting                | Description                                                            | Default       |
+|------------------------|------------------------------------------------------------------------|---------------|
+|`ADNS9800_CLOCK_SPEED`  | (Optional) Sets the clock speed that the sensor runs at.               | `2000000`     |
+|`ADNS9800_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false`       |
+|`ADNS9800_SPI_MODE`     | (Optional) Sets the SPI Mode for the sensor.                           | `3`           |
+|`ADNS9800_SPI_DIVISOR`  | (Optional) Sets the SPI Divisor used for SPI communication.            | _varies_      |
+|`ADNS9800_CS_PIN`       | (Required) Sets the Cable Select pin connected to the sensor.          | _not defined_ |
+The CPI range is 800-8200, in increments of 200. Defaults to 1800 CPI. 
+### Analog Joystick
+To use an analog joystick to control the pointer, add this to your `rules.mk`
+```make
+POINTING_DEVICE_DRIVER = analog_joystick
+```
+The Analog Joystick is an analog (ADC) driven sensor.  There are a variety of joysticks that you can use for this.
+| Setting                          | Description                                                                | Default       |
+|----------------------------------|----------------------------------------------------------------------------|---------------|
+|`ANALOG_JOYSTICK_X_AXIS_PIN`      | (Required) The pin used for the vertical/X axis.                           | _not defined_ |
+|`ANALOG_JOYSTICK_Y_AXIS_PIN`      | (Required) The pin used for the horizontal/Y axis.                         | _not defined_ |
+|`ANALOG_JOYSTICK_AXIS_MIN`        | (Optional) Sets the lower range to be considered movement.                 | `0`           |
+|`ANALOG_JOYSTICK_AXIS_MAX`        | (Optional) Sets the upper range to be considered movement.                 | `1023`        |
+|`ANALOG_JOYSTICK_SPEED_REGULATOR` | (Optional) The divisor used to slow down movement. (lower makes it faster) | `20`          |
+|`ANALOG_JOYSTICK_READ_INTERVAL`   | (Optional) The interval in milliseconds between reads.                     | `10`          |
+|`ANALOG_JOYSTICK_SPEED_MAX`       | (Optional) The maxiumum value used for motion.                             | `2`           |
+|`ANALOG_JOYSTICK_CLICK_PIN`       | (Optional) The pin wired up to the press switch of the analog stick.       | _not defined_ |
+### Cirque Trackpad
+To use the Cirque Trackpad sensor, add this to your `rules.mk`:
+```make
+POINTING_DEVICE_DRIVER = cirque_pinnacle_i2c
+```
+or
+```make
+POINTING_DEVICE_DRIVER = cirque_pinnacle_spi
+```
+This supports the Cirque Pinnacle 1CA027 Touch Controller, which is used in the TM040040, TM035035 and the TM023023 trackpads. These are I2C or SPI compatible, and both configurations are supported.
+| Setting                         | Description                                                                     | Default               |
+|---------------------------------|---------------------------------------------------------------------------------|-----------------------|
+|`CIRQUE_PINNACLE_X_LOWER`        | (Optional) The minimum reachable X value on the sensor.                         | `127`                 |
+|`CIRQUE_PINNACLE_X_UPPER`        | (Optional) The maximum reachable X value on the sensor.                         | `1919`                |
+|`CIRQUE_PINNACLE_Y_LOWER`        | (Optional) The minimum reachable Y value on the sensor.                         | `63`                  |
+|`CIRQUE_PINNACLE_Y_UPPER`        | (Optional) The maximum reachable Y value on the sensor.                         | `1471`                |
+|`CIRQUE_PINNACLE_TAPPING_TERM`   | (Optional) Length of time that a touch can be to be considered a tap.           | `TAPPING_TERM`/`200`  |
+|`CIRQUE_PINNACLE_TOUCH_DEBOUNCE` | (Optional) Length of time that a touch can be to be considered a tap.           | `TAPPING_TERM`/`200`  |
-Keep in mind that a report_mouse_t (here "mouseReport") has the following properties:
+| I2C Setting              | Description                                                                     | Default |
+|--------------------------|---------------------------------------------------------------------------------|---------|
+|`CIRQUE_PINNACLE_ADDR`    | (Required) Sets the I2C Address for the Cirque Trackpad                         | `0x2A`  |
+|`CIRQUE_PINNACLE_TIMEOUT` | (Optional) The timeout for i2c communication with the trackpad in milliseconds. | `20`    |
+| SPI Setting                   | Description                                                            | Default       |
+|-------------------------------|------------------------------------------------------------------------|---------------|
+|`CIRQUE_PINNACLE_CLOCK_SPEED`  | (Optional) Sets the clock speed that the sensor runs at.               | `1000000`     |
+|`CIRQUE_PINNACLE_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false`       |
+|`CIRQUE_PINNACLE_SPI_MODE`     | (Optional) Sets the SPI Mode for the sensor.                           | `1`           |
+|`CIRQUE_PINNACLE_SPI_DIVISOR`  | (Optional) Sets the SPI Divisor used for SPI communication.            | _varies_      |
+|`CIRQUE_PINNACLE_SPI_CS_PIN`   | (Required) Sets the Cable Select pin connected to the sensor.          | _not defined_ |
+Default Scaling/CPI is 1024.
+### Pimoroni Trackball
+To use the Pimoroni Trackball module, add this to your `rules.mk`:
+```make
+POINTING_DEVICE_DRIVER = pimoroni_trackball
+```
+The Pimoroni Trackball module is a I2C based breakout board with an RGB enable trackball. 
+| Setting                             | Description                                                                        | Default |
+|-------------------------------------|------------------------------------------------------------------------------------|---------|
+|`PIMORONI_TRACKBALL_ADDRESS`         | (Required) Sets the I2C Address for the Pimoroni Trackball.                        | `0x0A`  |
+|`PIMORONI_TRACKBALL_TIMEOUT`         | (Optional) The timeout for i2c communication with the trackpad in milliseconds.    | `100`   |
+|`PIMORONI_TRACKBALL_INTERVAL_MS`     | (Optional) The update/read interval for the sensor in milliseconds.                | `8`     |
+|`PIMORONI_TRACKBALL_SCALE`           | (Optional) The multiplier used to generate reports from the sensor.                | `5`     |
+|`PIMORONI_TRACKBALL_DEBOUNCE_CYCLES` | (Optional) The number of scan cycles used for debouncing on the ball press.        | `20`    |
+|`PIMORONI_TRACKBALL_ERROR_COUNT`     | (Optional) Specifies the number of read/write errors until the sensor is disabled. | `10`  |
+### PMW 3360 Sensor
+To use the PMW 3360 sensor, add this to your `rules.mk`
+```make
+POINTING_DEVICE_DRIVER = pmw3360
+```
+The PMW 3360 is an SPI driven optical sensor, that uses a built in IR LED for surface tracking.
+| Setting                     | Description                                                                                | Default       |
+|-----------------------------|--------------------------------------------------------------------------------------------|---------------|
+|`PMW3360_CS_PIN`             | (Required) Sets the Cable Select pin connected to the sensor.                              | _not defined_ |
+|`PMW3360_CLOCK_SPEED`        | (Optional) Sets the clock speed that the sensor runs at.                                   | `2000000`     |
+|`PMW3360_SPI_LSBFIRST`       | (Optional) Sets the Least/Most Significant Byte First setting for SPI.                     | `false`       |
+|`PMW3360_SPI_MODE`           | (Optional) Sets the SPI Mode for the sensor.                                               | `3`           |
+|`PMW3360_SPI_DIVISOR`        | (Optional) Sets the SPI Divisor used for SPI communication.                                | _varies_      |
+|`ROTATIONAL_TRANSFORM_ANGLE` | (Optional) Allows for the sensor data to be rotated +/- 30 degrees directly in the sensor. | `0`           |
+The CPI range is 100-12000, in increments of 100. Defaults to 1600 CPI.
+### Custom Driver
+If you have a sensor type that isn't supported here, you can manually implement it, by adding these functions (with the correct implementation for your device):
+```c
+void           pointing_device_driver_init(void) {}
+report_mouse_t pointing_device_driver_get_report(report_mouse_t mouse_report) { return mouse_report; }
+uint16_t       pointing_device_driver_get_cpi(void) { return 0; }
+void           pointing_device_driver_set_cpi(uint16_t cpi) {}
+```
+!> Ideally, new sensor hardware should be added to `drivers/sensors/` and `quantum/pointing_device_drivers.c`, but there may be cases where it's very specific to the hardware.  So these functions are provided, just in case. 
+## Common Configuration
+| Setting                       | Description                                                           | Default       |
+|-------------------------------|-----------------------------------------------------------------------|---------------|
+|`POINTING_DEVICE_ROTATION_90`  | (Optional) Rotates the X and Y data by  90 degrees.                   | _not defined_ |
+|`POINTING_DEVICE_ROTATION_180` | (Optional) Rotates the X and Y data by 180 degrees.                   | _not defined_ |
+|`POINTING_DEVICE_ROTATION_270` | (Optional) Rotates the X and Y data by 270 degrees.                   | _not defined_ |
+|`POINTING_DEVICE_INVERT_X`     | (Optional) Inverts the X axis report.                                 | _not defined_ |
+|`POINTING_DEVICE_INVERT_Y`     | (Optional) Inverts the Y axis report.                                 | _not defined_ |
+|`POINTING_DEVICE_MOTION_PIN`   | (Optional) If supported, will only read from sensor if pin is active. | _not defined_ |
+## Callbacks and Functions 
+| Function                          | Description                                                                                                                            |
+|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
+| `pointing_device_init_kb(void)`                            | Callback to allow for keyboard level initialization. Useful for additional hardware sensors.                  |
+| `pointing_device_init_user(void)`                          | Callback to allow for user level initialization. Useful for additional hardware sensors.                      |
+| `pointing_device_task_kb(mouse_report)`                    | Callback that sends sensor data, so keyboard code can intercept and modify the data.  Returns a mouse report. |
+| `pointing_device_task_user(mouse_report)`                  | Callback that sends sensor data, so user coe can intercept and modify the data.  Returns a mouse report.      |
+| `pointing_device_handle_buttons(buttons, pressed, button)` | Callback to handle hardware button presses. Returns a `uint8_t`.                                              |
+| `pointing_device_get_cpi(void)`                            | Gets the current CPI/DPI setting from the sensor, if supported.                                               |
+| `pointing_device_set_cpi(uint16_t)`                        | Sets the CPI/DPI, if supported.                                                                               |
+| `pointing_device_get_report(void)`                         | Returns the current mouse report (as a `mouse_report_t` data structure).                                      | 
+| `pointing_device_set_report(mouse_report)`                 | Sets the mouse report to the assigned `mouse_report_t` data structured passed to the function.                | 
+| `pointing_device_send(void)`                               | Sends the current mouse report to the host system.  Function can be replaced.                                 | 
+| `has_mouse_report_changed(old, new)`                       | Compares the old and new `mouse_report_t` data and returns true only if it has changed.                       |
+# Manipulating Mouse Reports
+The 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.
@@ -21,8 +207,10 @@ Keep in mind that a report_mouse_t (here "mouseReport") has the following proper
 * `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 all 8 bits are used.  These bits represent the mouse button state - bit 0 is mouse button 1, and bit 7 is mouse button 8.
-Once you have made the necessary changes to the mouse report, you need to send it:
+To manually manipulate the mouse reports outside of the `pointing_device_task_*` functions, you can use:
+* `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
 * `pointing_device_send()` - Sends the mouse report to the host and zeroes out the report. 
 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.
@@ -31,6 +219,8 @@ Additionally, by default, `pointing_device_send()` will only send a report when
 Also, you use the `has_mouse_report_changed(new, old)` function to check to see if the report has changed.
+## Example
 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:
 ```c

diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md index 905c2a8f9..031ee52c1 100644 --- a/docs/feature_pointing_device.md +++ b/docs/feature_pointing_device.md
@@ -1,19 +1,205 @@
1	# Pointing Device :id=pointing-device	1	# Pointing Device :id=pointing-device
2		2
3	Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around. 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.	3	Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around. There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and hardware driven. 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.
4		4
5	To enable Pointing Device, uncomment the following line in your rules.mk:	5	To enable Pointing Device, uncomment the following line in your rules.mk:
6		6
7	```makefile	7	```make
8	POINTING_DEVICE_ENABLE = yes	8	POINTING_DEVICE_ENABLE = yes
9	```	9	```
10		10
11	To manipulate the mouse report, you can use the following functions:	11	## Sensor Drivers
12		12
13	* `pointing_device_get_report()` - Returns the current report_mouse_t that represents the information sent to the host computer	13	There are a number of sensors that are supported by default. Note that only one sensor can be enabled by `POINTING_DEVICE_DRIVER` at a time. If you need to enable more than one sensor, then you need to implement it manually.
14	* `pointing_device_set_report(report_mouse_t newMouseReport)` - Overrides and saves the report_mouse_t to be sent to the host computer	14
		15	### ADNS 5050 Sensor
		16
		17	To use the ADNS 5050 sensor, add this to your `rules.mk`
		18
		19	```make
		20	POINTING_DEVICE_DRIVER = adns5050
		21	```
		22
		23	The ADNS 5050 sensor uses a serial type protocol for communication, and requires an additional light source.
		24
		25	\| Setting \| Description \|
		26	\|--------------------\|---------------------------------------------------------------------\|
		27	\|`ADNS5050_SCLK_PIN` \| (Required) The pin connected to the clock pin of the sensor. \|
		28	\|`ADNS5050_SDIO_PIN` \| (Required) The pin connected to the data pin of the sensor. \|
		29	\|`ADNS5050_CS_PIN` \| (Required) The pin connected to the cable select pin of the sensor. \|
		30
		31	The CPI range is 125-1375, in increments of 125. Defaults to 500 CPI.
		32
		33	### ADSN 9800 Sensor
		34
		35	To use the ADNS 9800 sensor, add this to your `rules.mk`
		36
		37	```make
		38	POINTING_DEVICE_DRIVER = adns9800
		39	```
		40
		41	The ADNS 9800 is an SPI driven optical sensor, that uses laser output for surface tracking.
		42
		43	\| Setting \| Description \| Default \|
		44	\|------------------------\|------------------------------------------------------------------------\|---------------\|
		45	\|`ADNS9800_CLOCK_SPEED` \| (Optional) Sets the clock speed that the sensor runs at. \| `2000000` \|
		46	\|`ADNS9800_SPI_LSBFIRST` \| (Optional) Sets the Least/Most Significant Byte First setting for SPI. \| `false` \|
		47	\|`ADNS9800_SPI_MODE` \| (Optional) Sets the SPI Mode for the sensor. \| `3` \|
		48	\|`ADNS9800_SPI_DIVISOR` \| (Optional) Sets the SPI Divisor used for SPI communication. \| _varies_ \|
		49	\|`ADNS9800_CS_PIN` \| (Required) Sets the Cable Select pin connected to the sensor. \| _not defined_ \|
		50
		51
		52	The CPI range is 800-8200, in increments of 200. Defaults to 1800 CPI.
		53
		54	### Analog Joystick
		55
		56	To use an analog joystick to control the pointer, add this to your `rules.mk`
		57
		58	```make
		59	POINTING_DEVICE_DRIVER = analog_joystick
		60	```
		61
		62	The Analog Joystick is an analog (ADC) driven sensor. There are a variety of joysticks that you can use for this.
		63
		64	\| Setting \| Description \| Default \|
		65	\|----------------------------------\|----------------------------------------------------------------------------\|---------------\|
		66	\|`ANALOG_JOYSTICK_X_AXIS_PIN` \| (Required) The pin used for the vertical/X axis. \| _not defined_ \|
		67	\|`ANALOG_JOYSTICK_Y_AXIS_PIN` \| (Required) The pin used for the horizontal/Y axis. \| _not defined_ \|
		68	\|`ANALOG_JOYSTICK_AXIS_MIN` \| (Optional) Sets the lower range to be considered movement. \| `0` \|
		69	\|`ANALOG_JOYSTICK_AXIS_MAX` \| (Optional) Sets the upper range to be considered movement. \| `1023` \|
		70	\|`ANALOG_JOYSTICK_SPEED_REGULATOR` \| (Optional) The divisor used to slow down movement. (lower makes it faster) \| `20` \|
		71	\|`ANALOG_JOYSTICK_READ_INTERVAL` \| (Optional) The interval in milliseconds between reads. \| `10` \|
		72	\|`ANALOG_JOYSTICK_SPEED_MAX` \| (Optional) The maxiumum value used for motion. \| `2` \|
		73	\|`ANALOG_JOYSTICK_CLICK_PIN` \| (Optional) The pin wired up to the press switch of the analog stick. \| _not defined_ \|
		74
		75
		76	### Cirque Trackpad
		77
		78	To use the Cirque Trackpad sensor, add this to your `rules.mk`:
		79
		80	```make
		81	POINTING_DEVICE_DRIVER = cirque_pinnacle_i2c
		82	```
		83
		84	or
		85
		86	```make
		87	POINTING_DEVICE_DRIVER = cirque_pinnacle_spi
		88	```
		89
		90
		91	This supports the Cirque Pinnacle 1CA027 Touch Controller, which is used in the TM040040, TM035035 and the TM023023 trackpads. These are I2C or SPI compatible, and both configurations are supported.
		92
		93	\| Setting \| Description \| Default \|
		94	\|---------------------------------\|---------------------------------------------------------------------------------\|-----------------------\|
		95	\|`CIRQUE_PINNACLE_X_LOWER` \| (Optional) The minimum reachable X value on the sensor. \| `127` \|
		96	\|`CIRQUE_PINNACLE_X_UPPER` \| (Optional) The maximum reachable X value on the sensor. \| `1919` \|
		97	\|`CIRQUE_PINNACLE_Y_LOWER` \| (Optional) The minimum reachable Y value on the sensor. \| `63` \|
		98	\|`CIRQUE_PINNACLE_Y_UPPER` \| (Optional) The maximum reachable Y value on the sensor. \| `1471` \|
		99	\|`CIRQUE_PINNACLE_TAPPING_TERM` \| (Optional) Length of time that a touch can be to be considered a tap. \| `TAPPING_TERM`/`200` \|
		100	\|`CIRQUE_PINNACLE_TOUCH_DEBOUNCE` \| (Optional) Length of time that a touch can be to be considered a tap. \| `TAPPING_TERM`/`200` \|
15		101
16	Keep in mind that a report_mouse_t (here "mouseReport") has the following properties:	102	\| I2C Setting \| Description \| Default \|
		103	\|--------------------------\|---------------------------------------------------------------------------------\|---------\|
		104	\|`CIRQUE_PINNACLE_ADDR` \| (Required) Sets the I2C Address for the Cirque Trackpad \| `0x2A` \|
		105	\|`CIRQUE_PINNACLE_TIMEOUT` \| (Optional) The timeout for i2c communication with the trackpad in milliseconds. \| `20` \|
		106
		107	\| SPI Setting \| Description \| Default \|
		108	\|-------------------------------\|------------------------------------------------------------------------\|---------------\|
		109	\|`CIRQUE_PINNACLE_CLOCK_SPEED` \| (Optional) Sets the clock speed that the sensor runs at. \| `1000000` \|
		110	\|`CIRQUE_PINNACLE_SPI_LSBFIRST` \| (Optional) Sets the Least/Most Significant Byte First setting for SPI. \| `false` \|
		111	\|`CIRQUE_PINNACLE_SPI_MODE` \| (Optional) Sets the SPI Mode for the sensor. \| `1` \|
		112	\|`CIRQUE_PINNACLE_SPI_DIVISOR` \| (Optional) Sets the SPI Divisor used for SPI communication. \| _varies_ \|
		113	\|`CIRQUE_PINNACLE_SPI_CS_PIN` \| (Required) Sets the Cable Select pin connected to the sensor. \| _not defined_ \|
		114
		115	Default Scaling/CPI is 1024.
		116
		117	### Pimoroni Trackball
		118
		119	To use the Pimoroni Trackball module, add this to your `rules.mk`:
		120
		121	```make
		122	POINTING_DEVICE_DRIVER = pimoroni_trackball
		123	```
		124
		125	The Pimoroni Trackball module is a I2C based breakout board with an RGB enable trackball.
		126
		127	\| Setting \| Description \| Default \|
		128	\|-------------------------------------\|------------------------------------------------------------------------------------\|---------\|
		129	\|`PIMORONI_TRACKBALL_ADDRESS` \| (Required) Sets the I2C Address for the Pimoroni Trackball. \| `0x0A` \|
		130	\|`PIMORONI_TRACKBALL_TIMEOUT` \| (Optional) The timeout for i2c communication with the trackpad in milliseconds. \| `100` \|
		131	\|`PIMORONI_TRACKBALL_INTERVAL_MS` \| (Optional) The update/read interval for the sensor in milliseconds. \| `8` \|
		132	\|`PIMORONI_TRACKBALL_SCALE` \| (Optional) The multiplier used to generate reports from the sensor. \| `5` \|
		133	\|`PIMORONI_TRACKBALL_DEBOUNCE_CYCLES` \| (Optional) The number of scan cycles used for debouncing on the ball press. \| `20` \|
		134	\|`PIMORONI_TRACKBALL_ERROR_COUNT` \| (Optional) Specifies the number of read/write errors until the sensor is disabled. \| `10` \|
		135
		136	### PMW 3360 Sensor
		137
		138	To use the PMW 3360 sensor, add this to your `rules.mk`
		139
		140	```make
		141	POINTING_DEVICE_DRIVER = pmw3360
		142	```
		143
		144	The PMW 3360 is an SPI driven optical sensor, that uses a built in IR LED for surface tracking.
		145
		146	\| Setting \| Description \| Default \|
		147	\|-----------------------------\|--------------------------------------------------------------------------------------------\|---------------\|
		148	\|`PMW3360_CS_PIN` \| (Required) Sets the Cable Select pin connected to the sensor. \| _not defined_ \|
		149	\|`PMW3360_CLOCK_SPEED` \| (Optional) Sets the clock speed that the sensor runs at. \| `2000000` \|
		150	\|`PMW3360_SPI_LSBFIRST` \| (Optional) Sets the Least/Most Significant Byte First setting for SPI. \| `false` \|
		151	\|`PMW3360_SPI_MODE` \| (Optional) Sets the SPI Mode for the sensor. \| `3` \|
		152	\|`PMW3360_SPI_DIVISOR` \| (Optional) Sets the SPI Divisor used for SPI communication. \| _varies_ \|
		153	\|`ROTATIONAL_TRANSFORM_ANGLE` \| (Optional) Allows for the sensor data to be rotated +/- 30 degrees directly in the sensor. \| `0` \|
		154
		155	The CPI range is 100-12000, in increments of 100. Defaults to 1600 CPI.
		156
		157
		158	### Custom Driver
		159
		160	If you have a sensor type that isn't supported here, you can manually implement it, by adding these functions (with the correct implementation for your device):
		161
		162	```c
		163	void pointing_device_driver_init(void) {}
		164	report_mouse_t pointing_device_driver_get_report(report_mouse_t mouse_report) { return mouse_report; }
		165	uint16_t pointing_device_driver_get_cpi(void) { return 0; }
		166	void pointing_device_driver_set_cpi(uint16_t cpi) {}
		167	```
		168
		169	!> Ideally, new sensor hardware should be added to `drivers/sensors/` and `quantum/pointing_device_drivers.c`, but there may be cases where it's very specific to the hardware. So these functions are provided, just in case.
		170
		171	## Common Configuration
		172
		173	\| Setting \| Description \| Default \|
		174	\|-------------------------------\|-----------------------------------------------------------------------\|---------------\|
		175	\|`POINTING_DEVICE_ROTATION_90` \| (Optional) Rotates the X and Y data by 90 degrees. \| _not defined_ \|
		176	\|`POINTING_DEVICE_ROTATION_180` \| (Optional) Rotates the X and Y data by 180 degrees. \| _not defined_ \|
		177	\|`POINTING_DEVICE_ROTATION_270` \| (Optional) Rotates the X and Y data by 270 degrees. \| _not defined_ \|
		178	\|`POINTING_DEVICE_INVERT_X` \| (Optional) Inverts the X axis report. \| _not defined_ \|
		179	\|`POINTING_DEVICE_INVERT_Y` \| (Optional) Inverts the Y axis report. \| _not defined_ \|
		180	\|`POINTING_DEVICE_MOTION_PIN` \| (Optional) If supported, will only read from sensor if pin is active. \| _not defined_ \|
		181
		182
		183	## Callbacks and Functions
		184
		185	\| Function \| Description \|
		186	\|-----------------------------------\|----------------------------------------------------------------------------------------------------------------------------------------\|
		187	\| `pointing_device_init_kb(void)` \| Callback to allow for keyboard level initialization. Useful for additional hardware sensors. \|
		188	\| `pointing_device_init_user(void)` \| Callback to allow for user level initialization. Useful for additional hardware sensors. \|
		189	\| `pointing_device_task_kb(mouse_report)` \| Callback that sends sensor data, so keyboard code can intercept and modify the data. Returns a mouse report. \|
		190	\| `pointing_device_task_user(mouse_report)` \| Callback that sends sensor data, so user coe can intercept and modify the data. Returns a mouse report. \|
		191	\| `pointing_device_handle_buttons(buttons, pressed, button)` \| Callback to handle hardware button presses. Returns a `uint8_t`. \|
		192	\| `pointing_device_get_cpi(void)` \| Gets the current CPI/DPI setting from the sensor, if supported. \|
		193	\| `pointing_device_set_cpi(uint16_t)` \| Sets the CPI/DPI, if supported. \|
		194	\| `pointing_device_get_report(void)` \| Returns the current mouse report (as a `mouse_report_t` data structure). \|
		195	\| `pointing_device_set_report(mouse_report)` \| Sets the mouse report to the assigned `mouse_report_t` data structured passed to the function. \|
		196	\| `pointing_device_send(void)` \| Sends the current mouse report to the host system. Function can be replaced. \|
		197	\| `has_mouse_report_changed(old, new)` \| Compares the old and new `mouse_report_t` data and returns true only if it has changed. \|
		198
		199
		200	# Manipulating Mouse Reports
		201
		202	The report_mouse_t (here "mouseReport") has the following properties:
17		203
18	* `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.	204	* `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.
19	* `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.	205	* `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.
@@ -21,8 +207,10 @@ Keep in mind that a report_mouse_t (here "mouseReport") has the following proper
21	* `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).	207	* `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).
22	* `mouseReport.buttons` - this is a uint8_t in which all 8 bits are used. These bits represent the mouse button state - bit 0 is mouse button 1, and bit 7 is mouse button 8.	208	* `mouseReport.buttons` - this is a uint8_t in which all 8 bits are used. These bits represent the mouse button state - bit 0 is mouse button 1, and bit 7 is mouse button 8.
23		209
24	Once you have made the necessary changes to the mouse report, you need to send it:	210	To manually manipulate the mouse reports outside of the `pointing_device_task_*` functions, you can use:
25		211
		212	* `pointing_device_get_report()` - Returns the current report_mouse_t that represents the information sent to the host computer
		213	* `pointing_device_set_report(report_mouse_t newMouseReport)` - Overrides and saves the report_mouse_t to be sent to the host computer
26	* `pointing_device_send()` - Sends the mouse report to the host and zeroes out the report.	214	* `pointing_device_send()` - Sends the mouse report to the host and zeroes out the report.
27		215
28	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.	216	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.
@@ -31,6 +219,8 @@ Additionally, by default, `pointing_device_send()` will only send a report when
31		219
32	Also, you use the `has_mouse_report_changed(new, old)` function to check to see if the report has changed.	220	Also, you use the `has_mouse_report_changed(new, old)` function to check to see if the report has changed.
33		221
		222	## Example
		223
34	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:	224	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:
35		225
36	```c	226	```c