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 # Show the Python file and line number responsible for creating log messages. 644 show_python_file: False 645 # Show the Python logger responsible for creating log messages. 646 show_python_logger: False 647 # Show the 'file' metadata column. 648 show_source_file: False 649 650 # Custom Column Ordering 651 # By default columns are ordered as: 652 # time, level, metadata1, metadata2, ..., message 653 # The log message is always the last value and not required in this list. 654 column_order: 655 # Column name 656 - time 657 - level 658 - metadata1 659 - metadata2 660 661 # If True, any metadata field not listed above in 'column_order' 662 # will be hidden in table view. 663 column_order_omit_unspecified_columns: False 664 665 # Unique Colors for Column Values 666 # Color format: 'bg:#BG-HEX #FG-HEX STYLE' 667 # All parts are optional. 668 # Empty strings will leave styling unchanged. 669 column_colors: 670 # Column name 671 time: 672 level: 673 metadata1: 674 # Field values 675 # Default will be applied if no match found 676 default: '#98be65' 677 BATTERY: 'bg:#6699cc #000000 bold' 678 CORE1: 'bg:#da8548 #000000 bold' 679 CORE2: 'bg:#66cccc #000000 bold' 680 metadata2: 681 default: '#ffcc66' 682 APP: 'bg:#ff6c6b #000000 bold' 683 WIFI: '#555555' 684 685 # Each window column is normally aligned side by side in vertical splits. You 686 # can change this to one group of windows on top of the other with horizontal 687 # splits using this method 688 689 # Default: vertical 690 window_column_split_method: vertical 691 692 # Window Layout 693 windows: 694 # First window column (vertical split) 695 # Each split should have a unique name and include either 696 # 'stacked' or 'tabbed' to select a window pane display method. 697 Split 1 stacked: 698 # Items here are window titles, each should be unique. 699 # Window 1 700 Device Logs: 701 height: 33 # Weighted value for window height 702 hidden: False # Hide this window if True 703 # Window 2 704 Python Repl: 705 height: 67 706 # Window 3 707 Host Logs: 708 hidden: True 709 710 # Second window column 711 Split 2 tabbed: 712 # This is a duplicate of the existing 'Device Logs' window. 713 # The title is 'NEW DEVICE' 714 NEW DEVICE: 715 duplicate_of: Device Logs 716 # Log filters are defined here 717 filters: 718 # Metadata column names here or 'all' 719 source_name: 720 # Matching method name here 721 # regex, regex-inverted, string, string-inverted 722 regex: 'USB' 723 module: 724 # An inverted match will remove matching log lines 725 regex-inverted: 'keyboard' 726 NEW HOST: 727 duplicate_of: Host Logs 728 filters: 729 all: 730 string: 'FLASH' 731 732 # Third window column 733 Split 3 tabbed: 734 # This is a brand new log Window 735 Keyboard Logs - IBM: 736 loggers: 737 # Python logger names to include in this log window 738 my_cool_keyboard_device: 739 # Level the logger should be set to. 740 level: DEBUG 741 # The empty string logger name is the root Python logger. 742 # In most cases this should capture all log messages. 743 '': 744 level: DEBUG 745 filters: 746 all: 747 regex: 'IBM Model M' 748 Keyboard Logs - Apple: 749 loggers: 750 my_cool_keyboard_device: 751 level: DEBUG 752 filters: 753 all: 754 regex: 'Apple.*USB' 755 756 # Command Runner dialog size and position 757 command_runner: 758 width: 80 759 height: 10 760 position: 761 top: 3 # 3 lines below the top edge of the screen 762 # Alternatively one of these options can be used instead: 763 # bottom: 2 # 2 lines above the bottom edge of the screen 764 # left: 2 # 2 lines away from the left edge of the screen 765 # right: 2 # 2 lines away from the right edge of the screen 766 767 # Key bindings can be changed as well with the following format: 768 # named-command: [ list_of_keys ] 769 # Where list_of_keys is a string of keys one for each alternate key 770 # To see all named commands open '[Help] > View Key Binding Config' 771 # See below for the names of special keys 772 key_bindings: 773 log-pane.move-cursor-up: 774 - j 775 - up 776 log-pane.move-cursor-down: 777 - k 778 - down 779 log-pane.search-next-match: 780 - n 781 log-pane.search-previous-match: 782 - N 783 784 # Chorded keys are supported. 785 # For example, 'z t' means pressing z quickly followed by t. 786 log-pane.shift-line-to-top: 787 - z t 788 log-pane.shift-line-to-center: 789 - z z 790 791 # Project and User defined Python snippets 792 # Press Ctrl-t the Python Repl to select which snippet to insert. 793 794 # Python Repl Snippets (Project owned) 795 snippets: 796 Count Ten Times: 797 code: | 798 for i in range(10): 799 print(i) 800 description: | 801 Print out 1 through 10 each on a separate line 802 803 Local Variables: 804 code: | 805 locals() 806 description: | 807 Return all local Python variables. 808 809 # Python Repl Snippets (User owned) 810 user_snippets: 811 Pretty print format function: 812 code: | 813 import pprint 814 _pretty_format = pprint.PrettyPrinter(indent=1, width=120).pformat 815 description: | 816 Create a function named `_pretty_format` which returns a pretty 817 formatted string for a Python object. 818 819 Example: 820 821 ```python 822 from dataclasses import dataclass 823 824 @dataclass 825 class CodeSnippet: 826 title: str 827 code: str 828 description: str = '' 829 830 _pretty_format(CodeSnippet('one', '1')) 831 ``` 832 833 The last line will return the string: 834 835 ``` 836 "CodeSnippet(title='one', code='1', description='')" 837 ``` 838 839 Global variables: 840 code: | 841 globals() 842 description: | 843 Return all global Python variables. 844 845 846Python Repl Snippets 847-------------------- 848Python code snippets can be defined under the ``snippets:`` or 849``user_snippets:`` section. We suggest reserving ``user_snippets:`` for the user 850based config files (``$HOME/.pw_console.yaml`` or 851``$PW_PROJECT_ROOT/.pw_console.user.yaml``). ``snippets:`` is best suited for a 852project specific config file shared by all team members: 853``$PW_PROJECT_ROOT/.pw_console.yaml`` 854 855Snippets consist of a title followed by ``code: |`` and optionally 856``description: |``. The YAML operator ``|`` will concatenate the following lines 857into a string and strip leading whitespace. 858 859 860.. code-block:: yaml 861 862 snippets: 863 Count Ten Times: 864 code: | 865 for i in range(10): 866 print(i) 867 description: | 868 Print out 1 through 10 each on a separate line 869 870Inserting this snippet will paste the for loop above into the Python Repl input 871window. 872 873Descriptions are markdown formatted and displayed below the selected snippet 874window. Fenced code blocks will have the correct syntax highlighting 875applied. For example the following will apply Python syntax highlighting to the 876code block below ``Example:``. 877 878.. code-block:: yaml 879 880 snippets: 881 Pretty print format function: 882 code: | 883 import pprint 884 _pretty_format = pprint.PrettyPrinter(indent=1, width=120).pformat 885 description: | 886 Create a function named `_pretty_format` which returns a pretty 887 formatted string for a Python object. 888 889 Example: 890 891 ```python 892 from dataclasses import dataclass 893 894 @dataclass 895 class CodeSnippet: 896 title: str 897 code: str 898 description: str = '' 899 900 _pretty_format(CodeSnippet('one', '1')) 901 ``` 902 903If identical description text needs to be repeated for multiple snippets in a 904row you can set ``description: USE_PREVIOUS``. For example these two snippets 905will have the same description text: 906``Helper functions for pretty printing Python objects.`` 907 908 909.. code-block:: yaml 910 911 snippets: 912 Pretty print format function: 913 code: | 914 import pprint 915 _pretty_format = pprint.PrettyPrinter(indent=1, width=120).pformat 916 description: | 917 Helper functions for pretty printing Python objects. 918 919 Pretty print function: 920 code: | 921 import pprint 922 _pretty_print = pprint.PrettyPrinter(indent=1, width=120).pprint 923 description: USE_PREVIOUS 924 925 926 927Changing Keyboard Shortcuts 928--------------------------- 929 930Pigweed Console uses `prompt_toolkit 931<https://python-prompt-toolkit.readthedocs.io/en/latest/>`_ to manage its 932keybindings. 933 934Bindings can be changed in the YAML config file under the ``key_bindings:`` 935section by adding a named function followed by a of keys to bind. For example 936this config sets the keys for log pane cursor movement. 937 938- Moving down is set to :kbd:`j` or the :kbd:`Down` arrow. 939- Moving up is set to :kbd:`k` or the :kbd:`Up` arrow. 940 941.. code-block:: yaml 942 943 key_bindings: 944 log-pane.move-cursor-down: 945 - j 946 - down 947 log-pane.move-cursor-up: 948 - k 949 - up 950 951List of Special Key Names 952~~~~~~~~~~~~~~~~~~~~~~~~~ 953 954This table is from prompt_toolkit's :bdg-link-primary-line:`List of special keys 955<https://python-prompt-toolkit.readthedocs.io/en/latest/pages/advanced_topics/key_bindings.html#list-of-special-keys>`. 956 957.. list-table:: 958 :widths: 30 70 959 :header-rows: 1 960 961 * - Keyboard Function 962 - Key Values 963 964 * - Literal characters 965 - ``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`` 966 ``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`` 967 ``1 2 3 4 5 6 7 8 9 0`` 968 ``! @ # $ % ^ & * ( )`` 969 ``- _ + = ~`` 970 971 * - Escape and Shift-Escape 972 - ``escape`` ``s-escape`` 973 974 * - Arrows 975 - ``left`` ``right`` ``up`` ``down`` 976 977 * - Navigation 978 - ``home`` ``end`` ``delete`` ``pageup`` ``pagedown`` ``insert`` 979 980 * - Control-letter 981 - ``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`` 982 ``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`` 983 984 * - Control-number 985 - ``c-1`` ``c-2`` ``c-3`` ``c-4`` ``c-5`` ``c-6`` ``c-7`` ``c-8`` ``c-9`` ``c-0`` 986 987 * - Control-arrow 988 - ``c-left`` ``c-right`` ``c-up`` ``c-down`` 989 990 * - Other control keys 991 - ``c-@`` ``c-\`` ``c-]`` ``c-^`` ``c-_`` ``c-delete`` 992 993 * - Shift-arrow 994 - ``s-left`` ``s-right`` ``s-up`` ``s-down`` 995 996 * - Control-Shift-arrow 997 - ``c-s-left`` ``c-s-right`` ``c-s-up`` ``c-s-down`` 998 999 * - Other Shift` keys 1000 - ``s-delete`` ``s-tab`` 1001 1002 * - F Keys 1003 - ``f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12`` 1004 ``f13 f14 f15 f16 f17 f18 f19 f20 f21 f22 f23 f24`` 1005 1006There are some key aliases as well. Most of these exist due to how keys are 1007processed in VT100 terminals. For example when pressing :kbd:`Tab` terminal 1008emulators receive :kbd:`Ctrl-i`. 1009 1010.. list-table:: 1011 :widths: 40 60 1012 :header-rows: 1 1013 1014 * - Key 1015 - Key Value Alias 1016 1017 * - Space 1018 - ``space`` 1019 1020 * - ``c-h`` 1021 - ``backspace`` 1022 1023 * - ``c-@`` 1024 - ``c-space`` 1025 1026 * - ``c-m`` 1027 - ``enter`` 1028 1029 * - ``c-i`` 1030 - ``tab`` 1031 1032Binding Alt / Option / Meta 1033~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1034 1035In terminals the :kbd:`Alt` key is converted into a leading :kbd:`Escape` key 1036press. For example pressing :kbd:`Alt-t` actually sends the :kbd:`Escape` key 1037followed by the :kbd:`t` key. Similarly :kbd:`Ctrl-Alt-t` sends :kbd:`Escape` 1038followed by :kbd:`Ctrl-t`. 1039 1040To bind :kbd:`Alt` (or :kbd:`Option` on MacOS) add ``escape`` before the key 1041that should be modified. 1042 1043.. code-block:: yaml 1044 1045 key_bindings: 1046 window-manager.move-pane-down: 1047 - escape c-up # Alt-Ctrl-up 1048 window-manager.move-pane-left: 1049 - escape c-left # Alt-Ctrl-left 1050 window-manager.move-pane-right: 1051 - escape c-right # Alt-Ctrl-right 1052 window-manager.move-pane-up: 1053 - escape c-down # Alt-Ctrl-down 1054 1055Key Sequence Bindings 1056~~~~~~~~~~~~~~~~~~~~~ 1057 1058Bindings can consist of multiple key presses in sequence. This is also known as 1059chorded keys. Multiple keys separated by spaces define a chorded key 1060binding. For example to bind :kbd:`z` quickly followed by :kbd:`t` use ``z t``. 1061 1062.. code-block:: yaml 1063 1064 key_bindings: 1065 log-pane.shift-line-to-top: 1066 - z t 1067 log-pane.shift-line-to-center: 1068 - z z 1069 1070 1071Known Issues 1072------------ 1073 1074Log Window 1075~~~~~~~~~~ 1076 1077- Tab character rendering will not work in the log pane view. They will 1078 appear as ``^I`` since prompt_toolkit can't render them. See this issue for 1079 details: 1080 https://github.com/prompt-toolkit/python-prompt-toolkit/issues/556 1081 1082 1083Upcoming Features 1084----------------- 1085 1086For upcoming features see the Pigweed Console Bug Hotlist at: 1087https://bugs.chromium.org/u/542633886/hotlists/Console 1088 1089 1090Feature Requests 1091~~~~~~~~~~~~~~~~ 1092 1093Create a feature request bugs using this template: 1094https://bugs.chromium.org/p/pigweed/issues/entry?owner=tonymd@google.com&labels=Type-Enhancement,Priority-Medium&summary=pw_console 1095
