Pete Johanson
4 years ago
committed by
GitHub
19 changed files with 231 additions and 99 deletions
|
After Width: | Height: | Size: 2.4 MiB |
|
After Width: | Height: | Size: 17 KiB |
|
After Width: | Height: | Size: 7.7 KiB |
|
After Width: | Height: | Size: 60 KiB |
|
After Width: | Height: | Size: 50 KiB |
|
After Width: | Height: | Size: 7.1 KiB |
|
After Width: | Height: | Size: 11 KiB |
|
After Width: | Height: | Size: 157 KiB |
@ -0,0 +1,33 @@ |
|||||||
|
--- |
||||||
|
id: customization |
||||||
|
title: Customizing ZMK |
||||||
|
sidebar_label: Customizing ZMK |
||||||
|
--- |
||||||
|
|
||||||
|
After verifying you can successfully flash the default firmware, you will probably want to begin customizing your keymap and other keyboard options. |
||||||
|
|
||||||
|
## Configuration Changes |
||||||
|
|
||||||
|
The setup script creates a `config/<shield>.conf` file that allows you to add additional configuration options to |
||||||
|
control what features and options are built into your firmware. Opening that file with your text editor will allow you to see the |
||||||
|
various config settings that can be commented/uncommented to modify how your firmware is built. |
||||||
|
|
||||||
|
## Keymap |
||||||
|
|
||||||
|
Once you have the basic user config completed, you can find the keymap file in `config/<shield>.keymap` and customize from there. |
||||||
|
Refer to the [Keymap](/docs/feature/keymaps) documentation to learn more. |
||||||
|
|
||||||
|
## Publishing |
||||||
|
|
||||||
|
After making any changes you want, you should commit the changes and then push them to GitHub. That will trigger a new |
||||||
|
GitHub Actions job to build your firmware which you can download once it completes. |
||||||
|
|
||||||
|
:::note |
||||||
|
If you need to, a review 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 these steps right. |
||||||
|
::: |
||||||
|
|
||||||
|
## Flashing Your Changes |
||||||
|
|
||||||
|
For normal keyboards, follow the same flashing instructions as before to flash your updated firmware. |
||||||
|
|
||||||
|
For split keyboards, only the central (left) side will need to be reflashed if you are just updating your keymap. |
||||||
@ -0,0 +1,96 @@ |
|||||||
|
--- |
||||||
|
id: dev-build-flash |
||||||
|
title: Building and Flashing |
||||||
|
sidebar_label: Building and Flashing |
||||||
|
--- |
||||||
|
|
||||||
|
import Tabs from '@theme/Tabs'; |
||||||
|
import TabItem from '@theme/TabItem'; |
||||||
|
|
||||||
|
export const OsTabs = (props) => (<Tabs |
||||||
|
groupId="operating-systems" |
||||||
|
defaultValue="debian" |
||||||
|
values={[ |
||||||
|
{label: 'Debian/Ubuntu', value: 'debian'}, |
||||||
|
{label: 'Raspberry OS', value: 'raspberryos'}, |
||||||
|
{label: 'Fedora', value: 'fedora'}, |
||||||
|
{label: 'Windows', value: 'win'}, |
||||||
|
{label: 'macOS', value: 'mac'}, |
||||||
|
] |
||||||
|
}>{props.children}</Tabs>); |
||||||
|
|
||||||
|
## Building |
||||||
|
|
||||||
|
From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout: |
||||||
|
|
||||||
|
```sh |
||||||
|
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 an MCU board addon. |
||||||
|
|
||||||
|
### Keyboard (Shield) + MCU Board |
||||||
|
|
||||||
|
ZMK treats keyboards that take an MCU addon board as [shields](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) |
||||||
|
|
||||||
|
Given the following: |
||||||
|
|
||||||
|
- MCU Board: Proton-C |
||||||
|
- Keyboard PCB: kyria_left |
||||||
|
- Keymap: default |
||||||
|
|
||||||
|
You can build ZMK with the following: |
||||||
|
|
||||||
|
```sh |
||||||
|
west build -b proton_c -- -DSHIELD=kyria_left |
||||||
|
``` |
||||||
|
|
||||||
|
### Keyboard With Onboard MCU |
||||||
|
|
||||||
|
Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) as far as Zephyr™ is concerned. |
||||||
|
|
||||||
|
Given the following: |
||||||
|
|
||||||
|
- Keyboard: Planck (rev6) |
||||||
|
- Keymap: default |
||||||
|
|
||||||
|
you can build ZMK with the following: |
||||||
|
|
||||||
|
```sh |
||||||
|
west build -b planck_rev6 |
||||||
|
``` |
||||||
|
|
||||||
|
### Pristine Building |
||||||
|
When building for a new board and/or shield after having built one previously, you may need to enable the pristine build option. This option removes all existing files in the build directory before regenerating them, and can be enabled by adding either --pristine or -p to the command: |
||||||
|
|
||||||
|
```sh |
||||||
|
west build -p -b proton_c -- -DSHIELD=kyria_left |
||||||
|
``` |
||||||
|
### Building For Split Keyboards |
||||||
|
|
||||||
|
:::note |
||||||
|
For split keyboards, you will have to build and flash each side separately the first time you install ZMK. |
||||||
|
::: |
||||||
|
|
||||||
|
By default, the `build` command outputs a single .uf2 file named `zmk.uf2` so building left and then right immediately after will overwrite your left firmware. In addition, you will need to pristine build each side to ensure the correct files are used. To avoid having to pristine build every time and separate the left and right build files, we recommend setting up separate build directories for each half. You can do this by using the `-d` parameter and first building left into `build/left`: |
||||||
|
|
||||||
|
``` |
||||||
|
west build -d build/left -b nice_nano -- -DSHIELD=kyria_left |
||||||
|
``` |
||||||
|
and then building right into `build/right`: |
||||||
|
``` |
||||||
|
west build -d build/right -b nice_nano -- -DSHIELD=kyria_right |
||||||
|
``` |
||||||
|
This produces `left` and `right` subfolders under the `build` directory and two separate .uf2 files. For future work on a specific half, use the `-d` parameter again to ensure you are building into the correct location. |
||||||
|
|
||||||
|
## Flashing |
||||||
|
|
||||||
|
Once built, the previously supplied parameters will be remembered so you can run the following to flash your |
||||||
|
board with it in bootloader mode: |
||||||
|
|
||||||
|
``` |
||||||
|
west flash |
||||||
|
``` |
||||||
|
|
||||||
|
For boards that have drag and drop .uf2 flashing capability, the .uf2 file to flash can be found in `build/zephyr` (or `build/left|right/zephyr` if you followed the instructions for splits) and is by default named `zmk.uf2`. |
||||||
Loading…
Reference in new issue