User Guide

See also

This guide can be viewed online at: https://pigweed.dev/pw_console/

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

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

  2. Type quit or exit in the Python Input window and 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 a YAML file. By default these files will be loaded one after the other:

  • $PW_PROJECT_ROOT/.pw_console.yaml

  • $HOME/.pw_console.yaml

Each file follows the same format with settings in $HOME overriding ones in $PW_PROJECT_ROOT.

It’s also possible to specify a config file via a shell environment variable.

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

Example Config

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

  # 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 Any metadata field not listed above 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.
  # See prompt_toolkit style format docs here:
  #   https://python-prompt-toolkit.readthedocs.io/en/latest/pages/advanced_topics/styling.html
  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 with a new title
      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
        filters:
          all:
            regex: 'IBM Model M'
      Keyboard Logs - Apple:
        loggers:
          my_cool_keyboard_device:
            level: DEBUG
        filters:
          all:
            regex: 'Apple.*USB'

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