mirror of https://github.com/zmkfirmware/zmk.git
docs: Replace user setup script with ZMK CLI
This deletes the Bash and PowerShell setup scripts in favor of using ZMK CLI. The old setup scripts are broken, since the config repo template uses ZMK version 0.3, while the setup scripts use hardware metadata from the main branch. ZMK CLI doesn't have this issue, because it clones the version of ZMK listed in the config repo to get hardware metadata. Much of the "Installing ZMK" page has been rewritten to give instructions for installing ZMK CLI and using it to create and modify a config repo. The previously-hidden page on ZMK CLI has been added to the sidebar and repurposed into general documentation for the tool.
This commit is contained in:
Joel Spadin
parent
fed2cf69da
commit
be73872ec8
|
|
@ -6,14 +6,33 @@ sidebar_label: Installing ZMK
|
|||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
export const OsTabs = (props) => (
|
||||
<Tabs
|
||||
groupId="operating-system"
|
||||
queryString
|
||||
defaultValue="linux"
|
||||
values={[
|
||||
{ label: "Linux", value: "linux" },
|
||||
{ label: "Windows", value: "win" },
|
||||
{ label: "Mac OS", value: "mac" }
|
||||
]}
|
||||
>
|
||||
{/* eslint-disable-next-line */}
|
||||
{props.children}
|
||||
</Tabs>
|
||||
|
||||
);
|
||||
|
||||
Unlike other keyboard firmwares, ZMK Firmware has been built from the ground up to allow users to manage
|
||||
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 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.
|
||||
|
||||
:::info
|
||||
ZMK currently has an **experimental** command line program set to replace the below steps. It is designed to automate a number of steps for you and be easier to use. Give it a try by following the instructions found [here](user-setup-cli.mdx). Feedback and bug reports are very much welcome.
|
||||
:::info[Something Isn't Working?]
|
||||
|
||||
If you run into any issues when following these instructions, please [file an issue on GitHub](https://github.com/zmkfirmware/zmk-cli/issues) or [join us on Discord](https://zmk.dev/community/discord/invite) and let us know what went wrong so we can improve ZMK CLI and this guide.
|
||||
|
||||
:::
|
||||
|
||||
## Summary
|
||||
|
|
@ -24,170 +43,306 @@ to build your firmware for you in the cloud, which you can then download and fla
|
|||
|
||||
Following the steps in this guide, you will:
|
||||
|
||||
1. Install ZMK CLI, a command line tool for setting up ZMK.
|
||||
1. Create a new repository in GitHub that will contain your user config.
|
||||
1. Download and run a small shell script that will automate most of the setup. The script will:
|
||||
1. Prompt you for which board (e.g. nice!nano) and shield (e.g. Lily58 or Kyria) you want to create a configuration for.
|
||||
1. Prompt you for your GitHub username and repo where the config should be pushed.
|
||||
1. Use `git` to clone a template repository that will be the basis for your user's config repository.
|
||||
1. Use the given board and shield to update the included GitHub Action to build for the correct hardware.
|
||||
1. Commit the initial version.
|
||||
1. (If info was provided) Push the local repo to your GitHub repository.
|
||||
1. Add your own keymap overlay (`keymap.overlay`) file to the repository, and change your keymap.
|
||||
1. Update the configuration flags for your user config, to enable/disable any ZMK features you would like to include.
|
||||
1. Commit and push the updates to trigger a new GitHub Action run.
|
||||
1. Use ZMK CLI to clone the repo to your computer so you can edit the files.
|
||||
1. Select a keyboard to use and update the `build.yaml` file so GitHub will build firmware for that keyboard.
|
||||
1. Add your own `.keymap` and `.conf` files to customize your keymap and enable/disable other ZMK features.
|
||||
1. Commit and push the updates to trigger a new GitHub Action run to build the firmware.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The remainder of this guide assumes the following prerequisites:
|
||||
You will need to install a few tools before you can get started.
|
||||
|
||||
1. You have an active, working [GitHub](https://github.com/) account.
|
||||
1. You have installed and configured the [`git`](https://git-scm.com/) version control tool.
|
||||
1. You have locally configured git to access your github account. If using [personal access tokens](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token), please be sure it was created with the "workflow" scope option selected.
|
||||
Many instructions in this guide use commands that need to be run in a terminal application.
|
||||
|
||||
- On Windows, use [Windows Terminal](https://apps.microsoft.com/detail/9n0dx20hk701) or PowerShell.
|
||||
- On other operating systems, the terminal program is usually just named "Terminal".
|
||||
|
||||
### Install Git
|
||||
|
||||
Open a terminal and run the following command. If Git is already installed, it will print out a version number.
|
||||
|
||||
```sh
|
||||
git --version
|
||||
```
|
||||
|
||||
If it gives an error instead, install Git from https://git-scm.com/install/. Close and re-open your terminal and run the `git --version` command again to check if it installed correctly.
|
||||
|
||||
:::note
|
||||
If you need to, a quick read 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 started.
|
||||
This guide will have you run several more `git` commands later. If you aren't familiar with Git, check out [Learn The Basics Of Git In Under 10 Minutes](https://www.freecodecamp.org/news/learn-the-basics-of-git-in-under-10-minutes-da548267cc91/) to help you get started.
|
||||
:::
|
||||
|
||||
## GitHub Repo
|
||||
### Set Up a GitHub Account
|
||||
|
||||
Before running the setup script, you will first need to create a new GitHub repository to host the config.
|
||||
You will need a GitHub account. [Create an account](https://github.com/signup) if you don't have one yet.
|
||||
|
||||
1. Navigate to [https://github.com/new](https://github.com/new)
|
||||
1. When prompted for the repo name, enter `zmk-config`.
|
||||
1. The repository can be public or private
|
||||
1. Do **not** check any of the options to initialize the repository with a README or other files.
|
||||
1. Click "Create repository"
|
||||
Next, you will need to authenticate your local Git installation with GitHub. There are several ways to do this, but the following two are the simplest. Pick whichever seems easiest to you:
|
||||
|
||||
## User Config Setup Script
|
||||
#### Authenticate with GitHub CLI
|
||||
|
||||
To start the setup process, run the following from your command line prompt:
|
||||
Install [GitHub CLI](https://cli.github.com/) and run the following command in a terminal. Follow the instructions it gives you, and it will open GitHub in a web browser for you to log in.
|
||||
|
||||
<Tabs
|
||||
queryString="command"
|
||||
defaultValue="curl"
|
||||
values={[
|
||||
{label: 'Using curl', value: 'curl'},
|
||||
{label: 'Using wget', value: 'wget'},
|
||||
{label: 'Using PowerShell', value: 'powershell'},
|
||||
]}>
|
||||
<TabItem value="curl">
|
||||
```sh
|
||||
gh auth login
|
||||
```
|
||||
|
||||
```bash
|
||||
bash -c "$(curl -fsSL https://zmk.dev/setup.sh)"
|
||||
#### Authenticate with a Personal Access Token
|
||||
|
||||
Create a [personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) and make sure to create it with the "workflow" scope option selected.
|
||||
|
||||
When running `git` commands later in this guide, Git will ask for your username and password. Enter your GitHub username, but **do not enter your password**. Instead, paste your access token for the password. You won't be able to see the token again after you create it, so keep the page open until you've done this and/or copy it to a secure location. If you lose the token, simply create another one.
|
||||
|
||||
### Install Python and pipx
|
||||
|
||||
ZMK CLI requires Python version 3.10 or above.
|
||||
|
||||
There are several ways you can install ZMK CLI, but for simplicity, this guide will use [pipx](https://pipx.pypa.io/stable/). (If you are already familiar with another Python package manager such as [uv](https://github.com/astral-sh/uv), you can install the `zmk` package with it instead, but that will not be covered in this guide.)
|
||||
|
||||
The instructions for installing Python and pipx differ depending on your operating system.
|
||||
|
||||
<OsTabs>
|
||||
<TabItem value="linux">
|
||||
|
||||
Python comes preinstalled on most Linux distributions, but pipx needs to be installed separately. In case Python isn't already installed, this guide will have you install both. Pick the commands relevant to the distribution you are using:
|
||||
|
||||
#### Ubuntu 23.04 or above
|
||||
|
||||
```sh
|
||||
sudo apt update
|
||||
sudo apt install python3 pipx
|
||||
pipx ensurepath
|
||||
```
|
||||
|
||||
#### Ubuntu 22.04
|
||||
|
||||
```sh
|
||||
sudo apt update
|
||||
sudo apt install python3
|
||||
python3 -m pip install --user pipx
|
||||
python3 -m pipx ensurepath
|
||||
```
|
||||
|
||||
#### Ubuntu 20.04
|
||||
|
||||
Ubuntu 20.04 comes with an older version of Python. You can install Python 3.10 from the deadsnakes PPA with the following commands:
|
||||
|
||||
```sh
|
||||
sudo add-apt-repository ppa:deadsnakes/ppa
|
||||
sudo apt install python3.10
|
||||
python3.10 -m pip install --user pipx
|
||||
python3.10 -m pipx ensurepath
|
||||
```
|
||||
|
||||
You will then need to replace `python3` with `python3.10` in the rest of the installation instructions.
|
||||
|
||||
#### Fedora 35 or above
|
||||
|
||||
```sh
|
||||
sudo dnf install python3 pipx
|
||||
pipx ensurepath
|
||||
```
|
||||
|
||||
If you have an older version of Fedora, you will need to update your operating system to a newer version or [build Python from source](https://docs.python.org/3/using/unix.html#building-python).
|
||||
|
||||
#### Other distributions
|
||||
|
||||
Install Python 3 and pipx using your distribution's package manager. If there is no package for pipx, install it with `pip` after installing Python:
|
||||
|
||||
```sh
|
||||
python3 -m pip install --user pipx
|
||||
python3 -m pipx ensurepath
|
||||
```
|
||||
|
||||
Check the version of Python you installed:
|
||||
|
||||
```sh
|
||||
python3 --version
|
||||
```
|
||||
|
||||
If this prints a version less than 3.10, you will need to update your operating system to a newer version or [build Python from source](https://docs.python.org/3/using/unix.html#building-python).
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="win">
|
||||
|
||||
Open https://www.python.org/downloads/ and select "Download Python install manager". Run the installer, then open a terminal and run the following command to install the latest version of Python 3:
|
||||
|
||||
```sh
|
||||
py install 3
|
||||
```
|
||||
|
||||
Next, install pipx:
|
||||
|
||||
```sh
|
||||
py -m pip install --user pipx
|
||||
py -m pipx ensurepath
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="wget">
|
||||
|
||||
```bash
|
||||
bash -c "$(wget https://zmk.dev/setup.sh -O -)" '' --wget
|
||||
<TabItem value="mac">
|
||||
|
||||
First, install Homebrew from https://brew.sh/. Next, open a terminal and run:
|
||||
|
||||
```sh
|
||||
brew install pipx
|
||||
pipx ensurepath
|
||||
```
|
||||
|
||||
This should automatically install Python 3 if it is missing.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="powershell">
|
||||
</OsTabs>
|
||||
|
||||
```powershell
|
||||
powershell -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://zmk.dev/setup.ps1'))"
|
||||
### Verify pipx Install
|
||||
|
||||
Close and re-open your terminal, then run:
|
||||
|
||||
```sh
|
||||
pipx --version
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
It should print a version number. If not, go back to the previous step and make sure you installed pipx correctly. You can also try logging out of your computer and logging back in to make sure any environment variables changes made during installation take effect.
|
||||
|
||||
### Keyboard Selection
|
||||
### Install ZMK CLI
|
||||
|
||||
When prompted, enter the number for the corresponding keyboard you would like to target:
|
||||
Finally, we'll install ZMK CLI. Open a terminal and run:
|
||||
|
||||
```
|
||||
Keyboard Selection:
|
||||
1) 2% Milk 19) Ferris 0.2 37) Nibble
|
||||
2) A. Dux 20) Fourier Rev. 1 38) nice!60
|
||||
3) BAT43 21) Helix 39) Osprette
|
||||
4) BDN9 Rev2 22) Hummingbird 40) Pancake
|
||||
5) BFO-9000 23) Iris 41) Planck Rev6
|
||||
6) Boardsource 3x4 Macropad 24) etc...
|
||||
Pick an keyboard:
|
||||
```sh
|
||||
pipx install zmk
|
||||
zmk --version
|
||||
```
|
||||
|
||||
:::note[For a keyboard not in the included list:]
|
||||
If you are building firmware for a new keyboard that is not included in the built-in
|
||||
list of keyboards, you can choose any keyboard from the list that is similar to yours
|
||||
(e.g. in terms of unibody/split and [onboard controller](hardware.mdx#onboard) /
|
||||
[composite](hardware.mdx#composite)) to generate the repository,
|
||||
and edit / add necessary files. You can follow the [new shield guide](development/hardware-integration/new-shield.mdx) if you are adding support for a composite keyboard.
|
||||
:::
|
||||
It should print a version number if everything installed correctly.
|
||||
|
||||
### MCU Board Selection
|
||||
On Linux, you may get an error saying you need to install another package such as `python3.10-venv`. If so, follow the instructions in the error message, then try the above commands again.
|
||||
|
||||
If the keyboard selected uses an onboard controller you will skip this step.
|
||||
When prompted, enter the number for the corresponding MCU board you would like to target:
|
||||
## Config Repo Setup
|
||||
|
||||
```
|
||||
MCU Board Selection:
|
||||
1) BlueMicro840 v1 5) nRF52840 M.2 Module 9) QMK Proton-C
|
||||
2) Mikoto 5.20 6) nRFMicro 1.1 (flipped) 10) Seeed Studio XIAO SAMD21
|
||||
3) nice!nano v1 7) nRFMicro 1.1/1.2 11) Seeed Studio XIAO nRF52840
|
||||
4) nice!nano v2 8) nRFMicro 1.3/1.4 12) Quit
|
||||
Pick an MCU board:
|
||||
Now that ZMK CLI is installed, you can use it to initialize a repository.
|
||||
|
||||
The `zmk init` command walks you through creating a GitHub repository, then clones it to your computer so you can edit it.
|
||||
|
||||
<details>
|
||||
<summary>I already cloned my repo</summary>
|
||||
|
||||
If you have already created a repo and cloned it to your computer, for example with the old ZMK setup script, you do not need to do this. Instead, run the following command to point ZMK CLI to your repo, replacing `/path/to/zmk-config` with the actual path to the repo folder.
|
||||
|
||||
```sh
|
||||
zmk config user.home "/path/to/zmk-config"
|
||||
```
|
||||
|
||||
### Keymap Customization
|
||||
Then, [skip to the next step](#add-a-keyboard).
|
||||
|
||||
At the next prompt, you have an opportunity to decide if you want the stock keymap file copied in
|
||||
for further customization:
|
||||
</details>
|
||||
|
||||
```
|
||||
Copy in the stock keymap for customization? [Yn]:
|
||||
Open a terminal and use the `cd` command to move to a folder where you'd like to place the ZMK files (it will create a `zmk-config` subfolder in this location), then run `zmk init`. For example:
|
||||
|
||||
```sh
|
||||
cd ~/Documents
|
||||
zmk init
|
||||
```
|
||||
|
||||
Hit `Enter` or type `yes`/`y` to accept this. If you want to keep the stock keymap, or write a keymap
|
||||
from scratch, type in `no`/`n`.
|
||||
|
||||
### GitHub Details
|
||||
|
||||
In order to have your new configuration automatically pushed, and then built using GitHub Actions, enter
|
||||
some information about your particular GitHub info:
|
||||
Follow the instructions it gives you. If you already have a ZMK config repo on GitHub, you can enter its URL when prompted, for example:
|
||||
|
||||
```
|
||||
GitHub Username (leave empty to skip GitHub repo creation): petejohanson
|
||||
GitHub Repo Name: zmk-config
|
||||
GitHub Repo: https://github.com/petejohanson/zmk-config.git
|
||||
Repository URL: https://github.com/myusername/zmk-config
|
||||
```
|
||||
|
||||
Only the GitHub username is required; if you are happy with the defaults offered in the square brackets, you can simply hit `Enter`.
|
||||
Otherwise, leave this first prompt blank and press <kbd>Enter</kbd>, and it will walk you through creating a new repo.
|
||||
|
||||
:::note
|
||||
If you are using SSH keys for git push, change GitHub Repo field to the SSH scheme, e.g. `git@github.com:petejohanson/zmk-config.git`.
|
||||
:::
|
||||
Once you finish following all the instructions, you will have a copy of the repo stored on your computer. All `zmk` commands will run on this repo (unless the working directory is inside a different repo). If you ever forget where the repo is located, you can run `zmk cd` to find it.
|
||||
|
||||
### Confirming Selections
|
||||
### Add a Keyboard
|
||||
|
||||
The setup script will confirm all of your selections one last time, before performing the setup:
|
||||
To start building firmware for a new keyboard, run the following command:
|
||||
|
||||
```
|
||||
Preparing a user config for:
|
||||
* MCU Board: nice_nano
|
||||
* Shield: kyria
|
||||
* GitHub Repo To Push (please create this in GH first!): https://github.com/petejohanson/zmk-config.git
|
||||
|
||||
Continue? [Yn]:
|
||||
```sh
|
||||
zmk keyboard add
|
||||
```
|
||||
|
||||
After hitting `Enter` or typing `y`, the script will create an initial config in a directory named after the repo name,
|
||||
update the GitHub Action YAML file, commit the initial version, and then push to your repo.
|
||||
Follow the instructions to select a keyboard (and controller board if necessary). It will add the keyboard to your repo's `build.yaml` file so GitHub knows to build it, and it will create `config/<keyboard>.keymap` and `config/<keyboard>.conf` files for you to edit.
|
||||
|
||||
:::info
|
||||
<details>
|
||||
<summary>My keyboard isn't listed</summary>
|
||||
|
||||
If you used the default GitHub repo URL using the `https://` scheme, you may be prompted for your username + password in order to
|
||||
push the initial commit.
|
||||
If ZMK doesn't support your keyboard by default, you have two options:
|
||||
|
||||
**Add a Module**
|
||||
|
||||
ZMK can be extended with [modules](features/modules.mdx) to add new keyboards. If someone has already created a module for your keyboard, run the following command to add it, replacing `<url>` with the URL of the Git repository for the module:
|
||||
|
||||
```sh
|
||||
zmk module add <url>
|
||||
```
|
||||
|
||||
For example, `zmk module add https://github.com/cannonkeys/zmk-cannonkeys-keyboards` would add support for CannonKeys keyboards.
|
||||
|
||||
Run `zmk keyboard add` again, and the new keyboards should appear in the list.
|
||||
|
||||
**Create It Yourself**
|
||||
|
||||
If nobody has created a module for your keyboard yet, or if it is your own custom design, you will need to set it up yourself. Your config repo is already set up as a module, so you can define new keyboards there. See ZMK's [new keyboard shield guide](development/hardware-integration/new-shield.mdx) for more information.
|
||||
|
||||
ZMK CLI can also help generate some of the boilerplate for defining a new keyboard:
|
||||
|
||||
```sh
|
||||
zmk keyboard new
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Edit Your Keymap and Configuration
|
||||
|
||||
See the [customizing ZMK](customization.md) documentation for instructions on editing your keymap and configuring ZMK settings.
|
||||
|
||||
As a shortcut to open your keymap in a text editor, you can run the following command, replacing `<keyboard>` with the ID of the keyboard you chose earlier:
|
||||
|
||||
```sh
|
||||
zmk code <keyboard>
|
||||
```
|
||||
|
||||
If you have an editor like [VS Code](https://code.visualstudio.com/) that can open a folder, you can also run the command without a keyboard ID to open your config repo directly:
|
||||
|
||||
```sh
|
||||
zmk code
|
||||
```
|
||||
|
||||
The first time you run this command, it will try to identify which text editors you have installed and ask you which one to use. If you want to change this later, change the [`core.editor`](zmk-cli.mdx#coreeditor) setting.
|
||||
|
||||
### Commit and Push to GitHub
|
||||
|
||||
After you've changed your keymap to your liking, you need to commit and push your changes.
|
||||
|
||||
Run the following commands to go to the repo directory, mark all your changed files to be added to the commit, create the commit, and push it to GitHub.
|
||||
|
||||
```sh
|
||||
zmk cd
|
||||
git add .
|
||||
git commit -m "Initial commit"
|
||||
git push
|
||||
```
|
||||
|
||||
The text after `-m` is the "commit message", which gives a name to the commit. This is your first commit, so we're calling it "initial commit" here, but you can name it whatever you like. When you make more commits later, it's a good idea to use the commit message to write a description of the changes you made.
|
||||
|
||||
:::warning
|
||||
|
||||
If the `git push` command asks you for a username and password, enter your GitHub username, but **do not enter your password**. Instead, paste your access token for the password. (Go back to the [GitHub account setup instructions](#set-up-a-github-account) if you need to create a token.)
|
||||
|
||||
:::
|
||||
|
||||
## Installing the Firmware
|
||||
## Install the Firmware
|
||||
|
||||
### Download the Archive
|
||||
|
||||
Once the setup script is complete and the new user config repository has been pushed, GitHub will automatically run the action
|
||||
to build your keyboard firmware files. You can view the actions by clicking on the "Actions" tab on your GitHub repository.
|
||||
Once you push a commit, GitHub will automatically run the action to build your keyboard firmware files. Run the following command to open the GitHub Actions page in your browser:
|
||||
|
||||
```sh
|
||||
zmk download
|
||||
```
|
||||
|
||||
Or, you can manually open your GitHub repository in your browser and click the "Actions" tab at the top.
|
||||
|
||||
|
||||
|
||||
|
|
@ -196,13 +351,13 @@ 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.
|
||||
Once downloaded, extract the zip and you can verify it should contain one or more `.uf2` or `.hex` files, which contain the firmware you need to write to your keyboard.
|
||||
|
||||
### Flashing UF2 Files
|
||||
### Flash 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.
|
||||
If your firmware contains a `.uf2` file, then you flash the new firmware by putting the keyboard into bootloader mode and copying the file directly to it in file explorer.
|
||||
|
||||
First, put your keyboard 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.
|
||||
|
||||
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 unmount the USB storage, automatically restart and load your newly
|
||||
|
|
@ -218,6 +373,12 @@ Please refer to [split keyboards documentation](features/split-keyboards.md) for
|
|||
|
||||
:::
|
||||
|
||||
### Flash Hex Files
|
||||
|
||||
If your firmware contains a `.hex` file, then you will use DFU to flash the firmware. [QMK Toolbox](https://qmk.fm/toolbox) is an easy-to-use tool with support for DFU flashing.
|
||||
|
||||
Open QMK Toolbox, click the "Open" button, and select the correct `.hex` file (e.g. left or right if working on a split). Consult the documentation for your keyboard to figure out how to enter bootloader or DFU mode (often this is done by pressing a pair of buttons on the keyboard or by holding a specific key as you plug in the USB cable), and once QMK Toolbox detects the keyboard, click "Flash" to flash the firmware.
|
||||
|
||||
## Wirelessly Connecting Your Keyboard
|
||||
|
||||
ZMK will automatically advertise itself as connectable if it is not currently connected to a device. You should be able to see your keyboard from the bluetooth scanning view of your computer or phone / tablet. It is reported by some users that the connections with Android / iOS devices are generally smoother than with laptops, so if you have trouble connecting, you could try to connect from your phone or tablet first to eliminate any potential hardware issues with bluetooth receivers.
|
||||
|
|
|
|||
|
|
@ -1,167 +1,24 @@
|
|||
---
|
||||
title: (EXPERIMENTAL) Installing ZMK
|
||||
sidebar_label: (EXPERIMENTAL) Installing ZMK
|
||||
title: ZMK CLI
|
||||
sidebar_label: ZMK CLI
|
||||
---
|
||||
|
||||
This is an **experimental** command line program to help set up ZMK. [Click here to return to the main documentation](user-setup.mdx).
|
||||
ZMK CLI is a command line tool which helps with setting up a ZMK config repo and automates some common tasks such as adding new keyboards to your repository.
|
||||
|
||||
ZMK CLI walks you through installing ZMK and setting up a GitHub repository to store and build custom firmware. It also automates some common tasks such as adding new keyboards to your repository.
|
||||
|
||||
The instructions below contain commands that need to be run in a terminal program. On Windows, use the [Windows Terminal](https://apps.microsoft.com/detail/9n0dx20hk701) or PowerShell. On other operating systems, the terminal program is usually just named "Terminal".
|
||||
|
||||
:::info
|
||||
If you use this program, any bug reports are highly appreciated. We are happy to help you fix your setup if you encounter a bug through the usage of this program.
|
||||
:::
|
||||
|
||||
## Installation
|
||||
|
||||
### Preliminaries
|
||||
|
||||
#### Make sure you have Git installed
|
||||
|
||||
The below commands should print a version number if the program is installed.
|
||||
|
||||
```sh
|
||||
git --version
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>I don't have Git installed.</summary>
|
||||
|
||||
Install Git from https://git-scm.com/downloads.
|
||||
|
||||
If you have Windows 11, you can instead open a terminal and run:
|
||||
|
||||
```sh
|
||||
winget install git.git
|
||||
```
|
||||
|
||||
Re-open your terminal and test to make sure it is now installed.
|
||||
|
||||
</details>
|
||||
|
||||
#### Make sure you have Python installed
|
||||
|
||||
ZMK CLI requires Python 3.10 or newer.
|
||||
|
||||
```sh
|
||||
python3 --version
|
||||
```
|
||||
|
||||
Note that some operating systems may use `python` in place of `python3`.
|
||||
|
||||
<details>
|
||||
<summary>I don't have Python 3.10 or newer installed.</summary>
|
||||
|
||||
##### On Windows and macOS
|
||||
|
||||
Install the latest version of Python from https://www.python.org/downloads/.
|
||||
|
||||
If you have Windows 11, you can instead open a terminal and run:
|
||||
|
||||
```sh
|
||||
winget install python3
|
||||
```
|
||||
|
||||
Re-open your terminal and test to make sure it is now installed.
|
||||
|
||||
##### On Linux
|
||||
|
||||
Install `python3` with your package manager.
|
||||
|
||||
If the version is older than 3.10, you will need to find and install a package for a newer version of Python. On Ubuntu 20.04 and older, you can get Python 3.10 from the deadsnakes PPA with the following commands:
|
||||
|
||||
```sh
|
||||
sudo add-apt-repository ppa:deadsnakes/ppa
|
||||
sudo apt install python3.10
|
||||
```
|
||||
|
||||
You will then need to replace `python3` with `python3.10` in the rest of the installation instructions.
|
||||
|
||||
Re-open your terminal and test to make sure it is now installed.
|
||||
|
||||
</details>
|
||||
|
||||
#### (Recommended) Make sure you have pipx installed
|
||||
|
||||
ZMK CLI can be installed with pip, but using [pipx](https://github.com/pypa/pipx) is recommended to avoid conflicts between Python packages.
|
||||
|
||||
```sh
|
||||
pipx --version
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>I don't have pipx installed.</summary>
|
||||
|
||||
### On Windows and Linux
|
||||
|
||||
Open a terminal and run:
|
||||
|
||||
```sh
|
||||
python3 -m pip install --user pipx
|
||||
python3 -m pipx ensurepath
|
||||
```
|
||||
|
||||
Some Linux distributions may disallow installing packages with pip. If this gives you an error, see the [install instructions](https://github.com/pypa/pipx?tab=readme-ov-file#on-linux) specific to your distribution.
|
||||
|
||||
Re-open your terminal and test to make sure it is now installed.
|
||||
|
||||
### On macOS
|
||||
|
||||
Open Terminal and run:
|
||||
|
||||
```sh
|
||||
brew install pipx
|
||||
pipx ensurepath
|
||||
```
|
||||
|
||||
Re-open your terminal and test to make sure it is now installed.
|
||||
|
||||
</details>
|
||||
|
||||
### Install ZMK CLI
|
||||
|
||||
Run the following commands:
|
||||
|
||||
```sh
|
||||
pipx install zmk
|
||||
zmk --help
|
||||
```
|
||||
|
||||
It should print a help message if everything installed correctly.
|
||||
|
||||
On Linux, you may get an error saying you need to install another package such as `python3.10-venv`. If so, follow the instructions in the error message, then try the above commands again.
|
||||
See the [ZMK installation guide](user-setup.mdx#prerequisites) for instructions on installing ZMK CLI.
|
||||
|
||||
## Using ZMK CLI
|
||||
|
||||
The instructions below contain commands that need to be run in a terminal program.
|
||||
|
||||
- On Windows, use [Windows Terminal](https://apps.microsoft.com/detail/9n0dx20hk701) or PowerShell.
|
||||
- On other operating systems, the terminal program is usually just named "Terminal".
|
||||
|
||||
All ZMK CLI commands start with `zmk`. Run `zmk --help` for general usage instructions. For help with a specific subcommand, add `--help` after the subcommand, e.g. `zmk init --help`.
|
||||
|
||||
### Initialize a Repository
|
||||
|
||||
:::warning
|
||||
If you have already created a repo and cloned it to your computer, you do not need to run this command. Set the [user.home](#userhome) setting to point to the existing repo instead.
|
||||
:::
|
||||
|
||||
The `zmk init` command walks you through creating a GitHub repository, then clones it to your computer so you can edit it.
|
||||
|
||||
Open a terminal and use the `cd` command to move to a directory where you'd like to place the ZMK files, then run `zmk init`. For example:
|
||||
|
||||
```sh
|
||||
cd ~/Documents
|
||||
zmk init
|
||||
```
|
||||
|
||||
Follow the instructions it gives you. If you already have a ZMK config repo, you can enter its URL when prompted, for example:
|
||||
|
||||
```
|
||||
Repository URL: https://github.com/myusername/zmk-config
|
||||
```
|
||||
|
||||
Otherwise, leave this first prompt blank and press <kbd>Enter</kbd>, and it will walk you through creating a new repo.
|
||||
|
||||
Once you finish following all the instructions, you will have a copy of the repo stored on your computer. All `zmk` commands will run on this repo (unless the working directory is inside a different repo). If you ever forget where the repo is located, you can run `zmk cd` to find it.
|
||||
|
||||
Now that you have a repo created, see the instructions below for how ZMK CLI can automate some common tasks, or see [Customizing ZMK](customization.md) for more hands-on customization information.
|
||||
The `zmk init` command walks you through creating a GitHub repository, then clones it to your computer so you can edit it. See the [ZMK installation guide](user-setup.mdx#config-repo-setup) for more details on this command.
|
||||
|
||||
### Keyboard Management
|
||||
|
||||
|
|
@ -194,12 +51,19 @@ This won't walk you through all of the details of adding support for a new keybo
|
|||
[Modules](features/modules.mdx) can add support for new keyboards, behaviors, and other features to ZMK. Use the `zmk module` command to install modules into your repo:
|
||||
|
||||
```sh
|
||||
zmk module add # Add a module
|
||||
zmk module remove # Remove an installed module
|
||||
zmk module list # List the installed modules
|
||||
zmk update # Update the local copies of ZMK and modules to their latest versions
|
||||
zmk module add # Add a module
|
||||
zmk module add <url> # Add a module given the URL of the repo
|
||||
zmk module remove # Remove an installed module
|
||||
zmk module list # List the installed modules
|
||||
zmk update # Update the local copies of ZMK and modules to their latest versions
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
ZMK CLI stores a copy of ZMK and any modules in a `.zmk` folder so it can read board and shield information from them. This folder is only used by ZMK CLI and is not necessary for building firmware, therefore ZMK CLI will automatically add it to your repo's `.gitignore` file.
|
||||
|
||||
:::
|
||||
|
||||
### Edit Keymap and Config Files
|
||||
|
||||
The `zmk code` command will open ZMK files in a text editor:
|
||||
|
|
@ -49,7 +49,6 @@ module.exports = {
|
|||
path.resolve(__dirname, "src/hardware-metadata-collection-plugin"),
|
||||
path.resolve(__dirname, "src/hardware-metadata-static-plugin"),
|
||||
path.resolve(__dirname, "src/hardware-schema-typescript-plugin"),
|
||||
path.resolve(__dirname, "src/setup-script-generation-plugin"),
|
||||
],
|
||||
themeConfig: {
|
||||
colorMode: {
|
||||
|
|
|
|||
|
|
@ -255,6 +255,7 @@
|
|||
"resolved": "https://registry.npmjs.org/@algolia/client-search/-/client-search-5.39.0.tgz",
|
||||
"integrity": "sha512-/IYpF10BpthGZEJQZMhMqV4AqWr5avcWfZm/SIKK1RvUDmzGqLoW/+xeJVX9C8ZnNkIC8hivbIQFaNaRw0BFZQ==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@algolia/client-common": "5.39.0",
|
||||
"@algolia/requester-browser-xhr": "5.39.0",
|
||||
|
|
@ -420,6 +421,7 @@
|
|||
"resolved": "https://registry.npmjs.org/@babel/core/-/core-7.28.4.tgz",
|
||||
"integrity": "sha512-2BCOP7TN8M+gVDj7/ht3hsaO/B/n5oDbiAyyvnRlNOs+u1o+JWNYTQrmpuNp1/Wq2gcFrI01JAW+paEKDMx/CA==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@babel/code-frame": "^7.27.1",
|
||||
"@babel/generator": "^7.28.3",
|
||||
|
|
@ -2257,6 +2259,7 @@
|
|||
}
|
||||
],
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
},
|
||||
|
|
@ -2279,6 +2282,7 @@
|
|||
}
|
||||
],
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
|
|
@ -2388,6 +2392,7 @@
|
|||
"resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz",
|
||||
"integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"cssesc": "^3.0.0",
|
||||
"util-deprecate": "^1.0.2"
|
||||
|
|
@ -2809,6 +2814,7 @@
|
|||
"resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz",
|
||||
"integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"cssesc": "^3.0.0",
|
||||
"util-deprecate": "^1.0.2"
|
||||
|
|
@ -3672,6 +3678,7 @@
|
|||
"resolved": "https://registry.npmjs.org/@docusaurus/plugin-content-docs/-/plugin-content-docs-3.9.1.tgz",
|
||||
"integrity": "sha512-DyLk9BIA6I9gPIuia8XIL+XIEbNnExam6AHzRsfrEq4zJr7k/DsWW7oi4aJMepDnL7jMRhpVcdsCxdjb0/A9xg==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@docusaurus/core": "3.9.1",
|
||||
"@docusaurus/logger": "3.9.1",
|
||||
|
|
@ -4307,6 +4314,7 @@
|
|||
"resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-svg-core/-/fontawesome-svg-core-6.7.2.tgz",
|
||||
"integrity": "sha512-yxtOBWDrdi5DD5o1pmVdq3WMCvnobT0LU6R8RyyVXPvFRd2o79/0NCuQoCjNTeZz9EzA9xS3JxNWfv54RIHFEA==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@fortawesome/fontawesome-common-types": "6.7.2"
|
||||
},
|
||||
|
|
@ -4752,6 +4760,7 @@
|
|||
"resolved": "https://registry.npmjs.org/@mdx-js/react/-/react-3.1.0.tgz",
|
||||
"integrity": "sha512-QjHtSaoameoalGnKDT3FoIl4+9RwyTmo9ZJGBdLOks/YOiWHoRDI3PUwEzOE7kEmGcV3AFcp9K6dYu9rEuKLAQ==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@types/mdx": "^2.0.0"
|
||||
},
|
||||
|
|
@ -5401,6 +5410,7 @@
|
|||
"resolved": "https://registry.npmjs.org/@svgr/core/-/core-8.1.0.tgz",
|
||||
"integrity": "sha512-8QqtOQT5ACVlmsvKOJNEaWmRPmcojMOzCz4Hs2BGG/toAp/K38LcsMRyLp349glq5AzJbCEeimEoxaX6v/fLrA==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@babel/core": "^7.21.3",
|
||||
"@svgr/babel-preset": "8.1.0",
|
||||
|
|
@ -6095,6 +6105,7 @@
|
|||
"resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.18.tgz",
|
||||
"integrity": "sha512-t4yC+vtgnkYjNSKlFx1jkAhH8LgTo2N/7Qvi83kdEaUtMDiwpbLAktKDaAMlRcJ5eSxZkH74eEGt1ky31d7kfQ==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@types/prop-types": "*",
|
||||
"csstype": "^3.0.2"
|
||||
|
|
@ -6276,6 +6287,7 @@
|
|||
"integrity": "sha512-H+vqmWwT5xoNrXqWs/fesmssOW70gxFlgcMlYcBaWNPIEWDgLa4W9nkSPmhuOgLnXq9QYgkZ31fhDyLhleCsAg==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@typescript-eslint/scope-manager": "8.30.1",
|
||||
"@typescript-eslint/types": "8.30.1",
|
||||
|
|
@ -6681,6 +6693,7 @@
|
|||
"resolved": "https://registry.npmjs.org/acorn/-/acorn-8.14.1.tgz",
|
||||
"integrity": "sha512-OvQ/2pUDKmgfCg++xsTX1wGxfTaszcHVcTctW4UJB4hibJx2HXxxO5UmVgyjMa+ZDsiaf5wWLXYpRWMmBI0QHg==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"bin": {
|
||||
"acorn": "bin/acorn"
|
||||
},
|
||||
|
|
@ -6754,6 +6767,7 @@
|
|||
"resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz",
|
||||
"integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"fast-deep-equal": "^3.1.1",
|
||||
"fast-json-stable-stringify": "^2.0.0",
|
||||
|
|
@ -6818,6 +6832,7 @@
|
|||
"resolved": "https://registry.npmjs.org/algoliasearch/-/algoliasearch-5.39.0.tgz",
|
||||
"integrity": "sha512-DzTfhUxzg9QBNGzU/0kZkxEV72TeA4MmPJ7RVfLnQwHNhhliPo7ynglEWJS791rNlLFoTyrKvkapwr/P3EXV9A==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@algolia/abtesting": "1.5.0",
|
||||
"@algolia/client-abtesting": "5.39.0",
|
||||
|
|
@ -7455,6 +7470,7 @@
|
|||
}
|
||||
],
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"baseline-browser-mapping": "^2.8.3",
|
||||
"caniuse-lite": "^1.0.30001741",
|
||||
|
|
@ -7754,6 +7770,7 @@
|
|||
"resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-11.0.3.tgz",
|
||||
"integrity": "sha512-ci2iJH6LeIkvP9eJW6gpueU8cnZhv85ELY8w8WiFtNjMHA5ad6pQLaJo9mEly/9qUyCpvqX8/POVUTf18/HFdw==",
|
||||
"license": "Apache-2.0",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@chevrotain/cst-dts-gen": "11.0.3",
|
||||
"@chevrotain/gast": "11.0.3",
|
||||
|
|
@ -8477,6 +8494,7 @@
|
|||
"resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz",
|
||||
"integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"cssesc": "^3.0.0",
|
||||
"util-deprecate": "^1.0.2"
|
||||
|
|
@ -8796,6 +8814,7 @@
|
|||
"resolved": "https://registry.npmjs.org/cytoscape/-/cytoscape-3.32.0.tgz",
|
||||
"integrity": "sha512-5JHBC9n75kz5851jeklCPmZWcg3hUe6sjqJvyk3+hVqFaKcHwHgxsjeN1yLmggoUc6STbtm9/NQyabQehfjvWQ==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"engines": {
|
||||
"node": ">=0.10"
|
||||
}
|
||||
|
|
@ -9205,6 +9224,7 @@
|
|||
"resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz",
|
||||
"integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==",
|
||||
"license": "ISC",
|
||||
"peer": true,
|
||||
"engines": {
|
||||
"node": ">=12"
|
||||
}
|
||||
|
|
@ -10127,6 +10147,7 @@
|
|||
"integrity": "sha512-jV7AbNoFPAY1EkFYpLq5bslU9NLNO8xnEeQXwErNibVryjk67wHVmddTBilc5srIttJDBrB0eMHKZBFbSIABCw==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@eslint-community/eslint-utils": "^4.2.0",
|
||||
"@eslint-community/regexpp": "^4.12.1",
|
||||
|
|
@ -17151,6 +17172,7 @@
|
|||
}
|
||||
],
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"nanoid": "^3.3.11",
|
||||
"picocolors": "^1.1.1",
|
||||
|
|
@ -18054,6 +18076,7 @@
|
|||
"resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz",
|
||||
"integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"cssesc": "^3.0.0",
|
||||
"util-deprecate": "^1.0.2"
|
||||
|
|
@ -18942,6 +18965,7 @@
|
|||
"resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
|
||||
"integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"loose-envify": "^1.1.0"
|
||||
},
|
||||
|
|
@ -18976,6 +19000,7 @@
|
|||
"resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
|
||||
"integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"loose-envify": "^1.1.0",
|
||||
"scheduler": "^0.23.2"
|
||||
|
|
@ -19032,6 +19057,7 @@
|
|||
"resolved": "https://registry.npmjs.org/@docusaurus/react-loadable/-/react-loadable-6.0.0.tgz",
|
||||
"integrity": "sha512-YMMxTUQV/QFSnbgrP3tjDzLHRg7vsbMn8e9HAa8o/1iXoiomo48b7sk/kkmWEuWNDPJVlKSJRB6Y2fHqdJk+SQ==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@types/react": "*"
|
||||
},
|
||||
|
|
@ -19060,6 +19086,7 @@
|
|||
"resolved": "https://registry.npmjs.org/react-router/-/react-router-5.3.4.tgz",
|
||||
"integrity": "sha512-Ys9K+ppnJah3QuaRiLxk+jDWOR1MekYQrlytiXxC1RyfbdsZkS5pvKAzCCr031xHixZwpnsYNT5xysdFHQaYsA==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@babel/runtime": "^7.12.13",
|
||||
"history": "^4.9.0",
|
||||
|
|
@ -19968,6 +19995,7 @@
|
|||
"resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz",
|
||||
"integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"fast-deep-equal": "^3.1.3",
|
||||
"fast-uri": "^3.0.1",
|
||||
|
|
@ -21288,6 +21316,7 @@
|
|||
"integrity": "sha512-M7BAV6Rlcy5u+m6oPhAPFgJTzAioX/6B0DxyvDlo9l8+T3nLKbrczg2WLUyzd45L8RqfUMyGPzekbMvX2Ldkwg==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"engines": {
|
||||
"node": ">=12"
|
||||
},
|
||||
|
|
@ -21433,7 +21462,8 @@
|
|||
"version": "2.8.1",
|
||||
"resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
|
||||
"integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
|
||||
"license": "0BSD"
|
||||
"license": "0BSD",
|
||||
"peer": true
|
||||
},
|
||||
"node_modules/type-check": {
|
||||
"version": "0.4.0",
|
||||
|
|
@ -21594,6 +21624,7 @@
|
|||
"integrity": "sha512-aJn6wq13/afZp/jT9QZmwEjDqqvSGp1VT5GVg+f/t6/oVyrgXM6BY1h9BRh/O5p3PlUPAe+WuiEZOmb/49RqoQ==",
|
||||
"devOptional": true,
|
||||
"license": "Apache-2.0",
|
||||
"peer": true,
|
||||
"bin": {
|
||||
"tsc": "bin/tsc",
|
||||
"tsserver": "bin/tsserver"
|
||||
|
|
@ -22551,6 +22582,7 @@
|
|||
"resolved": "https://registry.npmjs.org/webpack/-/webpack-5.98.0.tgz",
|
||||
"integrity": "sha512-UFynvx+gM44Gv9qFgj0acCQK2VE1CtdfwFdimkapco3hlPCJ/zeq73n2yVKimVbtm+TnApIugGhLJnkU6gjYXA==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@types/eslint-scope": "^3.7.7",
|
||||
"@types/estree": "^1.0.6",
|
||||
|
|
@ -23325,6 +23357,7 @@
|
|||
"resolved": "https://registry.npmjs.org/zod/-/zod-4.1.11.tgz",
|
||||
"integrity": "sha512-WPsqwxITS2tzx1bzhIKsEs19ABD5vmCVa4xBo2tq/SrV4RNZtfws1EnCWQXM6yh8bD08a1idvkB5MZSBiZsjwg==",
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"funding": {
|
||||
"url": "https://github.com/sponsors/colinhacks"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -13,6 +13,7 @@ module.exports = {
|
|||
"faq",
|
||||
"user-setup",
|
||||
"customization",
|
||||
"zmk-cli",
|
||||
{
|
||||
type: "category",
|
||||
label: "Troubleshooting",
|
||||
|
|
|
|||
|
|
@ -1,70 +0,0 @@
|
|||
/*
|
||||
* Copyright (c) 2021 The ZMK Contributors
|
||||
*
|
||||
* SPDX-License-Identifier: MIT
|
||||
*/
|
||||
|
||||
var PrebuildPlugin = require("prebuild-webpack-plugin");
|
||||
const path = require("path");
|
||||
const fs = require("fs");
|
||||
const glob = require("glob");
|
||||
const yaml = require("js-yaml");
|
||||
const Mustache = require("mustache");
|
||||
|
||||
function generateSetupScripts() {
|
||||
return glob("../app/boards/**/*.zmk.yml", (error, files) => {
|
||||
const aggregated = files.map((f) => ({
|
||||
...yaml.load(fs.readFileSync(f, "utf8")),
|
||||
__base_dir: path.basename(path.dirname(f)),
|
||||
}));
|
||||
|
||||
const data = aggregated.reduce(
|
||||
(agg, item) => {
|
||||
switch (item.type) {
|
||||
case "shield":
|
||||
item.compatible = true;
|
||||
item.split = item.siblings?.length > 1;
|
||||
agg.keyboards.push(item);
|
||||
break;
|
||||
case "board":
|
||||
if (item.features?.includes("keys")) {
|
||||
agg.keyboards.push(item);
|
||||
} else {
|
||||
item.usb_only = !item.outputs?.includes("ble");
|
||||
agg.boards.push(item);
|
||||
}
|
||||
break;
|
||||
}
|
||||
return agg;
|
||||
},
|
||||
{ keyboards: [], boards: [] }
|
||||
);
|
||||
|
||||
data.keyboards.sort((a, b) => a.name.localeCompare(b.name));
|
||||
data.boards.sort((a, b) => a.name.localeCompare(b.name));
|
||||
|
||||
for (let script_ext of ["sh", "ps1"]) {
|
||||
const templateBuffer = fs.readFileSync(
|
||||
`src/templates/setup.${script_ext}.mustache`,
|
||||
"utf8"
|
||||
);
|
||||
const script = Mustache.render(templateBuffer, data);
|
||||
fs.writeFileSync(`static/setup.${script_ext}`, script);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
module.exports = function () {
|
||||
return {
|
||||
name: "setup-script-generation-plugin",
|
||||
configureWebpack() {
|
||||
return {
|
||||
plugins: [
|
||||
new PrebuildPlugin({
|
||||
build: generateSetupScripts,
|
||||
}),
|
||||
],
|
||||
};
|
||||
},
|
||||
};
|
||||
};
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
|
||||
# Ignore generated setup script
|
||||
|
||||
setup.ps1
|
||||
setup.sh
|
||||
|
|
@ -22,4 +22,5 @@
|
|||
/docs/development/tests /docs/development/local-toolchain/tests 301
|
||||
/docs/development/guides/new-behavior /docs/development/new-behavior 301
|
||||
/docs/development/hardware-integration/studio-setup /docs/development/hardware-integration/physical-layouts 301
|
||||
/docs/keymaps/behaviors/mod-tap /docs/keymaps/behaviors/hold-tap#mod-tap
|
||||
/docs/keymaps/behaviors/mod-tap /docs/keymaps/behaviors/hold-tap#mod-tap
|
||||
/docs/user-setup-cli /docs/user-setup 301
|
||||
|
|
|
|||
Loading…
Reference in New Issue