Merge pull request #4 from zmkfirmware/docs/better-dev-setup-instructions
Improved dev setup docs.
This commit is contained in:
Pete Johanson
GitHub
commit
b83b8c6a69
3 changed files with 237 additions and 9 deletions
|
|
@ -1,11 +1,11 @@
|
|||
# Zephyr Mechanical Keyboard (ZMK) Firmware
|
||||
# Zephyr™ Mechanical Keyboard (ZMK) Firmware
|
||||
|
||||
[](https://github.com/zmkfirmware/zmk/actions)
|
||||
|
||||
[](https://app.netlify.com/sites/zmk/deploys)
|
||||
|
||||
This project is a complete work in progress, with absolutely nothing functioning yet. The goal is to explore a new MK firmware
|
||||
with a less restritive license and better BLE support, built on top of the [Zephyr Project](https://www.zephyrproject.org/)
|
||||
with a less restritive license and better BLE support, built on top of the [Zephyr™ Project](https://www.zephyrproject.org/)
|
||||
|
||||
Basic WIP website to learn more: https://zmk.netlify.app/
|
||||
|
||||
|
|
|
|||
|
|
@ -4,9 +4,237 @@ title: Basic Setup
|
|||
sidebar_label: Basic Setup
|
||||
---
|
||||
|
||||
1. Install `west` from pip.
|
||||
1. Install the ARM SDK from Zephyr project.
|
||||
1. (Optional) Install 32-bit libs for building and testing locally.
|
||||
1. `west init -l zmk`
|
||||
1. Build it.
|
||||
1. Flash it.
|
||||
## Prerequisites
|
||||
|
||||
A unix-like environment with the following base packages installed:
|
||||
|
||||
- Git
|
||||
- Python 3
|
||||
- `pip`
|
||||
- `wget`
|
||||
- devicetree compiler
|
||||
- CMake
|
||||
- `dfu-util`
|
||||
- Various build essentials, e.g. gcc, automake, autoconf
|
||||
|
||||
### Debian/Ubuntu
|
||||
|
||||
On Debian and Ubuntu, we'll use apt to install our base dependencies:
|
||||
|
||||
#### Apt Update
|
||||
|
||||
First, if you haven't updated recently, or if this is a new install from WSL,
|
||||
you should update to get the latest package information:
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
```
|
||||
|
||||
#### Install Dependencies
|
||||
|
||||
With the latest package information, you can now install the base dependencies:
|
||||
|
||||
```bash
|
||||
sudo apt install -y \
|
||||
git \
|
||||
wget \
|
||||
autoconf \
|
||||
automake \
|
||||
build-essential \
|
||||
ccache \
|
||||
device-tree-compiler \
|
||||
dfu-util \
|
||||
g++ \
|
||||
gcc \
|
||||
gcc-multilib \
|
||||
libtool \
|
||||
make \
|
||||
ninja-build \
|
||||
cmake \
|
||||
python3-dev \
|
||||
python3-pip \
|
||||
python3-setuptools \
|
||||
xz-utils
|
||||
```
|
||||
|
||||
:::note
|
||||
Ubuntu 18.04 LTS release packages a version of CMake that is too old. Please upgrade to Ubuntu 20.04 LTS
|
||||
or download and install CMake version 3.13.1 or newer manually.
|
||||
:::
|
||||
|
||||
### Fedora
|
||||
|
||||
TODO
|
||||
|
||||
### macOS
|
||||
|
||||
TODO
|
||||
|
||||
### WSL
|
||||
|
||||
Windows Subsystem for Linux can use various Linux distributions. Find a WSL installation on the [Windows Store](https://aka.ms/wslstore).
|
||||
|
||||
After installing your preferred flavor, follow the directions above on [Debian/Ubuntu](#debianubuntu) or [Fedora](#fedora).
|
||||
|
||||
:::note
|
||||
On WSL2 don't put the project files into `/mnt/c/` as file I/O speeds are extremely slow. Instead, run everything in the Linux system and use `cp` to move files over to `/mnt/c/` as needed.
|
||||
:::
|
||||
|
||||
## Setup
|
||||
|
||||
### West Build Command
|
||||
|
||||
`west` is the [Zephyr™ meta-tool](https://docs.zephyrproject.org/latest/guides/west/index.html) used to configure and build Zephyr™ applications. It can be installed by using the `pip` python package manager:
|
||||
|
||||
```bash
|
||||
pip3 install --user west
|
||||
```
|
||||
|
||||
:::note
|
||||
If you don't already have it configured, you may need to update your
|
||||
`PATH` to include the pip install path. See [User Installs](https://pip.pypa.io/en/stable/user_guide/#user-installs) and [Stack Overflow](https://stackoverflow.com/questions/38112756/how-do-i-access-packages-installed-by-pip-user) for more details.
|
||||
:::
|
||||
|
||||
### Zephyr™ ARM SDK
|
||||
|
||||
To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system:
|
||||
|
||||
```
|
||||
export ZSDK_VERSION=0.11.2
|
||||
wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \
|
||||
sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \
|
||||
rm "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run"
|
||||
```
|
||||
|
||||
The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults shouldn normally work as expected.
|
||||
|
||||
### Source Code
|
||||
|
||||
Next, you'll need to clone the ZMK source repository if you haven't already:
|
||||
|
||||
```
|
||||
git clone https://github.com/zmkfirmware/zmk.git
|
||||
```
|
||||
|
||||
### Initialize & Update Zephyr Workspace
|
||||
|
||||
Since ZMK is built as a Zephyr™ application, the next step is
|
||||
to use `west` to initialize and update your workspace. The ZMK
|
||||
Zephyr™ application is in the `app/` source directory:
|
||||
|
||||
#### Step into the repository
|
||||
|
||||
```bash
|
||||
cd zmk
|
||||
```
|
||||
|
||||
#### Initialize West
|
||||
|
||||
```bash
|
||||
west init -l app/
|
||||
```
|
||||
|
||||
:::note
|
||||
If you encounter errors like `command not found: west` then your `PATH` environment variable is likely
|
||||
missing the Python 3 user packages directory. See the [West Build Command](#west-build-command)
|
||||
section again for links to how to do this
|
||||
:::
|
||||
|
||||
#### Update To Fetch Modules
|
||||
|
||||
```bash
|
||||
west update
|
||||
```
|
||||
|
||||
#### Export Zephyr™ Core
|
||||
|
||||
```bash
|
||||
west zephyr-export
|
||||
```
|
||||
|
||||
#### Install Zephyr Python Dependencies
|
||||
|
||||
```bash
|
||||
pip3 install --user -r zephyr/scripts/requirements.txt
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
By default, the Zephyr™ SDK will create a file named `~/.zephyrrc` with the correct environment variables to build ZMK.
|
||||
We suggest two main [options](https://docs.zephyrproject.org/latest/guides/env_vars.html?highlight=zephyrrc) for how to load those settings.
|
||||
|
||||
#### Per Shell
|
||||
|
||||
To load the Zephyr environment properly for just one transient shell, run the following from your ZMK checkout directory:
|
||||
|
||||
```
|
||||
source zephyr/zephyr-env.sh
|
||||
```
|
||||
|
||||
#### All Shells
|
||||
|
||||
To load the environment variables for your shell every time,
|
||||
append the existing `~/.zephyrrc` file to your shell's RC file and then start a new shell.
|
||||
|
||||
##### Bash
|
||||
|
||||
```
|
||||
cat ~/.zephyrrc >> ~/.bashrc
|
||||
```
|
||||
|
||||
##### ZSH
|
||||
|
||||
```
|
||||
cat ~/.zephyrrc >> ~/.zshrc
|
||||
```
|
||||
|
||||
## Build
|
||||
|
||||
From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout:
|
||||
|
||||
```bash
|
||||
cd app
|
||||
```
|
||||
|
||||
To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with
|
||||
an onboard MCU, or one that uses a MCU board addon.
|
||||
|
||||
### Keyboard (Shield) + MCU Board
|
||||
|
||||
ZMK treats keyboards that take a MCU addon board as [shields](https://docs.zephyrproject.org/latest/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/latest/guides/porting/board_porting.html)
|
||||
|
||||
Given the following:
|
||||
|
||||
- MCU Board: Proton-C
|
||||
- Keyboard PCB: kyria
|
||||
- Keymap: default
|
||||
|
||||
You can build ZMK with the following:
|
||||
|
||||
```bash
|
||||
west build -b proton_c -- -DSHIELD=kyria -DKEYMAP=default
|
||||
```
|
||||
|
||||
### Keyboard With Onboard MCU
|
||||
|
||||
Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/latest/guides/porting/board_porting.html) as far as Zephyr™ is concerned.
|
||||
|
||||
Given the following:
|
||||
|
||||
- Keyboard: Planck
|
||||
- Keymap: default
|
||||
|
||||
you can build ZMK with the following:
|
||||
|
||||
```bash
|
||||
west build -b planck -- -DKEYMAP=default
|
||||
```
|
||||
|
||||
## Flashing
|
||||
|
||||
Once built, the previously supplied parameters will be remember, so you can simply run the following to flash your
|
||||
board, with it in bootloader mode:
|
||||
|
||||
```
|
||||
west flash
|
||||
```
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ sidebar_label: Introduction
|
|||
---
|
||||
|
||||
ZMK Firmware is an open source (MIT) keyboard
|
||||
firmware built on the [Zephyr Project](https://zephyrproject.com/) RTOS.
|
||||
firmware built on the [Zephyr™ Project](https://zephyrproject.com/) RTOS.
|
||||
|
||||
The goal is to provider a powerful, featureful keyboard firmware that is free
|
||||
of licensing issues that prevent upstream BLE support as a first-class
|
||||
|
|
|
|||
Loading…
Reference in a new issue