Skip to content

Commit

Permalink
docs: Document split central separately for pointing
Browse files Browse the repository at this point in the history
  • Loading branch information
@caksoylar
caksoylar committed Jan 3, 2025
1 parent 7b00104 commit 6de64fc
Show file tree
Hide file tree
Showing 2 changed files with 132 additions and 46 deletions.
2 changes: 1 addition & 1 deletion docs/docs/config/pointing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Additional properties can be set on child nodes, which allows changing the setti

## Input Split

Input splits are used for [pointing devices on split peripherals](../development/hardware-integration/pointing.mdx#split).
Input splits are used for [pointing devices on split peripherals](../development/hardware-integration/pointing.mdx#listener-and-input-split-device).

### Devicetree

Expand Down
176 changes: 131 additions & 45 deletions docs/docs/development/hardware-integration/pointing.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,10 @@ The configuration details will thus vary depending on if you are adding a pointi
export const SplitTabs = (props) => (
<Tabs
groupId="part-type"
defaultValue="central"
defaultValue="unibody"
values={[
{ label: "Unibody or Split Central", value: "central" },
{ label: "Unibody", value: "unibody" },
{ label: "Split Central", value: "central" },
{ label: "Split Peripheral", value: "peripheral" },
]}
>
Expand All @@ -38,35 +39,24 @@ See the documentation on [pin control](./pinctrl.mdx) if you need to configure t
This node should always be set up in the `.overlay`/`.dts` file for the keyboard side that has the device attached to it.

<SplitTabs>
<TabItem value="central">
<TabItem value="unibody">

For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml), a node like following would be added to the `.overlay`/`.dts` file for the unibody or central part:
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml), a node like following would be added to the `.overlay`/`.dts` file for the keyboard, like `<keyboard>.overlay`:

```dts title="<central>.overlay"
&pro_micro_spi {
status = "okay";
cs-gpios = <&pro_micro 19 GPIO_ACTIVE_LOW>;
</TabItem>
<TabItem value="central">

glidepoint: glidepoint@0 {
compatible = "cirque,pinnacle";
reg = <0>;
spi-max-frequency = <1000000>;
status = "okay";
dr-gpios = <&pro_micro 5 (GPIO_ACTIVE_HIGH)>;
sensitivity = "4x";
sleep;
no-taps;
};
};
```
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml) on a central part, a node like following would be added to the `.overlay`/`.dts` file for the central part of the keyboard, like `<central>.overlay`:

</TabItem>
<TabItem value="peripheral">

For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml), a node like following would be added to the `.overlay`/`.dts` file for the peripheral part:
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml) on one of the peripheral parts, a node like following would be added to the `.overlay`/`.dts` file for that peripheral part, like `<peripheral>.overlay`:

```dts title="<peripheral>.overlay"
</TabItem>
</SplitTabs>

```dts
&pro_micro_spi {
status = "okay";
cs-gpios = <&pro_micro 19 GPIO_ACTIVE_LOW>;
Expand All @@ -85,28 +75,82 @@ For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr
};
```

</TabItem>
</SplitTabs>

The specifics of the properties required to set for a given driver will vary; always consult the devicetree bindings file for the specific driver to see what properties can be set.

## Listener
## Listener and Input Split Device

Every input device needs an associated listener added that listens for events from the device and processes them before sending the events to the host using a HID mouse report.
See [input listener configuration](../../config/pointing.md#input-listener) for the full details.

If your pointing device is on a split peripheral part, you also need to define and use an input split device on all keyboard parts.

<SplitTabs>
<TabItem value="central">
<TabItem value="unibody">

For example, to add a listener for the above device, add to your `.overlay`/`.dts` file for the unibody or central part a node like the following:
To add a listener for the above device, add to your `.overlay`/`.dts` file for the keyboard a node like the following:

```dts title="<central>.overlay"
```dts title="<keyboard>.overlay"
/ {
glidepoint_listener {
compatible = "zmk,input-listener";
device = <&glidepoint>;
};
};
```

</TabItem>
<TabItem value="central">

### Shared Configuration

The input listener that is used by the central side is added in a shared in a common `.dtsi` file that is included into both central and peripheral `.overlay`/`.dts` files, but disabled by default.
This is so that keymaps (which are included for both central and peripheral builds) can reference the listener to add input processors without failing with an undefined reference error.

```dts title="<keyboard>-pointing.dtsi"
/ {
glidepoint_listener: glidepoint_listener {
compatible = "zmk,input-listener";
status = "disabled";
};
};
```

