pwarren
/
zmk_mf68
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #301 from innovaker/docs-eslint-prettier 

docs: Add eslint, prettier and eslint-mdx support
This commit is contained in:
Pete Johanson 2020-10-27 12:56:44 -04:00 committed by GitHub
parent c707ab45ef 1ac78498eb
commit 2f09957ae2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
26 changed files with 3072 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/.eslintignore Normal file
View File

@ -0,0 +1,2 @@
node_modules
build

29
docs/.eslintrc.js Normal file
View File

@ -0,0 +1,29 @@
module.exports = {
env: {
browser: true,
commonjs: true,
es2021: true,
node: true,
},
extends: [
"eslint:recommended",
"plugin:react/recommended",
"plugin:mdx/recommended",
"prettier",
"prettier/react",
],
parserOptions: {
ecmaFeatures: {
jsx: true,
},
ecmaVersion: 2021,
sourceType: "module",
},
plugins: ["react"],
rules: {},
settings: {
react: {
version: "detect",
},
},
};

3
docs/.prettierignore Normal file
View File

@ -0,0 +1,3 @@
node_modules
build
.docusaurus

3
docs/.prettierrc.js Normal file
View File

@ -0,0 +1,3 @@
module.exports = {
endOfLine: "auto",
};

1
docs/README.md
View File

@ -23,4 +23,3 @@ $ npm build
```
This command generates static content into the `build` directory and can be served using any static contents hosting service.

15
docs/docs/behavior/hold-tap.md
View File

@ -4,17 +4,18 @@ sidebar_label: Hold-Tap
---
## Summary
Hold-tap is the basis for other behaviors such as layer-tap and mod-tap.
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'.
![Simple behavior](../assets/hold-tap/case1_2.png)
By default, the hold-tap is configured to also select the 'hold' functionality if another key is tapped while it's active:
By default, the hold-tap is configured to also select the 'hold' functionality if another key is tapped while it's active:
![Hold preferred behavior](../assets/hold-tap/case1_2.png)
@ -23,10 +24,11 @@ We call this the 'hold-preferred' flavor of hold-taps. While this flavor may wor
![Hold-tap comparison](../assets/hold-tap/comparison.png)
### 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:
```
@ -44,7 +46,7 @@ A code example which configures a mod-tap setting that works with homerow mods:
bindings = <&kp>, <&kp>;
};
};
keymap {
compatible = "zmk,keymap";
@ -63,4 +65,5 @@ If this config does not work for you, try the flavor "tap-preferred" and a short
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`.
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`.

2
docs/docs/behavior/key-press.md
View File

@ -64,4 +64,4 @@ Example:
```
&cp M_PREV
```
```

2
docs/docs/behavior/layers.md
View File

@ -46,6 +46,7 @@ Example:
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: `&lt`
- Parameter: The layer number to enable when held, e.g. `1`
- Parameter: The keycode to send when tapped, e.g. `A`
@ -56,7 +57,6 @@ Example:
&lt LOWER SPC
```
## Toggle Layer
The "toggle layer" behavior enables a layer until the layer is manually disabled.

1
docs/docs/behavior/mod-tap.md
View File

@ -40,4 +40,3 @@ You can configure a different tapping term in your keymap:
}
}
```

32
docs/docs/behavior/power.md
View File

@ -10,11 +10,12 @@ These page contains some of the power management behaviors currently supported b
## External Power Control
The External power control behavior allows enabling or disabling the VCC power output
to save power. Some of the LEDs will consume power even in OFF state. To preserve
to save power. Some of the LEDs will consume power even in OFF state. To preserve
battery life in this scenario, some controller boards have support to disable the
external power completely.
The following boards currently support this feature:
- nRFMicro
- nice!nano
@ -31,11 +32,11 @@ This will allow you to reference the actions defined in this header such as `EXT
Here is a table describing the command for each define:
| Define | Action | Alias |
| ------------ | -------------------------------------- | -------- |
| `EXT_POWER_OFF_CMD` | Disable the external power. | `EP_OFF` |
| `EXT_POWER_ON_CMD` | Enable the external power. | `EP_ON` |
| `EXT_POWER_TOGGLE_CMD` | Toggle the external power. | `EP_TOG` |
| Define | Action | Alias |
| ---------------------- | --------------------------- | -------- |
| `EXT_POWER_OFF_CMD` | Disable the external power. | `EP_OFF` |
| `EXT_POWER_ON_CMD` | Enable the external power. | `EP_ON` |
| `EXT_POWER_TOGGLE_CMD` | Toggle the external power. | `EP_TOG` |
### Behavior Binding
@ -46,19 +47,18 @@ Here is a table describing the command for each define:
1. Behavior binding to enable the external power
```
&ext_power EP_ON
```
```
&ext_power EP_ON
```
1. Behavior binding to disable the external power
```
&ext_power EP_OFF
```
```
&ext_power EP_OFF
```
1. Behavior binding to toggle the external power
```
&ext_power EP_TOG
```
```
&ext_power EP_TOG
```

