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