User Guide

See also

This guide can be viewed online at: https://pigweed.dev/pw_console/py/pw_console/docs/user_guide.html

The Pigweed Console provides a Python repl (read eval print loop) and log viewer in a single-window terminal based interface.

Starting the Console

pw rpc -s localhost:33000 --proto-globs pw_rpc/echo.proto

Exiting

There are a few ways to exit the Pigweed Console user interface:

  1. Click the [File] menu and then Exit.

  2. Type quit or exit in the Python Input window and press Enter.

  3. Press Ctrl-d once to show the quit confirmation dialog. From there press Ctrl-d a second time or y will exit.

  4. Press Ctrl-x quickly followed by Ctrl-c will exit without confirmation.

  5. Press Ctrl-p to search for commands, type exit, then press Enter.

Interface Layout

On startup the console will display multiple windows one on top of the other.

+---------------------------------------------------------+
| [File] [Edit] [View] [Window] [Help]    Pigweed Console |
+=========================================================+
|                                                         |
|                                                         |
|                                                         |
| Log Window                                              |
+=========================================================+
|                                                         |
|                                                         |
| Python Results                                          |
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
|                                                         |
| Python Input                                            |
+---------------------------------------------------------+

Color Depth

Some terminals support full 24-bit color and pw console will use that by default in most cases. One notable exeception is Apple Terminal on MacOS which supports 256 colors only. iTerm2 is a good MacOS alternative that supports 24-bit colors.

To force a particular color depth: set one of these environment variables before launching the console. For bash and zsh shells you can use the export command.

# 1 bit | Black and white
export PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_1_BIT
# 4 bit | ANSI colors
export PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_4_BIT
# 8 bit | 256 colors
export PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_8_BIT
# 24 bit | True colors
export PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_24_BIT

For Windows command prompt (cmd.exe) use the set command:

set PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_1_BIT
set PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_4_BIT
set PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_8_BIT
set PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_24_BIT

Configuration

Pigweed Console supports loading project and user specific settings stored in YAML files. Each file follows the same format and are loaded one after the other. Any setting specified multiple locations will be overridden by files loaded later in the startup sequence.

  1. $PW_PROJECT_ROOT/.pw_console.yaml

    Project level config file. This is intended to be a file living somewhere under a project folder and is checked into version control. It serves as a base config for all users to inherit from.

  2. $PW_PROJECT_ROOT/.pw_console.user.yaml

    User’s personal config file for a specific project. This can be a file that lives in a project folder but is git-ignored and not checked into version control. This lets users change settings applicable to this project only.

  3. $HOME/.pw_console.yaml

    A global user based config file. This file is located in the user’s home directory and settings here apply to all projects. This is a good location to set appearance options such as:

    ui_theme: nord
    code_theme: pigweed-code
    swap_light_and_dark: False
    spaces_between_columns: 2
    hide_date_from_log_time: False
    

It’s also possible to specify a config file via a shell environment variable. If this method is used only this config file is applied. Project and user config file options will not be set.

export PW_CONSOLE_CONFIG_FILE=/home/.config/pw_console/config.yaml

Example Config

---
config_title: pw_console

# Repl and Search History files
# Setting these to a file located $PW_PROJECT_ROOT is a
# good way to make Python repl history project specific.

# Default: $HOME/.pw_console_history
repl_history: $PW_PROJECT_ROOT/.pw_console_history

# Default: $HOME/.pw_console_search
search_history: $PW_PROJECT_ROOT/.pw_console_search

# Theme Settings

# Default: dark
ui_theme: high-contrast-dark

# Default: pigweed-code
code_theme: material

# Default: False
swap_light_and_dark: False

# Log Table View Settings

# Number of spaces to insert between columns
# Default: 2
spaces_between_columns: 2

# Hide the year month and day from the time column.
hide_date_from_log_time: False

# Show the Python file and line number responsible for creating log messages.
show_python_file: False
# Show the Python logger responsible for creating log messages.
show_python_logger: False
# Show the 'file' metadata column.
show_source_file: False

# Custom Column Ordering
# By default columns are ordered as:
#   time, level, metadata1, metadata2, ..., message
# The log message is always the last value and not required in this list.
column_order:
  # Column name
  - time
  - level
  - metadata1
  - metadata2

# If True, any metadata field not listed above in 'column_order'
# will be hidden in table view.
column_order_omit_unspecified_columns: False

# Unique Colors for Column Values
#   Color format: 'bg:#BG-HEX #FG-HEX STYLE'
# All parts are optional.
# Empty strings will leave styling unchanged.
column_colors:
  # Column name
  time:
  level:
  metadata1:
    # Field values
    # Default will be applied if no match found
    default: '#98be65'
    BATTERY: 'bg:#6699cc #000000 bold'
    CORE1: 'bg:#da8548 #000000 bold'
    CORE2: 'bg:#66cccc #000000 bold'
  metadata2:
    default: '#ffcc66'
    APP: 'bg:#ff6c6b #000000 bold'
    WIFI: '#555555'

# Each window column is normally aligned side by side in vertical splits. You
# can change this to one group of windows on top of the other with horizontal
# splits using this method

# Default: vertical
window_column_split_method: vertical