3
docs/docs/bond-reset.md
View File

@ -17,7 +17,6 @@ list, you will need to clear the bonds.
Split keyboards will need to be cleared on both halves. For best results try to reset them at the same time.
### Kyria
![Kyria bond-reset combo](assets/bond-clearing/kyria.jpg)
@ -28,4 +27,4 @@ Split keyboards will need to be cleared on both halves. For best results try to
### Lily58
![Lily58 bond-reset combo](assets/bond-clearing/lily58.jpg)
![Lily58 bond-reset combo](assets/bond-clearing/lily58.jpg)

16
docs/docs/customization.md
View File

@ -5,14 +5,15 @@ 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.
[In the initial setup tutorial](user-setup), you created a Github repository called `zmk-config`. This repository is a discrete filesystem which works
with the main `zmk` firmware repository to build your desired firmware. The main advantage of a discrete configuration folder is ensuring that the
working components of ZMK are kept separate from your personal keyboard settings, reducing the amount of file manipulation in the configuration process.
[In the initial setup tutorial](user-setup), you created a Github repository called `zmk-config`. This repository is a discrete filesystem which works
with the main `zmk` firmware repository to build your desired firmware. The main advantage of a discrete configuration folder is ensuring that the
working components of ZMK are kept separate from your personal keyboard settings, reducing the amount of file manipulation in the configuration process.
This makes flashing ZMK to your keyboard much easier, especially because you don't need to keep an up-to-date copy of zmk on your computer at all times.
On default `zmk-config` folder should contain two files:
* `<shield>.conf`
* `<shield>`.keymap
- `<shield>.conf`
- `<shield>`.keymap
However, your config folder can also be modified to include a `boards/` directory for keymaps and configurations for multiple boards/shields
outside of the default keyboard setting definitions.
@ -39,11 +40,10 @@ If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https:
## Building from a local `zmk` fork using `zmk-config`
[As outlined here](dev-build-flash), firmware comes in the form of .uf2 files, which can be built locally using the command `west build`. Normally,
[As outlined here](dev-build-flash), firmware comes in the form of .uf2 files, which can be built locally using the command `west build`. Normally,
`west build` will default to using the in-tree .keymap and .conf files found in your local copy of the `zmk` repository. However, you can append the command, `-DZMK_CONFIG="C:/the/absolute/path/config"` to `west build` in order to use the contents of your `zmk-config` folder instead of the
default keyboard settings.
**Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.**
**Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.**
For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this:

9
docs/docs/dev-build.md
View File

@ -62,11 +62,13 @@ 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
@ -78,25 +80,26 @@ By default, the `build` command outputs a single .uf2 file named `zmk.uf2` so bu
```
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.
### Building from `zmk-config` Folder
Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](user-setup#github-repo) by adding
Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](user-setup#github-repo) by adding
`-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.**
For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this:
```
west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config"
```
## Flashing
Once built, the previously supplied parameters will be remembered so you can run the following to flash your

24
docs/docs/dev-guide-new-shield.md
View File

