Improve user setup process
Changed the user setup documentation to use a new setup process where users create the repo from the template repo, then run one of two new tools to add a keyboard to it: - In a web browser, using github.dev and the ZMK Tools extension. - Locally, using a new Python setup script. Also made various other improvements to the setup documentation, such as including instructions for flashing keyboards that use DFU instead of UF2.
This commit is contained in:
Joel Spadin
parent
391f80f069
commit
76c437647e
5 changed files with 175 additions and 135 deletions
BIN
docs/docs/assets/user-setup/add-keyboard-command.png
Normal file
BIN
docs/docs/assets/user-setup/add-keyboard-command.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.4 KiB |
BIN
docs/docs/assets/user-setup/commit-and-push.png
Normal file
BIN
docs/docs/assets/user-setup/commit-and-push.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
BIN
docs/docs/assets/user-setup/keyboard-list.png
Normal file
BIN
docs/docs/assets/user-setup/keyboard-list.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.9 KiB |
BIN
docs/docs/assets/user-setup/stage-all-changes.png
Normal file
BIN
docs/docs/assets/user-setup/stage-all-changes.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
|
|
@ -21,161 +21,176 @@ 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. 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.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The remainder of this guide assumes the following prerequisites:
|
||||
|
||||
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.
|
||||
|
||||
:::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.
|
||||
:::
|
||||
1. Run an automated tool which will prompt you for a keyboard (e.g. Lily58 or Kyria) and MCU board (e.g. nice!nano) and add the necessary files to your repository.
|
||||
1. Change your keymap and/or configuration files to enable/disable optional ZMK features.
|
||||
1. Commit and push the updates to trigger a new Github Action to run.
|
||||
|
||||
## GitHub Repo
|
||||
|
||||
Before running the setup script, you will first need to create a new GitHub repository to host the config.
|
||||
Before running the setup tool, you will first need to create a new GitHub repository to host the config.
|
||||
|
||||
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"
|
||||
1. Create a [GitHub](https://github.com/) account if necessary and log in.
|
||||
1. Navigate to [https://github.com/zmkfirmware/unified-zmk-config-template](https://github.com/zmkfirmware/unified-zmk-config-template).
|
||||
1. Click "Use this template".
|
||||
1. Enter a repository name, for example `zmk-config`. You may also make the repository private if you like.
|
||||
1. Click "Create repository from template".
|
||||
1. Keep this browser tab open. You will need the repository URL in a later step.
|
||||
|
||||
## User Config Setup Script
|
||||
## User Config Setup
|
||||
|
||||
To start the setup process, run the following from your command line prompt:
|
||||
There are two ways to quickly set up your user config repository:
|
||||
|
||||
1. In a web browser using [github.dev](https://github.dev/).
|
||||
1. On your PC by downloading and running a Python script. This option requires more work to set up, but you can use your text editor of choice to edit keymaps.
|
||||
|
||||
<Tabs
|
||||
defaultValue="curl"
|
||||
defaultValue="browser"
|
||||
values={[
|
||||
{label: 'Using curl', value: 'curl'},
|
||||
{label: 'Using wget', value: 'wget'},
|
||||
{label: 'Using PowerShell', value: 'PowerShell'},
|
||||
{label: "Web Browser Setup", value: "browser"},
|
||||
{label: "Local Setup", value: "local"},
|
||||
]}>
|
||||
<TabItem value="curl">
|
||||
<TabItem value="browser">
|
||||
|
||||
In your web browser, go to your repository's page on GitHub and press the `.` (period) key or swap `.com` for `.dev` in the URL to open it in a web-based instance of Visual Studio Code.
|
||||
|
||||
Next, press `Ctrl+P`, paste the following command in the command palette that appears at the top, and press `Enter` to install the ZMK Tools extension.
|
||||
|
||||
```
|
||||
bash -c "$(curl -fsSL https://zmk.dev/setup.sh)"
|
||||
ext install spadin.zmk-tools
|
||||
```
|
||||
|
||||
### Keyboard Selection (Browser)
|
||||
|
||||
With the extension installed, press `Ctrl+Shift+P` and run the `ZMK: Add Keyboard` command from the command palette.
|
||||
|
||||
|
||||
|
||||
When prompted, select your keyboard from the list. If your keyboard requires a controller, you will be prompted to select that as well.
|
||||
|
||||
|
||||
|
||||
The extension will copy the necessary files to the `config` directory in your repository, update the GitHub Actions file, and open the keymap for editing.
|
||||
|
||||
:::note
|
||||
If you are building firmware for a new keyboard that is not included in the built-in list, see the [guide for adding a new keyboard shield](development/new-shield.md) instead.
|
||||
:::
|
||||
|
||||
### Committing and Pushing Changes (Browser)
|
||||
|
||||
Your changes are not saved to GitHub until you commit and push them. To do this:
|
||||
|
||||
1. Press `Ctrl+Shift+G` or click the "Source Control" tab on the left to see a list of pending changes.
|
||||
1. Hover your mouse over "Changes" above the list of changed files and click the `+` (Stage All Changes) button on the right.
|
||||
|
||||
|
||||
|
||||
1. Type a description of the change in the "Message" box.
|
||||
1. Click the `✓` (Commit and Push) button at the top.
|
||||
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="wget">
|
||||
<TabItem value="local">
|
||||
|
||||
```
|
||||
bash -c "$(wget https://zmk.dev/setup.sh -O -)" '' --wget
|
||||
Local setup requires the following prerequisites:
|
||||
|
||||
1. You have installed and configured the [Git](https://git-scm.com/) version control tool.
|
||||
1. You have 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.
|
||||
1. Python is installed.
|
||||
|
||||
Python is typically installed by default on Linux and macOS. For Windows, you can [install it from the Microsoft Store](https://www.microsoft.com/store/productId/9PJPW5LDXLZ5), or you can find install instructions for all OSes on [the Python website](https://www.python.org/downloads/).
|
||||
|
||||
:::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 with Git.
|
||||
:::
|
||||
|
||||
Next, download the ZMK setup script by opening a terminal window and running the following command. On Windows, use [Windows Terminal](https://www.microsoft.com/store/productId/9N0DX20HK701), Command Prompt, or PowerShell.
|
||||
|
||||
```sh
|
||||
pip3 install --user --upgrade zmk.setup
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="PowerShell">
|
||||
Run the following command to start the the setup script. If this does not work, try replacing `python3` with `python`.
|
||||
|
||||
```sh
|
||||
python3 -m zmk.setup
|
||||
```
|
||||
|
||||
The script will now ask you for your repository's URL. In your web browser, go to your repository's page and click the green "Code" button. Copy the URL shown there and paste it into the terminal (depending on the terminal used, this may be done with `Ctrl+V`, `Ctrl+Shift+V`, or right click). Press `Enter` and the script will clone the repository to your PC in a directory named after the repo name.
|
||||
|
||||
```
|
||||
powershell -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://zmk.dev/setup.ps1'))"
|
||||
Next, go to your repo page on GitHub and click the "Code" button. Copy the
|
||||
repo URL and paste it here (Ctrl+Shift+V or right click).
|
||||
|
||||
Repo URL: https://github.com/petejohanson/zmk-config.git
|
||||
```
|
||||
|
||||
:::note
|
||||
If you are using SSH keys for Git authentication, change to the SSH tab and paste that instead, e.g. `git@github.com:petejohanson/zmk-config.git`.
|
||||
:::
|
||||
|
||||
### Keyboard Selection (Local)
|
||||
|
||||
When prompted, select your keyboard from the list using the arrow keys and press `Enter`. If your keyboard requires a controller, you will be prompted to select that as well.
|
||||
|
||||
```
|
||||
Pick a keyboard:
|
||||
> 2% Milk
|
||||
A. Dux
|
||||
BAT43
|
||||
BDN9 Rev2
|
||||
BFO-9000
|
||||
```
|
||||
|
||||
:::note
|
||||
If you are building firmware for a new keyboard that is not included in the built-in list, you can choose any keyboard from the list that is similar to yours to generate the repository, then edit or add necessary files according to the [guide for adding a new keyboard shield](development/new-shield.md).
|
||||
:::
|
||||
|
||||
### Confirming Selections (Local)
|
||||
|
||||
The setup script will confirm all of your selections one last time before making changes to the repository:
|
||||
|
||||
```
|
||||
Adding the following to your user config repo:
|
||||
- Shield: Kyria (kyria_left kyria_right)
|
||||
- MCU Board: nice!nano v2 (nice_nano_v2)
|
||||
- Repo URL: https://github.com/petejohanson/zmk-config.git
|
||||
|
||||
Continue?
|
||||
> Yes
|
||||
No
|
||||
```
|
||||
|
||||
After selecting "Yes" and pressing `Enter`, the script will copy the necessary files to the `config` directory in your repository, update the GitHub Action YAML file, make a commit, and then push it to GitHub.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
You can now edit the keymap and configuration files in your text editor of choice.
|
||||
|
||||
### Committing and Pushing Changes (Local)
|
||||
|
||||
The setup script will automatically commit and push changes to add new keyboards. However, if you edit keymap or configuration files, your changes are not saved to GitHub until you commit and push them. To do this, use the `cd` command to navigate to the repository, then run the following commands:
|
||||
|
||||
```sh
|
||||
git add .
|
||||
git commit -m "Type a description of the change here"
|
||||
git push
|
||||
```
|
||||
|
||||
### Adding More Keyboards (Local)
|
||||
|
||||
To add another keyboard to the same repository, use the `cd` command to navigate to the repository and run the setup script again. The script will recognize that you are already in a ZMK user config repository, so you will not need to clone it again.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### MCU Board Selection
|
||||
## Installing the Firmware
|
||||
|
||||
When prompted, enter the number for the corresponding MCU board you would like to target:
|
||||
### Downloading the Archive
|
||||
|
||||
```
|
||||
MCU Board Selection:
|
||||
1) nice!nano
|
||||
2) QMK Proton-C
|
||||
3) Quit
|
||||
Pick an MCU board:
|
||||
```
|
||||
|
||||
### Keyboard Shield Selection
|
||||
|
||||
:::note
|
||||
If you are building firmware for a new keyboard shield that is not included in the built-in
|
||||
list of shields, you can choose any shield from the list that is similar to yours to generate the repository,
|
||||
and edit / add necessary files according to the [guide for adding new keyboard shield](development/new-shield.md).
|
||||
:::
|
||||
|
||||
When prompted, enter the number for the corresponding keyboard shield you would like to target:
|
||||
|
||||
```
|
||||
Keyboard Shield Selection:
|
||||
1) Kyria
|
||||
2) Lily58
|
||||
3) Quit
|
||||
Pick an keyboard:
|
||||
```
|
||||
|
||||
### Keymap Customization
|
||||
|
||||
At the next prompt, you have an opportunity to decide if you want the stock keymap file copied in
|
||||
for further customization:
|
||||
|
||||
```
|
||||
Copy in the stock keymap for customization? [Yn]:
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
GitHub Username (leave empty to skip GitHub repo creation): petejohanson
|
||||
GitHub Repo Name: zmk-config
|
||||
GitHub Repo: https://github.com/petejohanson/zmk-config.git
|
||||
```
|
||||
|
||||
Only the GitHub username is required; if you are happy with the defaults offered in the square brackets, you can simply hit `Enter`.
|
||||
|
||||
:::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`.
|
||||
:::
|
||||
|
||||
### Confirming Selections
|
||||
|
||||
The setup script will confirm all of your selections one last time, before performing the setup:
|
||||
|
||||
```
|
||||
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]:
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
:::info
|
||||
|
||||
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.
|
||||
|
||||
:::
|
||||
|
||||
## Installing 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.
|
||||
Every time you push a change to your user config repository, 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.
|
||||
|
||||
|
||||
|
||||
|
|
@ -184,16 +199,41 @@ 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.
|
||||
Download and extract the zip archive. It should contain one or more `.uf2` or `.bin` files.
|
||||
|
||||
### Flashing UF2 Files
|
||||
### Flashing Firmware
|
||||
|
||||
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.
|
||||
You will use a different process for flashing depending on the type of files in the firmware archive.
|
||||
|
||||
Once this happens, copy the correct UF2 file (e.g. left or right if working on a split), and paste it onto the root of that USB mass
|
||||
storage device. Once the flash is complete, the controller should automatically restart, and load your newly flashed firmware.
|
||||
<Tabs
|
||||
defaultValue="uf2"
|
||||
values={[
|
||||
{label: "UF2 Files", value: "uf2"},
|
||||
{label: "Bin Files", value: "bin"},
|
||||
]}>
|
||||
<TabItem value="uf2">
|
||||
|
||||
To flash UF2 firmware, first connect your keyboard to your PC with a USB cable and put it 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 automatically restart and run your newly flashed firmware.
|
||||
|
||||
:::note
|
||||
There is a known issue with the Adafruit nrf52 bootloader where it may reboot into the new firmware before reporting the copy as complete. If your OS says the copy failed, it usually does not mean the firmware failed to flash.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="bin">
|
||||
|
||||
If your firmware archive only contains `.bin` files, your controller likely uses DFU to update firmware. [QMK Toolbox](https://github.com/qmk/qmk_toolbox) is an easy to use flashing tool which supports DFU.
|
||||
|
||||
Grab the latest version for your OS from the [releases page](https://github.com/qmk/qmk_toolbox/releases) and run the application. Drag and drop the correct Bin file (e.g. left or right if working on a split) onto the window, or click the "Open" button and select the file to flash.
|
||||
|
||||
Connect your keyboard to your PC with a USB cable, and check the log window at the bottom to see if QMK Toolbox has detected your keyboard. If not, you may need to put the keyboard into a bootloader or DFU mode. Consult the documentation for your keyboard or MCU board for how to do this. It is typically done with a dedicated "bootloader" button, by pressing a combination of buttons, or by double clicking or holding a reset button.
|
||||
|
||||
Once your keyboard is detected, press the "Flash" button to flash the new firmware.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Wirelessly Connecting Your Keyboard
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue