Masters tuning

doc/cli.rst

@@ -0,0 +1,117 @@
+Command-Line Interface
+======================
+
+pyX2Cscope can be launched from the terminal with arguments that control which
+GUI is started, which ELF file is loaded, and how the connection is
+established.  Providing ``-e`` and ``-p`` at launch skips all manual input —
+the application loads the ELF and connects to the target immediately.
+
+.. code-block:: console
+
+   python -m pyx2cscope [options]        # when installed with pip
+   pyX2Cscope.exe [options]              # standalone executable
+
+Quick reference
+---------------
+
+.. list-table::
+   :widths: 22 12 66
+   :header-rows: 1
+
+   * - Argument
+     - Short
+     - Description
+   * - ``--elf <path>``
+     - ``-e``
+     - Path to the ELF file generated by the firmware build.
+       Required to load variable information.  If omitted, pyX2Cscope looks
+       for a path stored in ``config.ini``.
+   * - ``--port <port>``
+     - ``-p``
+     - Serial port to connect to (e.g. ``COM3``, ``/dev/ttyUSB0``).
+       Use ``AUTO`` to scan for the first available LNet device automatically.
+   * - ``--web``
+     - ``-w``
+     - Start the Web GUI instead of the Qt GUI.
+   * - ``--qt``
+     - ``-q``
+     - Explicitly start the Qt GUI (default when ``-w`` is not given).
+   * - ``--web-port <port>``
+     - ``-wp``
+     - TCP port for the web server (default: ``5000``).
+       Only used with ``-w``.
+   * - ``--host <host>``
+     - —
+     - Host address for the web server (default: ``localhost``).
+       Set to ``0.0.0.0`` to allow connections from other devices on the
+       network.  Only used with ``-w``.
+   * - ``--log-level <level>``
+     - ``-l``
+     - Logging verbosity.  One of ``DEBUG``, ``INFO``, ``WARNING``,
+       ``ERROR`` (default), ``CRITICAL``.
+   * - ``--log-console``
+     - ``-c``
+     - Print log output to the terminal in addition to the log file.
+   * - ``--install <pkg> …``
+     - —
+     - *Standalone executable only.* Install one or more Python packages
+       into the ``libs/`` folder using the bundled interpreter.
+       See :ref:`installing-extra-libraries`.
+   * - ``--version``
+     - ``-v``
+     - Print the version number and exit.
+   * - ``--help``
+     - ``-h``
+     - Print the full help message and exit.
+
+Examples
+--------
+
+Start the Qt GUI, load an ELF, and auto-connect:
+
+.. code-block:: console
+
+   pyX2Cscope.exe -e firmware.elf -p AUTO
+
+Start the Web GUI on the default port:
+
+.. code-block:: console
+
+   pyX2Cscope.exe -e firmware.elf -p COM3 -w
+
+Start the Web GUI and allow access from other devices on the network:
+
+.. code-block:: console
+
+   pyX2Cscope.exe -e firmware.elf -w --host 0.0.0.0 -wp 8080
+
+Run with verbose logging to the terminal:
+
+.. code-block:: console
+
+   pyX2Cscope.exe -e firmware.elf -l DEBUG -c
+
+Install an extra library into the standalone executable:
+
+.. code-block:: console
+
+   pyX2Cscope.exe --install scipy
+
+.. _installing-extra-libraries:
+
+Installing extra libraries (standalone executable)
+--------------------------------------------------
+
+The standalone ``pyX2Cscope.exe`` ships with a bundled Python interpreter and
+a fixed set of packages.  If your firmware uses a communication layer or
+post-processing routine that requires an additional package (e.g. ``scipy``,
+``pandas``), you can install it into the ``libs/`` folder that sits next to the
+executable:
+
+.. code-block:: console
+
+   pyX2Cscope.exe --install scipy
+   pyX2Cscope.exe --install scipy pandas   # multiple packages at once
+
+The packages are installed via the bundled ``pip`` and are isolated from your
+system Python.  They persist across restarts of the executable.

doc/gui.rst

@@ -0,0 +1,46 @@
+Graphical User Interfaces
+=========================
+
+pyX2Cscope ships with two ready-to-use graphical interfaces: a **Qt desktop
+application** and a **Web interface** built on Flask.  Both expose the same
+core functionality — connecting to a target, reading and writing variables,
+recording scope data, and running Python scripts — but they are designed for
+different use cases and deployment scenarios.
+
+.. list-table::
+   :widths: 20 40 40
+   :header-rows: 1
+
+   * -
+     - Qt GUI
+     - Web GUI
+   * - **Best for**
+     - Desktop / laptop, single user
+     - Remote access, shared setups, headless machines
+   * - **How to start**
+     - ``python -m pyx2cscope``
+     - ``python -m pyx2cscope -w``
+   * - **Access**
+     - Native window on the local machine
+     - Any browser, including phones and tablets on the same network
+   * - **Scripting**
+     - Built-in editor, output in a dedicated tab
+     - Browser-based editor, output streamed via WebSocket
+   * - **Standalone exe**
+     - ``pyX2Cscope.exe`` (default)
+     - ``pyX2Cscope.exe -w``
+
+Both interfaces are also examples of how to build your own custom GUI on top
+of the pyX2Cscope API — the source code is part of the package and can be
+used as a starting point.
+
+See the following sections for details:
+
+.. toctree::
+   :maxdepth: 1
+
+   cli
+   gui_qt
+   gui_web
+   scripting_scripts
+   vscode

