mirror of
https://github.com/zmkfirmware/zmk.git
synced 2026-03-20 13:05:20 -05:00
132 lines
4.6 KiB
Plaintext
132 lines
4.6 KiB
Plaintext
---
|
|
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,
|
|
Zephyr can be configured to create a USB CDC ACM device and the direct all `printk`, console output, and log
|
|
messages to that device instead.
|
|
|
|
:::danger[Battery Life Impact]
|
|
|
|
Enabling logging increases the power usage of your keyboard, and can have a non-trivial impact to your time on battery.
|
|
It is recommended to only enable logging when needed, and not leaving it on by default.
|
|
|
|
:::
|
|
|
|
## USB Logging Snippet
|
|
|
|
The `zmk-usb-logging` snippet is used to enable logging.
|
|
|
|
If using GitHub Actions to build your firmware, enabling logging
|
|
requires adding a `snippet: zmk-usb-logging` to your `build.yaml` file for any build you want logging enabled, e.g.
|
|
|
|
```yaml
|
|
---
|
|
include:
|
|
- board: nice_nano
|
|
shield: corne_left
|
|
snippet: zmk-usb-logging
|
|
```
|
|
|
|
When building locally, the `-S`/`--snippet` flag can be passed to `west build` to enable the snippet, e.g.
|
|
|
|
```sh
|
|
west build -b nice_nano -S zmk-usb-logging -- -DSHIELD="corne_left"
|
|
```
|
|
|
|
### Additional Config
|
|
|
|
Logging can be further configured using Kconfig described in [the Zephyr documentation](https://docs.zephyrproject.org/4.1.0/services/logging/index.html).
|
|
For instance, setting `CONFIG_LOG_PROCESS_THREAD_STARTUP_DELAY_MS` to a large value such as `8000` might help catch issues that happen near keyboard
|
|
boot, before you can connect to view the logs.
|
|
|
|
## 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.
|
|
|
|
<Tabs
|
|
queryString="operating-system"
|
|
defaultValue="linux"
|
|
values={[
|
|
{label: 'Linux', value: 'linux'},
|
|
{label: 'Windows', value: 'win'},
|
|
{label: 'MacOS', value: 'macos'}
|
|
]}>
|
|
<TabItem value="linux">
|
|
|
|
On Linux, this should be a device like `/dev/ttyACM0` and you can connect with `minicom` or `tio` as usual, e.g.:
|
|
|
|
```sh
|
|
sudo tio /dev/ttyACM0
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="win">
|
|
|
|
On Windows, you can use [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html). 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.
|
|
|
|
|
|
|
|
|
|
|
|
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)):
|
|
|
|
```sh
|
|
sudo tio /dev/tty.usbmodem14401
|
|
```
|
|
|
|
Alternatively, `cu` should be preinstalled (see `man cu` for usage instructions):
|
|
|
|
```sh
|
|
sudo cu -l /dev/tty.usbmodem14401
|
|
```
|
|
|
|
You should see the console printing `Disconnected` or `Connected` when you disconnect or reconnect the USB cable.
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
From there, you should see the various log messages from ZMK and Zephyr, depending on which systems you have set to what log levels.
|
|
|
|
## Adding USB Logging to a Board
|
|
|
|
Standard boards such as the nice!nano and Seeed Studio XIAO family have the necessary configuration for logging already added, however if you are developing your own standalone board you may wish to add the ability to use USB logging in the future.
|
|
|
|
To do so, you need to follow the upstream Zephyr [`cdc-acm-console` snippet requirements](https://docs.zephyrproject.org/4.1.0/snippets/cdc-acm-console/README.html#requirements) steps.
|
|
|
|
Usually, this just requires ensuring that the USB node has been tagged with the `zephyr_udc0` label, e.g.
|
|
|
|
```dts
|
|
zephyr_udc0: &usbd {
|
|
status = "okay";
|
|
};
|
|
```
|
|
|
|
## Enabling Logging on Older Boards
|
|
|
|
Previously, enabling logging required setting the `CONFIG_ZMK_USB_LOGGING` Kconfig symbol. If for whatever reason
|
|
a custom board definition does not support the new `zmk-usb-logging` snippet, you can try setting this symbol at the keyboard level, typically in the `config/<your_keyboard>.conf`
|
|
file if you are using a [user config repository](user-setup.mdx). It can also be enabled at the ZMK level using the `app/prj.conf` file, or other
|
|
search locations described in the [configuration overview](config/index.md#config-file-locations).
|
|
|
|
:::note
|
|
In Github Actions, you can check the `<Keyboard> Kconfig file` step output to verify the options above have been enabled
|
|
for you successfully.
|
|
:::
|
|
|
|
```ini
|
|
# Turn on logging, and set ZMK logging to debug output
|
|
CONFIG_ZMK_USB_LOGGING=y
|
|
```
|