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