Added a page on ZMK modules and modified some other files around that topic, along with minor changes to sidebars.js to make the sidebar nicer.
This commit is contained in:
Nicolas Munnich
parent
95890e951e
commit
41723d18c9
5 changed files with 210 additions and 232 deletions
|
|
@ -28,12 +28,14 @@ When using a split keyboard, you can use a single file without the `_left` or `_
|
||||||
|
|
||||||
### Board Folder
|
### Board Folder
|
||||||
|
|
||||||
ZMK will search for config files in either of:
|
ZMK will search for config files in:
|
||||||
|
|
||||||
- [`zmk/app/boards/arm/<board>`](https://github.com/zmkfirmware/zmk/tree/main/app/boards/arm)
|
- [`zmk/app/boards/arm/<board>`](https://github.com/zmkfirmware/zmk/tree/main/app/boards/arm)
|
||||||
- `zmk-config/config/boards/arm/<board>`
|
- `zmk-config/boards/arm/<board>`
|
||||||
|
- `<module>/boards/arm/<board>`
|
||||||
|
- `zmk-config/config/boards/arm/<board>` (For backwards compatibility only, do not use.)
|
||||||
|
|
||||||
...where `<board>` is the name of the board. These files describe the hardware of the board.
|
...where `<board>` is the name of the board and `<module>` is the root directory of any [included module](#../features/modules.mdx). These files describe the hardware of the board.
|
||||||
|
|
||||||
ZMK will search the board folder for the following config files:
|
ZMK will search the board folder for the following config files:
|
||||||
|
|
||||||
|
|
@ -48,12 +50,14 @@ For more documentation on creating and configuring a new board, see [Zephyr's bo
|
||||||
|
|
||||||
### Shield Folder
|
### Shield Folder
|
||||||
|
|
||||||
When building with a shield, ZMK will search for config files in either of:
|
When building with a shield, ZMK will search for config files in:
|
||||||
|
|
||||||
- [`zmk/app/boards/shields/<shield>`](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields)
|
- [`zmk/app/boards/shields/<shield>`](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields)
|
||||||
- `zmk-config/config/boards/shields/<shield>`
|
- `zmk-config/boards/shields/<shield>`
|
||||||
|
- `<module>/boards/shields/<shield>`
|
||||||
|
- `zmk-config/config/boards/shields/<shield>` (For backwards compatibility only, do not use.)
|
||||||
|
|
||||||
...where `<shield>` is the name of the shield. These files describe the hardware of the shield that the board is plugged into.
|
...where `<shield>` is the name of the shield and `<module>` is the root directory of any [included module](#../features/modules.mdx). These files describe the hardware of the shield that the board is plugged into.
|
||||||
|
|
||||||
ZMK will search the shield folder for the following config files:
|
ZMK will search the shield folder for the following config files:
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -51,6 +51,13 @@ Follow these steps to create your new repository:
|
||||||
- Select Public or Private, depending on your preference.
|
- Select Public or Private, depending on your preference.
|
||||||
- Click the green "Create repository" button
|
- Click the green "Create repository" button
|
||||||
|
|
||||||
|
The repository is a combination of the directories and files required of a ZMK config, and those required of a shield module. To create a shield module, the following components are needed:
|
||||||
|
|
||||||
|
- The `boards/shields` directory, where the keyboard's files will go
|
||||||
|
- The `zephyr/module.yml` file, which identifies and describes the module. See the [Zephyr documentation](https://docs.zephyrproject.org/3.5.0/develop/modules.html#module-yaml-file-description) for details on customising this file. For the purposes of creating a shield module, the default found in the template can be left untouched.
|
||||||
|
|
||||||
|
Neither of these should be moved out of their parent directory. The other files and directories are unnecessary for the purposes of a shield module.
|
||||||
|
|
||||||
## New Shield Directory
|
## New Shield Directory
|
||||||
|
|
||||||
:::note
|
:::note
|
||||||
|
|
|
||||||
|
|
@ -1,100 +0,0 @@
|
||||||
---
|
|
||||||
title: Beta Testing
|
|
||||||
sidebar_label: Beta Testing
|
|
||||||
---
|
|
||||||
|
|
||||||
import Tabs from "@theme/Tabs";
|
|
||||||
import TabItem from "@theme/TabItem";
|
|
||||||
|
|
||||||
You may find that ZMK does not support a feature or keyboard that you are interesting in using. You may find that someone
|
|
||||||
has already taken the time to submit the feature you need as a [Pull Request](https://github.com/zmkfirmware/zmk/pulls). If you find the feature you need as a pull request,
|
|
||||||
this page is for you!
|
|
||||||
|
|
||||||
## Developer Repositories and Branches
|
|
||||||
|
|
||||||
For a developer to submit a pull request to ZMK, they must first clone the original ZMK repository. After they have a copy
|
|
||||||
of the source code, they may create a feature branch to work within. When they have finished, they will publish the feature
|
|
||||||
branch and create the pull request.
|
|
||||||
|
|
||||||
### Finding the Repository Page from the Pull Request
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### Finding the Repository URL
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### Finding the Repository Branch
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Testing Features
|
|
||||||
|
|
||||||
Testing features will require you to modify the `west.yml` file. You will need to add a new remote for the pull request you
|
|
||||||
would like to test, and change the selected remote and revision (or branch) for the `zmk` project.
|
|
||||||
|
|
||||||
### Examples
|
|
||||||
|
|
||||||
<Tabs
|
|
||||||
defaultValue="zmk"
|
|
||||||
values={[
|
|
||||||
{label: 'Default', value: 'zmk'},
|
|
||||||
{label: 'PR685: Macros', value: 'macros'},
|
|
||||||
{label: 'PR649: Add &sleep behavior', value: 'sleep'},
|
|
||||||
]}>
|
|
||||||
<TabItem value="zmk">
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
manifest:
|
|
||||||
remotes:
|
|
||||||
- name: zmkfirmware
|
|
||||||
url-base: https://github.com/zmkfirmware
|
|
||||||
projects:
|
|
||||||
- name: zmk
|
|
||||||
remote: zmkfirmware
|
|
||||||
revision: main
|
|
||||||
import: app/west.yml
|
|
||||||
self:
|
|
||||||
path: config
|
|
||||||
```
|
|
||||||
|
|
||||||
</TabItem>
|
|
||||||
<TabItem value="macros">
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
manifest:
|
|
||||||
remotes:
|
|
||||||
- name: zmkfirmware
|
|
||||||
url-base: https://github.com/zmkfirmware
|
|
||||||
- name: okke-formsma
|
|
||||||
url-base: https://github.com/okke-formsma
|
|
||||||
projects:
|
|
||||||
- name: zmk
|
|
||||||
remote: okke-formsma
|
|
||||||
revision: macros
|
|
||||||
import: app/west.yml
|
|
||||||
self:
|
|
||||||
path: config
|
|
||||||
```
|
|
||||||
|
|
||||||
</TabItem>
|
|
||||||
<TabItem value="sleep">
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
manifest:
|
|
||||||
remotes:
|
|
||||||
- name: zmkfirmware
|
|
||||||
url-base: https://github.com/zmkfirmware
|
|
||||||
- name: mcrosson
|
|
||||||
url-base: https://github.com/mcrosson
|
|
||||||
projects:
|
|
||||||
- name: zmk
|
|
||||||
remote: mcrosson
|
|
||||||
revision: feat-behavior-sleep
|
|
||||||
import: app/west.yml
|
|
||||||
self:
|
|
||||||
path: config
|
|
||||||
```
|
|
||||||
|
|
||||||
</TabItem>
|
|
||||||
</Tabs>
|
|
||||||
|
|
@ -3,7 +3,10 @@ title: Modules
|
||||||
sidebar_label: Modules
|
sidebar_label: Modules
|
||||||
---
|
---
|
||||||
|
|
||||||
ZMK makes use of [Zephyr modules]() to include additional source code or configuration files into its build. The most common uses of this feature are:
|
import Tabs from "@theme/Tabs";
|
||||||
|
import TabItem from "@theme/TabItem";
|
||||||
|
|
||||||
|
ZMK makes use of [Zephyr modules](https://docs.zephyrproject.org/3.5.0/develop/modules.html) to include additional source code or configuration files into its build. You can think of them as similar to plugins or themes. The most common uses of this feature are:
|
||||||
|
|
||||||
- Building firmware for a keyboard external to ZMK's tree
|
- Building firmware for a keyboard external to ZMK's tree
|
||||||
- Adding functionality to ZMK, such as a driver or a behaviour
|
- Adding functionality to ZMK, such as a driver or a behaviour
|
||||||
|
|
@ -14,18 +17,21 @@ A common ZMK setup thus consists of the following separate Git repositories:
|
||||||
- Any number of ZMK modules, maintained by the module's owner. Some modules may contain multiple keyboards or functionalities. If all of your keyboards and functionalities are internal to ZMK's tree, then no modules are necessary.
|
- Any number of ZMK modules, maintained by the module's owner. Some modules may contain multiple keyboards or functionalities. If all of your keyboards and functionalities are internal to ZMK's tree, then no modules are necessary.
|
||||||
- The ZMK firmware itself, maintained by its contributors.
|
- The ZMK firmware itself, maintained by its contributors.
|
||||||
|
|
||||||
Further information on creating modules for ZMK and ZMK's overall file structure can be found [in the corresponding section]().
|
|
||||||
|
|
||||||
:::note
|
:::note
|
||||||
The shift to using modules for keyboards is a relatively recent one, and not all designs may be properly configured to be used as a module. If this is the case for your keyboard, then we would strongly suggest asking your vendor or designer to rectify this.
|
The shift to using modules for keyboards is a relatively recent one, and not all designs may be properly configured to be used as a module. If this is the case for your keyboard, then we would strongly suggest asking your vendor or designer to rectify this.
|
||||||
:::
|
:::
|
||||||
|
|
||||||
## Building With Modules
|
## Building With Modules
|
||||||
|
|
||||||
Adding modules to your ZMK build is as simple as modifying the `west.yml` found in your `zmk-config`'s `config` directory. You will need to:
|
Adding modules to your ZMK build is as simple as modifying the `west.yml` found in your `zmk-config`'s `config` directory. The recommended way of doing so is:
|
||||||
1. Find and add the URL base for the module.
|
|
||||||
|
|
||||||
### Example
|
1. Find the URL base (the parent URL) for the module and add it as an entry to the [remotes](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html#remotes).
|
||||||
|
2. Add the module as an entry to the [projects](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html#projects).
|
||||||
|
Aside from the mandatory `name`, `remote`, and the commonly used `revision` properties, take note of the `import` property under `projects`. Some modules may have other modules as dependencies. This property allows the specifying of an additional west manifest file found in the tree of the module, which will automatically import all dependencies.
|
||||||
|
|
||||||
|
For more information on `west.yml`, see [West Manifests](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html).
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
<Tabs
|
<Tabs
|
||||||
defaultValue="zmk"
|
defaultValue="zmk"
|
||||||
|
|
@ -51,20 +57,51 @@ manifest:
|
||||||
```
|
```
|
||||||
|
|
||||||
</TabItem>
|
</TabItem>
|
||||||
<TabItem value="alt">
|
<TabItem value="ma">
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
manifest:
|
manifest:
|
||||||
remotes:
|
remotes:
|
||||||
- name: zmkfirmware
|
- name: zmkfirmware
|
||||||
url-base: https://github.com/zmkfirmware
|
url-base: https://github.com/zmkfirmware
|
||||||
- name: forkedzmk
|
- name: module_a_base
|
||||||
url-base: https://github.com/forkedzmk
|
url-base: https://github.com/alice
|
||||||
projects:
|
projects:
|
||||||
- name: zmk
|
- name: zmk
|
||||||
remote: forkedzmk
|
remote: zmkfirmware
|
||||||
revision: specificpr
|
revision: main
|
||||||
import: app/west.yml
|
import: app/west.yml
|
||||||
|
- name: module_a
|
||||||
|
remote: module_a_base
|
||||||
|
revision: main
|
||||||
|
self:
|
||||||
|
path: config
|
||||||
|
```
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="mab">
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
manifest:
|
||||||
|
remotes:
|
||||||
|
- name: zmkfirmware
|
||||||
|
url-base: https://github.com/zmkfirmware
|
||||||
|
- name: module_a_base
|
||||||
|
url-base: https://github.com/alice
|
||||||
|
- name: module_b_base
|
||||||
|
url-base: https://github.com/bob
|
||||||
|
projects:
|
||||||
|
- name: zmk
|
||||||
|
remote: zmkfirmware
|
||||||
|
revision: main
|
||||||
|
import: app/west.yml
|
||||||
|
- name: module_a
|
||||||
|
remote: module_a_base
|
||||||
|
revision: main
|
||||||
|
- name: module_b
|
||||||
|
remote: module_b_base
|
||||||
|
revision: main
|
||||||
|
import: west.yml
|
||||||
self:
|
self:
|
||||||
path: config
|
path: config
|
||||||
```
|
```
|
||||||
|
|
|
||||||
260
docs/sidebars.js
260
docs/sidebars.js
|
|
@ -1,120 +1,150 @@
|
||||||
module.exports = {
|
module.exports = {
|
||||||
docs: {
|
docs: [
|
||||||
"Getting Started": [
|
{
|
||||||
"intro",
|
type: "category",
|
||||||
"hardware",
|
label: "Getting Started",
|
||||||
"faq",
|
link: {
|
||||||
"user-setup",
|
type: "doc",
|
||||||
"customization",
|
id: "intro",
|
||||||
{
|
},
|
||||||
type: "category",
|
collapsed: false,
|
||||||
label: "Troubleshooting",
|
items: [
|
||||||
link: {
|
"hardware",
|
||||||
type: "doc",
|
"faq",
|
||||||
id: "troubleshooting/index",
|
"user-setup",
|
||||||
|
"customization",
|
||||||
|
{
|
||||||
|
type: "category",
|
||||||
|
label: "Troubleshooting",
|
||||||
|
link: {
|
||||||
|
type: "doc",
|
||||||
|
id: "troubleshooting/index",
|
||||||
|
},
|
||||||
|
collapsed: true,
|
||||||
|
items: [
|
||||||
|
"troubleshooting/building-issues",
|
||||||
|
"troubleshooting/flashing-issues",
|
||||||
|
"troubleshooting/connection-issues",
|
||||||
|
],
|
||||||
},
|
},
|
||||||
collapsed: true,
|
],
|
||||||
items: [
|
},
|
||||||
"troubleshooting/building-issues",
|
{
|
||||||
"troubleshooting/flashing-issues",
|
Features: [
|
||||||
"troubleshooting/connection-issues",
|
"features/keymaps",
|
||||||
],
|
"features/bluetooth",
|
||||||
|
"features/combos",
|
||||||
|
"features/conditional-layers",
|
||||||
|
"features/debouncing",
|
||||||
|
"features/displays",
|
||||||
|
"features/encoders",
|
||||||
|
"features/modules",
|
||||||
|
"features/underglow",
|
||||||
|
"features/backlight",
|
||||||
|
"features/battery",
|
||||||
|
"features/soft-off",
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: "category",
|
||||||
|
label: "Behaviors",
|
||||||
|
link: {
|
||||||
|
type: "doc",
|
||||||
|
id: "behaviors/index",
|
||||||
},
|
},
|
||||||
],
|
collapsed: true,
|
||||||
Features: [
|
items: [
|
||||||
"features/keymaps",
|
"behaviors/key-press",
|
||||||
"features/bluetooth",
|
"behaviors/layers",
|
||||||
"features/combos",
|
"behaviors/misc",
|
||||||
"features/conditional-layers",
|
"behaviors/hold-tap",
|
||||||
"features/debouncing",
|
"behaviors/mod-tap",
|
||||||
"features/displays",
|
"behaviors/mod-morph",
|
||||||
"features/encoders",
|
"behaviors/macros",
|
||||||
"features/underglow",
|
"behaviors/key-toggle",
|
||||||
"features/backlight",
|
"behaviors/sticky-key",
|
||||||
"features/battery",
|
"behaviors/sticky-layer",
|
||||||
"features/soft-off",
|
"behaviors/tap-dance",
|
||||||
"features/beta-testing",
|
"behaviors/caps-word",
|
||||||
],
|
"behaviors/key-repeat",
|
||||||
Behaviors: [
|
"behaviors/sensor-rotate",
|
||||||
"behaviors/index",
|
"behaviors/mouse-emulation",
|
||||||
"behaviors/key-press",
|
"behaviors/reset",
|
||||||
"behaviors/layers",
|
"behaviors/bluetooth",
|
||||||
"behaviors/misc",
|
"behaviors/outputs",
|
||||||
"behaviors/hold-tap",
|
"behaviors/underglow",
|
||||||
"behaviors/mod-tap",
|
"behaviors/backlight",
|
||||||
"behaviors/mod-morph",
|
"behaviors/power",
|
||||||
"behaviors/macros",
|
"behaviors/soft-off",
|
||||||
"behaviors/key-toggle",
|
],
|
||||||
"behaviors/sticky-key",
|
},
|
||||||
"behaviors/sticky-layer",
|
{
|
||||||
"behaviors/tap-dance",
|
Codes: [
|
||||||
"behaviors/caps-word",
|
"codes/index",
|
||||||
"behaviors/key-repeat",
|
"codes/keyboard-keypad",
|
||||||
"behaviors/sensor-rotate",
|
"codes/modifiers",
|
||||||
"behaviors/mouse-emulation",
|
"codes/editing",
|
||||||
"behaviors/reset",
|
"codes/media",
|
||||||
"behaviors/bluetooth",
|
"codes/applications",
|
||||||
"behaviors/outputs",
|
"codes/input-assist",
|
||||||
"behaviors/underglow",
|
"codes/power",
|
||||||
"behaviors/backlight",
|
],
|
||||||
"behaviors/power",
|
},
|
||||||
"behaviors/soft-off",
|
{
|
||||||
],
|
type: "category",
|
||||||
Codes: [
|
label: "Configuration",
|
||||||
"codes/index",
|
link: {
|
||||||
"codes/keyboard-keypad",
|
type: "doc",
|
||||||
"codes/modifiers",
|
id: "config/index",
|
||||||
"codes/editing",
|
|
||||||
"codes/media",
|
|
||||||
"codes/applications",
|
|
||||||
"codes/input-assist",
|
|
||||||
"codes/power",
|
|
||||||
],
|
|
||||||
Configuration: [
|
|
||||||
"config/index",
|
|
||||||
"config/backlight",
|
|
||||||
"config/battery",
|
|
||||||
"config/behaviors",
|
|
||||||
"config/bluetooth",
|
|
||||||
"config/combos",
|
|
||||||
"config/displays",
|
|
||||||
"config/encoders",
|
|
||||||
"config/keymap",
|
|
||||||
"config/kscan",
|
|
||||||
"config/power",
|
|
||||||
"config/underglow",
|
|
||||||
"config/system",
|
|
||||||
],
|
|
||||||
Development: [
|
|
||||||
"development/clean-room",
|
|
||||||
"development/pre-commit",
|
|
||||||
"development/documentation",
|
|
||||||
{
|
|
||||||
type: "category",
|
|
||||||
label: "Setup",
|
|
||||||
collapsed: true,
|
|
||||||
items: [
|
|
||||||
"development/setup/index",
|
|
||||||
"development/setup/docker",
|
|
||||||
"development/setup/native",
|
|
||||||
],
|
|
||||||
},
|
},
|
||||||
"development/build-flash",
|
collapsed: true,
|
||||||
"development/boards-shields-keymaps",
|
items: [
|
||||||
"development/posix-board",
|
"config/backlight",
|
||||||
"development/tests",
|
"config/battery",
|
||||||
"development/usb-logging",
|
"config/behaviors",
|
||||||
"development/ide-integration",
|
"config/bluetooth",
|
||||||
{
|
"config/combos",
|
||||||
type: "category",
|
"config/displays",
|
||||||
label: "Guides",
|
"config/encoders",
|
||||||
collapsed: false,
|
"config/keymap",
|
||||||
items: [
|
"config/kscan",
|
||||||
"development/new-shield",
|
"config/power",
|
||||||
"development/hardware-metadata-files",
|
"config/underglow",
|
||||||
"development/new-behavior",
|
"config/system",
|
||||||
],
|
],
|
||||||
},
|
},
|
||||||
],
|
{
|
||||||
},
|
Development: [
|
||||||
|
"development/clean-room",
|
||||||
|
"development/pre-commit",
|
||||||
|
"development/documentation",
|
||||||
|
{
|
||||||
|
type: "category",
|
||||||
|
label: "Setup",
|
||||||
|
collapsed: true,
|
||||||
|
items: [
|
||||||
|
"development/setup/index",
|
||||||
|
"development/setup/docker",
|
||||||
|
"development/setup/native",
|
||||||
|
],
|
||||||
|
},
|
||||||
|
"development/build-flash",
|
||||||
|
"development/boards-shields-keymaps",
|
||||||
|
"development/posix-board",
|
||||||
|
"development/tests",
|
||||||
|
"development/usb-logging",
|
||||||
|
"development/ide-integration",
|
||||||
|
{
|
||||||
|
type: "category",
|
||||||
|
label: "Guides",
|
||||||
|
collapsed: false,
|
||||||
|
items: [
|
||||||
|
"development/new-shield",
|
||||||
|
"development/hardware-metadata-files",
|
||||||
|
"development/new-behavior",
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
};
|
};
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue