diff options
| author | Nick <nick.win999@gmail.com> | 2020-09-15 14:41:59 -0500 |
|---|---|---|
| committer | Nick <nick.win999@gmail.com> | 2020-09-15 14:41:59 -0500 |
| commit | 18d21b0362c5c09902836ed4791bd13e1efd9a9a (patch) | |
| tree | 3f78a0ef43fc23e93195e1205a31f77154af7e76 /docs | |
| parent | 81bc157f539235ad032fde78b6f6cec7a16d2c39 (diff) | |
| parent | c0806d27f1d048db335ecc854eab61b59e23ea7a (diff) | |
Merge remote-tracking branch 'upstream/main' into underglow/state-persistence
Diffstat (limited to 'docs')
43 files changed, 754 insertions, 156 deletions
diff --git a/docs/docs/assets/bond-clearing/debug.log b/docs/docs/assets/bond-clearing/debug.log new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/docs/assets/bond-clearing/debug.log diff --git a/docs/docs/assets/bond-clearing/lily58.jpg b/docs/docs/assets/bond-clearing/lily58.jpg Binary files differnew file mode 100644 index 0000000..4087e7d --- /dev/null +++ b/docs/docs/assets/bond-clearing/lily58.jpg diff --git a/docs/docs/assets/env-var/env_var.png b/docs/docs/assets/env-var/env_var.png Binary files differnew file mode 100644 index 0000000..77ebbc5 --- /dev/null +++ b/docs/docs/assets/env-var/env_var.png diff --git a/docs/docs/assets/env-var/gnuarmemb.png b/docs/docs/assets/env-var/gnuarmemb.png Binary files differnew file mode 100644 index 0000000..42e38ec --- /dev/null +++ b/docs/docs/assets/env-var/gnuarmemb.png diff --git a/docs/docs/assets/env-var/new_variable.png b/docs/docs/assets/env-var/new_variable.png Binary files differnew file mode 100644 index 0000000..3cc72bd --- /dev/null +++ b/docs/docs/assets/env-var/new_variable.png diff --git a/docs/docs/assets/env-var/start_menu.png b/docs/docs/assets/env-var/start_menu.png Binary files differnew file mode 100644 index 0000000..fc7d9b5 --- /dev/null +++ b/docs/docs/assets/env-var/start_menu.png diff --git a/docs/docs/assets/env-var/zephyr_toolchain.png b/docs/docs/assets/env-var/zephyr_toolchain.png Binary files differnew file mode 100644 index 0000000..5a8ec50 --- /dev/null +++ b/docs/docs/assets/env-var/zephyr_toolchain.png diff --git a/docs/docs/assets/hold-tap/case1_2.png b/docs/docs/assets/hold-tap/case1_2.png Binary files differnew file mode 100644 index 0000000..818ac83 --- /dev/null +++ b/docs/docs/assets/hold-tap/case1_2.png diff --git a/docs/docs/assets/hold-tap/case_hold_preferred.png b/docs/docs/assets/hold-tap/case_hold_preferred.png Binary files differnew file mode 100644 index 0000000..6d7fd43 --- /dev/null +++ b/docs/docs/assets/hold-tap/case_hold_preferred.png diff --git a/docs/docs/assets/hold-tap/comparison.png b/docs/docs/assets/hold-tap/comparison.png Binary files differnew file mode 100644 index 0000000..419b204 --- /dev/null +++ b/docs/docs/assets/hold-tap/comparison.png diff --git a/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg b/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg Binary files differnew file mode 100644 index 0000000..f72d407 --- /dev/null +++ b/docs/docs/assets/pro-micro/pro-micro-pins-labelled.jpg diff --git a/docs/docs/assets/troubleshooting/filetransfer/linux.png b/docs/docs/assets/troubleshooting/filetransfer/linux.png Binary files differnew file mode 100644 index 0000000..c192dfa --- /dev/null +++ b/docs/docs/assets/troubleshooting/filetransfer/linux.png diff --git a/docs/docs/assets/troubleshooting/filetransfer/windows.png b/docs/docs/assets/troubleshooting/filetransfer/windows.png Binary files differnew file mode 100644 index 0000000..91cb8a6 --- /dev/null +++ b/docs/docs/assets/troubleshooting/filetransfer/windows.png diff --git a/docs/docs/assets/troubleshooting/keymaps/errorscreen.png b/docs/docs/assets/troubleshooting/keymaps/errorscreen.png Binary files differnew file mode 100644 index 0000000..73b5b58 --- /dev/null +++ b/docs/docs/assets/troubleshooting/keymaps/errorscreen.png diff --git a/docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png b/docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png Binary files differnew file mode 100644 index 0000000..50d2c73 --- /dev/null +++ b/docs/docs/assets/troubleshooting/keymaps/healthyEDIT.png diff --git a/docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png b/docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png Binary files differnew file mode 100644 index 0000000..3fd8dc7 --- /dev/null +++ b/docs/docs/assets/troubleshooting/keymaps/unhealthyEDIT.png diff --git a/docs/docs/assets/usb-logging/com.jpg b/docs/docs/assets/usb-logging/com.jpg Binary files differnew file mode 100644 index 0000000..e2ab9a8 --- /dev/null +++ b/docs/docs/assets/usb-logging/com.jpg diff --git a/docs/docs/assets/usb-logging/putty.jpg b/docs/docs/assets/usb-logging/putty.jpg Binary files differnew file mode 100644 index 0000000..dfbb4bd --- /dev/null +++ b/docs/docs/assets/usb-logging/putty.jpg diff --git a/docs/docs/behavior/bluetooth.md b/docs/docs/behavior/bluetooth.md new file mode 100644 index 0000000..f802a9a --- /dev/null +++ b/docs/docs/behavior/bluetooth.md @@ -0,0 +1,76 @@ +--- +title: Bluetooth Behavior +sidebar_label: Bluetooth +--- + +## Summary + +The bluetooth behavior allows management of various settings and states related to the bluetooth connection(s) +between the keyboard and the host. By default, ZMK supports five "profiles" for selecting which bonded host +computer/laptop/keyboard should receive the keyboard input; many of the commands here operation on those profiles. + +## Bluetooth Command Defines + +Bluetooth command defines are provided through the [`dt-bindings/zmk/bt.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/bt.h) header, +which is added at the top of the keymap file: + +``` +#include <dt-bindings/zmk/bt.h> +``` + +This will allow you to reference the actions defined in this header such as `BT_CLR_CMD`. + +Here is a table describing the command for each define: + +| Define | Action | +| ------------ | ---------------------------------------------------------------------------------------------- | +| `BT_CLR_CMD` | Clear bond information between the keyboard and host for the selected profile [^1] | +| `BT_NXT_CMD` | Switch to the next profile, cycling through to the first one when the end is reached. | +| `BT_PRV_CMD` | Switch to the previous profile, cycling through to the last one when the beginning is reached. | +| `BT_SEL_CMD` | Select the 0-indexed profile by number. | + +Because at least one bluetooth commands takes an additional parameter, it is recommended to use +the following aliases in your keymap to avoid having to specify an ignored second parameter: + +| Define | Action | +| -------- | -------------------------------------------------------------------------------- | +| `BT_CLR` | Alias for `BT_CLR_CMD 0` to clear the current profile's bond to the current host | +| `BT_NXT` | Alias for `BT_NXT_CMD 0` to select the next profile | +| `BT_PRV` | Alias for `BT_PRV_CMD 0` to select the previous profile | +| `BT_SEL` | Alias for `BT_SEL_CMD` to select the given profile, e.g. `&bt BT_SEL 1` | + +## Bluetooth Behavior + +The bluetooth behavior completes an bluetooth action given on press. + +### Behavior Binding + +- Reference: `&bt` +- Parameter #1: The bluetooth command define, e.g. `BT_CLR_CMD` +- Parameter #2: (Reserved for future bluetooth command types) + +### Examples + +1. Behavior binding to clear the paired host for the selected profile: + + ``` + &bt BT_CLR + ``` + +1. Behavior binding to select the next profile: + + ``` + &bt BT_NXT + ``` + +1. Behavior binding to select the previous profile: + + ``` + &bt BT_NXT + ``` + +1. Behavior binding to select the 2nd profile (passed parameters are [zero based](https://en.wikipedia.org/wiki/Zero-based_numbering)): + + ``` + &bt BT_SEL 1 + ``` diff --git a/docs/docs/behavior/hold-tap.md b/docs/docs/behavior/hold-tap.md new file mode 100644 index 0000000..9f8f5fa --- /dev/null +++ b/docs/docs/behavior/hold-tap.md @@ -0,0 +1,66 @@ +--- +title: Hold-tap behavior +sidebar_label: Hold-Tap +--- + +## Summary +Hold-tap is the basis for other behaviors such as layer-tap and mod-tap. + +Simply put, the hold-tap key will output the 'hold' behavior if it's held for a while, and output the 'tap' behavior when it's tapped quickly. + + +### Hold-Tap +The `tapping_term_ms` parameter decides between a 'tap' and a 'hold'. + + + +By default, the hold-tap is configured to also select the 'hold' functionality if another key is tapped while it's active: + + + +We call this the 'hold-preferred' flavor of hold-taps. While this flavor may work very well for a ctrl/escape key, it's not very well suited for home-row mods or layer-taps. That's why there are two more flavors to choose from: 'tap-preferred' and 'balanced'. + + + +### Basic usage +For basic usage, please see [mod-tap](./mod-tap.md) and [layer-tap](./layers.md) pages. + + +### Advanced Configuration +A code example which configures a mod-tap setting that works with homerow mods: + +``` +#include <behaviors.dtsi> +#include <dt-bindings/zmk/keys.h> + +/ { + behaviors { + hm: homerow_mods { + compatible = "zmk,behavior-hold-tap"; + label = "HOMEROW_MODS"; + #binding-cells = <2>; + tapping_term_ms = <175>; + flavor = "balanced"; + bindings = <&kp>, <&kp>; + }; + }; + + keymap { + compatible = "zmk,keymap"; + + default_layer { + bindings = < + &hm LCTL A &hm LGUI S &hm LALT D &hm LSFT F + >; + }; + }; +}; + +``` + +If this config does not work for you, try the flavor "tap-preferred" and a short tapping_term_ms such as 120ms. + +If you want to use a tap-hold with a keycode from a different code page, you have to define another behavior with another "bindings" parameter.For example, if you want to use SHIFT and volume up, define the bindings like `bindings = <&kp>, <&cp>;`. Only single-argument behaviors are supported at the moment. + +#### Comparison to QMK +The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting in QMK. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`.
\ No newline at end of file diff --git a/docs/docs/behavior/key-press.md b/docs/docs/behavior/key-press.md index 1ae7e31..d427f9d 100644 --- a/docs/docs/behavior/key-press.md +++ b/docs/docs/behavior/key-press.md @@ -1,5 +1,6 @@ --- -title: Key Presses +title: Key Press Behaviors +sidebar_label: Key Press --- ## Summary @@ -7,7 +8,7 @@ title: Key Presses The most basic of behaviors, is the ability to send certain keycode presses and releases in response to activating a certain key. -For reference on keycode values, see the [USB HID Usage Tables](https://www.usb.org/document-library/hid-usage-tables-12). +For reference on keycode values, see pages 83-89 of the [USB HID Usage Tables](https://www.usb.org/document-library/hid-usage-tables-12). ## Keycode Defines @@ -26,6 +27,11 @@ There is an [open issue](https://github.com/zmkfirmware/zmk/issues/21) to provid complete set of defines for the full keypad and consumer usage pages in the future for ZMK. ::: +### Improperly defined keymap - `dtlib.DTError: <board>.dts.pre.tmp:<line number>` + +When compiling firmware from a keymap, it may be common to encounter an error in the form of a`dtlib.DTError: <board>.dts.pre.tmp:<line number>`. +For instructions to resolve such an error, click [here](../troubleshooting###Improperly-defined-keymap) + ## Keypad Key Press The "keypad key press" behavior sends standard keypad keycodes on press/release. @@ -58,4 +64,4 @@ Example: ``` &cp M_PREV -``` +```
\ No newline at end of file diff --git a/docs/docs/behavior/layers.md b/docs/docs/behavior/layers.md index 3e520ca..c769388 100644 --- a/docs/docs/behavior/layers.md +++ b/docs/docs/behavior/layers.md @@ -1,5 +1,6 @@ --- -title: Layers +title: Layer Behaviors +sidebar_label: Layers --- ## Summary @@ -25,7 +26,7 @@ This allows you to use those defines, e.g. `LOWER` later in your keymap. ## Momentary Layer -The "momentary layer" behavior allows you to enable a layer while a certain key is pressed. Immediately upon +The "momentary layer" behavior enables a layer while a certain key is pressed. Immediately upon activation of the key, the layer is enabled, and immediately open release of the key, the layer is disabled again. @@ -40,9 +41,25 @@ Example: &mo LOWER ``` +## Layer-tap + +The "layer-tap" behavior enables a layer when a key is held, and output another key when the key is only tapped for a short time. For more information on the inner workings of layer-tap, see [hold-tap](./hold-tap.md). + +### Behavior Binding +- Reference: `<` +- Parameter: The layer number to enable when held, e.g. `1` +- Parameter: The keycode to send when tapped, e.g. `A` + +Example: + +``` +< LOWER SPC +``` + + ## Toggle Layer -The "toggle layer" behavior allows you to enable a layer until the layer is manually disabled. +The "toggle layer" behavior enables a layer until the layer is manually disabled. ### Behavior Binding @@ -56,12 +73,13 @@ Example: ``` "Toggle layer" for a : + ``` #define DEFAULT 0 #define NAVI 1 #define NONE 0 - + / { keymap { compatible = "zmk,keymap"; @@ -89,4 +107,4 @@ Example: }; ``` -It is possible to use "toggle layer" to have keys that raise and lower the layers as well.
\ No newline at end of file +It is possible to use "toggle layer" to have keys that raise and lower the layers as well. diff --git a/docs/docs/behavior/lighting.md b/docs/docs/behavior/lighting.md index 432960e..2d4f532 100644 --- a/docs/docs/behavior/lighting.md +++ b/docs/docs/behavior/lighting.md @@ -1,15 +1,16 @@ --- -title: Lighting +title: Lighting Behavior +sidebar_label: Lighting --- ## Summary -Lighting is often used for either aesthetics or for the practical purposes of lighting up keys in the dark. +Lighting is often used for either aesthetics or for the practical purposes of lighting up keys in the dark. Currently ZMK supports RGB underglow, which can be changed and configured using its behavior. ## RGB Action Defines -RGB actions defines are provided through the [`dt-bindings/zmk/rgb.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/rgb.h) header, +RGB actions defines are provided through the [`dt-bindings/zmk/rgb.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/rgb.h) header, which is added at the top of the keymap file: ``` @@ -21,7 +22,7 @@ This will allow you to reference the actions defined in this header such as `RGB Here is a table describing the action for each define: | Define | Action | -|-----------|-----------------------------------------------------------| +| --------- | --------------------------------------------------------- | | `RGB_TOG` | Toggles the RGB feature on and off | | `RGB_HUI` | Increases the hue of the RGB feature | | `RGB_HUD` | Decreases the hue of the RGB feature | @@ -47,4 +48,4 @@ Example: ``` &rgb_ug RGB_TOG -```
\ No newline at end of file +``` diff --git a/docs/docs/behavior/misc.md b/docs/docs/behavior/misc.md index 799c91c..446ba33 100644 --- a/docs/docs/behavior/misc.md +++ b/docs/docs/behavior/misc.md @@ -1,5 +1,6 @@ --- -title: Miscellaneous +title: Miscellaneous Behaviors +sidebar_label: Miscellaneous --- ## Summary diff --git a/docs/docs/behavior/mod-tap.md b/docs/docs/behavior/mod-tap.md index cae667e..068928a 100644 --- a/docs/docs/behavior/mod-tap.md +++ b/docs/docs/behavior/mod-tap.md @@ -1,16 +1,13 @@ --- -title: Mod-Tap +title: Mod-Tap Behavior +sidebar_label: Mod-Tap --- ## Summary -The Mod-Tap behavior allows varying the effect of pressing and releasing a key position depending -on whether it is used with other simultaneous key presses at the same time. +The Mod-Tap sends a different keypress, if it's tapped or held. When you tap the key shortly, the first keycode is sent. If you hold the key for longer than 200ms, the second keycode is sent. -If pressed and released independently, the Mod-Tap behavior will send the press and release events -for the configure keycode. If pressed and held while another key is pressed and released, then -the configured modifiers will be applied to that _other_ key press, and no press will be generated -on the release of the Mod-Tap key. +If you press another key within the 200ms, the 'mod' behavior is also activated. ## Mod-Tap @@ -19,11 +16,28 @@ The Mod-Tap behavior either acts as a held modifier, or as a tapped keycode. ### Behavior Binding - Reference: `&mt` -- Parameter #1: The modifiers to be used when activating as a modifier, e.g. `MOD_LSFT` +- Parameter #1: The keycode to be sent when activating as a modifier, e.g. `LSFT` - Parameter #2: The keycode to sent when used as a tap, e.g. `A`, `B`. Example: ``` -&mt MOD_LSFT A +&mt LSFT A ``` + +### Configuration + +You can configure a different tapping term in your keymap: + +``` +&mt { + tapping_term_ms = <400>; +}; + +/ { + keymap { + ... + } +} +``` + diff --git a/docs/docs/behavior/reset.md b/docs/docs/behavior/reset.md new file mode 100644 index 0000000..8cf122b --- /dev/null +++ b/docs/docs/behavior/reset.md @@ -0,0 +1,43 @@ +--- +title: Reset Behaviors +sidebar_label: Reset +--- + +## Summary + +There are two available behaviors that can be used to trigger a reset of the keyboard. +The first is a soft reset, that will simply reset and re-run the currently flashed +firmware; the second when triggered will reset into the bootloader, allowing you to +flash a new firmware to the keyboard. + +## Reset + +The basic reset behavior will reset the keyboard and re-run the firmware flashed +to the device + +### Behavior Binding + +- Reference: `&reset` +- Parameters: None + +Example: + +``` +&reset +``` + +## Bootloader Reset + +The bootloader reset behavior will reset the keyboard and put it into bootloader mode, allowing +you to flash a new firmware. + +### Behavior Binding + +- Reference: `&bootloader` +- Parameters: None + +Example: + +``` +&bootloader +``` diff --git a/docs/docs/bond-reset.md b/docs/docs/bond-reset.md index 1d3732b..1ba79ee 100644 --- a/docs/docs/bond-reset.md +++ b/docs/docs/bond-reset.md @@ -4,8 +4,8 @@ title: Reset BLE Connections sidebar_label: BLE Reset --- -Known as a 'bond reset', a special key combination, that is not related to the user defined key map, which -clears all wireless connection configurations. The keys must be held for 3 to 5 seconds after the device is +Known as a 'bond reset', each keyboard has a special key combination independent of the user defined key map which will +clear all wireless connection configurations. The keys must be held for 3 to 5 seconds after the device is reset. :::warning @@ -13,15 +13,19 @@ Currently, ZMK only supports a single BLE host. If you remove the keyboard from list, you will need to clear the bonds. ::: -### Split Keyboards +## Split Keyboards Split keyboards will need to be cleared on both halves. For best results try to reset them at the same time. -## Kyria +### Kyria  -## Corne +### Corne -
\ No newline at end of file + + +### Lily58 + +
\ No newline at end of file diff --git a/docs/docs/customization.md b/docs/docs/customization.md new file mode 100644 index 0000000..0bb1794 --- /dev/null +++ b/docs/docs/customization.md @@ -0,0 +1,33 @@ +--- +id: customization +title: Customizing ZMK +sidebar_label: Customizing ZMK +--- + +After verifying you can successfully flash the default firmware, you will probably want to begin customizing your keymap and other keyboard options. + +## Configuration Changes + +The setup script creates a `config/<shield>.conf` file that allows you to add additional configuration options to +control what features and options are built into your firmware. Opening that file with your text editor will allow you to see the +various config settings that can be commented/uncommented to modify how your firmware is built. + +## Keymap + +Once you have the basic user config completed, you can find the keymap file in `config/<shield>.keymap` and customize from there. +Refer to the [Keymap](/docs/feature/keymaps) documentation to learn more. + +## Publishing + +After making any changes you want, you should commit the changes and then push them to GitHub. That will trigger a new +GitHub Actions job to build your firmware which you can download once it completes. + +:::note +If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https://www.freecodecamp.org/news/learn-the-basics-of-git-in-under-10-minutes-da548267cc91/) will help you get these steps right. +::: + +## Flashing Your Changes + +For normal keyboards, follow the same flashing instructions as before to flash your updated firmware. + +For split keyboards, only the central (left) side will need to be reflashed if you are just updating your keymap. diff --git a/docs/docs/dev-boards-shields-keymaps.md b/docs/docs/dev-boards-shields-keymaps.md index cfe5252..9ed5a32 100644 --- a/docs/docs/dev-boards-shields-keymaps.md +++ b/docs/docs/dev-boards-shields-keymaps.md @@ -35,6 +35,8 @@ in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck ## Pro Micro Compatible Keyboard + + For keyboards that require a (usually Pro Micro compatible) add-on board to operate, the ZMK integration pieces are places in the _shield_ definition for that keyboard, allowing users to swap in different Pro Micro compatible boards (e.g. Proton-C, or nice!nano) and build a firmware the matches their actual diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md new file mode 100644 index 0000000..816468e --- /dev/null +++ b/docs/docs/dev-build.md @@ -0,0 +1,96 @@ +--- +id: dev-build-flash +title: Building and Flashing +sidebar_label: Building and Flashing +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const OsTabs = (props) => (<Tabs +groupId="operating-systems" +defaultValue="debian" +values={[ +{label: 'Debian/Ubuntu', value: 'debian'}, +{label: 'Raspberry OS', value: 'raspberryos'}, +{label: 'Fedora', value: 'fedora'}, +{label: 'Windows', value: 'win'}, +{label: 'macOS', value: 'mac'}, +] +}>{props.children}</Tabs>); + +## Building + +From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout: + +```sh +cd app +``` + +To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with +an onboard MCU, or one that uses an MCU board addon. + +### Keyboard (Shield) + MCU Board + +ZMK treats keyboards that take an MCU addon board as [shields](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) + +Given the following: + +- MCU Board: Proton-C +- Keyboard PCB: kyria_left +- Keymap: default + +You can build ZMK with the following: + +```sh +west build -b proton_c -- -DSHIELD=kyria_left +``` + +### Keyboard With Onboard MCU + +Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) as far as Zephyrâ„¢ is concerned. + +Given the following: + +- Keyboard: Planck (rev6) +- Keymap: default + +you can build ZMK with the following: + +```sh +west build -b planck_rev6 +``` + +### Pristine Building +When building for a new board and/or shield after having built one previously, you may need to enable the pristine build option. This option removes all existing files in the build directory before regenerating them, and can be enabled by adding either --pristine or -p to the command: + +```sh +west build -p -b proton_c -- -DSHIELD=kyria_left +``` +### Building For Split Keyboards + +:::note +For split keyboards, you will have to build and flash each side separately the first time you install ZMK. +::: + +By default, the `build` command outputs a single .uf2 file named `zmk.uf2` so building left and then right immediately after will overwrite your left firmware. In addition, you will need to pristine build each side to ensure the correct files are used. To avoid having to pristine build every time and separate the left and right build files, we recommend setting up separate build directories for each half. You can do this by using the `-d` parameter and first building left into `build/left`: + +``` +west build -d build/left -b nice_nano -- -DSHIELD=kyria_left +``` +and then building right into `build/right`: +``` +west build -d build/right -b nice_nano -- -DSHIELD=kyria_right +``` +This produces `left` and `right` subfolders under the `build` directory and two separate .uf2 files. For future work on a specific half, use the `-d` parameter again to ensure you are building into the correct location. + +## Flashing + +Once built, the previously supplied parameters will be remembered so you can run the following to flash your +board with it in bootloader mode: + +``` +west flash +``` + +For boards that have drag and drop .uf2 flashing capability, the .uf2 file to flash can be found in `build/zephyr` (or `build/left|right/zephyr` if you followed the instructions for splits) and is by default named `zmk.uf2`. diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 8556623..6140b07 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -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. @@ -60,6 +64,10 @@ endif ## Shield Overlay + + +ZMK uses the green color coded pin names to generate devicetree node references. For example, to refer to the node `D0` in the devicetree files, use `&pro_micro_d 0` or to refer to `A1`, use `&pro_micro_a 1`. + 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: @@ -195,6 +203,91 @@ 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), overlay (.overlay), and keymap (.keymap) files. + +<Tabs +defaultValue="conf" +values={[ +{label: '.conf', value: 'conf'}, +{label: '.dtsi', value: 'dtsi'}, +{label: '.overlay', value: 'overlay'}, +{label: '.keymap', value: 'keymap'}, +]}> +<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> +<TabItem value = "keymap"> +Add the following line to your keymap file to add default encoder behavior bindings: + +``` +sensor-bindings = <&inc_dec_cp M_VOLU M_VOLD>; +``` +Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](/docs/feature/encoders) and [Keymap](/docs/feature/keymaps) feature documentation for more details. + +</TabItem> +</Tabs> + ## Testing Once you've fully created the new keyboard shield definition, diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index 3bc8a0c..c5fb4b9 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -3,6 +3,9 @@ id: dev-guide-usb-logging title: USB Logging --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## Overview If you are developing ZMK on a device that does not have a built in UART for debugging and log/console output, @@ -11,7 +14,7 @@ messages to that device instead. ## Kconfig -The following KConfig values need to be set, either by copy and paste into the `app/prj.conf` file, or by running +The following KConfig values need to be set, either by copy and pasting into the `app/prj.conf` file, or by running `west build -t menuconfig` and manually enabling the various settings in that UI. ``` @@ -42,12 +45,32 @@ CONFIG_USB_UART_DTR_WAIT=n ## Viewing Logs -After flashing the updated ZMK image, the board should expose a USB CDC ACM device, that you can connect to and view the logs. +After flashing the updated ZMK image, the board should expose a USB CDC ACM device that you can connect to and view the logs. -On Linux, this should be a device like `/dev/ttyACM0` and you can connect with `minicom` or `tio` as usual, e.g.: +<Tabs +defaultValue="linux" +values={[ +{label: 'Linux', value: 'linux'}, +{label: 'Windows', value: 'win'}, +]}> +<TabItem value="linux"> +On Linux, this should be a device like `/dev/ttyACM0` and you can connect with `minicom` or `tio` as usual, e.g.: ``` sudo tio /dev/ttyACM0 ``` +</TabItem> +<TabItem value="win"> + +On Windows, you can use [PuTTY](https://www.putty.org/). Once installed, use Device Manager to figure out which COM port your controller is communicating on (listed under 'Ports (COM & LPT)') and specify that as the 'Serial line' in PuTTY. + + + + + +If you already have the Ardunio IDE installed you can also use its built-in Serial Monitor. + +</TabItem> +</Tabs> From there, you should see the various log messages from ZMK and Zephyr, depending on which systems you have set to what log levels. diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 5cceb73..1d7d703 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -52,6 +52,7 @@ sudo apt install -y \ autoconf \ automake \ build-essential \ + bzip2 \ ccache \ device-tree-compiler \ dfu-util \ @@ -91,6 +92,7 @@ sudo apt install -y \ autoconf \ automake \ build-essential \ + bzip2 \ ccache \ device-tree-compiler \ dfu-util \ @@ -130,6 +132,7 @@ sudo dnf install -y \ wget \ autoconf \ automake \ + bzip2 \ ccache \ dtc \ dfu-util \ @@ -178,9 +181,9 @@ brew install cmake ninja python3 ccache dtc git wget ## Setup -### West Build Command +### West Installation -`west` is the [Zephyrâ„¢ meta-tool](https://docs.zephyrproject.org/latest/guides/west/index.html) used to configure and build Zephyrâ„¢ applications. +`west` is the [Zephyrâ„¢ meta-tool](https://docs.zephyrproject.org/2.3.0/guides/west/index.html) used to configure and build Zephyrâ„¢ applications. West can be installed by using the `pip` python package manager. @@ -189,14 +192,31 @@ pip3 install --user -U west ``` :::danger pip user packages -If you haven't done so yet, you may need to add the Python Pip user package directory to your `PATH`, e.g.: +If you haven't done so yet, you may need to add the Python Pip user package directory to your `PATH` otherwise your computer will not be able to find the `west` command. +::: -``` +<Tabs +defaultValue="linux" +values={[ +{label: 'Linux', value: 'linux'}, +{label: 'Windows', value: 'win'}, +]}> +<TabItem value = 'linux'> +Run the following commands: + +```sh echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc source ~/.bashrc ``` -::: +</TabItem> +<TabItem value = 'win'> + +1. See the [Environment Variables](#environment-variables) section on how to get to the Environment Variables page. +3. Click "Edit..." and then "New" to add the directory where your west.exe is located. By default this should be something like `C:\Python38\Scripts`. + +</TabItem> +</Tabs> ### Toolchain Installation @@ -223,7 +243,7 @@ The installation will prompt with several questions about installation location, <TabItem value="raspberryos"> Because Raspberry OS (Raspbian) runs on the same architecture (but different ABI) as the keyboard MCUs, -the operating system's installed [cross compilers](https://docs.zephyrproject.org/latest/getting_started/toolchain_other_x_compilers.html) can be used to target the different ABI. +the operating system's installed [cross compilers](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_other_x_compilers.html) can be used to target the different ABI. First, the cross compiler should be installed: @@ -259,23 +279,20 @@ The installation will prompt with several questions about installation location, #### GNU ARM Embedded -Since the Zephyrâ„¢ SDK is not available for Windows, we recommending following the steps to install the [GNU ARM Embedded](https://docs.zephyrproject.org/latest/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded). +Since the Zephyrâ„¢ SDK is not available for Windows, we recommending following the steps to install the [GNU ARM Embedded](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded). </TabItem> <TabItem value="mac"> -#### Zephyrâ„¢ ARM SDK +#### GNU ARM Embedded -To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyrâ„¢ ARM SDK to your system: +Since the Zephyrâ„¢ SDK is not available for macOS, we recommending following the steps to install the [GNU ARM Embedded](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded). -``` -export ZSDK_VERSION=0.11.2 -wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \ - sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \ - rm "zephyr-toolchain-arm-\${ZSDK_VERSION}-setup.run" -``` +:::warning Security Controls Workaround -The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults should normally work as expected. +Please be sure to read the [additional setup instructions](https://docs.zephyrproject.org/2.3.0/getting_started/installation_mac.html#mac-gatekeeper) needed to address security controls found in macOS 10.15 Catalina and newer + +::: </TabItem> </OsTabs> @@ -341,10 +358,41 @@ pip3 install --user -r zephyr/scripts/requirements-base.txt ### Environment Variables +#### For GNU ARM Embedded on Windows + +On Windows, you will have to set two environment variables for ZMK to build properly: `ZEPHYR_TOOLCHAIN_VARIANT` and `GNUARMEMB_TOOLCHAIN_PATH`. + +<details> +<summary> Steps to Update Environment Variables </summary> + +1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it. + + + +2. Click 'Environment Variables...'. + + + +3. Click "New..." under System variables to create a new system variable. + + + +4. Set the variable name to 'ZEPHYR_TOOLCHAIN_VARIANT' and value to 'gnuarmemb'. Click OK to save. + + + +5. Create another variable with variable name 'GNUARMEMB_TOOLCHAIN_PATH' and value set to wherever you installed your toolchain. Click OK to save. + + + +</details> + +#### For Zephyr + By default, the Zephyrâ„¢ SDK will create a file named `~/.zephyrrc` with the correct environment variables to build ZMK. -We suggest two main [options](https://docs.zephyrproject.org/latest/guides/env_vars.html?highlight=zephyrrc) for how to load those settings. +We suggest two main [options](https://docs.zephyrproject.org/2.3.0/guides/env_vars.html?highlight=zephyrrc) for how to load those settings. -#### Per Shell +##### Per Shell To load the Zephyr environment properly for just one transient shell, run the following from your ZMK checkout directory: @@ -390,7 +438,7 @@ source zephyr/zephyr-env.cmd </TabItem> </OsTabs> -#### All Shells +##### All Shells To load the environment variables for your shell every time, append the existing `~/.zephyrrc` file to your shell's RC file and then start a new shell. @@ -401,7 +449,6 @@ defaultValue="bash" values={[ {label: 'bash', value: 'bash'}, {label: 'zsh', value: 'zsh'}, -{label: 'cmd.exe', value: 'cmd'}, ] }> @@ -421,61 +468,4 @@ cat ~/.zephyrrc >> ~/.zshrc </TabItem> -<TabItem value="cmd"> - -`cmd.exe` instructions coming soon! - -</TabItem> - </Tabs> - -## Build - -From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout: - -```sh -cd app -``` - -To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with -an onboard MCU, or one that uses a MCU board addon. - -### Keyboard (Shield) + MCU Board - -ZMK treats keyboards that take a MCU addon board as [shields](https://docs.zephyrproject.org/latest/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/latest/guides/porting/board_porting.html) - -Given the following: - -- MCU Board: Proton-C -- Keyboard PCB: kyria_left -- Keymap: default - -You can build ZMK with the following: - -```sh -west build -b proton_c -- -DSHIELD=kyria_left -DKEYMAP=default -``` - -### Keyboard With Onboard MCU - -Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/latest/guides/porting/board_porting.html) as far as Zephyrâ„¢ is concerned. - -Given the following: - -- Keyboard: Planck (rev6) -- Keymap: default - -you can build ZMK with the following: - -```sh -west build -b planck_rev6 -- -DKEYMAP=default -``` - -## Flashing - -Once built, the previously supplied parameters will be remember, so you can simply run the following to flash your -board, with it in bootloader mode: - -``` -west flash -``` diff --git a/docs/docs/dev-tests.md b/docs/docs/dev-tests.md new file mode 100644 index 0000000..68d4725 --- /dev/null +++ b/docs/docs/dev-tests.md @@ -0,0 +1,20 @@ +--- +id: dev-tests +title: Tests +sidebar_label: Tests +--- + +Running tests requires [native posix support](./dev-posix-board). Any folder under `/app/tests` +containing `native_posix.keymap` will be selected when running `./run-test.sh all`. + +## Creating a New Test Set +1. Copy the test set that most closely resembles the tests you will be creating. +2. Rename the newly created test set to the behavior you're testing e.g, toggle-layer +3. Modify `behavior_keymap.dtsi` to create a keymap using the behavior and related behaviors +4. Modify `test_case/native_posix.keymap` for a simulated use case +5. Modify `test_case/events.patterns` to collect relevant logs to the test + - See: [sed manual](https://www.gnu.org/software/sed/manual/sed.html) and + [tutorial](https://www.digitalocean.com/community/tutorials/the-basics-of-using-the-sed-stream-editor-to-manipulate-text-in-linux) +6. Modify `test_case/keycode_events.snapshot` for to include the expected output +7. Rename the `test_case` folder to describe the test. +8. Repeat steps 4 to 7 for every test case
\ No newline at end of file diff --git a/docs/docs/faq.md b/docs/docs/faq.md index 2ab158d..d8bbd71 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -76,7 +76,7 @@ Please note, many keyboards only have a single PCB which includes the “brainsâ ### What bootloader does ZMK use? -ZMK isn’t designed for any particular bootloader, and supports flashing different boards with different flash utilities (e.g. OpenOCD, nrfjprog, etc.). So if you have any difficulties, please let us know on [Discord](https://discord.gg/VJnx9kr)! +ZMK isn’t designed for any particular bootloader, and supports flashing different boards with different flash utilities (e.g. OpenOCD, nrfjprog, etc.). So if you have any difficulties, please let us know on [Discord](https://zmkfirmware.dev/community/discord/invite)! ### Can I contribute? @@ -84,11 +84,11 @@ Of course! Please use the developer [documentation](/docs) to get started! ### I have an idea! What should I do? -Please join us on [Discord](https://discord.gg/VJnx9kr) and discuss it with us! +Please join us on [Discord](https://zmkfirmware.dev/community/discord/invite) and discuss it with us! ### I want to add a new keyboard! What should I do? -The exact process for the management of all the possible hardware is still being finalized, but any developer looking to contribute new keyboard definitions should chat with us on [Discord](https://discord.gg/VJnx9kr) to get started. +The exact process for the management of all the possible hardware is still being finalized, but any developer looking to contribute new keyboard definitions should chat with us on [Discord](https://zmkfirmware.dev/community/discord/invite) to get started. ### Does ZMK have a Code of Conduct? diff --git a/docs/docs/feature/encoders.md b/docs/docs/feature/encoders.md index 16537ad..38ff9d3 100644 --- a/docs/docs/feature/encoders.md +++ b/docs/docs/feature/encoders.md @@ -3,4 +3,42 @@ title: Encoders sidebar_label: Encoders --- -TODO: Documentation on encoders. +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 + +To enable encoders for boards that have existing encoder support, uncomment the `EC11_CONFIG=y` and `CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y` lines in your board's .conf file in your `zmk-config/config` folder. Save and push your changes, then download and flash the new firmware. + +## Customizing EC11 Encoder Behavior + +Encoder behavior in ZMK is configured in two different locations as the push button and rotation behaviors are handled in two separate ways. + +### Push Button + +Keyboards and macropads with encoder support will typically take the two EC11 pins responsible for the push button and include them as part of the matrix for the keys. To configure what is sent by the push button, find the encoder's position in the keyboard matrix and assign it a behavior the same as you would any other key. + +### Rotation + +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>; +``` + +- `BINDING` is one of two rotation bindings that are currently defined, `&inc_dec_cp` for consumer key presses or `&inc_dec_kp` for normal key presses (see [Key Press](/docs/behavior/key-press) for the difference between the two). +- `CW_KEY` is the keycode activated by a clockwise turn. +- `CCW_KEY` is the keycode activated by a counter-clockwise turn. + +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 with two encoders could look like: + +``` +sensor-bindings = <&inc_dec_cp M_VOLU M_VOLD &inc_dec_kp PGUP PGDN>; +``` + +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. diff --git a/docs/docs/feature/keymaps.md b/docs/docs/feature/keymaps.md index 020df17..56fc2cc 100644 --- a/docs/docs/feature/keymaps.md +++ b/docs/docs/feature/keymaps.md @@ -4,7 +4,7 @@ title: Keymaps & Behaviors sidebar_label: Keymaps --- -ZMK uses an declarative approach to keymaps, instead of using C code for all keymap configuration. +ZMK uses a declarative approach to keymaps instead of using C code for all keymap configuration. Right now, ZMK uses the devicetree syntax to declare those keymaps; future work is envisioned for supporting dynamic loading of declarative keymaps, e.g. over USB Mass Storage or via a custom BLE service. @@ -55,7 +55,7 @@ in the stack _also_ get the event. ## Behavior Bindings Binding a behavior at a certain key position may include up to two extra parameters that are used to -alter the behavior when that specific key position is activated/deactived. For example, when binding +alter the behavior when that specific key position is activated/deactivated. For example, when binding the "key press" (`kp`) behavior at a certain key position, you must specific _which_ keycode should be used for that key position. @@ -80,7 +80,7 @@ A keymap file is composed of several sections, that together make up a valid dev ### Includes -THe devicetree files are actually preprocessed before being finally leveraged by Zephyr. This allows using standard C defines to create meaningful placeholders +The devicetree files are actually preprocessed before being finally leveraged by Zephyr. This allows using standard C defines to create meaningful placeholders for what would otherwise be cryptic integer keycodes, etc. This also allows bringing in _other_ devicetree nodes from separate files. The top two lines of most keymaps should include: diff --git a/docs/docs/hardware.md b/docs/docs/hardware.md index 9e6a956..299d1f5 100644 --- a/docs/docs/hardware.md +++ b/docs/docs/hardware.md @@ -11,7 +11,7 @@ have had their hardware details codified in boards/shields for ZMK. ::: -Being built on a solid technical foundation of the Zephyrâ„¢ RTOS, it's possible to make ZMK support a wide diversity of hardware targets. +With the solid technical foundation of Zephyrâ„¢ RTOS, ZMK can support a wide diversity of hardware targets. That being said, there are currently only a few specific [boards](/docs/faq#what-is-a-board)/[shields](/docs/faq#what-is-a-shield) that have been written and tested by the ZMK contributors. ## Boards diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 514c76e..8c1c043 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -5,33 +5,38 @@ sidebar_label: Introduction --- ZMK Firmware is an open source (MIT) keyboard -firmware built on the [Zephyrâ„¢ Project](https://zephyrproject.com/) RTOS. +firmware built on the [Zephyrâ„¢ Project](https://zephyrproject.org/) Real Time Operating System (RTOS). -The goal is to provider a powerful, featureful keyboard firmware that is free +The goal is to provide a powerful, featureful keyboard firmware that is free of licensing issues that prevent upstream BLE support as a first-class feature. ## Features -At this point, ZMK is _missing_ more features than it has. Currently, the mostly working bits +At this point, ZMK is still missing many features. Currently, the working bits include: -- HID Over GATT (HOG) - This is the official term for BLE HID devices -- Keymaps and layers with basic keycodes -- Some initial work on one "behavior", Mod-Tap -- Basic HID over USB -- Basic consumer (media) keycodes. -- Basic OLED display logic -- Basic Split support -- Encoders +- Wireless connectivity via BLE HID Over GATT (HOG) +- USB connectivity +- Low active power usage +- Split keyboard support +- [Keymaps and layers](behavior/layers) +- [Hold-tap](behavior/hold-tap) (which includes [mod-tap](behavior/mod-tap), [layer-tap](behavior/layers)) +- [Basic HID over USB](behavior/key-press) +- [Basic consumer (media) keycodes](behavior/key-press#consumer-key-press) +- [Encoders](feature/encoders) +- Basic [OLED display support](feature/displays) +- [RGB Underglow](feature/underglow) ## Missing Features -- One Shot -- Layer Tap -- Complete split support +- One Shot Keys +- Combo keys +- Macros +- Complete split support (encoders and RGB are not supported on the 'peripheral' side) - Battery reporting -- Low power mode +- Low power sleep states +- Low power mode (to toggle LEDs and screen off) - Shell over BLE ## Code Of Conduct diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md new file mode 100644 index 0000000..deb89b6 --- /dev/null +++ b/docs/docs/troubleshooting.md @@ -0,0 +1,61 @@ +--- +id: troubleshooting +title: Troubleshooting +sidebar_title: Troubleshooting +--- +### Summary + +The following page provides suggestions for common errors that may occur during firmware compilation. If the information provided is insufficient to resolve the issue, feel free to seek out help from the [ZMK Discord](https://zmkfirmware.dev/community/discord/invite). + +### File Transfer Error + +Variations of the warnings shown below occur when flashing the `<firmware>.uf2` onto the microcontroller. This is because the microcontroller resets itself before the OS receives confirmation that the file transfer is complete. Errors like this are normal and can generally be ignored. Verification of a functional board can be done by attempting to pair your newly flashed keyboard to your computer via Bluetooth or plugging in a USB cable if `ZMK_USB` is enabled in your Kconfig.defconfig. + +|  | +| :-------------------------------------------------------------------------------: | +| An example of the file transfer error on Windows 10 | + +|  | +| :-------------------------------------------------------------------------------: | +| An example of the file transfer error on Linux | + + +### CMake Error + +``` +CMake Warning at C:/zmk/zephyr/subsys/usb/CMakeLists.txt:28 (message): + CONFIG_USB_DEVICE_VID has default value 0x2FE3. + + This value is only for testing and MUST be configured for USB products. + + +CMake Warning at C:/zmk/zephyr/subsys/usb/CMakeLists.txt:34 (message): + CONFIG_USB_DEVICE_PID has default value 0x100. + + This value is only for testing and MUST be configured for USB products. +``` + +CMake Warnings shown above during `west build` are normal occurrences. They should not negatively affect the firmware's ability to function as normal. + +On the other hand, an error along the lines of `CMake Error at (zmk directory)/zephyr/cmake/generic_toolchain.cmake:64 (include): include could not find load file:` during firmware compilation indicates that the Zephyr Environment Variables are not properly defined. +For more information, click [here](../docs/dev-setup#environment-variables). + + +### dtlib.DTError + +An error along the lines of `dtlib.DTError: <board>.dts.pre.tmp:<line number>` during firmware compilation indicates an issue within the `<shield>.keymap` file. +This can be verified by checking the file in question, found in `mkdir/app/build`. + +|  | +| :-------------------------------------------------------------------------------: | +| An example of the dtlib.DTError when compiling an iris with the nice!nano while the keymap is not properly defined | + +After opening the `<board>.dts.pre.tmp:<line number>` and scrolling down to the referenced line, one can locate errors within their shield's keymap by checking if the referenced keycodes were properly converted into the correct [USB HID Usage ID](https://www.usb.org/document-library/hid-usage-tables-12). + +|  | +| :-------------------------------------------------------------------------------: | +| An incorrectly defined keymap unable to compile. As shown in red, `&kp SPAC` is not a valid reference to the [USB HID Usage ID](https://www.usb.org/document-library/hid-usage-tables-12) used for "Keyboard Spacebar" | + +|  | +| :-------------------------------------------------------------------------------: | +| A properly defined keymap with successful compilation. As shown in red, the corrected keycode (`&kp SPC`) references the proper Usage ID defined in the [USB HID Usage Tables](https://www.usb.org/document-library/hid-usage-tables-12)| diff --git a/docs/docs/user-setup.md b/docs/docs/user-setup.md index be230d2..2aade82 100644 --- a/docs/docs/user-setup.md +++ b/docs/docs/user-setup.md @@ -11,8 +11,7 @@ Unlike other keyboard firmwares, ZMK Firmware has been built from the ground up their own keyboard configurations, including keymaps, specific hardware details, etc. all outside of the core ZMK Firmware source repository. -In addition to this, most users do not need to install any complicated toolchains or tools to build ZMK, -instead using GitHub Actions to automatically build the user's configured firmware for them. +In addition to this, most users will not need to install any complicated toolchains or tools to build ZMK. GitHub Actions is used instead to automatically build the user's configured firmware for them. ## Summary @@ -170,7 +169,7 @@ a link to download the `firmware` upload: Once downloaded, extract the zip and you can verify it should contain one or more `uf2` files, which will be copied to your keyboard. -### Installing UF2 Files +### Flashing UF2 Files To flash the firmware, first put your board into bootloader mode by double clicking the reset button (either on the MCU board itself, or the one that is part of your keyboard). The controller should appear in your OS as a new USB storage device. @@ -178,24 +177,10 @@ or the one that is part of your keyboard). The controller should appear in your Once this happens, copy the correct UF2 file (e.g. left or right if working on a split), and paste it onto the root of that USB mass storage device. Once the flash is complete, the controller should automatically restart, and load your newfly flashed firmware. -## Customization +## Wirelessly Connecting Your Keyboard -### Configuration Changes +Connecting your keyboard wirelessly is the same as adding other Bluetooth devides: press the reset button and scan for devices. However, pairing and bonding is still currently being worked on to increase relability and ease of use. In addition, users have in general reported that Bluetooth pairing with computers tends to be quite finnicky. Try out the connection with your tablet or phone first, as those devices seem to work much more consistently. See [BLE Reset](./bond-reset.md) for help on resetting your MCUs if you're experiencing connection issues. -The setup script creates a `config/<shield>.conf` file that allows you to add additional configuration options to -control what features and options are built into your firmware. Opening that file with your text editor you should see -various config settings that can be commented/uncommented to modify how your firmware is built. +### Connecting Split Keyboard Halves -### Keymap - -Once you have the basic user config completed, you can find the file in `config/<shield>.keymap` and customize from there. -Refer to the [Keymap](/docs/feature/keymaps) documentation to learn more. - -### Publishing - -After making any changes you want, you should commit the changes and then push them to GitHub. That will trigger a new -GitHub Actions job to build your firmware which you can download once it completes. - -:::note -If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https://www.freecodecamp.org/news/learn-the-basics-of-git-in-under-10-minutes-da548267cc91/) will help you get these steps right. -::: +For split keyboards, after flashing each half individually you can connect them together by resetting them at the same time. Within a few seconds of resetting, both halves should automatically connect to each other. diff --git a/docs/sidebars.js b/docs/sidebars.js index 8c7c97f..ace7fa1 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,6 +1,14 @@ module.exports = { someSidebar: { - "Getting Started": ["intro", "hardware", "faq", "user-setup", "bond-reset"], + "Getting Started": [ + "intro", + "hardware", + "faq", + "user-setup", + "customization", + "bond-reset", + "troubleshooting" + ], Features: [ "feature/keymaps", "feature/displays", @@ -11,15 +19,22 @@ module.exports = { "behavior/key-press", "behavior/layers", "behavior/misc", + "behavior/hold-tap", "behavior/mod-tap", + "behavior/reset", + "behavior/bluetooth", "behavior/lighting", ], Development: [ "dev-clean-room", "dev-setup", + "dev-build-flash", "dev-boards-shields-keymaps", "dev-posix-board", + "dev-tests", ], - "Dev Guides": ["dev-guide-new-shield", "dev-guide-usb-logging"], + "Dev Guides": [ + "dev-guide-new-shield", + "dev-guide-usb-logging"], }, }; diff --git a/docs/static/setup.sh b/docs/static/setup.sh index bb61df6..5d203a4 100644 --- a/docs/static/setup.sh +++ b/docs/static/setup.sh @@ -38,7 +38,7 @@ echo "" echo "Keyboard Shield Selection:" prompt="Pick an keyboard:" -options=("Kyria" "Lily58" "Corne") +options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle" "Iris" "RoMac") PS3="$prompt " # TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos. @@ -50,6 +50,10 @@ select opt in "${options[@]}" "Quit"; do 1 ) shield_title="Kyria" shield="kyria"; split="y"; break;; 2 ) shield_title="Lily58" shield="lily58"; split="y"; break;; 3 ) shield_title="Corne" shield="corne"; split="y"; break;; + 4 ) shield_title="Splitreus62" shield="splitreus62"; split="y"; break;; + 5 ) shield_title="Sofle" shield="sofle"; split="y"; break;; + 6 ) shield_title="Iris" shield="iris"; split="y"; break;; + 7 ) shield_title="RoMac" shield="romac"; split="n"; break;; # Add link to docs on adding your own custom shield in your ZMK config! # $(( ${#options[@]}+1 )) ) echo "Other!"; break;; @@ -59,6 +63,10 @@ select opt in "${options[@]}" "Quit"; do esac done +if [ "$split" == "n" ]; then + repo_path="https://github.com/zmkfirmware/zmk-config-template.git" +fi + read -e -p "Copy in the stock keymap for customization? [Yn]: " copy_keymap if [ -z "$copy_keymap" ] || [ "$copy_keymap" == "Y" ] || [ "$copy_keymap" == "y" ]; then copy_keymap="yes"; fi |