Users will use this node reference `&glidepoint_listener` in their keymaps if they want to add [input processors](#input-processors) to it.

### Central Configuration

In the central, we do the following:

- Include the shared .dtsi file.
- Enable the input listener that is created in our shared file.
- Assign the pointing device node to the listener.

```dts title="<central>.overlay"
// Pull in the shared configuration
#include "<keyboard>-pointing.dtsi"
// Node added in Input Device section above
&pro_micro_spi {
/* ... */
glidepoint: glidepoint@0 {
/* ... */
};
};
// Overrides for the input listener node
&glidepoint_listener {
status = "okay";
device = <&glidepoint>;
};
```

### Peripheral Configuration

Finally, we include the shared file in all peripherals so that the listener node reference is available like mentioned above:

```dts title="<peripheral>.overlay"
#include "<keyboard>-pointing.dtsi"
```

</TabItem>
Expand All @@ -119,7 +163,8 @@ To avoid duplicating work, this node can be defined in a common `.dtsi` file tha

All split pointers are identified using a unique integer value, which is specified using the `reg` property and in the `@#` suffix for the node. If adding multiple peripheral pointers, be sure that each is given a unique identifier.

Second, the input listener for the central side is added here, but disabled, so that keymaps (which are included for central and peripheral builds) can reference the listener to add input processors without issue.
Second, the input listener that is used by the central side is added here but disabled by default. This is so that keymaps (which are included for both central and peripheral builds) can reference the listener to add input processors without failing with an undefined reference error.

:::note

Input splits need to be nested under a parent node that properly sets `#address-cells = <1>` and `#size-cells = <0>`. These settings are what allow us to use a single integer number for the `reg` value.
Expand All @@ -146,6 +191,8 @@ Input splits need to be nested under a parent node that properly sets `#address-
};
```

Users will use this node reference `&glidepoint_listener` in their keymaps if they want to add [input processors](#input-processors) to it.

### Peripheral Configuration

In the peripheral .overlay/.dts file, we do the following:
Expand All @@ -159,26 +206,18 @@ In the peripheral .overlay/.dts file, we do the following:
// Node added in Input Device section above
&pro_micro_spi {
status = "okay";
cs-gpios = <&pro_micro 19 GPIO_ACTIVE_LOW>;
/* ... */
glidepoint: glidepoint@0 {
compatible = "cirque,pinnacle";
reg = <0>;
spi-max-frequency = <1000000>;
status = "okay";
dr-gpios = <&pro_micro 5 (GPIO_ACTIVE_HIGH)>;
sensitivity = "4x";
sleep;
no-taps;
/* ... */
};
};
// Overrides for the input-split child node
&glidepoint_split {
device = <&glidepoint>;
// Optional
input-processors = <&zip_xy_transform (INPUT_TRANSFORM_XY_SWAP | INPUT_TRANSFORM_X_INVERT | INPUT_TRANSFORM_Y_INVERT)>;
};
```
Expand All @@ -188,7 +227,7 @@ The [`input-processors` property](#input-processors) on the input split is optio
### Central Configuration

On the central, the input split acts as an input device, receiving events from the peripheral and raising them locally.
Here we first include the shared file, and then enable the [input listener](#listener) that is created, but disabled, in our shared file:
Here we first include the shared file, and then enable the input listener that is created, but disabled, in our shared file:

```dts title="<central>.overlay"
#include "<keyboard>-pointing.dtsi"
Expand Down Expand Up @@ -223,17 +262,64 @@ As an example, you could enhance the listener defined in the previous section wi
## Configuration Setting

If your keyboard hardware includes a pointing device by default, you can enable the [`ZMK_POINTING` config](../../config/pointing.md#general) in your keyboard definition.
To do that, add the following to your [`Kconfig.defconfig` file](new-shield.mdx#kconfigdefconfig):
You can do that in your [`Kconfig.defconfig` file](new-shield.mdx#kconfigdefconfig), where you can also enable the config for the communication protocol used by the pointing device:

<SplitTabs>
<TabItem value="unibody">

```kconfig title="Kconfig.defconfig"
if SHIELD_MY_KEYBOARD
# Other keyboard settings
config ZMK_POINTING
default y
config SPI
default y
endif
```

</TabItem>
<TabItem value="central">

```kconfig title="Kconfig.defconfig"
if SHIELD_MY_KEYBOARD_<CENTRAL>
# Other keyboard settings
config ZMK_POINTING
default y
config SPI
default y
endif
```

</TabItem>
<TabItem value="peripheral">

```kconfig title="Kconfig.defconfig"
if SHIELD_MY_KEYBOARD_<CENTRAL> || SHIELD_MY_KEYBOARD_<PERIPHERAL>
# Other keyboard settings
config ZMK_POINTING
default y
endif
if SHIELD_MY_KEYBOARD_<PERIPHERAL>
config SPI
default y
endif
```

If the hardware is optional, users should set `CONFIG_ZMK_POINTING=y` manually in their [user configuration file](new-shield.mdx#user-configuration-files).
</TabItem>
</SplitTabs>

If the hardware is optional, users should set `CONFIG_ZMK_POINTING=y` manually in their [user configuration file](new-shield.mdx#user-configuration-files), along with the config for the protocol.

0 comments on commit 6de64fc

Please sign in to comment.