@ -49,8 +49,8 @@ config SHIELD_MY_BOARD
This will make sure the new configuration `SHIELD_MY_BOARD` is set to true whenever `my_board` is added as a shield in your build.
**For split boards**, you will need to add configurations for the left and right sides.
```
config SHIELD_MY_BOARD_LEFT
def_bool $(shields_list_contains,my_board_left)
@ -77,7 +77,6 @@ config ZMK_KEYBOARD_NAME
endif
```
Similarly to defining the halves of a split board in `Kconfig.shield` it is important to set the `ZMK_KEYBOARD_NAME` for each half of a split keyboard.
```
@ -100,7 +99,6 @@ endif
![Labelled Pro Micro pins](assets/pro-micro/pro-micro-pins-labelled.jpg)
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`.
<Tabs
@ -190,7 +188,7 @@ 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)
, <&pro_micro_d 0 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row D from the schematic file
, <&pro_micro_d 4 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row E from the schematic file
;
};
```
@ -224,7 +222,7 @@ This is exemplified with the iris .overlay files.
```
// iris_right.overlay
#include "iris.dtsi"
#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>;
@ -245,13 +243,13 @@ This is exemplified with the iris .overlay files.
### .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.
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 halves
* `my_awesome_split_board_left.conf` - Configuration elements only affect left half
* `my_awesome_split_board_right.conf` - Configuration elements only affect right half
- `my_awesome_split_board.conf` - Configuration elements affect both halves
- `my_awesome_split_board_left.conf` - Configuration elements only affect left half
- `my_awesome_split_board_right.conf` - Configuration elements only affect right half
For proper communication between keyboard halves and that between the central half and the computer,
the **the central and peripheral halves of the keyboard must be defined**. This can be seen below.
@ -421,7 +419,6 @@ If building locally for split boards, you may need to add these lines to the spe
<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";
@ -431,6 +428,7 @@ left_encoder: encoder_left {
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.
@ -462,11 +460,12 @@ For split keyboards, make sure to add left hand encoders to the left .overlay fi
</TabItem>
<TabItem value = "keymap">
Add the following line to your keymap file to add default encoder behavior bindings:
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>
@ -521,6 +520,7 @@ jobs:
- board: proton_c
shield: clueboard_california
```
:::note
Notice that both the left and right halves of a split board need to be added to the list of shields for proper error checking.
:::note

2
docs/docs/dev-guide-usb-logging.md
View File

@ -56,9 +56,11 @@ values={[
<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">

9
docs/docs/dev-setup.md
View File

@ -169,9 +169,11 @@ Chocolatey is recommended and used for the following instructions. You can manua
```
It is recommended to install `dfu-util` to avoid any later confusion while flashing devices. You can do this by running this command with chocolatey:
``` shell
```shell
choco install dfu-util
```
</TabItem>
<TabItem value="mac">
@ -188,7 +190,6 @@ brew install cmake ninja python3 ccache dtc git wget dfu-util
This setup leverages the same [image which is used by the GitHub action](https://github.com/zmkfirmware/zephyr-west-action) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach is also the easiest to set up. No toolchain or dependencies are necessary when using Docker; the container image you'll be using already has the toolchain installed and set up to use.
1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system.
2. Install [VS Code](https://code.visualstudio.com/)
3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
@ -368,7 +369,6 @@ Since ZMK is built as a Zephyr™ application, the next step is
to use `west` to initialize and update your workspace. The ZMK
Zephyr™ application is in the `app/` source directory:
#### Step into the repository
<OsTabs>
@ -419,7 +419,7 @@ Click `Reopen in Container` in order to reopen the VS Code with the running cont
The first time you do this on your machine, it will pull the docker image down from the registry and build the container. Subsequent launches are much faster!
:::caution
All subsequent steps must be performed from the VS Code terminal _inside_ the container.
All subsequent steps must be performed from the VS Code terminal _inside_ the container.
:::
</TabItem>
@ -453,7 +453,6 @@ If you're using Docker, you're done with setup! You must restart the container a
Once your container is restarted, proceed to [Building and Flashing](./dev-build.md).
:::
#### Export Zephyr™ Core
```sh

9
docs/docs/dev-tests.md
View File

@ -8,13 +8,14 @@ Running tests requires [native posix support](./dev-posix-board). Any folder und
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
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)
- 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
8. Repeat steps 4 to 7 for every test case

47
docs/docs/faq.md
View File

