Added user and dev encoder docs
This commit is contained in:
Kevin
parent
5b493ef334
commit
6f74e61dd3
3 changed files with 88 additions and 6 deletions
|
|
@ -3,6 +3,9 @@ id: dev-guide-new-shield
|
|||
title: New Keyboard Shield
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
## Overview
|
||||
|
||||
This guide will walk through the steps necessary to add ZMK support for a keyboard the uses a (Pro Micro compatible) addon MCU board to provide the microprocessor.
|
||||
|
|
@ -13,6 +16,7 @@ The high level steps are:
|
|||
- Add the shield overlay file to define the [KSCAN driver]() for detecting key press/release.
|
||||
- (Optional) Add the matrix transform for mapping KSCAN row/column values to sane key positions. This is needed for non-rectangular keyboards, or where the underlying row/column pin arrangement does not map one to one with logical locations on the keyboard.
|
||||
- Add a default keymap, which users can override in their own configs as needed.
|
||||
- Add support for features such as encoders, OLED displays, or RGB underglow.
|
||||
|
||||
It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing.
|
||||
|
||||
|
|
@ -195,6 +199,81 @@ Further documentation on behaviors and bindings is forthcoming, but a summary of
|
|||
- `trans` is the "transparent" behavior, useful to be place in higher layers above `mo` bindings to be sure the key release is handled by the lower layer. No binding arguments are required.
|
||||
- `mt` is the "mod-tap" behavior, and takes two binding arguments, the modifier to use if held, and the keycode to send if tapped.
|
||||
|
||||
## Adding Features
|
||||
|
||||
### Encoders
|
||||
|
||||
EC11 encoder support can be added to your board or shield by adding the appropriate lines to your board/shield's configuration (.conf), device tree (.dtsi), and overlay (.overlay) files.
|
||||
|
||||
<Tabs
|
||||
defaultValue="conf"
|
||||
values={[
|
||||
{label: '.conf', value: 'conf'},
|
||||
{label: '.dtsi', value: 'dtsi'},
|
||||
{label: '.overlay', value: 'overlay'},
|
||||
]}>
|
||||
<TabItem value="conf">
|
||||
|
||||
In your configuration file you will need to add the following lines so that the encoders can be enabled/disabled:
|
||||
|
||||
```
|
||||
# Uncomment to enable encoder
|
||||
# CONFIG_EC11=y
|
||||
# CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y
|
||||
```
|
||||
|
||||
These should be commented by default for encoders that are optional/can be swapped with switches, but can be uncommented if encoders are part of the default design.
|
||||
|
||||
:::note
|
||||
If building locally for split boards, you may need to add these lines to the specific half's configuration file as well as the combined configuration file.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value = "dtsi">
|
||||
In your device tree file you will need to add the following lines to define the encoder sensor:
|
||||
|
||||
|
||||
```
|
||||
left_encoder: encoder_left {
|
||||
compatible = "alps,ec11";
|
||||
label = "LEFT_ENCODER";
|
||||
a-gpios = <PIN_A (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>;
|
||||
b-gpios = <PIN_B (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>;
|
||||
resolution = <4>;
|
||||
};
|
||||
```
|
||||
Here you will have to replace PIN_A and PIN_B with the appropriate pins that your PCB utilizes for the encoder(s). For keyboards that use the Pro Micro or any of the Pro Micro replacements, Sparkfun's [Pro Micro Hookup Guide](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro) has a pinout diagram that can be useful to determine the right pins. Reference either the blue numbers labeled "Arduino" (digital pins) or the green numbers labeled "Analog" (analog pins). For pins that are labeled as both digital and analog, refer to your specific board's .dtsi file to determine how you should refer to that pin.
|
||||
|
||||
Add additional encoders as necessary by duplicating the above lines, replacing `left` with whatever you would like to call your encoder, and updating the pins. Note that support for peripheral (right) side sensors over BLE is still in progress.
|
||||
|
||||
Once you have defined the encoder sensors, you will have to add them to the list of sensors:
|
||||
|
||||
```
|
||||
sensors {
|
||||
compatible = "zmk,keymap-sensors";
|
||||
sensors = <&left_encoder &right_encoder>;
|
||||
};
|
||||
```
|
||||
|
||||
In this example, a left_encoder and right_encoder are both added. Additional encoders can be added with spaces separating each, and the order they are added here determines the order in which you define their behavior in your keymap.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value = "overlay">
|
||||
Add the following lines to your overlay file(s) to enable the encoder:
|
||||
|
||||
```
|
||||
&left_encoder {
|
||||
status = "okay";
|
||||
};
|
||||
```
|
||||
|
||||
:::note
|
||||
For split keyboards, make sure to add left hand encoders to the left .overlay file and right hand encoders to the right .overlay file.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Testing
|
||||
|
||||
Once you've fully created the new keyboard shield definition,
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: Encoders
|
|||
sidebar_label: Encoders
|
||||
---
|
||||
|
||||
Existing support for encoders in ZMK is focused around the EC11 rotary encoder with push button design used in the majority of current keyboard and macropad designs.
|
||||
Existing support for encoders in ZMK is focused around the five pin EC11 rotary encoder with push button design used in the majority of current keyboard and macropad designs.
|
||||
|
||||
## Enabling EC11 Encoders
|
||||
|
||||
|
|
@ -19,7 +19,7 @@ Keyboards and macropads with encoder support will typically take the two EC11 pi
|
|||
|
||||
### Rotation
|
||||
|
||||
Rotation is handled separately as a type of sensor. The behavior for this is set by defining `sensor-bindings` within a layer but below the `bindings` for the regular keys in the following format:
|
||||
Rotation is handled separately as a type of sensor. The behavior for this is set in `sensor-bindings`, which is defined in each keymap layer in the following format:
|
||||
|
||||
```
|
||||
sensor-bindings = <BINDING CW_KEY CCW_KEY>;
|
||||
|
|
@ -29,12 +29,16 @@ sensor-bindings = <BINDING CW_KEY CCW_KEY>;
|
|||
- `CW_KEY` is the keycode activated by a clockwise turn.
|
||||
- `CCW_KEY` is the keycode activated by a counter-clockwise turn.
|
||||
|
||||
Behaviors for additional encoders can be configured by adding more `BINDING CW_KEY CCW_KEY` sets immediately after the first.
|
||||
Additional encoders can be configured by adding more `BINDING CW_KEY CCW_KEY` sets immediately after the first.
|
||||
|
||||
As an example, a complete `sensor-bindings` for a Kyria would look like:
|
||||
As an example, a complete `sensor-bindings` for a Kyria with two encoders could look like:
|
||||
|
||||
```
|
||||
sensor-bindings = <&inc_dec_cp M_VOLU M_VOLD &inc_dec_kp PGUP PGDN>;
|
||||
```
|
||||
|
||||
In this example, the left encoder is configured to control volume up and down while the right encoder sends either Page Up or Page Down.
|
||||
Here, the left encoder is configured to control volume up and down while the right encoder sends either Page Up or Page Down.
|
||||
|
||||
## Adding Encoder Support
|
||||
|
||||
See the [New Keyboard Shield](docs/dev-guide-new-shield) documentation for how to add or modify additional encoders to your shield.
|
||||
|
|
|
|||
|
|
@ -25,7 +25,6 @@ module.exports = {
|
|||
],
|
||||
"Dev Guides": [
|
||||
"dev-guide-new-shield",
|
||||
"dev-guide-add-encoders",
|
||||
"dev-guide-usb-logging"],
|
||||
},
|
||||
};
|
||||
|
|
|
|||
Loading…
Reference in a new issue