# Window Layout
windows:
  # First window column (vertical split)
  # Each split should have a unique name and include either
  # 'stacked' or 'tabbed' to select a window pane display method.
  Split 1 stacked:
    # Items here are window titles, each should be unique.
    # Window 1
    Device Logs:
      height: 33  # Weighted value for window height
      hidden: False  # Hide this window if True
    # Window 2
    Python Repl:
      height: 67
    # Window 3
    Host Logs:
      hidden: True

  # Second window column
  Split 2 tabbed:
    # This is a duplicate of the existing 'Device Logs' window.
    # The title is 'NEW DEVICE'
    NEW DEVICE:
      duplicate_of: Device Logs
      # Log filters are defined here
      filters:
        # Metadata column names here or 'all'
        source_name:
          # Matching method name here
          # regex, regex-inverted, string, string-inverted
          regex: 'USB'
        module:
          # An inverted match will remove matching log lines
          regex-inverted: 'keyboard'
    NEW HOST:
      duplicate_of: Host Logs
      filters:
        all:
          string: 'FLASH'

  # Third window column
  Split 3 tabbed:
    # This is a brand new log Window
    Keyboard Logs - IBM:
      loggers:
        # Python logger names to include in this log window
        my_cool_keyboard_device:
          # Level the logger should be set to.
          level: DEBUG
        # The empty string logger name is the root Python logger.
        # In most cases this should capture all log messages.
        '':
          level: DEBUG
      filters:
        all:
          regex: 'IBM Model M'
    Keyboard Logs - Apple:
      loggers:
        my_cool_keyboard_device:
          level: DEBUG
      filters:
        all:
          regex: 'Apple.*USB'

# Command Runner dialog size and position
command_runner:
  width: 80
  height: 10
  position:
    top: 3  # 3 lines below the top edge of the screen
    # Alternatively one of these options can be used instead:
    # bottom: 2  # 2 lines above the bottom edge of the screen
    # left: 2    # 2 lines away from the left edge of the screen
    # right: 2   # 2 lines away from the right edge of the screen

# Key bindings can be changed as well with the following format:
#   named-command: [ list_of_keys ]
# Where list_of_keys is a string of keys one for each alternate key
# To see all named commands open '[Help] > View Key Binding Config'
# See below for the names of special keys
key_bindings:
  log-pane.move-cursor-up:
  - j
  - up
  log-pane.move-cursor-down:
  - k
  - down
  log-pane.search-next-match:
  - n
  log-pane.search-previous-match:
  - N

  # Chorded keys are supported.
  # For example, 'z t' means pressing z quickly followed by t.
  log-pane.shift-line-to-top:
  - z t
  log-pane.shift-line-to-center:
  - z z

Changing Keyboard Shortcuts

Pigweed Console uses prompt_toolkit to manage its keybindings.

Bindings can be changed in the YAML config file under the key_bindings: section by adding a named function followed by a of keys to bind. For example this config sets the keys for log pane cursor movement.

  • Moving down is set to j or the Down arrow.

  • Moving up is set to k or the Up arrow.

key_bindings:
  log-pane.move-cursor-down:
  - j
  - down
  log-pane.move-cursor-up:
  - k
  - up

List of Special Key Names

This table is from prompt_toolkit’s List of special keys.

Keyboard Function

Key Values

Literal characters

a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 1 2 3 4 5 6 7 8 9 0 ! @ # $ % ^ & * ( ) - _ + = ~

Escape and Shift-Escape

escape s-escape

Arrows

left right up down

Navigation

home end delete pageup pagedown insert

Control-letter

c-a c-b c-c c-d c-e c-f c-g c-h c-i c-j c-k c-l c-m c-n c-o c-p c-q c-r c-s c-t c-u c-v c-w c-x c-y c-z

Control-number

c-1 c-2 c-3 c-4 c-5 c-6 c-7 c-8 c-9 c-0

Control-arrow

c-left c-right c-up c-down

Other control keys

c-@ c-\ c-] c-^ c-_ c-delete

Shift-arrow

s-left s-right s-up s-down

Control-Shift-arrow

c-s-left c-s-right c-s-up c-s-down

Other Shift` keys

s-delete s-tab

F Keys

f1  f2  f3  f4  f5  f6  f7  f8  f9  f10 f11 f12 f13 f14 f15 f16 f17 f18 f19 f20 f21 f22 f23 f24

There are some key aliases as well. Most of these exist due to how keys are processed in VT100 terminals. For example when pressing Tab terminal emulators receive Ctrl-i.

Key

Key Value Alias

Space

space

c-h

backspace

c-@

c-space

c-m

enter

c-i

tab

Binding Alt / Option / Meta

In terminals the Alt key is converted into a leading Escape key press. For example pressing Alt-t actually sends the Escape key followed by the t key. Similarly Ctrl-Alt-t sends Escape followed by Ctrl-t.

To bind Alt (or Option on MacOS) add escape before the key that should be modified.

key_bindings:
  window-manager.move-pane-down:
  - escape c-up  # Alt-Ctrl-up
  window-manager.move-pane-left:
  - escape c-left  # Alt-Ctrl-left
  window-manager.move-pane-right:
  - escape c-right  # Alt-Ctrl-right
  window-manager.move-pane-up:
  - escape c-down  # Alt-Ctrl-down

Key Sequence Bindings

Bindings can consist of multiple key presses in sequence. This is also known as chorded keys. Multiple keys separated by spaces define a chorded key binding. For example to bind z quickly followed by t use z t.

key_bindings:
  log-pane.shift-line-to-top:
  - z t
  log-pane.shift-line-to-center:
  - z z

Known Issues

Log Window

Upcoming Features

For upcoming features see the Pigweed Console Bug Hotlist at: https://bugs.chromium.org/u/542633886/hotlists/Console

Feature Requests

Create a feature request bugs using this template: https://bugs.chromium.org/p/pigweed/issues/entry?owner=tonymd@google.com&labels=Type-Enhancement,Priority-Medium&summary=pw_console