New Keyboard Shield
Before reading this section, it is vital that you read through our clean room policy.
Overview
This guide will walk through the steps necessary to add ZMK support for a keyboard that uses an add-on MCU board (e.g. Pro Micro compatible) to provide the microprocessor.
The high level steps are:
- From a template, create a new Zephyr module housed in a git repository containing one or more custom shields.
- Create a new shield directory.
- Add the base Kconfig files.
- Add the shield overlay file to define the KSCAN driver for detecting key press/release.
- Add the matrix transform for mapping KSCAN row/column values to key positions in the keymap.
- Add a physical layout definition to select the matrix transform and KSCAN instance.
- Add a default keymap, which users can override in their own configs as needed.
- Add a
<my_shield>.zmk.yml
metadata file to document the high level details of your shield, and the features it supports. - Update the
build.yaml
file from the repository template to have some sample builds of the firmware to test. - Add support for features such as encoders, OLED displays, or RGB underglow.
It may be helpful to review the upstream shields documentation to get a proper understanding of the underlying system before continuing.
ZMK support for split keyboards requires a few more files than single boards to ensure proper connectivity between the central and peripheral units. Check the following guides thoroughly to ensure that all the files are in place.
New Zephyr Module Repository
The first step to creating the shield is to create a new Zephyr module repository from a template.
This guide assumes you already have a configured GitHub account. If you don't yet have one, go ahead and sign up before continuing.
Follow these steps to create your new repository:
- Visit https://github.com/zmkfirmware/unified-zmk-config-template
- Click the green "Use this template" button
- In the drop down that opens, click "Use this template".
- In the following screen, provide the following information:
- A repository name, e.g.
my-shield-module
. - A brief description, e.g.
ZMK Support For MyShield Keyboard
. - Select Public or Private, depending on your preference.
- A repository name, e.g.
- Click the green "Create repository" button
The repository is a combination of the directories and files required of a ZMK config, and those required of a shield module. To create a shield module, the following components are needed:
- The
boards/shields
directory, where the keyboard's files will go - The
zephyr/module.yml
file, which identifies and describes the module. See the Zephyr documentation for details on customising this file. For the purposes of creating a shield module, the default found in the template can be left untouched.
Neither of these should be moved out of their parent directory. The other files and directories such as config
are not necessary for the purposes of a shield module, but rather intended to be used for user configuration and testing.
New Shield Directory
Shields in Zephyr module "board root" go into the boards/shields/
directory; that means the new shield directory in your module repository should be:
mkdir boards/shields/<keyboard_name>
Base Kconfig Files
You can check out the shields
folder in the ZMK repo that houses the in-tree supported shields in order to copy and modify as a starting point.
There are two required Kconfig files that need to be created for your new keyboard
shield to get it picked up for ZMK, Kconfig.shield
and Kconfig.defconfig
.
Kconfig.shield
The Kconfig.shield
file defines any additional Kconfig settings that may be relevant when using this keyboard. For most keyboards, there is just one additional configuration value for the shield itself.
config SHIELD_MY_BOARD
def_bool $(shields_list_contains,my_board)
Kconfig uses only commas for delimiters, and keeps all whitespaces in the function call. Therefore do not add a whitespace after the comma when configuring your shield as this would be treated as my_board
(with a leading whitespace) and will cause issues.
This will make sure that a new configuration value named SHIELD_MY_BOARD
is set to true whenever my_board
is used as the shield name, either as the SHIELD
variable in a local build or in your build.yaml
file when using Github Actions. Note that this configuration value will be used in Kconfig.defconfig
to set other properties about your shield, so make sure that they match.
For split boards, you will need to add configurations for the left and right sides. For example, if your split halves are named my_board_left
and my_board_right
, it would look like this:
config SHIELD_MY_BOARD_LEFT
def_bool $(shields_list_contains,my_board_left)
config SHIELD_MY_BOARD_RIGHT
def_bool $(shields_list_contains,my_board_right)
Kconfig.defconfig
The Kconfig.defconfig
file is where overrides for various configuration settings
that make sense to have different defaults when this shield is used. One main item
that usually has a new default value set here is the ZMK_KEYBOARD_NAME
value,
which controls the display name of the device over USB and BLE.
The updated new default values should always be wrapped inside a conditional on the shield config name defined in the Kconfig.shield
file. Here's the simplest example file.
The keyboard name must be less than or equal to 16 characters in length, otherwise the bluetooth advertising might fail and you will not be able to find your keyboard from your device.
if SHIELD_MY_BOARD
config ZMK_KEYBOARD_NAME
default "My Board"
endif
For split keyboards, Kconfig.defconfig
needs to specify a few more options.
Which side is central (usually the left) is determined via the configuration in this file.
For that side, the keyboard name is assigned and the central config is set.
The peripheral side is typically not assigned a name since only the central will be advertising for connections to other devices.
Finally, the split config needs to be set for both sides:
if SHIELD_MY_BOARD_LEFT
config ZMK_KEYBOARD_NAME
default "My Board"
config ZMK_SPLIT_ROLE_CENTRAL
default y
endif
if SHIELD_MY_BOARD_LEFT || SHIELD_MY_BOARD_RIGHT
config ZMK_SPLIT
default y
endif
Shield Overlays
- Arduino Uno Rev3 Shields
- BlackPill Shields
- Pro Micro Shields
- Seeed XIAO Shields
The GPIO pin references for the Uno format are a bit odd. The &arduino_header
label is used, but the numbering
starts at the A0
pin and increments as you go counter clockwise around the board. That means the D6
pin
can be referenced by &arduino_header 12
in your overlay files.
- GPIO:
&arduino_header
- I2C bus:
&arduino_i2c
- SPI bus:
&arduino_spi
- UART:
&arduino_serial
- ADC:
&arduino_adc
ZMK uses the blue color coded pin names to generate devicetree node references. For example, to refer to the pin labeled 17
in the diagram, use &blackpill 17
in the devicetree files.
- GPIO:
&blackpill
- I2C bus:
&blackpill_i2c
- SPI bus:
&blackpill_spi
- UART:
&blackpill_serial
ZMK uses the blue color coded "Arduino" pin names to generate devicetree node references. For example, to refer to the pin labeled 0
in the diagram, use &pro_micro 0
in the devicetree files.
- GPIO:
&pro_micro
- I2C bus:
&pro_micro_i2c
- SPI bus:
&pro_micro_spi
- UART:
&pro_micro_serial
ZMK uses the "D"-prefixed, green color coded pin names, e.g. D2
, to generate devicetree node references. For example, to refer to the pin labeled D0
in the diagram, use &xiao_d 0
in the devicetree files.
- GPIO:
&xiao_d
- I2C bus:
&xiao_i2c
- SPI bus:
&xiao_spi
- UART:
&xiao_serial
To use GPIO pins that are not part of the interconnects as described above, you can use the GPIO labels that are specific to each controller type.
For instance, pins numbered PX.Y
in nRF52840-based boards can be referred to via &gpioX Y
labels.
An example is &gpio1 7
for the P1.07
pin that the nice!nano exposes in the middle of the board.
- Unibody Shields
- Split Shields
The <shield_name>.overlay
is the devicetree description of the keyboard shield that is merged with the primary board devicetree description before the build. For ZMK, this file at a minimum should include the chosen node named zmk,kscan
that references a KSCAN driver instance. For a simple 3x3 macropad matrix,
this might look something like:
/ {
chosen {
zmk,kscan = &kscan0;
};
kscan0: kscan_0 {
compatible = "zmk,kscan-gpio-matrix";
diode-direction = "col2row";
wakeup-source;
col-gpios
= <&pro_micro 15 GPIO_ACTIVE_HIGH>
, <&pro_micro 14 GPIO_ACTIVE_HIGH>
, <&pro_micro 16 GPIO_ACTIVE_HIGH>
;
row-gpios
= <&pro_micro 19 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
, <&pro_micro 20 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
, <&pro_micro 21 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
;
};
};
See the Keyboard Scan configuration documentation for details on configuring the KSCAN driver.
.dtsi files and Shield Overlays (Split Shields)
Unlike unibody keyboards, split keyboards have a core .dtsi file with shield overlays for each half of the keyboard.
It is preferred to define only the col-gpios
or row-gpios
in the common shield .dtsi, depending on the diode-direction
value.
For col2row
directed boards like the iris, the shared .dtsi file may look like this:
#include <dt-bindings/zmk/matrix_transform.h>
/ {
chosen {
zmk,kscan = &kscan0;
zmk,matrix-transform = &default_transform;
};
default_transform: keymap_transform_0 {
compatible = "zmk,matrix-transform";
columns = <16>;
rows = <4>;
// | SW6 | SW5 | SW4 | SW3 | SW2 | SW1 | | SW1 | SW2 | SW3 | SW4 | SW5 | SW6 |
// | SW12 | SW11 | SW10 | SW9 | SW8 | SW7 | | SW7 | SW8 | SW9 | SW10 | SW11 | SW12 |
// | SW18 | SW17 | SW16 | SW15 | SW14 | SW13 | | SW13 | SW14 | SW15 | SW16 | SW17 | SW18 |
// | SW24 | SW23 | SW22 | SW21 | SW20 | SW19 | SW25 | | SW25 | SW19 | SW20 | SW21 | SW22 | SW23 | SW24 |
// | SW29 | SW28 | SW27 | SW26 | | SW26 | SW27 | SW28 | SW29 |
map = <
RC(0,0) RC(0,1) RC(0,2) RC(0,3) RC(0,4) RC(0,5) RC(0,6) RC(0,7) RC(0,8) RC(0,9) RC(0,10) RC(0,11)
RC(1,0) RC(1,1) RC(1,2) RC(1,3) RC(1,4) RC(1,5) RC(1,6) RC(1,7) RC(1,8) RC(1,9) RC(1,10) RC(1,11)
RC(2,0) RC(2,1) RC(2,2) RC(2,3) RC(2,4) RC(2,5) RC(2,6) RC(2,7) RC(2,8) RC(2,9) RC(2,10) RC(2,11)
RC(3,0) RC(3,1) RC(3,2) RC(3,3) RC(3,4) RC(3,5) RC(4,2) RC(4,9) RC(3,6) RC(3,7) RC(3,8) RC(3,9) RC(3,10) RC(3,11)
RC(4,3) RC(4,4) RC(4,5) RC(4,6) RC(4,7) RC(4,8)
>;
};
kscan0: kscan {
compatible = "zmk,kscan-gpio-matrix";
diode-direction = "col2row";
wakeup-source;
row-gpios
= <&pro_micro 6 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row A from the schematic file
, <&pro_micro 7 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row B from the schematic file
, <&pro_micro 8 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row C from the schematic file
, <&pro_micro 0 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row D from the schematic file
, <&pro_micro 4 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row E from the schematic file
;
};
};
Notice that in addition to the common row-gpios
that are declared in the kscan, the matrix transform is defined in the .dtsi.
The missing col-gpios
would be defined in your <boardname>_left.overlay
and <boardname>_right.overlay
files.
Keep in mind that the mirrored position of the GPIOs means that the col-gpios
will appear reversed when the .overlay files are compared to one another.
Furthermore, the column offset for the matrix transform should be added to the right half of the keyboard's overlay
because the keyboard's switch matrix is read from left to right, top to bottom.
This is exemplified with the iris .overlay files.
#include "iris.dtsi" // Notice that the main dtsi files are included in the overlay.
&kscan0 {
col-gpios
= <&pro_micro 19 GPIO_ACTIVE_HIGH> // col1 in the schematic
, <&pro_micro 18 GPIO_ACTIVE_HIGH> // col2 in the schematic
, <&pro_micro 15 GPIO_ACTIVE_HIGH> // col3 in the schematic
, <&pro_micro 14 GPIO_ACTIVE_HIGH> // col4 in the schematic
, <&pro_micro 16 GPIO_ACTIVE_HIGH> // col5 in the schematic
, <&pro_micro 10 GPIO_ACTIVE_HIGH> // col6 in the schematic
;
};
#include "iris.dtsi"
&default_transform { // The matrix transform for this board is 6 columns over because the left half is 6 columns wide according to the matrix.
col-offset = <6>;
};
&kscan0 {
col-gpios
= <&pro_micro 10 GPIO_ACTIVE_HIGH> // col6 in the schematic
, <&pro_micro 16 GPIO_ACTIVE_HIGH> // col5 in the schematic
, <&pro_micro 14 GPIO_ACTIVE_HIGH> // col4 in the schematic
, <&pro_micro 15 GPIO_ACTIVE_HIGH> // col3 in the schematic
, <&pro_micro 18 GPIO_ACTIVE_HIGH> // col2 in the schematic
, <&pro_micro 19 GPIO_ACTIVE_HIGH> // col1 in the schematic
;
};
See the Keyboard Scan configuration documentation for details on configuring the KSCAN driver.
.conf files (Split Shields)
While unibody boards only have one .conf file that applies configuration characteristics to the entire keyboard,
split keyboards are unique in that they contain multiple .conf files with different scopes.
For example, a split board called my_awesome_split_board
would have the following files:
my_awesome_split_board.conf
- Configuration elements affect both halvesmy_awesome_split_board_left.conf
- Configuration elements only affect left halfmy_awesome_split_board_right.conf
- Configuration elements only affect right half
In most case you'll only need to use the .conf file that affects both halves of a split board. It's used for adding features like deep-sleep or rotary encoders.
CONFIG_ZMK_SLEEP=y
The shared configuration in my_awesome_split_board.conf
is only applied when you are building with a zmk-config
folder and when it is present at config/my_awesome_split_board.conf
. If you are not using a zmk-config
folder, you will need to include the shared configuration in both my_awesome_split_board_left.conf
and my_awesome_split_board_right.conf
files.
Matrix Transform
Internally ZMK translates all row/column events into "key position" events to maintain a consistent model that works no matter what any possible GPIO matrix may look like for a certain keyboard. This is particularly helpful when:
- To reduce the used pins, an "efficient" number of rows/columns for the GPIO matrix is used, that does not match the physical layout of rows/columns of the actual key switches.
- For non rectangular keyboards with thumb clusters, non
1u
locations, etc.
A "key position" is the numeric index (zero-based) of a given key, which identifies the logical key location as perceived by the end user. All keymap mappings actually bind behaviors to key positions, not to row/column values.
The <shield_name>.overlay
must include a matrix transform that defines this mapping from row/column values to key positions.
Here is an example for the nice60, which uses an efficient 8x8 GPIO matrix, and uses a transform:
#include <dt-bindings/zmk/matrix_transform.h>
/ {
/* define kscan node with label `kscan0`... */
default_transform: keymap_transform_0 {
compatible = "zmk,matrix-transform";
columns = <8>;
rows = <8>;
// | MX1 | MX2 | MX3 | MX4 | MX5 | MX6 | MX7 | MX8 | MX9 | MX10 | MX11 | MX12 | MX13 | MX14 |
// | MX15 | MX16 | MX17 | MX18 | MX19 | MX20 | MX21 | MX22 | MX23 | MX34 | MX25 | MX26 | MX27 | MX28 |
// | MX29 | MX30 | MX31 | MX32 | MX33 | MX34 | MX35 | MX36 | MX37 | MX38 | MX39 | MX40 | MX41 |
// | MX42 | MX43 | MX44 | MX45 | MX46 | MX47 | MX48 | MX49 | MX50 | MX51 | MX52 | MX53 |
// | MX54 | MX55 | MX56 | MX57 | MX58 | MX59 | MX60 | MX61 |
map = <
RC(3,0) RC(2,0) RC(1,0) RC(0,0) RC(1,1) RC(0,1) RC(0,2) RC(1,3) RC(0,3) RC(1,4) RC(0,4) RC(0,5) RC(1,6) RC(1,7)
RC(4,0) RC(4,1) RC(3,1) RC(2,1) RC(2,2) RC(1,2) RC(2,3) RC(3,4) RC(2,4) RC(2,5) RC(1,5) RC(2,6) RC(2,7) RC(3,7)
RC(5,0) RC(5,1) RC(5,2) RC(4,2) RC(3,2) RC(4,3) RC(3,3) RC(4,4) RC(4,5) RC(3,5) RC(4,6) RC(3,6) RC(4,7)
RC(6,0) RC(6,1) RC(6,2) RC(6,3) RC(5,3) RC(6,4) RC(5,4) RC(6,5) RC(5,5) RC(6,6) RC(5,6) RC(5,7)
RC(7,0) RC(7,1) RC(7,2) RC(7,3) RC(7,5) RC(7,6) RC(6,7) RC(7,7)
>;
};
/* potentially other overlay nodes... */
};
Some important things to note:
- The
#include <dt-bindings/zmk/matrix_transform.h>
is critical. TheRC
macro is used to generate the internal storage in the matrix transform, and is actually replaced by a C preprocessor before the final devicetree is compiled into ZMK. RC(row, column)
is placed sequentially to define what row and column values that position corresponds to.- If you have a keyboard with options for
2u
keys in certain positions, ANSI vs. ISO layouts, or break away portions, define one matrix transform for each possible arrangement to be used in the physical layouts. This will allow the users to select the right layout in their keymap files.
See the matrix transform section in the Keyboard Scan configuration documentation for details and more examples of matrix transforms.
Physical Layout
The physical layout is the top level entity that aggregates all details about a certain possible layout for a keyboard: the matrix transform that defines the set of key positions and what row/column they correspond to, what kscan driver is used for that layout, etc.
For keyboards that support multiple layouts, setting a chosen
node to a defined physical layout in your keymap will allow selecting the specific layout that you've built.
A physical layout is very basic, e.g.:
/ {
default_layout: default_layout {
compatible = "zmk,physical-layout";
display-name = "Default Layout";
transform = <&default_transform>;
kscan = <&kscan0>;
};
};
When supporting multiple layouts, define the multiple layout nodes and then set a chosen
for the default:
/ {
chosen {
zmk,physical-layout = &default_layout;
...
};
default_layout: default_layout {
compatible = "zmk,physical-layout";
display-name = "Default Layout";
transform = <&default_transform>;
kscan = <&kscan0>;
};
alt_layout: alt_layout {
compatible = "zmk,physical-layout";
display-name = "Alternate Layout";
transform = <&alt_transform>;
kscan = <&alt_kscan0>;
};
};
This way, users can select a different layout by overriding the zmk,physical-layout
chosen node in their keymap file.
Some keyboards use different GPIO pins for different layouts, and need different kscan nodes created for each layout.
However, if all of your physical layouts use the same kscan
node under the hood, you can skip setting the kscan
property on each
layout and instead assign the zmk,kscan
chosen node to your single kscan instance.
Default Keymap
Each keyboard should provide a default keymap to be used when building the firmware, which can be overridden and customized by user configs. For "shield keyboards", this should be placed in the boards/shields/<shield_name>/<shield_name>.keymap
file. The keymap is configured as an additional devicetree overlay that includes the following:
- A node with
compatible = "zmk,keymap"
where each child node is a layer with abindings
array that binds each key position to a given behavior (e.g. key press, momentary layer, etc).
Here is an example simple keymap for the Kyria, with only one layer:
#include <behaviors.dtsi>
#include <dt-bindings/zmk/keys.h>
/ {
keymap {
compatible = "zmk,keymap";
default_layer {
// --------------------------------------------------------------------------------------------------------------------------------------------------------------------
// | ESC | Q | W | E | R | T | | Y | U | I | O | P | \ |
// | TAB | A | S | D | F | G | | H | J | K | L | ; | ' |
// | SHIFT | Z | X | C | V | B | CTRL+A | CTRL+C | | CTRL+V | CTRL+X | N | M | , | . | / | R CTRL |
// | GUI | DEL | RETURN | SPACE | ESCAPE | | RETURN | SPACE | TAB | BSPC | R ALT |
bindings = <
&kp ESC &kp Q &kp W &kp E &kp R &kp T &kp Y &kp U &kp I &kp O &kp P &kp BSLH
&kp TAB &kp A &kp S &kp D &kp F &kp G &kp H &kp J &kp K &kp L &kp SEMI &kp SQT
&kp LSHIFT &kp Z &kp X &kp C &kp V &kp B &kp LC(A) &kp LC(C) &kp LC(V) &kp LC(X) &kp N &kp M &kp COMMA &kp DOT &kp FSLH &kp RCTRL
&kp LGUI &kp DEL &kp RET &kp SPACE &kp ESC &kp RET &kp SPACE &kp TAB &kp BSPC &kp RALT
>;
sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN &inc_dec_kp PG_UP PG_DN>;
};
};
};
The two #include
lines at the top of the keymap are required in order to bring in the default set of behaviors to make them available to bind, and to import a set of defines for the key codes, so keymaps can use parameters like N2
or K
instead of the raw keycode numeric values.
Keymap Behaviors
For documentation on the available behaviors for use in keymaps, see the overview page for behaviors.
Metadata
ZMK makes use of an additional metadata YAML file for all boards and shields to provide high level information about the hardware to be incorporated into setup scripts/utilities, website hardware list, etc.
The naming convention for metadata files is {item_id}.zmk.yml
, where the item_id
is the board/shield identifier, including version information but excluding any optional split _left
/_right
suffix, e.g. corne.zmk.yml
or nrfmicro_11.zmk.yml
.
Here is a sample corne.zmk.yml
file from the repository:
file_format: "1"
id: corne
name: Corne
type: shield
url: https://github.com/foostan/crkbd/
requires: [pro_micro]
exposes: [i2c_oled]
features:
- keys
- display
siblings:
- corne_left
- corne_right
You should place a properly named foo.zmk.yml
file in the directory next to your other shield values, and fill it out completely and accurately. See Hardware Metadata Files for the full details.
Build File
To help you test/verify your firmware, update the build.yaml
to list your particular board/shield combinations you want built whenever changes are published to GitHub. Open build.yaml
with your editor and add a combination, e.g.:
# This file generates the GitHub Actions matrix
# For simple board + shield combinations, add them
# to the top level board and shield arrays, for more
# control, add individual board + shield combinations to
# the `include` property, e.g:
#
# board: [ "nice_nano_v2" ]
# shield: [ "corne_left", "corne_right" ]
# include:
# - board: bdn9_rev2
# - board: nice_nano_v2
# shield: reviung41
#
---
include:
- board: nice_nano_v2
shield: <my_shield>
For split keyboards, you will need to specify the halves/siblings separately, e.g.:
include:
- board: mikoto_520
shield: <my_shield>_left
- board: mikoto_520
shield: <my_shield>_right
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), overlay (.overlay), and keymap (.keymap) files.
- .conf
- .dtsi
- .overlay
- .keymap
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.
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.
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";
a-gpios = <PIN_A (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>;
b-gpios = <PIN_B (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>;
steps = <80>;
status = "disabled";
};
Here you need to replace PIN_A
and PIN_B
with the appropriate pins that your PCB utilizes for the encoder(s). See shield overlays section above on the appropriate node label and pin number to use for GPIOs.
The steps
property should corresponded to the documented pulses per rotation for the encoders used on the keyboard, typically found on the datasheet of the component. If users use different encoders when they build, the value can be overridden in their keymap.
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: sensors {
compatible = "zmk,keymap-sensors";
sensors = <&left_encoder &right_encoder>;
triggers-per-rotation = <20>;
};
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.
In addition, a default value for the number of times the sensors trigger the bound behavior per full rotation is set via the triggers-per-rotation
property. See Encoders Config for more details.
Add the following lines to your overlay file(s) to enable the encoder:
&left_encoder {
status = "okay";
};
For split keyboards, make sure to add left hand encoders to the left .overlay file and right hand encoders to the right .overlay file.
Testing
GitHub Actions
Using GitHub Actions to build your new firmware can save you from doing any local development setup, at the expense of a longer feedback loop if there are issues. To push your changes and trigger a build:
- Add all your pending changes with
git add .
- Commit your changes with
git commit -m "Initial shield"
- Push the changes to GitHub with
git push
Once pushed, click on the "Actions" tab of the repo you created in the first step, and you should see a new build running. If the build is successful, there will be a new firmware.zip
artifact shown on the summary screen you can download that will contain the new .uf2
files that can be flashed to the device.
Local Build
To build locally, be sure you've followed the development setup guide first.
Once you've fully created the new keyboard shield definition, you should be able to test with a build command like:
west build --pristine -b nice_nano_v2 -- -DSHIELD=<my_shield> -DZMK_EXTRA_MODULES=/full/path/to/your/module
# replace <my_shield> with e.g. <my_shield>_left for split keyboards, then repeat for <my_shield>_right
The above build command generates a build/zephyr/zmk.uf2
file that you can flash using the steps from the following section. See the dedicated building and flashing page for more details.
Flashing
If your board supports USB Flashing Format (UF2), copy that file onto the root of the USB mass storage device for your board. The controller should flash your built firmware and automatically restart once flashing is complete. If you need to flash an updated UF2 file with fixes, you can re-enter the bootloader by double tapping the reset button.
Alternatively, if your board supports flashing and you're not developing from within a Dockerized environment, enable Device Firmware Upgrade (DFU) mode on your board and run the following command to test your build:
west flash
Please have a look at documentation specific to building and flashing for additional information.
Further testing your keyboard shield without altering the root keymap file can be done with the use of -DZMK_CONFIG
in your west build
command,
shown here