kb01/zmk
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

More reshuffling, some typos, removed a file that wasn't supposed to be there, squashed commits

Browse source
This commit is contained in:
Nicolas Munnich 2024-05-14 02:27:41 +02:00
parent 864f45a415
commit 12f0f1a264
5 changed files with 367 additions and 94 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/docs/behaviors/index.mdx
View file

@ -46,9 +46,9 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors
## Reset behaviors
| Binding | Behavior | Description |
| ------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
| `&sys_reset` | [Reset](reset.md#reset) | Resets the keyboard and re-runs the firmware flashed to the device |
| Binding | Behavior | Description |
| ------------- | --------------------------------------- | ---------------------------------------------------------------------------------------- |
| `&sys_reset` | [Reset](reset.md#reset) | Resets the keyboard and re-runs the firmware flashed to the device |
| `&bootloader` | [Bootloader](reset.md#bootloader-reset) | Resets the keyboard and puts it into bootloader mode, allowing you to flash new firmware |
## Output selection behaviors

21
docs/docs/development/setup/docker.md
View file

@ -7,11 +7,28 @@ sidebar_label: Docker
Currently the Docker approach is only documented for VSCode, Microsoft's proprietary version of [Code OSS](https://github.com/microsoft/vscode) - See [here](https://github.com/microsoft/vscode/wiki/Differences-between-the-repository-and-Visual-Studio-Code) for more info on different versions. There is an alternative approach using [devcontainers](https://containers.dev/), but this is not documented yet - contributions are welcome!
:::
### Source Code
First, you'll need to clone the ZMK source repository if you haven't already. Open a terminal and navigate to the folder you would like to place your `zmk` directory in, then run the following command:
```sh
git clone https://github.com/zmkfirmware/zmk.git
```
:::warning
#### Windows Users
If you're using the Docker environment on Windows, you _must_ checkout the sources to a folder within `C:\Users\[your_user_here]` to avoid a potential permissions issue.
If you're using the WSL2 filesystem the sources should go under `~/` to avoid potential permissions issues.
:::
## Installing Development Tools
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)
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).
### Initialize & Update Zephyr Workspace

17
docs/docs/development/setup/getting-started.md
View file

@ -17,23 +17,6 @@ These commands should be run in a terminal such as Bash (Linux/MacOS/Docker), Po
We recommend reading through the setup process before following it step by step, to ensure that you are happy with installing the required dependencies.
:::
### Source Code
First, you'll need to clone the ZMK source repository if you haven't already. Open a terminal and navigate to the folder you would like to place your `zmk` directory in, then run the following command:
```sh
git clone https://github.com/zmkfirmware/zmk.git
```
:::warning
#### Windows Users
If you're using the Docker environment on Windows, you _must_ checkout the sources to a folder within `C:\Users\[your_user_here]` to avoid a potential permissions issue.
If you're using the WSL2 filesystem the sources should go under `~/` to avoid potential permissions issues.
:::
## Environment Setup
There are two ways to setup the ZMK development environment:

394
docs/docs/development/setup/native.mdx
View file

@ -7,44 +7,120 @@ import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
export const OsTabs = (props) => (
<Tabs
groupId="operating-systems"
defaultValue="linux"
<Tabs
groupId="operating-system"
defaultValue="ubuntu"
values={[
{ label: "Linux", value: "linux" },
{ label: "Ubuntu", value: "ubuntu" },
{ label: "Windows", value: "win" },
{ label: "macOS", value: "mac" },
{ label: "Mac OS", value: "mac" },
{ label: "Raspberry OS", value: "raspberryos" },
]}
>
{/* eslint-disable-next-line */}
{props.children}
</Tabs>
);
First, step into the `zmk` directory that you cloned in [Getting Started](/docs/development/setup/getting-started).
export const EnvTabs = (props) => (
<Tabs
groupId="python-environment"
defaultValue="venv"
values={[
{ label: "Install within Virtual Environment", value: "venv" },
{ label: "Install globally", value: "glob" },
]}
>
{/* eslint-disable-next-line */}
{props.children}
</Tabs>
);
export const WinTermTabs = (props) => (
<Tabs
groupId="windows-terminal-choice"
defaultValue="cmd"
values={[
{ label: "Command Prompt", value: "cmd" },
{ label: "Powershell", value: "ps" },
]}
>
{/* eslint-disable-next-line */}
{props.children}
</Tabs>
);
## 1. Install Zephyr Dependencies
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
:::info
Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) page may be of use for users of Linux distributions which are not based on Ubuntu.
:::
## 2. Source Code
Next, you'll need to clone the ZMK source repository if you haven't already. Open a terminal and navigate to the folder you would like to place your `zmk` directory in, then run the following command:
```sh
git clone https://github.com/zmkfirmware/zmk.git
```
Then step into the repository.
```sh
cd zmk
```
## 3. Get Zephyr and install Python dependencies
:::note
These steps are very similar to Zephyr's [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies) instructions, but specialised for ZMK.
:::
<OsTabs>
<TabItem value="linux">
<TabItem value="ubuntu">
## Install Zephyr and West
<EnvTabs>
<TabItem value="venv">
1. Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
1. Use `apt` to install Python `venv` package:
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
```sh
sudo apt install python3-venv
```
:::info
Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) page may be of use for distributions which are not based on Ubuntu.
:::
2. Create a new virtual environment:
2. Next, follow steps 1-4 from [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies).
```sh
python3 -m venv .venv
```
3. ZMK comes with its own copy of Zephyr, so you don't need to add a fresh copy to a separate directory.
3. Activate the virtual environment:
```sh
source .venv/bin/activate
```
Once activated your shell will be prefixed with `(.venv)`. The virtual environment can be deactivated at any time by running `deactivate`.
:::note
Remember to activate the virtual environment every time you start working.
:::
4. Install west:
```sh
pip3 install west
```
5. Initialise the application (This provides ZMK with its own copy of Zephyr):
```sh
west init -l app/
@ -55,35 +131,105 @@ west update
This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!
:::
4. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
6. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
```
5. ZMK does not need all of the additional dependencies found in Zephyr's `requirements.txt`, but it does need those found in `requirements-base.txt`
7. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip3 install -r zephyr/scripts/requirements-base.txt
```
6. Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
</TabItem>
<TabItem value="glob">
1. Install `west`, and make sure `~/.local/bin` is on your `PATH` environment variable:
```sh
pip3 install --user -U west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
```
2. Initialise the application (This provides ZMK with its own copy of Zephyr):
```sh
west init -l app/
west update
```
:::tip
This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!
:::
3. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
```
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip3 install --user -r zephyr/scripts/requirements-base.txt
```
</TabItem>
</EnvTabs>
## 4. Install Zephyr SDK
Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk).
Your setup is now complete.
</TabItem>
<TabItem value="win">
## Install Zephyr and West
<EnvTabs>
<TabItem value="venv">
1. Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
1. Create a new virtual environment:
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
```sh
python -m venv .venv
```
2. Next, follow steps 1-4 from [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies).
2. Activate the virtual environment:
3. ZMK comes with its own copy of Zephyr, so you don't need to add a fresh copy to a separate directory.
<WinTermTabs>
<TabItem value="cmd">
```sh
.venv\Scripts\activate.bat
```
</TabItem>
<TabItem value="ps">
```sh
.venv\Scripts\Activate.ps1
```
</TabItem>
</WinTermTabs>
Once activated your shell will be prefixed with `(.venv)`. The virtual environment can be deactivated at any time by running `deactivate`.
:::note
Remember to activate the virtual environment every time you start working.
:::
3. Install west:
```sh
pip install west
```
4. Initialise the application (This provides ZMK with its own copy of Zephyr):
```sh
west init -l app/
@ -94,19 +240,56 @@ west update
This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!
:::
4. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
5. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
```
5. ZMK does not need all of the additional dependencies found in Zephyr's `requirements.txt`, but it does need those found in `requirements-base.txt`
6. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip3 install -r zephyr/scripts/requirements-base.txt
pip install -r zephyr/scripts/requirements-base.txt
```
6. Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
</TabItem>
<TabItem value="glob">
1. Install `west`, and make sure `~/.local/bin` is on your `PATH` environment variable:
```sh
pip install -U west
```
2. Initialise the application (This provides ZMK with its own copy of Zephyr):
```sh
west init -l app/
west update
```
:::tip
This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!
:::
3. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
```
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip install -r zephyr/scripts/requirements-base.txt
```
</TabItem>
</EnvTabs>
## 4. Install Zephyr SDK
Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk).
:::note
`dfu-util` is required to flash devices that use DFU, but there is currently no maintained package for it on Chocolatey. [QMK Toolbox](https://github.com/qmk/qmk_toolbox) contains a working version of it though.
@ -117,16 +300,33 @@ Your setup is now complete.
</TabItem>
<TabItem value="mac">
## Install Zephyr and West
<EnvTabs>
<TabItem value="venv">
1. Create a new virtual environment:
1. Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
```sh
python3 -m venv .venv
```
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
2. Activate the virtual environment:
2. Next, follow steps 1-4 from [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies).
```sh
source .venv/bin/activate
```
3. ZMK comes with its own copy of Zephyr, so you don't need to add a fresh copy to a separate directory.
Once activated your shell will be prefixed with `(.venv)`. The virtual environment can be deactivated at any time by running `deactivate`.
:::note
Remember to activate the virtual environment every time you start working.
:::
3. Install west:
```sh
pip3 install west
```
4. Initialise the application (This provides ZMK with its own copy of Zephyr)
```sh
west init -l app/
@ -137,35 +337,92 @@ west update
This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!
:::
4. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
5. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
```
5. ZMK does not need all of the additional dependencies found in Zephyr's `requirements.txt`, but it does need those found in `requirements-base.txt`
6. Install the additional dependencies found in Zephyr's `requirements-base.txt`.
```sh
pip3 install -r zephyr/scripts/requirements-base.txt
```
6. Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
</TabItem>
<TabItem value="glob">
Your setup is now complete.
1. Install `west`
```sh
pip3 install -U west
```
2. Initialise the application (This provides ZMK with its own copy of Zephyr)
```sh
west init -l app/
west update
```
:::tip
This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!
:::
3. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
```
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`.
```sh
pip3 install -r ~/zephyrproject/zephyr/scripts/requirements-base.txt
```
</TabItem>
</EnvTabs>
## 4. Install Zephyr SDK
Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk).
</TabItem>
<TabItem value="raspberryos">
<EnvTabs>
<TabItem value="venv">
## Install Zephyr and West
1. Use `apt` to install Python `venv` package:
1. Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
```sh
sudo apt install python3-venv
```
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
2. Create a new virtual environment:
2. Next, follow steps 1-4 from [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies).
```sh
python3 -m venv .venv
```
3. ZMK comes with its own copy of Zephyr, so you don't need to add a fresh copy to a separate directory.
3. Activate the virtual environment:
```sh
source .venv/bin/activate
```
Once activated your shell will be prefixed with `(.venv)`. The virtual environment can be deactivated at any time by running `deactivate`.
:::note
Remember to activate the virtual environment every time you start working.
:::
4. Install west:
```sh
pip3 install west
```
5. Initialise the application (This provides ZMK with its own copy of Zephyr):
```sh
west init -l app/
@ -176,21 +433,60 @@ west update
This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!
:::
4. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
6. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
```
5. ZMK does not need all of the additional dependencies found in Zephyr's `requirements.txt`, but it does need those found in `requirements-base.txt`
7. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip3 install -r zephyr/scripts/requirements-base.txt
```
6. Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
</TabItem>
<TabItem value="glob">
#### Install Cross-Compile Toolchain
1. Install `west`, and make sure `~/.local/bin` is on your `PATH` environment variable:
```sh
pip3 install --user -U west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
```
2. Initialise the application (This provides ZMK with its own copy of Zephyr):
```sh
west init -l app/
west update
```
:::tip
This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!
:::
3. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
```
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip3 install --user -r ~/zephyrproject/zephyr/scripts/requirements-base.txt
```
</TabItem>
</EnvTabs>
## 4. Install Zephyr SDK
Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk).
## 5. Install Cross-Compile Toolchain
Because Raspberry OS runs on the same architecture (but different ABI) as ARM keyboard MCUs, the operating system's installed [cross compilers](https://docs.zephyrproject.org/3.5.0/develop/toolchains/other_x_compilers.html) can be used to target the different ABI. Building for non-ARM MCUs has not been tested.

23
docs/docs/development/setup/notes.md
View file

@ -1,23 +0,0 @@
### Notes about setup
As I cannot seem to figure out a reliable way to get comments working with Docusaurus, I'm writing notes in this file instead.
I don't know how accurate this is, and [Zephyr does not recommend WSL](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html), so I'm not sure this should be included.
:::note Windows Users
Please note the ZMK builds run slower (up to 3-5 minutes on slower hardware) with Docker on Windows if you don't use the WSL2 filesystem to store files. If you run into performance problems you can checkout the ZMK sources inside a WSL2 environment and run `code .` to open the sources. This can make builds run at near-native speed.
This approach will also need the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension installed in VS Code.
Files stored within WSL2 can be accessed via Windows Explorer by navigating to `\\wsl$`.
:::
Googling this seems to imply that there are workarounds, but I do not have access to a device to test it out. It is not included under the current docs, so I don't see a reason to include it until it is brought up by someone.
:::danger The Docker environment will NOT run on arm CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an arm CPU. :::
I think this is true, but I have not tested.
:::caution Windows Users If you're using the Docker environment on Windows, you must checkout the sources to a folder within C:\Users\[your_user_here] to avoid a potential permissions issue.
If you're using the WSL2 filesystem the sources should go under ~/ to avoid potential permissions issues. :::