diff --git a/docs/docs/assets/bond-clearing/debug.log b/docs/docs/assets/bond-clearing/debug.log new file mode 100644 index 00000000..e69de29b diff --git a/docs/docs/assets/bond-clearing/lily58.jpg b/docs/docs/assets/bond-clearing/lily58.jpg new file mode 100644 index 00000000..4087e7dc Binary files /dev/null and b/docs/docs/assets/bond-clearing/lily58.jpg differ diff --git a/docs/docs/assets/env-var/env_var.png b/docs/docs/assets/env-var/env_var.png new file mode 100644 index 00000000..77ebbc5b Binary files /dev/null and b/docs/docs/assets/env-var/env_var.png differ diff --git a/docs/docs/assets/env-var/gnuarmemb.png b/docs/docs/assets/env-var/gnuarmemb.png new file mode 100644 index 00000000..42e38ec1 Binary files /dev/null and b/docs/docs/assets/env-var/gnuarmemb.png differ diff --git a/docs/docs/assets/env-var/new_variable.png b/docs/docs/assets/env-var/new_variable.png new file mode 100644 index 00000000..3cc72bdb Binary files /dev/null and b/docs/docs/assets/env-var/new_variable.png differ diff --git a/docs/docs/assets/env-var/start_menu.png b/docs/docs/assets/env-var/start_menu.png new file mode 100644 index 00000000..fc7d9b5e Binary files /dev/null and b/docs/docs/assets/env-var/start_menu.png differ diff --git a/docs/docs/assets/env-var/zephyr_toolchain.png b/docs/docs/assets/env-var/zephyr_toolchain.png new file mode 100644 index 00000000..5a8ec50d Binary files /dev/null and b/docs/docs/assets/env-var/zephyr_toolchain.png differ diff --git a/docs/docs/assets/usb-logging/com.jpg b/docs/docs/assets/usb-logging/com.jpg new file mode 100644 index 00000000..e2ab9a83 Binary files /dev/null and b/docs/docs/assets/usb-logging/com.jpg differ diff --git a/docs/docs/assets/usb-logging/putty.jpg b/docs/docs/assets/usb-logging/putty.jpg new file mode 100644 index 00000000..dfbb4bd7 Binary files /dev/null and b/docs/docs/assets/usb-logging/putty.jpg differ diff --git a/docs/docs/bond-reset.md b/docs/docs/bond-reset.md index 1d3732b1..1ba79ee0 100644 --- a/docs/docs/bond-reset.md +++ b/docs/docs/bond-reset.md @@ -4,8 +4,8 @@ title: Reset BLE Connections sidebar_label: BLE Reset --- -Known as a 'bond reset', a special key combination, that is not related to the user defined key map, which -clears all wireless connection configurations. The keys must be held for 3 to 5 seconds after the device is +Known as a 'bond reset', each keyboard has a special key combination independent of the user defined key map which will +clear all wireless connection configurations. The keys must be held for 3 to 5 seconds after the device is reset. :::warning @@ -13,15 +13,19 @@ Currently, ZMK only supports a single BLE host. If you remove the keyboard from list, you will need to clear the bonds. ::: -### Split Keyboards +## Split Keyboards Split keyboards will need to be cleared on both halves. For best results try to reset them at the same time. -## Kyria +### Kyria ![Kyria bond-reset combo](assets/bond-clearing/kyria.jpg) -## Corne +### Corne -![Corne bond-reset combo](assets/bond-clearing/corne.jpg) \ No newline at end of file +![Corne bond-reset combo](assets/bond-clearing/corne.jpg) + +### Lily58 + +![Lily58 bond-reset combo](assets/bond-clearing/lily58.jpg) \ No newline at end of file diff --git a/docs/docs/customization.md b/docs/docs/customization.md new file mode 100644 index 00000000..0bb17941 --- /dev/null +++ b/docs/docs/customization.md @@ -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/.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/.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. diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md new file mode 100644 index 00000000..816468e2 --- /dev/null +++ b/docs/docs/dev-build.md @@ -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) => ({props.children}); + +## 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`. diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index 3bc8a0cd..c5fb4b9d 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -3,6 +3,9 @@ id: dev-guide-usb-logging title: USB Logging --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## Overview If you are developing ZMK on a device that does not have a built in UART for debugging and log/console output, @@ -11,7 +14,7 @@ messages to that device instead. ## Kconfig -The following KConfig values need to be set, either by copy and paste into the `app/prj.conf` file, or by running +The following KConfig values need to be set, either by copy and pasting into the `app/prj.conf` file, or by running `west build -t menuconfig` and manually enabling the various settings in that UI. ``` @@ -42,12 +45,32 @@ CONFIG_USB_UART_DTR_WAIT=n ## Viewing Logs -After flashing the updated ZMK image, the board should expose a USB CDC ACM device, that you can connect to and view the logs. +After flashing the updated ZMK image, the board should expose a USB CDC ACM device that you can connect to and view the logs. -On Linux, this should be a device like `/dev/ttyACM0` and you can connect with `minicom` or `tio` as usual, e.g.: + + +On Linux, this should be a device like `/dev/ttyACM0` and you can connect with `minicom` or `tio` as usual, e.g.: ``` sudo tio /dev/ttyACM0 ``` + + + +On Windows, you can use [PuTTY](https://www.putty.org/). Once installed, use Device Manager to figure out which COM port your controller is communicating on (listed under 'Ports (COM & LPT)') and specify that as the 'Serial line' in PuTTY. + +![Controller COM port](./assets/usb-logging/com.jpg) + +![PuTTY settings](assets/usb-logging/putty.jpg) + +If you already have the Ardunio IDE installed you can also use its built-in Serial Monitor. + + + From there, you should see the various log messages from ZMK and Zephyr, depending on which systems you have set to what log levels. diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index fae0aa09..1d7d703b 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -181,7 +181,7 @@ brew install cmake ninja python3 ccache dtc git wget ## Setup -### West Build Command +### West Installation `west` is the [Zephyr™ meta-tool](https://docs.zephyrproject.org/2.3.0/guides/west/index.html) used to configure and build Zephyr™ applications. @@ -192,14 +192,31 @@ pip3 install --user -U west ``` :::danger pip user packages -If you haven't done so yet, you may need to add the Python Pip user package directory to your `PATH`, e.g.: +If you haven't done so yet, you may need to add the Python Pip user package directory to your `PATH` otherwise your computer will not be able to find the `west` command. +::: -``` + + +Run the following commands: + +```sh echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc source ~/.bashrc ``` -::: + + + +1. See the [Environment Variables](#environment-variables) section on how to get to the Environment Variables page. +3. Click "Edit..." and then "New" to add the directory where your west.exe is located. By default this should be something like `C:\Python38\Scripts`. + + + ### Toolchain Installation @@ -341,10 +358,41 @@ pip3 install --user -r zephyr/scripts/requirements-base.txt ### Environment Variables +#### For GNU ARM Embedded on Windows + +On Windows, you will have to set two environment variables for ZMK to build properly: `ZEPHYR_TOOLCHAIN_VARIANT` and `GNUARMEMB_TOOLCHAIN_PATH`. + +
+ Steps to Update Environment Variables + +1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it. + +![Environment variables in Start Menu](assets/env-var/start_menu.png) + +2. Click 'Environment Variables...'. + +![Environment variables button](assets/env-var/env_var.png) + +3. Click "New..." under System variables to create a new system variable. + +![Environment variables menu](assets/env-var/new_variable.png) + +4. Set the variable name to 'ZEPHYR_TOOLCHAIN_VARIANT' and value to 'gnuarmemb'. Click OK to save. + +![Adding Zephyr toolchain variable](assets/env-var/zephyr_toolchain.png) + +5. Create another variable with variable name 'GNUARMEMB_TOOLCHAIN_PATH' and value set to wherever you installed your toolchain. Click OK to save. + +![Adding GNUARMEMB variable](assets/env-var/gnuarmemb.png) + +
+ +#### For Zephyr + 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/2.3.0/guides/env_vars.html?highlight=zephyrrc) for how to load those settings. -#### Per Shell +##### Per Shell To load the Zephyr environment properly for just one transient shell, run the following from your ZMK checkout directory: @@ -390,7 +438,7 @@ source zephyr/zephyr-env.cmd -#### All Shells +##### 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. @@ -401,7 +449,6 @@ defaultValue="bash" values={[ {label: 'bash', value: 'bash'}, {label: 'zsh', value: 'zsh'}, -{label: 'cmd.exe', value: 'cmd'}, ] }> @@ -421,61 +468,4 @@ cat ~/.zephyrrc >> ~/.zshrc - - -`cmd.exe` instructions coming soon! - - - - -## Build - -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 a MCU board addon. - -### Keyboard (Shield) + MCU Board - -ZMK treats keyboards that take a 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 -DKEYMAP=default -``` - -### 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 -- -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 -``` diff --git a/docs/docs/feature/keymaps.md b/docs/docs/feature/keymaps.md index 020df176..d991925b 100644 --- a/docs/docs/feature/keymaps.md +++ b/docs/docs/feature/keymaps.md @@ -4,7 +4,7 @@ title: Keymaps & Behaviors sidebar_label: Keymaps --- -ZMK uses an declarative approach to keymaps, instead of using C code for all keymap configuration. +ZMK uses a declarative approach to keymaps instead of using C code for all keymap configuration. Right now, ZMK uses the devicetree syntax to declare those keymaps; future work is envisioned for supporting dynamic loading of declarative keymaps, e.g. over USB Mass Storage or via a custom BLE service. @@ -80,7 +80,7 @@ A keymap file is composed of several sections, that together make up a valid dev ### Includes -THe devicetree files are actually preprocessed before being finally leveraged by Zephyr. This allows using standard C defines to create meaningful placeholders +The devicetree files are actually preprocessed before being finally leveraged by Zephyr. This allows using standard C defines to create meaningful placeholders for what would otherwise be cryptic integer keycodes, etc. This also allows bringing in _other_ devicetree nodes from separate files. The top two lines of most keymaps should include: diff --git a/docs/docs/hardware.md b/docs/docs/hardware.md index 9e6a956f..299d1f5c 100644 --- a/docs/docs/hardware.md +++ b/docs/docs/hardware.md @@ -11,7 +11,7 @@ have had their hardware details codified in boards/shields for ZMK. ::: -Being built on a solid technical foundation of the Zephyr™ RTOS, it's possible to make ZMK support a wide diversity of hardware targets. +With the solid technical foundation of Zephyr™ RTOS, ZMK can support a wide diversity of hardware targets. That being said, there are currently only a few specific [boards](/docs/faq#what-is-a-board)/[shields](/docs/faq#what-is-a-shield) that have been written and tested by the ZMK contributors. ## Boards diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 514c76e8..29045f76 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -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/) Real Time Operating System (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 diff --git a/docs/docs/user-setup.md b/docs/docs/user-setup.md index be230d28..2aade829 100644 --- a/docs/docs/user-setup.md +++ b/docs/docs/user-setup.md @@ -11,8 +11,7 @@ Unlike other keyboard firmwares, ZMK Firmware has been built from the ground up 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 do not need to install any complicated toolchains or tools to build ZMK, -instead using GitHub Actions to automatically build the user's configured firmware for them. +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. ## Summary @@ -170,7 +169,7 @@ 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. -### Installing UF2 Files +### Flashing 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. @@ -178,24 +177,10 @@ or the one that is part of your keyboard). The controller should appear in your 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 newfly flashed firmware. -## Customization +## Wirelessly Connecting Your Keyboard -### Configuration Changes +Connecting your keyboard wirelessly is the same as adding other Bluetooth devides: press the reset button and scan for devices. However, pairing and bonding is still currently being worked on to increase relability and ease of use. In addition, users have in general reported that Bluetooth pairing with computers tends to be quite finnicky. Try out the connection with your tablet or phone first, as those devices seem to work much more consistently. See [BLE Reset](./bond-reset.md) for help on resetting your MCUs if you're experiencing connection issues. -The setup script creates a `config/.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 you should see -various config settings that can be commented/uncommented to modify how your firmware is built. +### Connecting Split Keyboard Halves -### Keymap - -Once you have the basic user config completed, you can find the file in `config/.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. -::: +For split keyboards, after flashing each half individually you can connect them together by resetting them at the same time. Within a few seconds of resetting, both halves should automatically connect to each other. diff --git a/docs/sidebars.js b/docs/sidebars.js index d4266670..53c5cf3d 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,6 +1,6 @@ module.exports = { someSidebar: { - "Getting Started": ["intro", "hardware", "faq", "user-setup", "bond-reset"], + "Getting Started": ["intro", "hardware", "faq", "user-setup","customization", "bond-reset"], Features: [ "feature/keymaps", "feature/displays", @@ -18,6 +18,7 @@ module.exports = { Development: [ "dev-clean-room", "dev-setup", + "dev-build-flash", "dev-boards-shields-keymaps", "dev-posix-board", "dev-tests",