1.. _module-pw_console-user_guide: 2 3User Guide 4========== 5 6.. tip:: 7 8 This guide can be viewed while running pw_console under the ``[Help]`` menu 9 or online at: 10 https://pigweed.dev/pw_console/py/pw_console/docs/user_guide.html 11 12 13The Pigweed Console provides a Python repl (read eval print loop) and log viewer 14in a single-window terminal based interface. 15 16 17Starting the Console 18-------------------- 19 20Launching the console may be different if you implement your own custom console 21startup script. To launch pw_console in upstream Pigweed you can run in test 22mode with ``pw-console --test-mode``. 23 24.. seealso:: 25 26 Running pw_console for the :ref:`target-stm32f429i-disc1-stm32cube` and 27 :ref:`target-host-device-simulator` targets. 28 29Exiting 30~~~~~~~ 31 32There are a few ways to exit the Pigweed Console user interface: 33 341. Click the :guilabel:`[File]` menu and then :guilabel:`Exit`. 352. Type ``quit`` or ``exit`` in the Python Input window and press :kbd:`Enter`. 363. Press :kbd:`Ctrl-d` once to show the quit confirmation dialog. From there 37 press :kbd:`Ctrl-d` a second time or :kbd:`y` will exit. 384. Press :kbd:`Ctrl-x` quickly followed by :kbd:`Ctrl-c` will exit without 39 confirmation. 405. Press :kbd:`Ctrl-p` to search for commands, type ``exit``, then press 41 :kbd:`Enter`. 42 43 44Interface Layout 45---------------- 46 47On startup the console will display multiple windows one on top of the other. 48 49:: 50 51 +---------------------------------------------------------+ 52 | [File] [Edit] [View] [Window] [Help] Pigweed Console | 53 +=========================================================+ 54 | | 55 | | 56 | | 57 | Log Window | 58 +=========================================================+ 59 | | 60 | | 61 | Python Results | 62 +- - - - - - - - - - - - - - - - - - - - - - - - - - - - -+ 63 | | 64 | Python Input | 65 +---------------------------------------------------------+ 66 67 68Navigation 69---------- 70 71All menus, windows, and toolbar buttons can be clicked on. Scrolling with the 72mouse wheel should work too. This requires that your terminal is able to send 73mouse events. 74 75 76Navigation with the Keyboard 77~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 78 79The main menu can be searched by pressing :kbd:`Ctrl-p`. This opens a fuzzy 80search box containing all main menu item actions. 81 82Words separated by spaces are used to narrow down the match results. The order 83each word is entered does not matter. 84 85.. figure:: /pw_console/images/command_runner_main_menu.svg 86 :alt: Main menu item search dialog. 87 88============================================ ===================== 89Function Keys 90============================================ ===================== 91Open main menu search :kbd:`Ctrl-p` 92Cancel search :kbd:`Ctrl-c` 93Run selected item :kbd:`Enter` 94 95Select next item :kbd:`Tab` 96 :kbd:`Down` 97Select previous item :kbd:`Shift-Tab` 98 :kbd:`Up` 99============================================ ===================== 100 101Switching Focus 102~~~~~~~~~~~~~~~ 103 104Clicking on any window will focus on it. Alternatively, the key bindings below 105will switch focus. 106 107============================================ ===================== 108Function Keys 109============================================ ===================== 110Switch focus to the next window or tab :kbd:`Ctrl-Alt-n` 111Switch focus to the previous window or tab :kbd:`Ctrl-Alt-p` 112 113Switch focus to the next UI element :kbd:`Shift-Tab` 114 :kbd:`Ctrl-Right` 115Switch focus to the previous UI element :kbd:`Ctrl-Left` 116 117Move selection in the main menu :kbd:`Up` 118 :kbd:`Down` 119 :kbd:`Left` 120 :kbd:`Right` 121============================================ ===================== 122 123 124Toolbars 125~~~~~~~~ 126 127Log toolbar functions are clickable. You can also press the keyboard 128shortcut highlighted in blue: 129 130:: 131 132 / : Search f : [x] Follow t : [x] Table w : [ ] Wrap C : Clear 133 134 135Log Window 136~~~~~~~~~~ 137 138Log Window Navigation 139^^^^^^^^^^^^^^^^^^^^^ 140 141============================================ ===================== 142Function Keys 143============================================ ===================== 144Move cursor up 1 line :kbd:`Up` 145 :kbd:`k` 146 147Move cursor down 1 line :kbd:`Down` 148 :kbd:`j` 149 150Move cursor up 5 lines :guilabel:`Mouse Wheel Up` 151Move cursor down 5 lines :guilabel:`Mouse Wheel Down` 152 153Move cursor up one page :kbd:`PageUp` 154Move cursor down one page :kbd:`PageDown` 155 156Jump to the beginning :kbd:`g` 157Jump to the end :kbd:`G` 158============================================ ===================== 159 160Log Line Selection 161^^^^^^^^^^^^^^^^^^ 162 163============================================ ===================== 164Function Keys 165============================================ ===================== 166Select the next log line :kbd:`Shift-Down` 167Select the previous log line :kbd:`Shift-Up` 168 169Select a range of log lines :guilabel:`Left Mouse Drag` 170 171Select all lines :kbd:`Ctrl-a` 172Clear Selection :kbd:`Ctrl-c` 173============================================ ===================== 174 175When making log line selections a popup will appear in the upper right of the log 176window showing the number of lines selected along with copy and export options. 177 178:: 179 180 +--------------------------------------------------------+ 181 | 32 Selected Format: [✓] Table [ ] Markdown | 182 | [ Cancel ] [ Select All ] [ Save as File ] [ Copy ] | 183 +--------------------------------------------------------+ 184 185 186Log Window Functions 187^^^^^^^^^^^^^^^^^^^^ 188 189============================================ ===================== 190Function Keys 191============================================ ===================== 192Open the search bar :kbd:`/` 193 :kbd:`Ctrl-f` 194Save a copy of logs to a file :kbd:`Ctrl-o` 195Toggle line following. :kbd:`f` 196Toggle table view. :kbd:`t` 197Toggle line wrapping. :kbd:`w` 198Clear log pane history. :kbd:`C` 199============================================ ===================== 200 201Log Window Management 202^^^^^^^^^^^^^^^^^^^^^^^ 203 204============================================ ===================== 205Function Keys 206============================================ ===================== 207Duplicate this log pane. :kbd:`Insert` 208Remove log pane. :kbd:`Delete` 209============================================ ===================== 210 211Log Searching 212^^^^^^^^^^^^^ 213 214============================================ ===================== 215Function Keys 216============================================ ===================== 217Open the search bar :kbd:`/` 218 :kbd:`Ctrl-f` 219Navigate search term history :kbd:`Up` 220 :kbd:`Down` 221Start the search and highlight matches :kbd:`Enter` 222Close the search bar without searching :kbd:`Ctrl-c` 223============================================ ===================== 224 225Here is a view of the search bar: 226 227:: 228 229 +--------------------------------------------------------------------------+ 230 | Search Column:All Ctrl-t [ ] Invert Ctrl-v Matcher:REGEX Ctrl-n | 231 | / Search Enter Cancel Ctrl-c | 232 +--------------------------------------------------------------------------+ 233 234Across the top are various functions with keyboard shortcuts listed. Each of 235these are clickable with the mouse. 236 237**Search Parameters** 238 239- ``Column:All`` Change the part of the log message to match on. For example: 240 ``All``, ``Message`` or any extra metadata column. 241 242- ``Invert`` match. Find lines that don't match the entered text. 243 244- ``Matcher``: How the search input should be interpreted. 245 246 - ``REGEX``: Treat input text as a regex. 247 248 - ``STRING``: Treat input as a plain string. Any regex characters will be 249 escaped when search is performed. 250 251 - ``FUZZY``: input text is split on spaces using the ``.*`` regex. For 252 example if you search for ``idle run`` the resulting search regex used 253 under the hood is ``(idle)(.*?)(run)``. This would match both of these 254 lines: 255 256 .. code-block:: text 257 258 Idle task is running 259 Idle thread is running 260 261**Active Search Shortcuts** 262 263When a search is started the bar will close, log follow mode is disabled and all 264matches will be highlighted. At this point a few extra keyboard shortcuts are 265available. 266 267============================================ ===================== 268Function Keys 269============================================ ===================== 270Move to the next search result :kbd:`n` 271 :kbd:`Ctrl-g` 272 :kbd:`Ctrl-s` 273Move to the previous search result :kbd:`N` 274 :kbd:`Ctrl-r` 275Clear active search :kbd:`Ctrl-c` 276Creates a filter using the active search :kbd:`Ctrl-Alt-f` 277Reset all active filters. :kbd:`Ctrl-Alt-r` 278============================================ ===================== 279 280 281Log Filtering 282^^^^^^^^^^^^^ 283 284Log filtering allows you to limit what log lines appear in any given log 285window. Filters can be added from the currently active search or directly in the 286search bar. 287 288- With the search bar **open**: 289 290 Type something to search for then press :kbd:`Ctrl-Alt-f` or click on 291 :guilabel:`Add Filter`. 292 293- With the search bar **closed**: 294 295 Press :kbd:`Ctrl-Alt-f` to use the current search term as a filter. 296 297When a filter is active the ``Filters`` toolbar will appear at the bottom of the 298log window. For example, here are some logs with one active filter for 299``lorem ipsum``. 300 301:: 302 303 +------------------------------------------------------------------------------+ 304 | Time Lvl Module Message | 305 +------------------------------------------------------------------------------+ 306 | 20210722 15:38:14 INF APP Log message # 270 Lorem ipsum dolor sit amet | 307 | 20210722 15:38:24 INF APP Log message # 280 Lorem ipsum dolor sit amet | 308 | 20210722 15:38:34 INF APP Log message # 290 Lorem ipsum dolor sit amet | 309 | 20210722 15:38:44 INF APP Log message # 300 Lorem ipsum dolor sit amet | 310 | 20210722 15:38:54 INF APP Log message # 310 Lorem ipsum dolor sit amet | 311 | 20210722 15:39:04 INF APP Log message # 320 Lorem ipsum dolor sit amet | 312 +------------------------------------------------------------------------------+ 313 | Filters <lorem ipsum (X)> Ctrl-Alt-r : Clear Filters | 314 +------------------------------------------------------------------------------+ 315 | Logs / : Search f : [x] Follow t : [x] Table w : [ ] Wrap C : Clear | 316 +------------------------------------------------------------------------------+ 317 318**Stacking Filters** 319 320Adding a second filter on the above logs for ``# 2`` would update the filter 321toolbar to show: 322 323:: 324 325 +------------------------------------------------------------------------------+ 326 | Time Lvl Module Message | 327 +------------------------------------------------------------------------------+ 328 | | 329 | | 330 | | 331 | 20210722 15:38:14 INF APP Log message # 270 Lorem ipsum dolor sit amet | 332 | 20210722 15:38:24 INF APP Log message # 280 Lorem ipsum dolor sit amet | 333 | 20210722 15:38:34 INF APP Log message # 290 Lorem ipsum dolor sit amet | 334 +------------------------------------------------------------------------------+ 335 | Filters <lorem ipsum (X)> <# 2 (X)> Ctrl-Alt-r : Clear Filters | 336 +------------------------------------------------------------------------------+ 337 | Logs / : Search f : [x] Follow t : [x] Table w : [ ] Wrap C : Clear | 338 +------------------------------------------------------------------------------+ 339 340Any filter listed in the Filters toolbar and can be individually removed by 341clicking on the red ``(X)`` text. 342 343 344Python Window 345~~~~~~~~~~~~~ 346 347 348Running Code in the Python Repl 349^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 350 351- Type code and hit :kbd:`Enter` to run. 352- If multiple lines are used, move the cursor to the end and press 353 :kbd:`Enter` twice. 354- :kbd:`Up` / :kbd:`Down` Navigate command history 355- :kbd:`Ctrl-r` Start reverse history searching 356- :kbd:`Ctrl-c` Erase the input buffer 357- :kbd:`Ctrl-v` Paste text from the clipboard to the input buffer 358- :kbd:`Ctrl-Alt-c` Copy the Python Output to the system clipboard 359 360 - If the input buffer is empty: 361 :kbd:`Ctrl-c` cancels any currently running Python commands. 362 363- :kbd:`F2` Open the python repl settings (from 364 `ptpython <https://github.com/prompt-toolkit/ptpython>`__). This 365 works best in vertical split mode. 366 367 - To exit: hit :kbd:`F2` again. 368 - Navigate options with the arrow keys, Enter will close the menu. 369 370- :kbd:`F3` Open the python repl history (from 371 `ptpython <https://github.com/prompt-toolkit/ptpython>`__). 372 373 - To exit: hit :kbd:`F3` again. 374 - Left side shows previously entered commands 375 - Use arrow keys to navigate. 376 - :kbd:`Space` to select as many lines you want to use 377 378 - Selected lines will be appended to the right side. 379 380 - :kbd:`Enter` to accept the right side text, this will be inserted 381 into the repl. 382 383 384Copy & Pasting 385~~~~~~~~~~~~~~ 386 387Copying Text 388^^^^^^^^^^^^ 389 390Text can be copied from the Log and Python windows when they are in focus with 391these keybindings. 392 393============================================ ===================== 394Function Keys 395============================================ ===================== 396Copy Logs from the focused log window :kbd:`Ctrl-c` 397Copy Python Output if window is focused :kbd:`Ctrl-Alt-c` 398============================================ ===================== 399 400Text will be put in the host computer's system clipboard using the 401`pyperclip package <https://pypi.org/project/pyperclip/>`__. 402 403The above functions can also be accessed by clicking on the toolbar help text or 404accessed under the :guilabel:`[Edit]` menu. 405 406If you need to copy text from any other part of the UI you will have to use your 407terminal's built in text selection: 408 409**Linux** 410 411- Holding :kbd:`Shift` and dragging the mouse in most terminals. 412 413**Mac** 414 415- **Apple Terminal**: 416 417 Hold :kbd:`Fn` and drag the mouse 418 419- **iTerm2**: 420 421 Hold :kbd:`Cmd+Option` and drag the mouse 422 423**Windows** 424 425- **Git CMD** (included in `Git for Windows <https://git-scm.com/downloads>`__) 426 427 1. Click on the Git window icon in the upper left of the title bar 428 2. Click ``Edit`` then ``Mark`` 429 3. Drag the mouse to select text and press Enter to copy. 430 431- **Windows Terminal** 432 433 1. Hold :kbd:`Shift` and drag the mouse to select text 434 2. Press :kbd:`Ctrl-Shift-C` to copy. 435 436Pasting Text 437^^^^^^^^^^^^ 438 439Text can be pasted into the Python Input window from the system clipboard with 440:kbd:`Ctrl-v`. 441 442If you are using the console on a separate machine (over an ssh connection for 443example) then pasting will use that machine's clipboard. This may not be the 444computer where you copied the text. In that case you will need to use your 445terminal emulator's paste function. How to do this depends on what terminal you 446are using and on which OS. Here's how on various platforms: 447 448**Linux** 449 450- **XTerm** 451 452 :kbd:`Shift-Insert` pastes text 453 454- **Gnome Terminal** 455 456 :kbd:`Ctrl-Shift-V` pastes text 457 458**Windows** 459 460- **Git CMD** (included in `Git for Windows <https://git-scm.com/downloads>`__) 461 462 1. Click on the Git icon in the upper left of the windows title bar and open 463 ``Properties``. 464 2. Checkmark the option ``Use Ctrl+Shift+C/V as Copy Paste`` and hit ok. 465 3. Then use :kbd:`Ctrl-Shift-V` to paste. 466 467- **Windows Terminal** 468 469 1. :kbd:`Ctrl-Shift-V` pastes text. 470 2. :kbd:`Shift-RightClick` also pastes text. 471 472 473Window Management 474~~~~~~~~~~~~~~~~~ 475 476Any window can be hidden by clicking the :guilabel:`[x] Show Window` checkbox 477under the :guilabel:`[Window]` menu. 478 479The active window can be moved and resized with the following keys. There are 480also menu options under :guilabel:`[View]` for the same actions. Additionally, 481windows can be resized with the mouse by click dragging on the :guilabel:`====` 482text on the far right side of any toolbar. 483 484============================================ ===================== 485Function Keys 486============================================ ===================== 487Enlarge window height :kbd:`Alt-=` 488Shrink window height :kbd:`Alt--` 489 (:kbd:`Alt` and :kbd:`Minus`) 490Enlarge vertical split width :kbd:`Alt-,` 491Shrink vertical split width :kbd:`Alt-.` 492Reset window sizes :kbd:`Ctrl-u` 493 494Move window up :kbd:`Ctrl-Alt-Up` 495Move window down :kbd:`Ctrl-Alt-Down` 496Move window left :kbd:`Ctrl-Alt-Left` 497Move window right :kbd:`Ctrl-Alt-Right` 498============================================ ===================== 499 500Moving windows left and right will create a new vertical splits. Each vertical 501stack can contain multiple windows and show windows as a stack or tabbed 502view. 503 504For example here we have 3 window panes in a single stack. If you focus on Log 505Window 1 and move it to the right a new stack is formed in a vertical 506split. This can be done repeatedly to form additional window stacks. 507 508:: 509 510 +----------------------------------+ +----------------------------------+ 511 | [File] [View] [Window] Console | | [File] [View] [Window] Console | 512 +==================================+ +================+=================+ 513 | Log Window 1 | | Log Window 2 | Log Window 1 | 514 | | | | | 515 +==================================+ | | | 516 | Log Window 2 | | | | 517 | | | | | 518 +==================================+ +================+ | 519 | | | | | 520 | | | | | 521 | Python Results | | Python Results | | 522 | | | | | 523 | Python Input | | Python Input | | 524 +----------------------------------+ +----------------+-----------------+ 525 526Color Depth 527----------- 528 529Some terminals support full 24-bit color and pw console will use that by default 530in most cases. One notable exeception is Apple Terminal on MacOS which supports 531256 colors only. `iTerm2 <https://iterm2.com/>`__ is a good MacOS alternative 532that supports 24-bit colors. 533 534To force a particular color depth: set one of these environment variables before 535launching the console. For ``bash`` and ``zsh`` shells you can use the 536``export`` command. 537 538:: 539 540 # 1 bit | Black and white 541 export PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_1_BIT 542 # 4 bit | ANSI colors 543 export PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_4_BIT 544 # 8 bit | 256 colors 545 export PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_8_BIT 546 # 24 bit | True colors 547 export PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_24_BIT 548 549For Windows command prompt (``cmd.exe``) use the ``set`` command: 550 551:: 552 553 set PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_1_BIT 554 set PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_4_BIT 555 set PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_8_BIT 556 set PROMPT_TOOLKIT_COLOR_DEPTH=DEPTH_24_BIT 557 558Configuration 559------------- 560 561Pigweed Console supports loading project and user specific settings stored in 562YAML files. Each file follows the same format and are loaded one after the 563other. Any setting specified multiple locations will be overridden by files 564loaded later in the startup sequence. 565 5661. ``$PW_PROJECT_ROOT/.pw_console.yaml`` 567 568 Project level config file. This is intended to be a file living somewhere 569 under a project folder and is checked into version control. It serves as a 570 base config for all users to inherit from. 571 5722. ``$PW_PROJECT_ROOT/.pw_console.user.yaml`` 573 574 User's personal config file for a specific project. This can be a file that 575 lives in a project folder but is git-ignored and not checked into version 576 control. This lets users change settings applicable to this project only. 577 5783. ``$HOME/.pw_console.yaml`` 579 580 A global user based config file. This file is located in the user's home 581 directory and settings here apply to all projects. This is a good location to 582 set appearance options such as: 583 584 .. code-block:: yaml 585 586 --- 587 config_title: pw_console 588 ui_theme: nord 589 code_theme: pigweed-code 590 swap_light_and_dark: False 591 spaces_between_columns: 2 592 hide_date_from_log_time: False 593 594It's also possible to specify a config file via a shell environment variable. If 595this method is used only this config file is applied. Project and user config 596file options will not be set. 597 598:: 599 600 export PW_CONSOLE_CONFIG_FILE=/home/.config/pw_console/config.yaml 601 602Example Config 603~~~~~~~~~~~~~~ 604 605.. code-block:: yaml 606 607 --- 608 config_title: pw_console 609 610 # Repl and Search History files 611 # Setting these to a file located $PW_PROJECT_ROOT is a 612 # good way to make Python repl history project specific. 613 614 # Default: $HOME/.pw_console_history 615 repl_history: $PW_PROJECT_ROOT/.pw_console_history 616 617 # Default: $HOME/.pw_console_search 618 search_history: $PW_PROJECT_ROOT/.pw_console_search 619 620 # Theme Settings 621 622 # Default: dark 623 ui_theme: high-contrast-dark 624 625 # Default: pigweed-code 626 code_theme: material 627 628 # Default: False 629 swap_light_and_dark: False 630 631 # Log Table View Settings 632 633 # Number of spaces to insert between columns 634 # Default: 2 635 spaces_between_columns: 2 636 637 # Hide the year month and day from the time column. 638 hide_date_from_log_time: False 639 640 # Show the Python file and line number responsible for creating log messages. 641 show_python_file: False 642 # Show the Python logger responsible for creating log messages. 643 show_python_logger: False 644 # Show the 'file' metadata column. 645 show_source_file: False 646 647 # Custom Column Ordering 648 # By default columns are ordered as: 649 # time, level, metadata1, metadata2, ..., message 650 # The log message is always the last value and not required in this list. 651 column_order: 652 # Column name 653 - time 654 - level 655 - metadata1 656 - metadata2 657 658 # If True, any metadata field not listed above in 'column_order' 659 # will be hidden in table view. 660 column_order_omit_unspecified_columns: False 661 662 # Unique Colors for Column Values 663 # Color format: 'bg:#BG-HEX #FG-HEX STYLE' 664 # All parts are optional. 665 # Empty strings will leave styling unchanged. 666 column_colors: 667 # Column name 668 time: 669 level: 670 metadata1: 671 # Field values 672 # Default will be applied if no match found 673 default: '#98be65' 674 BATTERY: 'bg:#6699cc #000000 bold' 675 CORE1: 'bg:#da8548 #000000 bold' 676 CORE2: 'bg:#66cccc #000000 bold' 677 metadata2: 678 default: '#ffcc66' 679 APP: 'bg:#ff6c6b #000000 bold' 680 WIFI: '#555555' 681 682 # Each window column is normally aligned side by side in vertical splits. You 683 # can change this to one group of windows on top of the other with horizontal 684 # splits using this method 685 686 # Default: vertical 687 window_column_split_method: vertical 688 689 # Window Layout 690 windows: 691 # First window column (vertical split) 692 # Each split should have a unique name and include either 693 # 'stacked' or 'tabbed' to select a window pane display method. 694 Split 1 stacked: 695 # Items here are window titles, each should be unique. 696 # Window 1 697 Device Logs: 698 height: 33 # Weighted value for window height 699 hidden: False # Hide this window if True 700 # Window 2 701 Python Repl: 702 height: 67 703 # Window 3 704 Host Logs: 705 hidden: True 706 707 # Second window column 708 Split 2 tabbed: 709 # This is a duplicate of the existing 'Device Logs' window. 710 # The title is 'NEW DEVICE' 711 NEW DEVICE: 712 duplicate_of: Device Logs 713 # Log filters are defined here 714 filters: 715 # Metadata column names here or 'all' 716 source_name: 717 # Matching method name here 718 # regex, regex-inverted, string, string-inverted 719 regex: 'USB' 720 module: 721 # An inverted match will remove matching log lines 722 regex-inverted: 'keyboard' 723 NEW HOST: 724 duplicate_of: Host Logs 725 filters: 726 all: 727 string: 'FLASH' 728 729 # Third window column 730 Split 3 tabbed: 731 # This is a brand new log Window 732 Keyboard Logs - IBM: 733 loggers: 734 # Python logger names to include in this log window 735 my_cool_keyboard_device: 736 # Level the logger should be set to. 737 level: DEBUG 738 # The empty string logger name is the root Python logger. 739 # In most cases this should capture all log messages. 740 '': 741 level: DEBUG 742 filters: 743 all: 744 regex: 'IBM Model M' 745 Keyboard Logs - Apple: 746 loggers: 747 my_cool_keyboard_device: 748 level: DEBUG 749 filters: 750 all: 751 regex: 'Apple.*USB' 752 753 # Command Runner dialog size and position 754 command_runner: 755 width: 80 756 height: 10 757 position: 758 top: 3 # 3 lines below the top edge of the screen 759 # Alternatively one of these options can be used instead: 760 # bottom: 2 # 2 lines above the bottom edge of the screen 761 # left: 2 # 2 lines away from the left edge of the screen 762 # right: 2 # 2 lines away from the right edge of the screen 763 764 # Key bindings can be changed as well with the following format: 765 # named-command: [ list_of_keys ] 766 # Where list_of_keys is a string of keys one for each alternate key 767 # To see all named commands open '[Help] > View Key Binding Config' 768 # See below for the names of special keys 769 key_bindings: 770 log-pane.move-cursor-up: 771 - j 772 - up 773 log-pane.move-cursor-down: 774 - k 775 - down 776 log-pane.search-next-match: 777 - n 778 log-pane.search-previous-match: 779 - N 780 781 # Chorded keys are supported. 782 # For example, 'z t' means pressing z quickly followed by t. 783 log-pane.shift-line-to-top: 784 - z t 785 log-pane.shift-line-to-center: 786 - z z 787 788 # Python Repl Snippets (Project owned) 789 snippets: 790 Count Ten Times: | 791 for i in range(10): 792 print(i) 793 Local Variables: | 794 locals() 795 796 # Python Repl Snippets (User owned) 797 user_snippets: 798 Pretty print format function: | 799 import pprint 800 _pretty_format = pprint.PrettyPrinter(indent=1, width=120).pformat 801 Global variables: | 802 globals() 803 804 805Changing Keyboard Shortcuts 806--------------------------- 807 808Pigweed Console uses `prompt_toolkit 809<https://python-prompt-toolkit.readthedocs.io/en/latest/>`_ to manage its 810keybindings. 811 812Bindings can be changed in the YAML config file under the ``key_bindings:`` 813section by adding a named function followed by a of keys to bind. For example 814this config sets the keys for log pane cursor movement. 815 816- Moving down is set to :kbd:`j` or the :kbd:`Down` arrow. 817- Moving up is set to :kbd:`k` or the :kbd:`Up` arrow. 818 819.. code-block:: yaml 820 821 key_bindings: 822 log-pane.move-cursor-down: 823 - j 824 - down 825 log-pane.move-cursor-up: 826 - k 827 - up 828 829List of Special Key Names 830~~~~~~~~~~~~~~~~~~~~~~~~~ 831 832This table is from prompt_toolkit's :bdg-link-primary-line:`List of special keys 833<https://python-prompt-toolkit.readthedocs.io/en/latest/pages/advanced_topics/key_bindings.html#list-of-special-keys>`. 834 835.. list-table:: 836 :widths: 30 70 837 :header-rows: 1 838 839 * - Keyboard Function 840 - Key Values 841 842 * - Literal characters 843 - ``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`` 844 ``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`` 845 ``1 2 3 4 5 6 7 8 9 0`` 846 ``! @ # $ % ^ & * ( )`` 847 ``- _ + = ~`` 848 849 * - Escape and Shift-Escape 850 - ``escape`` ``s-escape`` 851 852 * - Arrows 853 - ``left`` ``right`` ``up`` ``down`` 854 855 * - Navigation 856 - ``home`` ``end`` ``delete`` ``pageup`` ``pagedown`` ``insert`` 857 858 * - Control-letter 859 - ``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`` 860 ``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`` 861 862 * - Control-number 863 - ``c-1`` ``c-2`` ``c-3`` ``c-4`` ``c-5`` ``c-6`` ``c-7`` ``c-8`` ``c-9`` ``c-0`` 864 865 * - Control-arrow 866 - ``c-left`` ``c-right`` ``c-up`` ``c-down`` 867 868 * - Other control keys 869 - ``c-@`` ``c-\`` ``c-]`` ``c-^`` ``c-_`` ``c-delete`` 870 871 * - Shift-arrow 872 - ``s-left`` ``s-right`` ``s-up`` ``s-down`` 873 874 * - Control-Shift-arrow 875 - ``c-s-left`` ``c-s-right`` ``c-s-up`` ``c-s-down`` 876 877 * - Other Shift` keys 878 - ``s-delete`` ``s-tab`` 879 880 * - F Keys 881 - ``f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12`` 882 ``f13 f14 f15 f16 f17 f18 f19 f20 f21 f22 f23 f24`` 883 884There are some key aliases as well. Most of these exist due to how keys are 885processed in VT100 terminals. For example when pressing :kbd:`Tab` terminal 886emulators receive :kbd:`Ctrl-i`. 887 888.. list-table:: 889 :widths: 40 60 890 :header-rows: 1 891 892 * - Key 893 - Key Value Alias 894 895 * - Space 896 - ``space`` 897 898 * - ``c-h`` 899 - ``backspace`` 900 901 * - ``c-@`` 902 - ``c-space`` 903 904 * - ``c-m`` 905 - ``enter`` 906 907 * - ``c-i`` 908 - ``tab`` 909 910Binding Alt / Option / Meta 911~~~~~~~~~~~~~~~~~~~~~~~~~~~ 912 913In terminals the :kbd:`Alt` key is converted into a leading :kbd:`Escape` key 914press. For example pressing :kbd:`Alt-t` actually sends the :kbd:`Escape` key 915followed by the :kbd:`t` key. Similarly :kbd:`Ctrl-Alt-t` sends :kbd:`Escape` 916followed by :kbd:`Ctrl-t`. 917 918To bind :kbd:`Alt` (or :kbd:`Option` on MacOS) add ``escape`` before the key 919that should be modified. 920 921.. code-block:: yaml 922 923 key_bindings: 924 window-manager.move-pane-down: 925 - escape c-up # Alt-Ctrl-up 926 window-manager.move-pane-left: 927 - escape c-left # Alt-Ctrl-left 928 window-manager.move-pane-right: 929 - escape c-right # Alt-Ctrl-right 930 window-manager.move-pane-up: 931 - escape c-down # Alt-Ctrl-down 932 933Key Sequence Bindings 934~~~~~~~~~~~~~~~~~~~~~ 935 936Bindings can consist of multiple key presses in sequence. This is also known as 937chorded keys. Multiple keys separated by spaces define a chorded key 938binding. For example to bind :kbd:`z` quickly followed by :kbd:`t` use ``z t``. 939 940.. code-block:: yaml 941 942 key_bindings: 943 log-pane.shift-line-to-top: 944 - z t 945 log-pane.shift-line-to-center: 946 - z z 947 948 949Known Issues 950------------ 951 952Log Window 953~~~~~~~~~~ 954 955- Tab character rendering will not work in the log pane view. They will 956 appear as ``^I`` since prompt_toolkit can't render them. See this issue for 957 details: 958 https://github.com/prompt-toolkit/python-prompt-toolkit/issues/556 959 960 961Upcoming Features 962----------------- 963 964For upcoming features see the Pigweed Console Bug Hotlist at: 965https://bugs.chromium.org/u/542633886/hotlists/Console 966 967 968Feature Requests 969~~~~~~~~~~~~~~~~ 970 971Create a feature request bugs using this template: 972https://bugs.chromium.org/p/pigweed/issues/entry?owner=tonymd@google.com&labels=Type-Enhancement,Priority-Medium&summary=pw_console 973
