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.

pyx2cscope [options]                  # when installed with pip
python -m pyx2cscope [options]        # when installed with pip
pyX2Cscope.exe [options]              # standalone executable

pyx2cscope --help lists all arguments.

Quick reference

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 try every available serial port and connect to the first one with an LNet device. Together with an ELF file (`-e` or `config.ini`), the GUI connects at startup.
`--web`	`-w`	Start the Web GUI instead of the Qt GUI. Cannot be combined with `-q`.
`--qt`	`-q`	Start the Qt GUI. This is the 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 next to the executable, without their dependencies. See Installing extra libraries (standalone executable).
`--with-deps`	—	Use together with `--install` to also install the dependencies of the packages.
`--vscode-task [<dir>]`	—	Add a `Run pyX2Cscope` task to `.vscode/tasks.json` of an MPLAB VS Code project (default: current folder) and exit. The ELF file is taken from `.vscode/<project>.mplab.json`; `-p`, `-w`, `-wp` and `--host` are used in the task. See VSCode Integration.
`--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:

pyX2Cscope.exe -e firmware.elf -p AUTO

Start the Web GUI on the default port:

pyX2Cscope.exe -e firmware.elf -p COM3 -w

Start the Web GUI and allow access from other devices on the network:

pyX2Cscope.exe -e firmware.elf -w --host 0.0.0.0 -wp 8080

Run with verbose logging to the terminal:

pyX2Cscope.exe -e firmware.elf -l DEBUG -c

Install an extra library into the standalone executable:

pyX2Cscope.exe --install scipy

Add a Run pyX2Cscope task to an MPLAB VS Code firmware project:

pyX2Cscope.exe --vscode-task path\to\my_project

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:

pyX2Cscope.exe --install scipy
pyX2Cscope.exe --install scipy pandas   # multiple packages at once
pyX2Cscope.exe --install mypackage --with-deps

The packages are installed with pip of a system Python whose version matches the Python bundled in the executable (e.g. Python 3.12), so that version must be installed on the system. By default the dependencies are not installed, so packages already bundled in the executable (such as numpy) are not replaced. Add --with-deps when a package needs dependencies that are not bundled. The libs/ folder is added to the import path when the executable starts, so the packages persist across restarts.

When pyX2Cscope is installed with pip, --install only prints the pip install command to use instead.