From a3c98fe6f3cf13738d16b497f0396c7bbe20ae0c Mon Sep 17 00:00:00 2001
From: Ivan Kravets <me@ikravets.com>
Date: Wed, 15 Jun 2022 15:16:06 +0300
Subject: [PATCH] Replaced monitor_flags with independent project configuration
 options: monitor_parity, monitor_eol, monitor_raw, monitor_echo

---
 core/userguide/device/cmd_monitor.rst | 26 +++++++++----
 integration/ide/vscode.rst            |  6 ++-
 projectconf/section_env_monitor.rst   | 54 +++++++++++++++++----------
 3 files changed, 57 insertions(+), 29 deletions(-)

diff --git a/core/userguide/device/cmd_monitor.rst b/core/userguide/device/cmd_monitor.rst
index 55fb4751af..87ce339ed8 100644
--- a/core/userguide/device/cmd_monitor.rst
+++ b/core/userguide/device/cmd_monitor.rst
@@ -62,24 +62,27 @@ The possible values are the same as documented for
 
 Set baud rate, default ``9600``.
 
-Can be customized in :ref:`projectconf` using :ref:`projectconf_monitor_speed`
-option.
+Can be customized in :ref:`projectconf`
+using :ref:`projectconf_monitor_speed` option.
 
 .. option::
     --parity
 
 Set parity (*None, Even, Odd, Space, Mark*), one of
-[``N``, ``E``, ``O``, ``S``, ``M``], default ``N``
+[``N``, ``E``, ``O``, ``S``, ``M``], default is ``N``.
+
+Can be customized in :ref:`projectconf` using
+:ref:`projectconf_monitor_parity` option.
 
 .. option::
     --rtscts
 
-Enable ``RTS/CTS`` flow control, default ``Off``
+Enable ``RTS/CTS`` flow control.
 
 .. option::
     --xonxoff
 
-Enable software flow control, default ``Off``
+Enable software flow control.
 
 .. option::
     --rts
@@ -100,7 +103,10 @@ option.
 .. option::
     --echo
 
-Enable local echo, default ``Off``
+Enable local echo.
+
+Can be customized in :ref:`projectconf`
+using :ref:`projectconf_monitor_echo` option.
 
 .. option::
     --encoding
@@ -118,12 +124,16 @@ Add text transformation. See available filters at :ref:`cmd_device_monitor_filte
 
 End of line mode (``CR``, ``LF`` or ``CRLF``), default ``CRLF``
 
-**NEW**: Available in Miniterm/PySerial 3.0
+Can be customized in :ref:`projectconf`
+using :ref:`projectconf_monitor_eol` option.
 
 .. option::
     --raw
 
-Do not apply any encodings/transformations
+Do not apply any encodings/transformations.
+
+Can be customized in :ref:`projectconf`
+using :ref:`projectconf_monitor_raw` option.
 
 .. option::
     --exit-char
diff --git a/integration/ide/vscode.rst b/integration/ide/vscode.rst
index 97432dcc7a..c80b13238b 100644
--- a/integration/ide/vscode.rst
+++ b/integration/ide/vscode.rst
@@ -249,9 +249,13 @@ You can customize Serial Port Monitor using
 
 * :ref:`projectconf_monitor_port`
 * :ref:`projectconf_monitor_speed`
+* :ref:`projectconf_monitor_parity`
+* :ref:`projectconf_monitor_filters`
 * :ref:`projectconf_monitor_rts`
 * :ref:`projectconf_monitor_dtr`
-* :ref:`projectconf_monitor_flags`
+* :ref:`projectconf_monitor_eol`
+* :ref:`projectconf_monitor_raw`
+* :ref:`projectconf_monitor_echo`
 
 Example:
 
diff --git a/projectconf/section_env_monitor.rst b/projectconf/section_env_monitor.rst
index 3133557b0e..2b7c70cf38 100644
--- a/projectconf/section_env_monitor.rst
+++ b/projectconf/section_env_monitor.rst
@@ -83,6 +83,16 @@ Example:
     ...
     monitor_speed = 115200
 
+.. _projectconf_monitor_parity:
+
+``monitor_parity``
+^^^^^^^^^^^^^^^^^^
+
+Type: ``String`` | Multiple: ``No`` | Default: ``N``
+
+Enable parity checking. See :option:`pio device monitor --parity`
+for the available values.
+
 .. _projectconf_monitor_filters:
 
 ``monitor_filters``
@@ -100,7 +110,10 @@ Example:
     [env:log_output_to_file_with_timestamp]
     ...
     platform = ...
-    monitor_filters = log2file, time, default
+    monitor_filters =
+      default   ; Remove typical terminal control codes from input
+      time      ; Add timestamp with milliseconds for each new line
+      log2file  ; Log data to a file “platformio-device-monitor-*.log” located in the current working directory
 
 .. _projectconf_monitor_rts:
 
@@ -120,29 +133,30 @@ Type: ``Number (0 or 1)`` | Multiple: ``No``
 
 A monitor initial ``DTR`` line state. See :option:`pio device monitor --dtr`.
 
-.. _projectconf_monitor_flags:
+.. _projectconf_monitor_eol:
 
-``monitor_flags``
-^^^^^^^^^^^^^^^^^
+``monitor_eol``
+^^^^^^^^^^^^^^^
 
-Type: ``String`` | Multiple: ``Yes``
+Type: ``String`` | Multiple: ``No`` | Default: ``CRLF``
 
-Pass extra flags and options to :ref:`cmd_device_monitor` command. Please note
-that each flag, option or its value should be passed in a new line. See
-example below.
+A monitor end of line mode. See :option:`pio device monitor --eol`.
 
-Available flags and options are the same which are documented for
-:ref:`cmd_device_monitor` command.
+.. _projectconf_monitor_raw:
 
-Example:
+``monitor_raw``
+^^^^^^^^^^^^^^^
 
-.. code-block:: ini
+Type: ``Bool (yes or no)`` | Multiple: ``No`` | Default: ``no``
 
-    [env:extra_monitor_flags]
-    platform = ...
-    board = ...
-    monitor_flags=
-        --parity
-        N
-        --encoding
-        hexlify
+Disable encodings/transformations of device output.
+See :option:`pio device monitor --raw`.
+
+.. _projectconf_monitor_echo:
+
+``monitor_echo``
+^^^^^^^^^^^^^^^^
+
+Type: ``Bool (yes or no)`` | Multiple: ``No`` | Default: ``no``
+
+Enable a monitor local echo. See :option:`pio device monitor --echo`.