Command Line Interface

PyPlumIO includes an interactive command-line utility for mapping ecoMAX controller service parameters and generating custom parameter modules.

Installation

The CLI utility requires optional dependencies (such as prompt_toolkit). Install PyPlumIO with the cli extra:

$ pip install "pyplumio[cli]"
# or with uv
$ uv add "pyplumio[cli]"

Usage

Run the CLI using the console script or Python module execution:

$ pyplumio
# or
$ python -m pyplumio

Command-Line Options

The CLI supports the following arguments:

usage: pyplumio [-h] [--url URL] [--output DIR] [--interval SECONDS] [--baudrate BAUDRATE]

options:
  -h, --help          show this help message and exit
  --url URL           Connection URL (e.g. socket://localhost:8899 or /dev/ttyUSB0).
                      If omitted, you will be prompted interactively.
  --output DIR        Output directory for generated files (default: current working directory).
  --interval SECONDS  Polling interval in seconds (default: 2.0).
  --baudrate BAUDRATE Serial baudrate (default: 115200).

Interactive Connection Setup

If --url is omitted, the CLI will guide you through configuring the connection:

  1. Connection Type: Choose between tcp and serial.

  2. TCP Settings: Enter host and port (default: 8899).

  3. Serial Settings: Enter the serial port path (e.g., /dev/ttyUSB0 or COM3).

Workflow & Parameter Mapping

Once connected, the CLI retrieves the controller model and product ID and continuously polls service parameters.

The interface consists of:

  • Header: Shows connected controller model, product ID, connection URL, last update timestamp, and keyboard shortcuts.

  • Table: Monospace scrollable list showing parameter indices, mapped names, current values, minimums, and maximums. Recently changed parameters are highlighted with inverted colors.

  • Live Preview: Real-time 4-line framed box docked above the input bar displaying active parameter fields, raw values, and live calculations.

  • Navigation: Use Up/Down arrow keys or PageUp and PageDown to scroll through the parameters list.

Interactive Wizard

At the bottom of the screen, a wizard guides you through naming and configuring each parameter:

  1. Index: Enter the parameter index from the table. While navigating the wizard past this step, table row ordering is frozen to prevent rows from jumping while typing.

  2. Name: Enter a unique snake_case name (e.g. heating_temp): - If the name is already used by another parameter index, it is rejected. - If the name matches a standard ecoMAX parameter for the connected product type, you will be prompted for confirmation ('<name>' is also a standard parameter; both will share one event name. Continue? [y/N]) to allow sharing the event name.

  3. Type: Select number or switch (defaults to switch if minimum is 0 and maximum is 1, otherwise number).

  4. Number Settings: If configuring a number: - Offset: Raw offset to subtract (default: 0). - Step: Multiplier/step (e.g. 1, 0.1, 10). - Unit: Physical unit of measurement (supports autocompletion for unit values such as °C, kW, rpm, %, etc., or enter none).

  5. Confirm: Confirm the decoded value and range match your controller display ([y/N]).

  6. Press Esc at any point to cancel the wizard.

Connection Resilience

If the serial connection or TCP bridge drops during a session, the CLI automatically stops background polling and notifies you via the status line:

Connection lost: <reason>. Ctrl+S still saves the last received frame, Ctrl+Q quits.

Even when disconnected, the application remains fully responsive. You can review mapped parameters, continue editing, and press Ctrl+S to save the files from the last received frame.

Saving & Output Files

Press Ctrl+S to save generated files. At least one parameter must be mapped; attempting to save with no mapped parameters will show:

Nothing to save: map at least one parameter first.

If generated files already exist in the target directory, you will be prompted to confirm overwrite ([y/N]).

The utility produces three files in the output directory:

  1. Custom Parameter Module: <output>/pyplumio/parameters/custom/<model_slug>.py Contains the CustomParameters class definition, model signature, and descriptions dictionary.

  2. Test Module: <output>/tests/parameters/custom/test_<model_slug>.py Parametrized pytest tests verifying every mapped parameter against real frame data.

  3. Captured Frame Test Data: <output>/tests/testdata/parameters/<model_slug>.json Raw frame capture used for reproducible testing.

Press Ctrl+Q to exit the application cleanly.

Contributing Mapped Parameters

Once you have mapped parameters for your controller model:

  1. Open a pull request against PyPlumIO adding the generated files.

  2. Alternatively, create an issue on GitHub and attach the generated files (or a zip archive containing them).