From eb8889883d1e91f58a42f0babc17a10fa3fa1b4a Mon Sep 17 00:00:00 2001
From: Cedric VINCENT <git@initro.org>
Date: Sun, 14 Nov 2021 19:46:57 +0100
Subject: [PATCH] feat(docs): Add documentation about PIM447 trackball driver.

---
 docs/docs/behaviors/trackball-pim447.md | 33 ++++++++++++
 docs/docs/features/trackballs.md        | 71 +++++++++++++++++++++++++
 docs/docs/intro.md                      |  1 +
 docs/sidebars.js                        |  2 +
 4 files changed, 107 insertions(+)
 create mode 100644 docs/docs/behaviors/trackball-pim447.md
 create mode 100644 docs/docs/features/trackballs.md

diff --git a/docs/docs/behaviors/trackball-pim447.md b/docs/docs/behaviors/trackball-pim447.md
new file mode 100644
index 00000000..af28eb23
--- /dev/null
+++ b/docs/docs/behaviors/trackball-pim447.md
@@ -0,0 +1,33 @@
+---
+title: Trackball PIM447 Behaviors
+sidebar_label: Trackball PIM447
+---
+
+The mode of the trackball PIM447 driver can be changed using the
+following key behaviors.
+
+- `&pim447_move`: set trackball mode to "move" .
+- `&pim447_scroll`: set trackball mode to "scroll" .
+- `&pim447_toggle`: toggle trackball mode (from "scroll" to "move", or vice versa).
+- `&pim447_move_scroll`: set trackball mode to "move" when pressed, then to "scroll" when released.
+- `&pim447_scroll_move`: set trackball mode to "scroll" when pressed, then to "move" when released.
+- `&pim447_toggle_toggle`: toggle trackball mode when pressed, then toggle again when released.
+
+Example:
+
+```
+#include <dt-bindings/zmk/trackball_pim447.h>
+
+/ {
+	keymap {
+		compatible = "zmk,keymap";
+
+		a_layer {
+			bindings = <&kp a
+				    &kp b
+				    &kp c
+				    &pim447_toggle>;
+		};
+	};
+};
+```
diff --git a/docs/docs/features/trackballs.md b/docs/docs/features/trackballs.md
new file mode 100644
index 00000000..e489c090
--- /dev/null
+++ b/docs/docs/features/trackballs.md
@@ -0,0 +1,71 @@
+---
+title: Trackballs
+sidebar_label: Trackballs
+---
+
+Only the [Pimoroni PIM447](https://shop.pimoroni.com/products/trackball-breakout)
+trackball is supported in ZMK so far.
+
+## Enable Trackball Support
+
+To enable support for PIM447 trackball — and to make it acts like a
+mouse — add the two following lines to the shield `.config` file:
+
+```ini
+CONFIG_ZMK_MOUSE=y
+CONFIG_ZMK_TRACKBALL_PIM447=y
+```
+
+Assuming the PIM447 trackball is connected to the `pro_micro_i2c` pins
+and its bus address hasn't been changed, then the following lines must
+be added to the shield `.overlay` file:
+
+```devicetree
+&pro_micro_i2c {
+	status = "okay";
+
+	trackball_pim447@a {
+		compatible = "pimoroni,trackball_pim447";
+		reg = <0xa>;
+		label = "TRACKBALL_PIM447";
+	};
+};
+```
+
+## Customize Trackball Driver Properties
+
+The PIM447 trackball driver can be configured according to a lot of
+different properties that are listed in the shield `.overlay` sample
+below:
+
+```devicetree
+#include <dt-bindings/zmk/trackball_pim447.h> // for PIM447_MOVE and PIM447_SCROLL constants.
+
+&pro_micro_i2c {
+	status = "okay";
+
+	trackball_pim447@a {
+		compatible = "pimoroni,trackball_pim447";
+		reg = <0xa>;
+		label = "TRACKBALL_PIM447";
+
+		move-factor = <2>;      // Increase pointer velocity (default: 1)
+		invert-move-x;          // Invert pointer X axis (left is right, and vice versa)
+		invert-move-y;          // Invert pointer Y axis (up is down, and vice versa)
+		button = <1>;           // Send right-click when pressing the ball (default: 0, ie. left-click)
+		swap-axes;              // Swap X and Y axes (horizontal is vertical, and vice versa)
+		scroll-divisor = <1>;   // Increase wheel velocity (default: 2)
+		invert-scroll-x;        // Invert wheel X axis (left is right, and vice versa)
+		invert-scroll-y;        // Invert wheel Y axis (up is down, and vice versa)
+		mode = <PIM447_SCROLL>; // Act as mouse wheels at startup (default: PIM447_MOVE for a pointer)
+	};
+};
+```
+
+## Change Trackball Driver Mode
+
+As seen at the end of the previous section, the PIM447 trackball
+driver can act as a mouse pointer or as mouse wheels according to the
+`mode` specified in the shield `.overlay` file.  It can also be
+changed dynamically using [dedicated key
+behaviors](/docs/behaviors/trackball-pim447).
diff --git a/docs/docs/intro.md b/docs/docs/intro.md
index e1983c93..ad89991e 100644
--- a/docs/docs/intro.md
+++ b/docs/docs/intro.md
@@ -40,6 +40,7 @@ ZMK is currently missing some features found in other popular firmware. This tab
 | Realtime Keymap Updating                                                                                                  | 💡  |           | ✅  |
 | AVR/8 Bit                                                                                                                 |     |           | ✅  |
 | [Wide Range of ARM Chips Supported](https://docs.zephyrproject.org/latest/boards/index.html)                              | ✅  |           |     |
+| [Trackballs](features/trackballs)                                                                                         | ✅  |           | ✅  |
 
 [^2]: Encoders are not currently supported on peripheral side splits.
 [^1]: OLEDs are currently proof of concept in ZMK.
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 545df5b3..54a01901 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -15,6 +15,7 @@ module.exports = {
       "features/displays",
       "features/encoders",
       "features/underglow",
+      "features/trackballs",
       "features/beta-testing",
     ],
     Behaviors: [
@@ -32,6 +33,7 @@ module.exports = {
       "behaviors/outputs",
       "behaviors/lighting",
       "behaviors/power",
+      "behaviors/trackball-pim447",
     ],
     Codes: [
       "codes/index",