doc/gui_qt.md

@@ -142,9 +142,27 @@ The **Export Variables** button in the Data Views toolbar allows you to:
 ### Save and Load Config
 
 The **Save Config** and **Load Config** buttons allow you to:
-- Save the entire configuration including ELF file path, connection settings, and all variable configurations.
+- Save the current WatchView and ScopeView variable lists to a `.json` file.
 - Load a previously saved configuration to quickly restore your setup.
-- When loading, the system automatically attempts to connect using the saved settings.
+- The saved file also stores the ELF file path and connection settings so that, when loading, the system automatically attempts to reconnect.
+
+The config file uses a **shared JSON format** that is cross-compatible with the Web GUI:
+
+```json
+{
+    "watch_view": [
+        {"variable": "motorSpeedRPM", "sfr": false, "live": true, "scaling": "1.0", "offset": "0.0"}
+    ],
+    "scope_view": [
+        {"variable": "motorSpeedRPM", "sfr": false, "trigger": false, "enable": true,
+         "color": "#ff0000", "gain": "1.0", "offset": "0.0"}
+    ],
+    "elf_file": "/path/to/firmware.elf",
+    "connection": { "interface": "UART", "port": "COM3" }
+}
+```
+
+A config file saved from the Web GUI (which omits `elf_file` and `connection`) can be loaded into the Qt app — the variable lists will be restored and the app will skip the reconnect step if no ELF path is present.
 
 ---
 

doc/gui_web.md

@@ -102,11 +102,38 @@ Supported formats: `.elf`, `.pkl`, `.yml`
 
 ### Export Variables
 
-After connecting, click the export icon in the header to export the variables currently used in
+After connecting, click the **export** icon (upload_file) in the header to export the variables currently used in
 Watch View, Scope View, and Dashboard.
 
 Choose either `.yml` or `.pkl`. SFR selections are preserved in the exported file too.
 
+### Save / Load Config
+
+Two additional icons appear in the header once connected:
+
+| Icon | Description |
+|------|-------------|
+| **save** | Download the current Watch View and Scope View variable list as `pyx2cscope_config.json` |
+| **folder_open** | Open a file picker to load a previously saved `pyx2cscope_config.json` |
+
+The config file is a JSON file containing **only variable data** (no connection settings):
+
+```json
+{
+    "watch_view": [
+        {"variable": "motorSpeedRPM", "sfr": false, "live": true, "scaling": 1, "offset": 0}
+    ],
+    "scope_view": [
+        {"variable": "motorSpeedRPM", "sfr": false, "trigger": false, "enable": true,
+         "color": "#FF0000", "gain": 1, "offset": 0}
+    ]
+}
+```
+
+This format is **shared with the Qt desktop app** — a config file saved from one GUI can be
+loaded into the other. When a config is loaded, all connected browser tabs are updated
+automatically via the WebSocket connection.
+
 ### Connecting
 
 Click the **Connect** button to establish communication with the target device.
@@ -151,11 +178,6 @@ To modify a variable value on the target:
 1. Enter a new value in the **Value** column
 2. Click the **Write** button (pencil icon) in the Actions column
 
-### Save/Load Configuration
-
-- **Save** - Export the current watch list to a `.cfg` file
-- **Load** - Import a previously saved watch list configuration
-
 ---
 
 ## Scope View
@@ -449,5 +471,7 @@ For advanced users, the Web GUI exposes REST API endpoints:
 | `/is-connected` | GET | Check connection status |
 | `/variables` | GET | Get list of available variables |
 | `/serial-ports` | GET | Get available COM ports |
+| `/config/save` | GET | Download Watch & Scope config as `pyx2cscope_config.json` |
+| `/config/load` | POST | Upload and apply a `pyx2cscope_config.json` file |
 
 Additional information can be found in the API documentation.

doc/index.rst

@@ -36,8 +36,7 @@ See the section examples to check some of the usages you may get by pyX2Cscope.
 
    install.rst
    scripting.rst
-   gui_qt.md
-   gui_web.md
+   gui.rst
    FW_Support
    example
    development.md