@ -7,7 +7,8 @@ sidebar_label: FAQs
### Why Zephyr™?
As a best-in-class RTOS, Zephyr™ brings many [benefits](https://www.zephyrproject.org/benefits) to ZMK, such as:
- A *single* platform [supporting](https://docs.zephyrproject.org/latest/boards) many architectures, processors and boards.
- A _single_ platform [supporting](https://docs.zephyrproject.org/latest/boards) many architectures, processors and boards.
- Optimization for low-powered, small memory footprint devices.
- Powerful hardware abstraction and configuration using [DeviceTree](https://docs.zephyrproject.org/latest/guides/dts/index.html) and [Kconfig](https://docs.zephyrproject.org/latest/guides/kconfig/index.html).
- A BLE stack that periodically obtains [qualification](https://docs.zephyrproject.org/latest/guides/bluetooth/bluetooth-qual.html) listings, making it easier for final products to obtain qualification from the Bluetooth® SIG.
@ -18,14 +19,14 @@ As a best-in-class RTOS, Zephyr™ brings many [benefits](https://www.zephyrproj
### Why yet another keyboard firmware?
That’s an excellent question! There are already great keyboard firmwares available, but ZMK has some advantages:
That’s an excellent question! There are already great keyboard firmwares available, but ZMK has some advantages:
- Zephyr™
- See [Why Zephyr™?](#why-zephyr)
- Licensing
- Just like other open source firmware, ZMK is all about the free and the sharing. However, some other projects use the GPL licence which prevents integration of libraries and drivers whose licenses are not GPL-compatible (such as some embedded BLE drivers). ZMK uses the permissive [MIT](https://github.com/zmkfirmware/zmk/blob/main/LICENSE) license which doesn’t have this limitation.
- Just like other open source firmware, ZMK is all about the free and the sharing. However, some other projects use the GPL licence which prevents integration of libraries and drivers whose licenses are not GPL-compatible (such as some embedded BLE drivers). ZMK uses the permissive [MIT](https://github.com/zmkfirmware/zmk/blob/main/LICENSE) license which doesn’t have this limitation.
- Wireless First
- ZMK is designed for the future, and we believe the future is wireless. So power efficiency plays a critical role in every design decision, just like in Zephyr™.
- ZMK is designed for the future, and we believe the future is wireless. So power efficiency plays a critical role in every design decision, just like in Zephyr™.
The ZMK contributors firmly believe that a keyboard firmware built on Zephyr™ will provide more long term benefits.
@ -35,9 +36,9 @@ ZMK uses the MIT [license](https://github.com/zmkfirmware/zmk/blob/main/LICENSE)
### What hardware/platforms does ZMK support?
ZMK has the potential to run on any platform supported by Zephyr™. However, it’s impractical for the ZMK contributors to test all possible hardware.
ZMK has the potential to run on any platform supported by Zephyr™. However, it’s impractical for the ZMK contributors to test all possible hardware.
The Zephyr™ [documentation](https://docs.zephyrproject.org/latest/boards/index.html) describes which hardware is currently natively supported by the Zephyr™ platform. *Similar documentation covering which keyboards have been integrated into ZMK is currently being planned.*
The Zephyr™ [documentation](https://docs.zephyrproject.org/latest/boards/index.html) describes which hardware is currently natively supported by the Zephyr™ platform. _Similar documentation covering which keyboards have been integrated into ZMK is currently being planned._
### Does ZMK compile for AVR?
@ -45,54 +46,56 @@ Sorry, Zephyr™ only supports 32-bit and 64-bit platforms.
### How do I get started?
ZMK is still in its infancy, so there’s a learning curve involved. But if you’d like to try it out, please check out the development [documentation](/docs) and the other FAQs. Please keep in mind that the project team is still small, so our support capability is limited whilst we focus on development. But we’ll try our best! Interested developers are also very welcome to contribute!
ZMK is still in its infancy, so there’s a learning curve involved. But if you’d like to try it out, please check out the development [documentation](/docs) and the other FAQs. Please keep in mind that the project team is still small, so our support capability is limited whilst we focus on development. But we’ll try our best! Interested developers are also very welcome to contribute!
### What is a “board”?
In ZMK, a *board* defines the *PCB* that *includes the MCU*.
In ZMK, a _board_ defines the _PCB_ that _includes the MCU_.
For keyboards, this is one of two options:
- Complete keyboard PCBs that include the MCU (e.g. the Planck or Preonic).
- Small MCU boards (e.g. the Proton-C or nice!nano) that expose pins and are designed to be combined with larger keyboard PCBs, or hand wired to switches to create the final keyboard.
### What is a “shield”?
In ZMK, a *shield* is a *PCB* or *hardwired set of components* that when combined with a MCU only [board](#what-is-a-board) like the Proton-C or nice!nano, results in a complete usable keyboard. Examples would be keyboard PCBs like the Kyria or Corne. The *shield* is usually the big PCB containing all the keys.
In ZMK, a _shield_ is a _PCB_ or _hardwired set of components_ that when combined with a MCU only [board](#what-is-a-board) like the Proton-C or nice!nano, results in a complete usable keyboard. Examples would be keyboard PCBs like the Kyria or Corne. The _shield_ is usually the big PCB containing all the keys.
### Why *boards* and *shields*? Why not just “keyboard”?
### Why _boards_ and _shields_? Why not just “keyboard”?
If you haven't already done so, please read these FAQs first:
- [What is a “board”?](#what-is-a-board)
- [What is a "shield"?](#what-is-a-shield)
When a keyboard accepts a small “PCB MCU module” (e.g. *Arduino Pro Micro*) for its “brains”, then it's important to conceptually separate the hardware into a [board](#what-is-a-board) PCB and a [shield](#what-is-a-shield) PCB.
When a keyboard accepts a small “PCB MCU module” (e.g. _Arduino Pro Micro_) for its “brains”, then it's important to conceptually separate the hardware into a [board](#what-is-a-board) PCB and a [shield](#what-is-a-shield) PCB.
The [shield](#what-is-a-shield) is a brainless shell containing all the keys, RGB LEDs, encoders etc. It maps all of these features to a standard pin footprint, such as the Pro Micro pinout.
The [shield](#what-is-a-shield) is a brainless shell containing all the keys, RGB LEDs, encoders etc. It maps all of these features to a standard pin footprint, such as the Pro Micro pinout.
To bring this brainless [shield](#what-is-a-shield) to life, you attach any MCU [board](#what-is-a-board) matching the footprint. For instance, the *nice!nano* is *pin-compatible* with the *Arduino Pro Micro*, so you can substitute either [board](#what-is-a-board) onto the [shield](#what-is-a-shield). But each [board](#what-is-a-board) comes with its own features (MCU, flash, BLE, etc.) which must also be handled.
To bring this brainless [shield](#what-is-a-shield) to life, you attach any MCU [board](#what-is-a-board) matching the footprint. For instance, the _nice!nano_ is _pin-compatible_ with the _Arduino Pro Micro_, so you can substitute either [board](#what-is-a-board) onto the [shield](#what-is-a-shield). But each [board](#what-is-a-board) comes with its own features (MCU, flash, BLE, etc.) which must also be handled.
Therefore in ZMK, [board](#what-is-a-board) and [shield](#what-is-a-shield) are considered two different (but related) entities so that it’s easier to mix and match them. They are combined during a ZMK build.
Therefore in ZMK, [board](#what-is-a-board) and [shield](#what-is-a-shield) are considered two different (but related) entities so that it’s easier to mix and match them. They are combined during a ZMK build.
Please note, many keyboards only have a single PCB which includes the “brains” (MCU) onboard. In ZMK, these have no [shield](#what-is-a-shield), only a [board](#what-is-a-board).
Please note, many keyboards only have a single PCB which includes the “brains” (MCU) onboard. In ZMK, these have no [shield](#what-is-a-shield), only a [board](#what-is-a-board).
### 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://zmkfirmware.dev/community/discord/invite)!
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?
Of course! Please use the developer [documentation](/docs) to get started!
Of course! Please use the developer [documentation](/docs) to get started!
### I have an idea! What should I do?
### I have an idea! What should I do?
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?
### 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://zmkfirmware.dev/community/discord/invite) to get started.
### Does ZMK have a Code of Conduct?
Yes, it does have a [Code of Conduct](https://github.com/zmkfirmware/zmk/blob/main/CODE_OF_CONDUCT.md)! Please give it a read!
Yes, it does have a [Code of Conduct](https://github.com/zmkfirmware/zmk/blob/main/CODE_OF_CONDUCT.md)! Please give it a read!
### What does “ZMK” mean?
@ -100,8 +103,8 @@ ZMK was originally coined as a quasi-acronym of “Zephyr Mechanical Keyboard”
### Is ZMK related to TMK or QMK?
No. But inspired by, of course!
No. But inspired by, of course!
### Who created ZMK?
ZMK was created by Pete Johanson. It is developed and maintained by the open source community.
ZMK was created by Pete Johanson. It is developed and maintained by the open source community.

2
docs/docs/feature/underglow.md
View File

@ -36,7 +36,7 @@ If your board or shield does not have RGB underglow configured, refer to [Adding
There are various Kconfig options used to configure the RGB underglow feature. These can all be set in the `.conf` file.
| Option | Description | Default |
|-------------------------------|------------------------------------------------|---------|
| ----------------------------- | ---------------------------------------------- | ------- |
| `ZMK_RGB_UNDERGLOW_HUE_STEP` | Hue step in degrees of 360 used by RGB actions | 10 |
| `ZMK_RGB_UNDERGLOW_SAT_STEP` | Saturation step in percent used by RGB actions | 10 |
| `ZMK_RGB_UNDERGLOW_BRT_STEP` | Brightness step in percent used by RGB actions | 10 |

58
docs/docs/intro.md
View File

@ -12,35 +12,35 @@ firmware built on the [Zephyr™ Project](https://zephyrproject.org/) Real Time
ZMK is currently missing some features found in other popular firmware. This table compares the features supported by ZMK, BlueMicro and QMK:
| **Feature** | ZMK | BlueMicro | QMK |
|--------------------------------------------------------------------------------------------------------|:-----------:|:------------:|:-----------:|
| Low Latency BLE Support | ✅ | ✅ | |
| Multi-Device BLE Support | ✅ | | |
| USB Connectivity | ✅ | | ✅ |
| User Configuration Repositories | ✅ | | |
| Split Keyboard Support | ✅ | ✅ | ✅ |
| [Keymaps and Layers](behavior/layers) | ✅ | ✅ | ✅ |
| [Hold-Tap](behavior/hold-tap) (which includes [Mod-Tap](behavior/mod-tap) and [Layer-Tap](behavior/layers/#layer-tap)) | ✅ | ✅ | ✅ |
| [Basic Keycodes](behavior/key-press) | ✅ | ✅ | ✅ |
| [Basic consumer (Media) Keycodes](behavior/key-press#consumer-key-press) | ✅ | ✅ | ✅ |
| [Encoders](feature/encoders)[^1] | ✅ | | ✅ |
| [OLED Display Support](feature/displays)[^2] | 🚧 | 🚧 | ✅ |
| [RGB Underglow](feature/underglow) | ✅ | ✅ | ✅ |
| One Shot Keys | 🚧 | ✅ | ✅ |
| Combo Keys | 🚧 | | ✅ |
| Macros | 🚧 | ✅ | ✅ |
| Mouse Keys | | ✅ | ✅ |
| Low Active Power Usage | ✅ | | |
| [Low Power Sleep States](https://github.com/zmkfirmware/zmk/pull/211) | 🚧 | ✅ | |
| [Low Power Mode (VCC Shutoff)](https://github.com/zmkfirmware/zmk/pull/242) | 🚧 | | |
| [Battery Reporting](https://github.com/zmkfirmware/zmk/issues/47) | 🚧 | ✅ | |
| Shell over BLE | | | |
| Realtime Keymap Updating | 💡 | | ✅ |
| AVR/8 Bit | | | ✅ |
| [Wide Range of ARM Chips Supported](https://docs.zephyrproject.org/latest/boards/index.html) | ✅ | | |
[^2]: Encoders are not currently supported on peripheral side splits.
[^1]: OLEDs are currently proof of concept in ZMK.
| **Feature** | ZMK | BlueMicro | QMK |
| ---------------------------------------------------------------------------------------------------------------------- | :-: | :-------: | :-: |
| Low Latency BLE Support | ✅ | ✅ | |
| Multi-Device BLE Support | ✅ | | |
| USB Connectivity | ✅ | | ✅ |
| User Configuration Repositories | ✅ | | |
| Split Keyboard Support | ✅ | ✅ | ✅ |
| [Keymaps and Layers](behavior/layers) | ✅ | ✅ | ✅ |
| [Hold-Tap](behavior/hold-tap) (which includes [Mod-Tap](behavior/mod-tap) and [Layer-Tap](behavior/layers/#layer-tap)) | ✅ | ✅ | ✅ |
| [Basic Keycodes](behavior/key-press) | ✅ | ✅ | ✅ |
| [Basic consumer (Media) Keycodes](behavior/key-press#consumer-key-press) | ✅ | ✅ | ✅ |
| [Encoders](feature/encoders)[^1] | ✅ | | ✅ |
| [OLED Display Support](feature/displays)[^2] | 🚧 | 🚧 | ✅ |
| [RGB Underglow](feature/underglow) | ✅ | ✅ | ✅ |
| One Shot Keys | 🚧 | ✅ | ✅ |
| Combo Keys | 🚧 | | ✅ |
| Macros | 🚧 | ✅ | ✅ |
| Mouse Keys | | ✅ | ✅ |
| Low Active Power Usage | ✅ | | |
| [Low Power Sleep States](https://github.com/zmkfirmware/zmk/pull/211) | 🚧 | ✅ | |
| [Low Power Mode (VCC Shutoff)](https://github.com/zmkfirmware/zmk/pull/242) | 🚧 | | |
| [Battery Reporting](https://github.com/zmkfirmware/zmk/issues/47) | 🚧 | ✅ | |
| Shell over BLE | | | |
| Realtime Keymap Updating | 💡 | | ✅ |
| AVR/8 Bit | | | ✅ |
| [Wide Range of ARM Chips Supported](https://docs.zephyrproject.org/latest/boards/index.html) | ✅ | | |
[^2]: Encoders are not currently supported on peripheral side splits.
[^1]: OLEDs are currently proof of concept in ZMK.
## Code Of Conduct

55
docs/docs/troubleshooting.md
View File

@ -3,6 +3,7 @@ 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).
@ -11,31 +12,30 @@ The following page provides suggestions for common errors that may occur during
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.
| ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/windows.png) |
| :-------------------------------------------------------------------------------: |
| An example of the file transfer error on Windows 10 |
| ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/windows.png) |
| :------------------------------------------------------------------------------: |
| An example of the file transfer error on Windows 10 |
| ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/linux.png) |
| :-------------------------------------------------------------------------------: |
| An example of the file transfer error on Linux |
| ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/mac.png) |
| :-------------------------------------------------------------------------------: |
| An example of the file transfer error on MacOS |
| ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/linux.png) |
| :----------------------------------------------------------------------------: |
| An example of the file transfer error on Linux |
| ![Example Error Screen](../docs/assets/troubleshooting/filetransfer/mac.png) |
| :--------------------------------------------------------------------------: |
| An example of the file transfer error on MacOS |
### 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.
```
@ -44,25 +44,24 @@ CMake Warnings shown above during `west build` are normal occurrences. They shou
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`.
| ![Example Error Screen](../docs/assets/troubleshooting/keymaps/errorscreen.png) |
| :-------------------------------------------------------------------------------: |
| An example of the dtlib.DTError when compiling an iris with the nice!nano while the keymap is not properly defined |
| ![Example Error Screen](../docs/assets/troubleshooting/keymaps/errorscreen.png) |
| :----------------------------------------------------------------------------------------------------------------: |
| 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).
| ![Unhealthy Keymap Temp](../docs/assets/troubleshooting/keymaps/unhealthyEDIT.png) |
| :-------------------------------------------------------------------------------: |
| 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" |
| ![Unhealthy Keymap Temp](../docs/assets/troubleshooting/keymaps/unhealthyEDIT.png) |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| 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" |
| ![Healthy Keymap Temp](../docs/assets/troubleshooting/keymaps/healthyEDIT.png) |
| :-------------------------------------------------------------------------------: |
| 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)|
| ![Healthy Keymap Temp](../docs/assets/troubleshooting/keymaps/healthyEDIT.png) |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| 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) |
### Split Keyboard Halves Unable to Pair
@ -74,19 +73,19 @@ Since then, a much simpler procedure of performing a bluetooth reset for split k
1. Log into Github and download the "settings clear" UF2 image from the [latest build in Github Actions](https://github.com/zmkfirmware/zmk/actions?query=workflow%3ABuild+branch%3Amain)
1. Put each half of the split keyboard into bootloader mode
1. Flash one of the halves of the split with the "settings clear" UF2 image from step 1. Immediately after flashing "settings clear" to the chosen half, immediately put it into bootloader mode
to avoid accidental bonding between the halves.
to avoid accidental bonding between the halves.
1. Repeat step 3 with the other half of the split keyboard
1. Flash the actual image for each half of the split keyboard (e.g `my_board_left.uf2` to the left half, `my_board_right.uf2` to the right half)
After completing these steps, pair the halves of the split keyboard together by resetting them at the same time. Most commonly, this is done by grounding the reset pins
for each of your keyboard's microcontrollers or pressing the reset buttons at the same time.
### Connectivity Issues ###
### Connectivity Issues
Some users may experience a poor connection between the keyboard and the host. This might be due to poor quality BLE hardware, a metal enclosure on the keyboard or host, or the distance between them. Increasing the transmit power of the keyboard's BLE radio may reduce the severity of this problem. To do this, set the `CONFIG_BT_CTLR_TX_PWR_PLUS_8` configuration value in the `.conf` file of your user config directory as such:
Some users may experience a poor connection between the keyboard and the host. This might be due to poor quality BLE hardware, a metal enclosure on the keyboard or host, or the distance between them. Increasing the transmit power of the keyboard's BLE radio may reduce the severity of this problem. To do this, set the `CONFIG_BT_CTLR_TX_PWR_PLUS_8` configuration value in the `.conf` file of your user config directory as such:
```
CONFIG_BT_CTLR_TX_PWR_PLUS_8=y
```
```
For the `nRF52840`, the value `PLUS_8` can be set to any multiple of four between `MINUS_20` and `PLUS_8`. The default value for this config is `0`, but if you are having connection issues it is recommended to set it to `PLUS_8` because the power consumption difference is negligible. For more information on changing the transmit power of your BLE device, please refer to [the Zephyr docs.](https://docs.zephyrproject.org/latest/reference/kconfig/CONFIG_BT_CTLR_TX_PWR_PLUS_8.html)

1
docs/docs/user-setup.md
View File

@ -84,6 +84,7 @@ bash -c "$(wget https://zmkfirmware.dev/setup.sh -O -)" '' --wget
```
iex ((New-Object System.Net.WebClient).DownloadString('https://zmkfirmware.dev/setup.ps1'))"
```
</TabItem>
</Tabs>

2867
docs/package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

7
docs/package.json
View File

@ -28,5 +28,12 @@
"last 1 firefox version",
"last 1 safari version"
]
},
"devDependencies": {
"eslint": "^7.12.0",
"eslint-config-prettier": "^6.14.0",
"eslint-plugin-mdx": "^1.8.2",
"eslint-plugin-react": "^7.21.5",
"prettier": "2.1.2"
}
}

6
docs/sidebars.js
View File

@ -6,7 +6,7 @@ module.exports = {
"faq",
"user-setup",
"customization",
"troubleshooting"
"troubleshooting",
],
Features: [
"feature/keymaps",
@ -33,8 +33,6 @@ module.exports = {
"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"],
},
};

20
docs/src/pages/index.js
View File

@ -5,6 +5,7 @@ import Link from "@docusaurus/Link";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import useBaseUrl from "@docusaurus/useBaseUrl";
import styles from "./styles.module.css";
import PropTypes from "prop-types";
const features = [
{
@ -12,7 +13,8 @@ const features = [
imageUrl: "img/undraw_zephyr.svg",
description: (
<>
With a wide range of architecture support, ZMK is ready for many existing keyboards.
With a wide range of architecture support, ZMK is ready for many
existing keyboards.
</>
),
},
@ -20,19 +22,13 @@ const features = [
title: <>Permissive Licensing</>,
imageUrl: "img/undraw_open_source.svg",
description: (
<>
MIT licensed to remove any future limitations in innovation.
</>
<>MIT licensed to remove any future limitations in innovation.</>
),
},
{
title: <>Wireless First</>,
imageUrl: "img/undraw_wireless.svg",
description: (
<>
Designed for the future, including wireless support.
</>
),
description: <>Designed for the future, including wireless support.</>,
},
];
@ -51,6 +47,12 @@ function Feature({ imageUrl, title, description }) {
);
}
Feature.propTypes = {
imageUrl: PropTypes.string.isRequired,
title: PropTypes.string.isRequired,
description: PropTypes.string.isRequired,
};
function Home() {
const context = useDocusaurusContext();
const { siteConfig = {} } = context;