pw_console/docs.rst


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

.. _module-pw_console:

==========
pw_console
==========
.. pigweed-module::
   :name: pw_console
   :tagline: Multi-purpose pluggable interactive console for dev & manufacturing
   :status: stable
   :languages: Python
   :code-size-impact: N/A (host) but works best with pw_rpc on device

The Pigweed Console provides a Python repl (read eval print loop) using
`ptpython`_ and a log message viewer in a single-window terminal based
interface. It is designed to be a replacement for `IPython's embed()`_ function.

.. figure:: images/pw_system_boot.png
  :alt: Pigweed Console screenshot with serial debug log messages.

--------
Features
--------

``pw_console`` aims to be a complete solution for interacting with hardware
devices using :ref:`module-pw_rpc` over a :ref:`module-pw_hdlc` transport.

- Interactive Python repl and log viewer in a single terminal window. This
  provides interactive RPC sending while the log viewer provides immediate
  feedback on device status.

  .. figure:: images/python_completion.png
    :alt: Pigweed Console screenshot showing RPC Python repl completions.

- Easily embeddable within a project's own custom console. This should allow
  users to define their own transport layer.

- Log viewer with searching and filtering.

------------
Contributing
------------
- All code submissions to ``pw_console`` require running the
  :ref:`module-pw_console-testing`.

- Commit messages should include a ``Testing:`` line with the steps that were
  manually run.

------
Guides
------
.. toctree::
  :maxdepth: 1

  py/pw_console/docs/user_guide
  embedding
  plugins
  testing
  internals

.. _IPython's embed(): https://ipython.readthedocs.io/en/stable/interactive/reference.html#embedding
.. _IPython: https://ipython.readthedocs.io/
.. _prompt_toolkit: https://python-prompt-toolkit.readthedocs.io/
.. _ptpython: https://github.com/prompt-toolkit/ptpython/