From ec6215f38e4f178740e0838bba3bf8ca6d9f1f0c Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 15:05:43 -0700 Subject: Added Arduino IDE to USB Logging --- docs/docs/dev-guide-usb-logging.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index 3bc8a0c..bb09364 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,26 @@ 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 the Arduino IDE which contains a built-in Serial Monitor. Download and install it from [their website](https://www.arduino.cc/en/main/software), then connect your board and under Tools select "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. -- cgit v1.2.3 From 35dc46bfbb472c01c2c791233bbe32734cb6dfd5 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 15:51:08 -0700 Subject: Made separate build and flash page with updated content --- docs/docs/dev-build.md | 88 ++++++++++++++++++++++++++++++++++++++ docs/docs/dev-guide-usb-logging.md | 4 +- docs/docs/dev-setup.md | 77 ++++++++++----------------------- docs/sidebars.js | 1 + 4 files changed, 113 insertions(+), 57 deletions(-) create mode 100644 docs/docs/dev-build.md (limited to 'docs') diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md new file mode 100644 index 0000000..2df15cd --- /dev/null +++ b/docs/docs/dev-build.md @@ -0,0 +1,88 @@ +--- +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 -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 +``` + +### 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 and regenerates them, and can be enabled by adding either --pristine or -p to the command: + +```sh +west build -p -b proton_c -- -DSHIELD=kyria_left -DKEYMAP=default +``` + +## 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` and is by default named `zmk.uf2`. + +:::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 you will have to +1. Build the left side with the `build` command provided above +2. Flash `zmk.uf2` to the left side +3. Replace DSHIELD with the right side (for the above example, this would be `kyria_right`) and build again +4. Flash `zmk.uf2` the right side +::: diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index bb09364..fa4b63b 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -51,7 +51,7 @@ After flashing the updated ZMK image, the board should expose a USB CDC ACM devi defaultValue="linux" values={[ {label: 'Linux', value: 'linux'}, -{label: 'Windows', value: 'windows'}, +{label: 'Windows', value: 'win'}, ]}> @@ -60,7 +60,7 @@ On Linux, this should be a device like `/dev/ttyACM0` and you can connect with ` sudo tio /dev/ttyACM0 ``` - + On Windows, you can use the Arduino IDE which contains a built-in Serial Monitor. Download and install it from [their website](https://www.arduino.cc/en/main/software), then connect your board and under Tools select "Serial Monitor". diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index fae0aa0..1c5c9dd 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,32 @@ 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. Go to the Start Menu and type "environment variables" to find and open the "Edit the system environment variables" option. +2. Click "Environment Variables...", and select the "Path" variable under System variables. +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 @@ -428,54 +446,3 @@ cat ~/.zephyrrc >> ~/.zshrc - -## 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/sidebars.js b/docs/sidebars.js index d426667..3710137 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -18,6 +18,7 @@ module.exports = { Development: [ "dev-clean-room", "dev-setup", + "dev-build-flash", "dev-boards-shields-keymaps", "dev-posix-board", "dev-tests", -- cgit v1.2.3 From 96020a469a5524817732dec59c2b22e0e6172504 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:21:56 -0700 Subject: Added win environment variables instructions --- docs/docs/dev-setup.md | 45 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 34 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 1c5c9dd..151a032 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -212,8 +212,7 @@ source ~/.bashrc -1. Go to the Start Menu and type "environment variables" to find and open the "Edit the system environment variables" option. -2. Click "Environment Variables...", and select the "Path" variable under System variables. +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`. @@ -359,10 +358,41 @@ pip3 install --user -r zephyr/scripts/requirements-base.txt ### Environment Variables +#### 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. + +![start menu](assets/env-var/start_menu.png) + +2. Click 'Environment Variables...'. + +![start menu](assets/env-var/env_var.png) + +3. Click "New..." under System variables to create a new system variable. + +![start menu](assets/env-var/new_variable.png) + +4. Set the variable name to 'ZEPHYR_TOOLCHAIN_VARIANT' and value to 'gnuarmemb'. Click OK to save. + +![start menu](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. + +![start menu](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: @@ -408,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. @@ -419,7 +449,6 @@ defaultValue="bash" values={[ {label: 'bash', value: 'bash'}, {label: 'zsh', value: 'zsh'}, -{label: 'cmd.exe', value: 'cmd'}, ] }> @@ -439,10 +468,4 @@ cat ~/.zephyrrc >> ~/.zshrc - - -`cmd.exe` instructions coming soon! - - - -- cgit v1.2.3 From 9b9174cc574b5d8d55cd2b4b583f44f0f7421404 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:22:39 -0700 Subject: Added lily58 reset photo --- docs/docs/assets/bond-clearing/lily58.jpg | Bin 0 -> 2566639 bytes docs/docs/bond-reset.md | 16 ++++++++++------ 2 files changed, 10 insertions(+), 6 deletions(-) create mode 100644 docs/docs/assets/bond-clearing/lily58.jpg (limited to 'docs') diff --git a/docs/docs/assets/bond-clearing/lily58.jpg b/docs/docs/assets/bond-clearing/lily58.jpg new file mode 100644 index 0000000..4087e7d Binary files /dev/null and b/docs/docs/assets/bond-clearing/lily58.jpg differ diff --git a/docs/docs/bond-reset.md b/docs/docs/bond-reset.md index 1d3732b..1ba79ee 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 -- cgit v1.2.3 From 133166c392540f8496f2dd42671ddda1bd547d2f Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:23:17 -0700 Subject: Pictures for environment variables --- docs/docs/assets/env-var/env_var.png | Bin 0 -> 17317 bytes docs/docs/assets/env-var/gnuarmemb.png | Bin 0 -> 7914 bytes docs/docs/assets/env-var/new_variable.png | Bin 0 -> 60899 bytes docs/docs/assets/env-var/start_menu.png | Bin 0 -> 51108 bytes docs/docs/assets/env-var/zephyr_toolchain.png | Bin 0 -> 7282 bytes 5 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/docs/assets/env-var/env_var.png create mode 100644 docs/docs/assets/env-var/gnuarmemb.png create mode 100644 docs/docs/assets/env-var/new_variable.png create mode 100644 docs/docs/assets/env-var/start_menu.png create mode 100644 docs/docs/assets/env-var/zephyr_toolchain.png (limited to 'docs') 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 0000000..77ebbc5 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 0000000..42e38ec 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 0000000..3cc72bd 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 0000000..fc7d9b5 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 0000000..5a8ec50 Binary files /dev/null and b/docs/docs/assets/env-var/zephyr_toolchain.png differ -- cgit v1.2.3 From 76095c64c6d51c2c7aaf9856d50847998a41b263 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:25:00 -0700 Subject: Fixed title --- docs/docs/dev-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 151a032..e9c635a 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -358,7 +358,7 @@ pip3 install --user -r zephyr/scripts/requirements-base.txt ### Environment Variables -#### GNU ARM Embedded on Windows +#### 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`. -- cgit v1.2.3 From d7bd09149b347c71259eb299f8e8f7ddaa4055f7 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:25:37 -0700 Subject: Added info on connecting keyboard --- docs/docs/user-setup.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/docs/user-setup.md b/docs/docs/user-setup.md index be230d2..b1ffefa 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,6 +177,14 @@ 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. +## Wirelessly Connecting Your Keyboard + +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. + +### Connecting Split Keyboard Halves + +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. + ## Customization ### Configuration Changes @@ -199,3 +206,5 @@ GitHub Actions job to build your firmware which you can download once it complet :::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, only the central (usually left) side will need to be reflashed after making updates to your keymap. -- cgit v1.2.3 From dad2d339b3fa038af1b87cdb60b79081d681a6c3 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:46:00 -0700 Subject: Added customization page --- docs/docs/customization.md | 33 +++++++++++++++++++++++++++++++++ docs/docs/feature/keymaps.md | 2 +- docs/docs/hardware.md | 2 +- docs/docs/intro.md | 2 +- docs/docs/user-setup.md | 24 ------------------------ docs/sidebars.js | 2 +- 6 files changed, 37 insertions(+), 28 deletions(-) create mode 100644 docs/docs/customization.md (limited to 'docs') diff --git a/docs/docs/customization.md b/docs/docs/customization.md new file mode 100644 index 0000000..0bb1794 --- /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/feature/keymaps.md b/docs/docs/feature/keymaps.md index 020df17..367b03c 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. diff --git a/docs/docs/hardware.md b/docs/docs/hardware.md index 9e6a956..299d1f5 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 514c76e..29045f7 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 b1ffefa..2aade82 100644 --- a/docs/docs/user-setup.md +++ b/docs/docs/user-setup.md @@ -184,27 +184,3 @@ Connecting your keyboard wirelessly is the same as adding other Bluetooth devide ### Connecting Split Keyboard Halves 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. - -## Customization - -### 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 you should see -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 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, only the central (usually left) side will need to be reflashed after making updates to your keymap. diff --git a/docs/sidebars.js b/docs/sidebars.js index 3710137..53c5cf3 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", -- cgit v1.2.3 From 276a2620b9a5259dd15cd4a6038a6144e5da9432 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 17:47:41 -0700 Subject: Minor capitalization fix --- docs/docs/feature/keymaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docs/feature/keymaps.md b/docs/docs/feature/keymaps.md index 367b03c..d991925 100644 --- a/docs/docs/feature/keymaps.md +++ b/docs/docs/feature/keymaps.md @@ -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: -- cgit v1.2.3 From 037970fe8c0122d156de4db92e3ef335e1902e55 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 18:43:13 -0700 Subject: Removed DKEYMAP and added split build directories --- docs/docs/dev-build.md | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md index 2df15cd..393f483 100644 --- a/docs/docs/dev-build.md +++ b/docs/docs/dev-build.md @@ -43,7 +43,7 @@ Given the following: You can build ZMK with the following: ```sh -west build -b proton_c -- -DSHIELD=kyria_left -DKEYMAP=default +west build -b proton_c -- -DSHIELD=kyria_left ``` ### Keyboard With Onboard MCU @@ -58,14 +58,29 @@ Given the following: you can build ZMK with the following: ```sh -west build -b planck_rev6 -- -DKEYMAP=default +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 and regenerates them, and can be enabled by adding either --pristine or -p to the command: ```sh -west build -p -b proton_c -- -DSHIELD=kyria_left -DKEYMAP=default +west build -p -b proton_c -- -DSHIELD=kyria_left +``` +### 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 each time and separate the left and right build files, we recommend setting up separate build directories for each half. You can do this by 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 ``` ## Flashing @@ -79,10 +94,3 @@ west flash For boards that have drag and drop .uf2 flashing capability, the .uf2 file to flash can be found in `build\zephyr` and is by default named `zmk.uf2`. -:::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 you will have to -1. Build the left side with the `build` command provided above -2. Flash `zmk.uf2` to the left side -3. Replace DSHIELD with the right side (for the above example, this would be `kyria_right`) and build again -4. Flash `zmk.uf2` the right side -::: -- cgit v1.2.3 From bc13cd1de1b647a519d051ed44f69a09ad75bfbf Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 19:22:43 -0700 Subject: Added PuTTY to USB Logging --- docs/docs/assets/usb-logging/com_port.PNG | Bin 0 -> 14258 bytes docs/docs/assets/usb-logging/putty.PNG | Bin 0 -> 19822 bytes docs/docs/dev-guide-usb-logging.md | 8 +++++++- 3 files changed, 7 insertions(+), 1 deletion(-) create mode 100644 docs/docs/assets/usb-logging/com_port.PNG create mode 100644 docs/docs/assets/usb-logging/putty.PNG (limited to 'docs') diff --git a/docs/docs/assets/usb-logging/com_port.PNG b/docs/docs/assets/usb-logging/com_port.PNG new file mode 100644 index 0000000..35934b8 Binary files /dev/null and b/docs/docs/assets/usb-logging/com_port.PNG differ diff --git a/docs/docs/assets/usb-logging/putty.PNG b/docs/docs/assets/usb-logging/putty.PNG new file mode 100644 index 0000000..b53d536 Binary files /dev/null and b/docs/docs/assets/usb-logging/putty.PNG differ diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index fa4b63b..62977c7 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -62,7 +62,13 @@ sudo tio /dev/ttyACM0 -On Windows, you can use the Arduino IDE which contains a built-in Serial Monitor. Download and install it from [their website](https://www.arduino.cc/en/main/software), then connect your board and under Tools select "Serial Monitor". +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_port.png) + +![PuTTY settings](assets/usb-logging/putty.png) + +If you already have the Ardunio IDE installed you can also use its built-in Serial Monitor. -- cgit v1.2.3 From 8594d832b663c92d5d1ccfe14c65419835f4059e Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 19:23:25 -0700 Subject: Added split build directories --- docs/docs/dev-build.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md index 393f483..b962a7d 100644 --- a/docs/docs/dev-build.md +++ b/docs/docs/dev-build.md @@ -62,26 +62,27 @@ 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 and regenerates them, and can be enabled by adding either --pristine or -p to the command: +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 ``` -### Split Keyboards +### 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 each time and separate the left and right build files, we recommend setting up separate build directories for each half. You can do this by first building left into `build\left`: +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`: +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 @@ -92,5 +93,5 @@ 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` and is by default named `zmk.uf2`. +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`. -- cgit v1.2.3 From 0a06760cda0cc9cbce4b4c188ea169194903a695 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 19:26:11 -0700 Subject: Updated alt text --- docs/docs/dev-setup.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index e9c635a..1d7d703 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -367,23 +367,23 @@ On Windows, you will have to set two environment variables for ZMK to build prop 1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it. -![start menu](assets/env-var/start_menu.png) +![Environment variables in Start Menu](assets/env-var/start_menu.png) 2. Click 'Environment Variables...'. -![start menu](assets/env-var/env_var.png) +![Environment variables button](assets/env-var/env_var.png) 3. Click "New..." under System variables to create a new system variable. -![start menu](assets/env-var/new_variable.png) +![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. -![start menu](assets/env-var/zephyr_toolchain.png) +![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. -![start menu](assets/env-var/gnuarmemb.png) +![Adding GNUARMEMB variable](assets/env-var/gnuarmemb.png) -- cgit v1.2.3 From 0e04596ef610aa5c23cae5bdc80fd63ee28b3701 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 21:04:32 -0700 Subject: Renamed COM port image --- docs/docs/assets/usb-logging/com-port.PNG | Bin 0 -> 14258 bytes docs/docs/assets/usb-logging/com_port.PNG | Bin 14258 -> 0 bytes docs/docs/dev-guide-usb-logging.md | 2 +- 3 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 docs/docs/assets/usb-logging/com-port.PNG delete mode 100644 docs/docs/assets/usb-logging/com_port.PNG (limited to 'docs') diff --git a/docs/docs/assets/usb-logging/com-port.PNG b/docs/docs/assets/usb-logging/com-port.PNG new file mode 100644 index 0000000..35934b8 Binary files /dev/null and b/docs/docs/assets/usb-logging/com-port.PNG differ diff --git a/docs/docs/assets/usb-logging/com_port.PNG b/docs/docs/assets/usb-logging/com_port.PNG deleted file mode 100644 index 35934b8..0000000 Binary files a/docs/docs/assets/usb-logging/com_port.PNG and /dev/null differ diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index 62977c7..b63494d 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -64,7 +64,7 @@ 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_port.png) +![Controller COM port](assets/usb-logging/com-port.png) ![PuTTY settings](assets/usb-logging/putty.png) -- cgit v1.2.3 From af23445aa02cea100ba064770a139b4971a6fc39 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 21:13:48 -0700 Subject: COM image fix --- docs/docs/assets/usb-logging/com-port.PNG | Bin 14258 -> 0 bytes docs/docs/assets/usb-logging/com.PNG | Bin 0 -> 14258 bytes docs/docs/dev-guide-usb-logging.md | 2 +- 3 files changed, 1 insertion(+), 1 deletion(-) delete mode 100644 docs/docs/assets/usb-logging/com-port.PNG create mode 100644 docs/docs/assets/usb-logging/com.PNG (limited to 'docs') diff --git a/docs/docs/assets/usb-logging/com-port.PNG b/docs/docs/assets/usb-logging/com-port.PNG deleted file mode 100644 index 35934b8..0000000 Binary files a/docs/docs/assets/usb-logging/com-port.PNG and /dev/null differ diff --git a/docs/docs/assets/usb-logging/com.PNG b/docs/docs/assets/usb-logging/com.PNG new file mode 100644 index 0000000..35934b8 Binary files /dev/null and b/docs/docs/assets/usb-logging/com.PNG differ diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index b63494d..6eca165 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -64,7 +64,7 @@ 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-port.png) +![Controller COM port](./assets/usb-logging/com.png) ![PuTTY settings](assets/usb-logging/putty.png) -- cgit v1.2.3 From 06af711f57df20b195a1cf37b1a31ceee9a672b6 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 21:20:38 -0700 Subject: Replaced png with jpg --- docs/docs/assets/usb-logging/com.PNG | Bin 14258 -> 0 bytes docs/docs/assets/usb-logging/com.jpg | Bin 0 -> 10993 bytes docs/docs/dev-guide-usb-logging.md | 2 +- 3 files changed, 1 insertion(+), 1 deletion(-) delete mode 100644 docs/docs/assets/usb-logging/com.PNG create mode 100644 docs/docs/assets/usb-logging/com.jpg (limited to 'docs') diff --git a/docs/docs/assets/usb-logging/com.PNG b/docs/docs/assets/usb-logging/com.PNG deleted file mode 100644 index 35934b8..0000000 Binary files a/docs/docs/assets/usb-logging/com.PNG and /dev/null differ diff --git a/docs/docs/assets/usb-logging/com.jpg b/docs/docs/assets/usb-logging/com.jpg new file mode 100644 index 0000000..e2ab9a8 Binary files /dev/null and b/docs/docs/assets/usb-logging/com.jpg differ diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index 6eca165..11b568e 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -64,7 +64,7 @@ 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.png) +![Controller COM port](./assets/usb-logging/com.jpg) ![PuTTY settings](assets/usb-logging/putty.png) -- cgit v1.2.3 From 212dd91e2910e58e5a5c0c32e8726f2efc396c22 Mon Sep 17 00:00:00 2001 From: Kevin Date: Sat, 29 Aug 2020 21:27:03 -0700 Subject: PuTTY image fix --- docs/docs/assets/bond-clearing/debug.log | 0 docs/docs/assets/usb-logging/putty.PNG | Bin 19822 -> 0 bytes docs/docs/assets/usb-logging/putty.jpg | Bin 0 -> 160650 bytes docs/docs/dev-guide-usb-logging.md | 2 +- 4 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 docs/docs/assets/bond-clearing/debug.log delete mode 100644 docs/docs/assets/usb-logging/putty.PNG create mode 100644 docs/docs/assets/usb-logging/putty.jpg (limited to 'docs') diff --git a/docs/docs/assets/bond-clearing/debug.log b/docs/docs/assets/bond-clearing/debug.log new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/assets/usb-logging/putty.PNG b/docs/docs/assets/usb-logging/putty.PNG deleted file mode 100644 index b53d536..0000000 Binary files a/docs/docs/assets/usb-logging/putty.PNG and /dev/null differ diff --git a/docs/docs/assets/usb-logging/putty.jpg b/docs/docs/assets/usb-logging/putty.jpg new file mode 100644 index 0000000..dfbb4bd Binary files /dev/null and b/docs/docs/assets/usb-logging/putty.jpg differ diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index 11b568e..c5fb4b9 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -66,7 +66,7 @@ On Windows, you can use [PuTTY](https://www.putty.org/). Once installed, use Dev ![Controller COM port](./assets/usb-logging/com.jpg) -![PuTTY settings](assets/usb-logging/putty.png) +![PuTTY settings](assets/usb-logging/putty.jpg) If you already have the Ardunio IDE installed you can also use its built-in Serial Monitor. -- cgit v1.2.3 From 45b1756a700ba0603f0a3b7708108c9ebc9fc945 Mon Sep 17 00:00:00 2001 From: Kevin Chen Date: Sat, 29 Aug 2020 21:36:00 -0700 Subject: Replaced \ with / Co-authored-by: Pete Johanson --- docs/docs/dev-build.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/docs/dev-build.md b/docs/docs/dev-build.md index b962a7d..816468e 100644 --- a/docs/docs/dev-build.md +++ b/docs/docs/dev-build.md @@ -93,5 +93,4 @@ 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`. - +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`. -- cgit v1.2.3