From e7cb863a4162b8d871cf0ba2fb2f298947682305 Mon Sep 17 00:00:00 2001 From: Chiyuan Zhang Date: Sun, 1 Nov 2020 13:22:34 -0800 Subject: [PATCH] update doc for new shield in user repo --- docs/docs/dev-guide-new-shield.md | 11 ++++++++++- docs/docs/dev-guide-usb-logging.md | 19 +++++++++++++++++++ docs/docs/user-setup.md | 6 ++++++ 3 files changed, 35 insertions(+), 1 deletion(-) diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 94f7d1dd..b61ece92 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -27,6 +27,15 @@ ZMK support for split keyboards requires a few more files than single boards to ## New Shield Directory +:::note +This guide describes how to add shield to the ZMK main repository. If you are building firmware for your +own prototype or handwired keyboard, it is recommended to use your own user config repository. Follow the +[user setup guide](./user-setup.md) to create your user config repository first. When following the rest +of this guide, replace the `app/` directory in the ZMK main repository with the `config/` directory in your +user config repository. Form example, `app/boards/shields/` should now be +`config/boards/shields/`. +::: + Shields for Zephyr applications go into the `boards/shields/` directory; since ZMK's Zephyr application lives in the `app/` subdirectory of the repository, that means the new shield directory should be: ```bash @@ -66,7 +75,7 @@ that make sense to have different defaults when this shield is used. One main it that usually has a new default value set here is the `ZMK_KEYBOARD_NAME` value, which controls the display name of the device over USB and BLE. -The updated new default values should always be wrapped inside a conditional on the shield config name defined in the `Kconfig.shield` file. Here's the simplest example file: +The updated new default values should always be wrapped inside a conditional on the shield config name defined in the `Kconfig.shield` file. Here's the simplest example file. Note: do not make the keyboard name too long, otherwise the bluetooth advertising might fail and you will not be able to find your keyboard from your laptop / tablet. ``` if SHIELD_MY_BOARD diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md index 7f1fad72..26706c2b 100644 --- a/docs/docs/dev-guide-usb-logging.md +++ b/docs/docs/dev-guide-usb-logging.md @@ -50,6 +50,13 @@ CONFIG_UART_CONSOLE_ON_DEV_NAME="CDC_ACM_0" CONFIG_USB_UART_DTR_WAIT=n ``` +:::note +If you are debugging your own keyboard in your [user config repository](./user-setup.md), use +`config/boards/shields//.conf` instead of `app/prj.conf`. In Github +Actions, you can search the `Kconfig file` build log to verify the options above have been enabled +for you successfully. +::: + ## 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. @@ -59,6 +66,7 @@ defaultValue="linux" values={[ {label: 'Linux', value: 'linux'}, {label: 'Windows', value: 'win'}, +{label: 'MacOS', value: 'macos'} ]}> @@ -79,6 +87,17 @@ On Windows, you can use [PuTTY](https://www.putty.org/). Once installed, use Dev If you already have the Ardunio IDE installed you can also use its built-in Serial Monitor. + + + +On MacOS, the device name is something like `/dev/tty.usbmodemXXXXX` where `XXXXX` is some numerical ID. +You can connect to the device with [tio](https://tio.github.io/) (can be installed via [Homebrew](https://formulae.brew.sh/formula/tio)): + +``` +sudo tio /dev/tty.usbmodem14401 +``` + +You should see tio printing `Disconnected` or `Connected` when you disconnect or reconnect the USB cable. diff --git a/docs/docs/user-setup.md b/docs/docs/user-setup.md index 1e1e1e8e..7f5348f0 100644 --- a/docs/docs/user-setup.md +++ b/docs/docs/user-setup.md @@ -33,6 +33,12 @@ Following the steps in this guide, you will: 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. +:::note +If you are building firmware for a new keyboard shield that is not included in the built-in +list of shields, you can choose any shield from the list that is similar to yours to generate the repository, +and edit / add necessary files according to the [guide for adding new keyboard shield](./dev-guide-new-shield.md). +::: + ## Prerequisites The remainder of this guide assumes the following prerequisites: