PyPlumIO is a native ecoNET library for Plum ecoMAX controllers

---

Overview

This package aims to provide complete and easy to use solution for communicating with climate devices by Plum Sp. z o.o.

Currently it supports reading and writing parameters of ecoMAX controllers by Plum Sp. z o.o., getting service password and sending network information to show on controller's display.

Devices can be connected directly via RS-485 to USB adapter or through network by using RS-485 to Ethernet/WiFi converter.

Table of contents

• Connecting
• Reading
• Writing
• Callbacks
• Mixers/Thermostats
• Schedules
• Protocol
  • Frame Structure
  • Requests and Responses
  • Communication
  • Versioning
• Supported frames

Quickstart

1. To use PyPlumIO, first install it using uv or pip:

uv add pyplumio
# or
pip install pyplumio

2. Connect to the ecoMAX controller:

>>> connection = pyplumio.serial_for_url("/dev/ttyUSB0")
>>> await connection.connect()
>>> ecomax = await connection.get("ecomax")

3. Print some values:

>>> print(await ecomax.get("heating_temp"))

4. Don’t forget to close the connection:

>>> await connection.close()

Home Assistant Integration

There is companion Home Assistant integration that is being co-developed with this package and depends on it. Click button below to check it out.

Development

This project uses uv for project and dependency management, and prek for Git hooks.

Setup

Install the project and development dependencies:

uv sync

Running Tests

Run the test suite with coverage enforcement (100% required):

uv run pytest

Code Quality & Formatting

Run linters, format checks, and cognitive complexity analysis:

uv run codespell
uv run ruff check .
uv run ruff format --check .
uv run complexipy . --max-complexity-allowed 15

Type Checking

Run type checking with mypy:

uv run mypy pyplumio tests

Git Hooks

Install and run Git hooks via prek:

prek install
prek run --all-files

Attribution

Special thanks to econetanalyze project by twkrol for initial information about protocol.

License

This product is distributed under MIT license.