Skip to content

Commit

Permalink
Add docs for pimoroni trackball handlers
Browse files Browse the repository at this point in the history
  • Loading branch information
xs5871 committed Aug 18, 2024
1 parent 5bcec78 commit 6627207
Showing 1 changed file with 80 additions and 9 deletions.
89 changes: 80 additions & 9 deletions docs/en/pimoroni_trackball.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Module handles usage of Trackball Breakout by Pimoroni.

### Usage
## Usage

Declare I2C bus and add this module in your main class.

Expand All @@ -17,24 +17,95 @@ keyboard.modules.append(trackball)

Module will also work when you cannot use `busio` and do `import bitbangio as io` instead.

### Key inputs, other handler combinations
## Key inputs, other handler combinations

### Builtin Handlers

There are a couple of builtin handlers for your convenience.
All parameters are show with their default values, optional parameters can be
omitted.

#### Pointing Handler

Plain pointing device, i.e. a mouse:

```python
PointingHandler(
# optional:
on_press=KC.MB_LMB,
)
```

#### Scroll Handler

Make the Trackball act as a 2D scroll wheel.
The default scroll direction is `NATURAL` and can be set to `ScrollDirection.REVERSE`
if the Apple behavior is preferred.

```python
ScrollHandler(
# optional:
scroll_direction=ScrollDirection.NATURAL,
on_press=KC.MB_LMB,
)
```

#### Key Handler

Emit key presses instead of movement:

```python
KeyHandler(
up, # key for the up direction
right, # key for the right direction
down, # key for the down direction
left, # key for the left direction
press, # key for pressing the trackball
# optional:
axis_snap=.25, # diagonal quantization accuracy
steps=8, # amount of rotational angle for one key tap
)
```

#### Custom Handler Example

Here's an example for a custom handler that scrolls up and down, holds keys
for left and right, and press is middle mouse button:

```python
from kmk.modules.pimoroni_trackball import TrackballHandler

CustomHandler(TrackballHandler):
def handle(self, keyboard, trackball, x, y, switch, state):
if x > 0:
keyboard.tap_key(KC.RIGHT)
elif x < 0:
keyboard.tap_key(KC.LEFT)

if y != 0:
AX.W.move(keyboard, y)

if switch:
keyboard.pre_process_key(KC.MB_MMB, is_pressed=state)
```

### Assigning Handlers
If you have used this thing on a mobile device, you will know it excels at cursor movement

```python

from kmk.modules.pimoroni_trackball import Trackball, TrackballMode, PointingHandler, KeyHandler, ScrollHandler, ScrollDirection

trackball = Trackball(
i2c,
mode=TrackballMode.MOUSE_MODE,
i2c,
mode=TrackballMode.MOUSE_MODE,
# optional: set rotation angle of the trackball breakout board, default is 1
angle_offset=1.6,
angle_offset=1.6,
handlers=[
# act like an encoder, input arrow keys, enter when pressed
KeyHandler(KC.UP, KC.RIGHT, KC.DOWN, KC.LEFT, KC.ENTER),
KeyHandler(KC.UP, KC.RIGHT, KC.DOWN, KC.LEFT, KC.ENTER),
# on layer 1 and above use the default pointing behavior, left click when pressed
PointingHandler(on_press=KC.MB_LMB),
PointingHandler(),
# use ScrollDirection.NATURAL (default) or REVERSE to change the scrolling direction, left click when pressed
ScrollHandler(scroll_direction=ScrollDirection.NATURAL, on_press=KC.MB_LMB)
]
Expand All @@ -49,7 +120,7 @@ KC.TB_HANDLER(1) # activate MouseHandler
```


### Backlight
## Backlight

Setup backlight color using below commands:

Expand All @@ -65,7 +136,7 @@ This module exposes one keycode `TB_MODE`, which on hold switches between `MOUSE
To choose the default mode, pass it in `Trackball` constructor.


#### Light animation
### Light animation

The trackball has a RGB LED which can be controlled with the [RGB extension](http://kmkfw.io/docs/rgb).
Example of very slowly glowing led, almost seamlessly changing colors:
Expand Down

0 comments on commit 6627207

Please sign in to comment.