Browse Source

Initial user setup docs, setup script fixes.

xmkb
Pete Johanson 4 years ago
parent
commit
fedd4381c2
  1. 147
      docs/docs/user-setup.md
  2. 2
      docs/sidebars.js
  3. 11
      docs/static/setup.sh

147
docs/docs/user-setup.md

@ -0,0 +1,147 @@
---
id: user-setup
title: Installing ZMK
sidebar_label: Installing ZMK
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Unless 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, a focus has been made on avoiding requiring end users who don't intend to develop
new ZMK features from having to install a plethora of complicated dependencies just to use ZMK.
## Summary
The following steps can be taken to obtain an installable firmware image for your device, without the need
to install any compiler or specialized toolchain. This is possible by leveraging [GitHub Actions](https://github.com/features/actions)
to build your firmware for you in the cloud, which you can then download and flash to your device.
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 prequisites:
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.
## GitHub Repo
Before running the setup script, 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"
## User Config Setup Script
To start the setup process, run the following from your command line prompt:
<Tabs
defaultValue="curl"
values={[
{label: 'Using curl', value: 'curl'},
{label: 'Using wget', value: 'wget'},
]}>
<Tab value="curl">
```
sh -c "$(curl -fsSL https://zmkfirmware.dev/setup.sh)"
```
</Tab>
<Tab value="wget">
```
sh -c "$(wget https://zmkfirmware.dev/setup.sh -O -)"
```
</Tab>
</Tabs>
### MCU Board Selection
When prompted, enter the number for the corresponding MCU board you would like to target:
```
MCU Board Selection:
1) nice!nano
2) QMK Proton-C
3) Quit
Pick an MCU board:
```
### Keyboard Shield Selection
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:
```
### 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`.
### 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.
:::
## Accessing Built Firmware
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.
## Keymap Changes
TODO: Document how to add your own keymap!

2
docs/sidebars.js

@ -1,6 +1,6 @@
module.exports = { module.exports = {
someSidebar: { someSidebar: {
"Getting Started": ["intro", "faq", "hardware"], "Getting Started": ["intro", "hardware", "user-setup", "faq"],
Development: [ Development: [
"dev-clean-room", "dev-clean-room",
"dev-setup", "dev-setup",

11
docs/static/setup.sh vendored

@ -39,6 +39,8 @@ prompt="Pick an keyboard:"
options=("Kyria" "Lily58") options=("Kyria" "Lily58")
PS3="$prompt " PS3="$prompt "
# TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos.
# select opt in "${options[@]}" "Other" "Quit"; do
select opt in "${options[@]}" "Other" "Quit"; do select opt in "${options[@]}" "Other" "Quit"; do
case "$REPLY" in case "$REPLY" in
@ -47,8 +49,8 @@ select opt in "${options[@]}" "Other" "Quit"; do
2 ) shield_title="Lily58" shield="lily58"; split="y"; break;; 2 ) shield_title="Lily58" shield="lily58"; split="y"; break;;
# Add link to docs on adding your own custom shield in your ZMK config! # Add link to docs on adding your own custom shield in your ZMK config!
$(( ${#options[@]}+1 )) ) echo "Other!"; break;; # $(( ${#options[@]}+1 )) ) echo "Other!"; break;;
$(( ${#options[@]}+2 )) ) echo "Goodbye!"; exit;; $(( ${#options[@]}+1 )) ) echo "Goodbye!"; exit;;
*) echo "Invalid option. Try another one.";continue;; *) echo "Invalid option. Try another one.";continue;;
esac esac
@ -101,4 +103,9 @@ git commit -m "Initial User Config."
if [ -n "$github_repo" ]; then if [ -n "$github_repo" ]; then
git remote add origin "$github_repo" git remote add origin "$github_repo"
git push --set-upstream origin $(git branch --show-current) git push --set-upstream origin $(git branch --show-current)
# TODO: Support determing the actions URL when non-https:// repo URL is used.
if [ "${github_repo}" != "${github_repo#https://}" ]; then
echo "Your firmware should be available from the GitHub Actions shortly: ${github_url%.git}/actions"
fi
fi fi

Loading…
Cancel
Save