Browse Source

update doc for new shield in user repo

xmkb
Chiyuan Zhang 4 years ago committed by Pete Johanson
parent
commit
e7cb863a41
  1. 11
      docs/docs/dev-guide-new-shield.md
  2. 19
      docs/docs/dev-guide-usb-logging.md
  3. 6
      docs/docs/user-setup.md

11
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 @@ -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/<keyboard_name>` should now be
`config/boards/shields/<keyboard_name>`.
:::
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 @@ -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

19
docs/docs/dev-guide-usb-logging.md

@ -50,6 +50,13 @@ CONFIG_UART_CONSOLE_ON_DEV_NAME="CDC_ACM_0" @@ -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/<your_keyboard>/<your_keyboard>.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" @@ -59,6 +66,7 @@ defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'Windows', value: 'win'},
{label: 'MacOS', value: 'macos'}
]}>
<TabItem value="linux">
@ -79,6 +87,17 @@ On Windows, you can use [PuTTY](https://www.putty.org/). Once installed, use Dev @@ -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.
</TabItem>
<TabItem value="macos">
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.
</TabItem>
</Tabs>

6
docs/docs/user-setup.md

@ -33,6 +33,12 @@ Following the steps in this guide, you will: @@ -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:

Loading…
Cancel
Save