# PyPlumIO is a native ecoNET library for Plum ecoMAX controllers.
[](https://badge.fury.io/py/PyPlumIO)
[](https://pypi.python.org/pypi/pyplumio/)
[](https://github.com/psf/black)
[](https://github.com/denpamusic/PyPlumIO/actions/workflows/ci.yml)
[](https://codeclimate.com/github/denpamusic/PyPlumIO/maintainability)
[](https://codeclimate.com/github/denpamusic/PyPlumIO/test_coverage)
[](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta)
## Overview
This package aims to provide complete and easy to use solution for communicating with climate devices by [Plum Sp. z o.o.](https://www.plum.pl/)
Currently it supports reading and writing parameters of ecoMAX automatic pellet boiler controllers, 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
- [Usage](#usage)
- [TCP](#tcp)
- [Serial](#serial)
- [Values and Parameters](#values-and-parameters)
- [Reading](#reading)
- [Writing](#writing)
- [Callbacks](#callbacks)
- [Filters](#filters)
- [Working with Mixers](#working-with-mixers)
- [Working with Schedules](#working-with-schedules)
- [Network Information](#network-information)
- [Protocol](#protocol)
- [Frame Structure](#frame-structure)
- [Requests and Responses](#requests-and-responses)
- [Communication](#communication)
- [Frame Versioning](#frame-versioning)
- [Home Assistant Integration](#home-assistant-integration)
- [Attribution](#attribution)
- [License](#license)
## Usage
To interact with devices, you must first initialize connection by utilizing `pyplumio.open_tcp_connection()` or `pyplumio.open_serial_connection()` methods.
You can find examples for each supported connection type below.
### TCP
This is intended to be used with RS-485 to Ethernet/WiFi converters, which are readily
available online or can be custom built using RS-485 to USB converter and ser2net software.
```python
import asyncio
import pyplumio
async def main():
async with pyplumio.open_tcp_connection("localhost", 8899) as connection:
ecomax = await connection.get_device("ecomax")
# Do something.
asyncio.run(main())
```
### Serial
This is intended to be used with RS-485 to USB adapters, that are connected directly to the device running PyPlumIO.
```python
import asyncio
import pyplumio
import logging
_LOGGER = logging.getLogger(__name__)
async def main():
async with pyplumio.open_serial_connection("/dev/ttyUSB0", baudrate=115200) as connection:
# You can also use optional timeout parameter of get_device method.
try:
ecomax = await connection.get_device("ecomax", timeout=10)
# Do something.
except asyncio.TimeoutError:
_LOGGER.error("Failed to get device within 10 seconds")
asyncio.run(main())
```
> NB: Although use of the `async with` statement is preferred, you can open the connection without it:
```python
import asyncio
import pyplumio
async def main():
connection = pyplumio.open_tcp_connection("localhost", 8899)
await connection.connect()
ecomax = await connection.get_device("ecomax")
# Do something.
await connection.close()
asyncio.run(main())
```
### Values and Parameters
Data can be immutable (Values) or mutable (Parameters). They can be accessed via
`AsyncDevice.get_value(name: str, timeout: float | None = None)` and `AsyncDevice.get_parameter(name: str, timeout: float | None = None)` methods.
Each device supports different attributes and parameters, you can check all available values and parameters by looking at `AsyncDevice.data` attribute.
### Reading
Interaction with the device is mainly done through async getter methods.
For example you can read current feed water temperature by awaiting for `AsyncDevice.get_value("heating_temp")`.
The following example will print out current feed water temperature and close the connection.
```python
import asyncio
import pyplumio
async def main():
async with pyplumio.open_tcp_connection("localhost", 8899) as connection:
ecomax = await connection.get_device("ecomax")
print(await ecomax.get_value("heating_temp"))
asyncio.run(main())
```
### Writing
You can change controller parameters by awaiting `AsyncDevice.set_value(name: str, value: int, timeout: float | None = None)` or
by getting parameter via `AsyncDevice.get_parameter(name: str, timeout: float | None = None)` method and calling `set(name, value)`.
In examples below, we'll set target temperature to 65 degrees Celsius (~ 150 degrees Fahrenheit) using both methods.
```python
import pyplumio
async def main():
async with pyplumio.open_tcp_connection("localhost", 8899) as connection:
ecomax = await connection.get_device("ecomax")
await ecomax.set_value("heating_target_temp", 65)
```
```python
import pyplumio
async def main():
async with pyplumio.open_tcp_connection("localhost", 8899) as connection:
ecomax = await connection.get_device("ecomax")
target_temp = await ecomax.get_parameter("heating_target_temp")
target_temp.set(65)
```
For a binary parameters, that can only have "0" or "1" value, you can also use string
literals "on", "off" or use `turn_on()`, `turn_off()` methods of the parameter instance.
```python
import pyplumio
async def main():
async with pyplumio.open_tcp_connection("localhost", 8899) as connection:
ecomax = await connection.get_device("ecomax")
await ecomax.set_value("boiler_control", "on")
```
```python
import pyplumio
async def main():
async with pyplumio.open_tcp_connection("localhost", 8899) as connection:
ecomax = await connection.get_device("ecomax")
boiler = await ecomax.get_parameter("boiler_control")
boiler.turn_on() # or boiler.turn_off()
```
Each parameter has a range of acceptable values. PyPlumIO will raise `ValueError` if value is not within the acceptable range.
You can check allowed range by reading `min_value` and `max_value` attributes of parameter object. Both `min_value` and `max_value` are inclusive.
```python
import pyplumio
async def main():
async with pyplumio.open_tcp_connection("localhost", 8899) as connection:
ecomax = await connection.get_device("ecomax")
target_temp = await ecomax.get_parameter("heating_target_temp")
print(target_temp.min_value) # Prints minimum allowed target temperature.
print(target_temp.max_value) # Prints maximum allowed target temperature.
```
### Callbacks
It's possible to register a callback, that will be called every time a data with
the certain name is received (e. g. heating_temp), using `AsyncDevice.subscribe(name, callback)` function, register callback that will be called only once using `AsyncDevice.subscribe_once(name, callback)` function or remove existing callback by calling `AsyncDevice.unsubscribe(name, callback).`
```python
import asyncio
import pyplumio
async def my_callback(value) -> None:
print(f"Heating Temperature: {value}")
async def main():
async with pyplumio.open_tcp_connection("localhost", 8899) as connection:
ecomax = await connection.get_device("ecomax")
ecomax.subscribe("heating_temp", my_callback)
# Wait until disconnected (forever)
connection.wait_until_done()
asyncio.run(main())
```
### Filters
Callbacks can be improved by using built-in filters `aggregate(callback, seconds)`, `on_change(callback)`,
`debounce(callback, min_calls)` `delta(callback)`, and `throttle(callback, seconds)`.
You can find examples on how to use them below:
```python
import pyplumio
from pyplumio.helpers.filters import aggregate, debounce, delta, on_change, throttle
async def main():
async with pyplumio.open_tcp_connection("localhost", 8899) as connection:
ecomax = await connection.get_device("ecomax")
# Callback "first_callback" will be awaited on every received frame
# that contains "heating_temp" regardless of whether value is
# changed or not.
ecomax.subscribe("heating_temp", first_callback)
# Callback "second_callback" will be awaited only if the
# "heating_temp" value is changed since last call.
ecomax.subscribe("heating_temp", on_change(second_callback))
# Callback "third_callback" will be awaited once the "heating_temp"
# value is stabilized across three received frames.
ecomax.subscribe("heating_temp", debounce(third_callback, min_calls=3))
# Callback "fourth_callback" will be awaited once in 5 seconds.
ecomax.subscribe("heating_temp", throttle(fourth_callback, seconds=5))
# Callback "fifth_callback" will be awaited with the sum of values
# accumulated over the span of 5 seconds. Works with numeric values only.
ecomax.subscribe("fuel_burned", aggregate(fifth_callback, seconds=5))
# Callback "sixth_callback" will be awaited with difference between
# values in the last and current calls.
ecomax.subscribe("heating_temp", delta(sixth_callback))
# Throttle callback can be chained with others.
# Callback "seventh_callback" will be awaited on value change but no
# sooner that 5 seconds.
ecomax.subscribe("heating_temp", throttle(on_change(seventh_callback), seconds=5))
```
### Working with Mixers
If your ecoMAX controller support mixers, you can access them via `mixers` property
through `AsyncDevice.get_value("mixers")` call.
Result of this call will be a list of `Mixer` instances.
`Mixer` class inherits `AsyncDevice` and provides access to getter/setter functions and
callback support.
Each device supports different attributes and parameters for mixers, you can check all
available values and parameters by looking at `Mixer.data` attribute.
```python
import asyncio
import pyplumio
from pyplumio.helpers.filters import on_change
async def my_callback(mixer_pump_status: bool) -> None:
print(f"Mixer Pump Working: {mixer_pump_status}")
async def main():
async with pyplumio.open_tcp_connection("localhost", 8899) as connection:
ecomax = await connection.get_device("ecomax")
mixers = await ecomax.get_value("mixers")
# Get single mixer from the list.
mixer = mixers[0]
mixer = await mixer.get_value("temp")
await mixer.set_value("mix_target_temp", 50)
mixer.subscribe("mixer_pump", on_change(my_callback))
# Print all available mixer data.
print(mixer.data)
# Wait until disconnected (forever)
connection.wait_until_done()
asyncio.run(main())
```
### Working with Schedules
You can set device schedule, enable/disable it and change associated parameter.
To disable the schedule, turn off "schedule_{schedule_name}_switch" parameter, by using
`AsyncDevice.set_value` method, to enable it turn in on.
```python
await ecomax.set_value("schedule_heating_switch", "off")
await ecomax.set_value("schedule_heating_switch", "on")
```
To change associated parameter value, use `AsyncDevice.set_value`
function with "schedule_{schedule_name}_parameter".
```python
await ecomax.set_value("schedule_heating_parameter", 10)
```
To set the schedule, you can use `set_state`, `set_on` or `set_off` functions and call
`commit` to send changes to device.
This example sets nighttime mode for Monday from 00:00 to 07:00 and switches back to daytime
mode from 07:00 to 00:00.
```python
heating_schedule = (await ecomax.get_value("schedules"))["heating"]
heating_schedule.monday.set_off(start="00:00", end="07:00")
heating_schedule.monday.set_on(start="07:00", end="00:00")
heating_schedule.commit()
```
For clarity sake, you might want to use `STATE_NIGHT` and `STATE_DAY`
constants from `pyplumio.helpers.schedule` with set state.
```python
heating_schedule.monday.set_state(STATE_NIGHT, "00:00", "07:00")
```
You may also omit one of the boundaries.
The other boundary is then set to the end or start of the day.
`heating_schedule.monday.set_on(start="07:00")` is equivalent to
`heating_schedule.monday.set_on(start="07:00", end="00:00")` and `heating_schedule.monday.set_off(end="07:00")` is
equivalent to `heating_schedule.monday.set_off(start="00:00", end="07:00")`.
This can be used to set state for a whole day: `heating_schedule.monday.set_on()`
To set schedule for all days you can iterate through Schedule object:
```python
heating_schedule = (await ecomax.get_value("schedules"))["heating"]
for weekday in heating_schedule:
weekday.set_on("00:00", "07:00")
weekday.set_off("07:00", "00:00")
heating_schedule.commit()
```
Following example showcases most of the methods described above:
```python
import pyplumio
from pyplumio.helpers.schedule import STATE_DAY, STATE_NIGHT
async def main():
async with pyplumio.open_tcp_connection("localhost", 8899) as connection:
ecomax = await connection.get_device("ecomax")
heating_schedule = (await ecomax.get_value("schedules"))["heating"]
# Turn heating schedule on.
await ecomax.set_value("schedule_heating_switch", "on")
# Drop heating temperature by 10 degrees during nighttime.
await ecomax.set_value("schedule_heating_parameter", 10)
for weekday in heating_schedule:
weekday.set_state(STATE_DAY, "00:00", "00:30")
weekday.set_state(STATE_NIGHT, "00:30", "09:00")
weekday.set_state(STATE_DAY, "09:00", "00:00")
# There will be no nighttime on sunday.
heating_schedule.sunday.set_state(STATE_DAY)
heating_schedule.commit()
asyncio.run(main())
```
### Network Information
You can send ethernet and wireless network information to the ecoMAX controller to show on it's
LCD. It serves information purposes only and can be omitted.
```python
import pyplumio
async def main():
ethernet = pyplumio.ethernet_parameters(
ip="10.10.1.100",
netmask="255.255.255.0",
gateway="10.10.1.1",
)
wireless = pyplumio.wireless_parameters(
ip="10.10.2.100",
netmask="255.255.255.0",
gateway="10.10.2.1",
ssid="My SSID",
encryption=pyplumio.WLAN_ENCRYPTION_WPA2,
signal_quality=100,
)
async with pyplumio.open_tcp_connection(
host="localhost",
port=8899,
ethernet_parameters=ethernet,
wireless_parameters=wireless,
) as connection:
# Do something.
```
## Protocol
Plum devices use RS-485 standard for communication. Each frame consists of header (7 bytes),
message type (1 byte), message data (optional), CRC (1 byte) and frame end delimiter (1 byte).
The minimum frame size therefore is 10 bytes.
Protocol supports unicast and broadcast frames. Broadcast frames will always have their
recipient address set to `0x00`, while unicast messages will have specific device address.
ecoMAX controller address is `0x45`, ecoSTER panel address is `0x51`.
### Frame Structure
- Header:
- [Byte] Frame start delimiter. Always `0x68`.
- [Unsigned Short] Byte size of the frame. Includes CRC and frame end delimiter.
- [Byte] Recipient address.
- [Byte] Sender address.
- [Byte] Sender type. PyPlumIO uses EcoNET type `48`.
- [Byte] ecoNET version. PyPlumIO uses version `5`.
- Body:
- [Byte] Frame type.
- [Byte*] Message data (optional).
- [Byte] Frame CRC.
- [Byte] Frame end delimiter. Always `0x16`.
### Requests and Responses
PyPlumIO splits frames into requests, responses and messages.
See [requests.py](https://github.com/denpamusic/PyPlumIO/blob/main/pyplumio/frames/requests.py),
[responses.py](https://github.com/denpamusic/PyPlumIO/blob/main/pyplumio/frames/responses.py) and
[messages.py](https://github.com/denpamusic/PyPlumIO/blob/main/pyplumio/frames/messages.py)
for a list of supported frame types.
For example, we can request list of editable parameters from the ecoMAX controller by sending
frame with frame type `49` and receive response with frame type `177` that contains requested parameters.
### Communication
The controller constantly sends `ProgramVersionRequest[type=64]` and `CheckDeviceRequest[type=48]`
requests to every known device on the network and broadcasts `RegulatorDataMessage[type=8]` message, that contains basic controller data.
Initial exchange between ecoMAX controller and PyPlumIO library can be illustrated with following diagram:
> NB: device network address is listed in square brackets.
```
ecoMAX[0x45] -> Broadcast[0x00]: RegulatorDataMessage[type=8] Contains basic ecoMAX data.
ecoMAX[0x45] -> PyPlumIO[0x56]: ProgramVersionRequest[type=64] Program version request.
ecoMAX[0x45] <- PyPlumIO[0x56]: ProgramVersionResponse[type=192] Contains program version.
ecoMAX[0x45] -> PyPlumIO[0x56]: CheckDeviceRequest[type=48] Check device request.
ecoMAX[0x45] <- PyPlumIO[0x56]: DeviceAvailableResponse[type=176] Contains network information.
ecoMAX[0x45] -> PyPlumIO[0x56]: SensorDataMessage[type=53] Contains ecoMAX sensor data.
```
### Versioning
Protocol has built-in way to track frame versions. This is used to synchronize changes between devices.
Both broadcast `RegulatorDataMessage[type=8]` and unicast `SensorDataMessage[type=53]` frames sent by ecoMAX controller contain versioning data.
This data can be represented with following dictionary:
```python
frame_versions: Dict[int, int] = {
49: 37,
50: 37,
54: 1,
56: 5,
57: 1,
61: 40767,
80: 1,
81: 1,
82: 1,
83: 1,
}
```
In this dictionary, keys are frame types and values are version numbers. In example above,
frame `ParametersRequest[type=49]` has version 37. If we change any parameters either remotely or
on the controller itself, version number will increase, so PyPlumIO will be able to tell that it's
need to request list of parameters again to obtain changes.
```python
frame_versions: Dict[int, int] = {
49: 38, # Note the version number change.
50: 37,
54: 1,
56: 5,
57: 1,
61: 40767,
80: 1,
81: 1,
82: 1,
83: 1,
}
```
## 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.
[](https://github.com/denpamusic/homeassistant-plum-ecomax)
## Attribution
Special thanks to [econetanalyze](https://github.com/twkrol/econetanalyze) project by twkrol for initial information about protocol.
## License
This product is distributed under MIT license.
Raw data
{
"_id": null,
"home_page": "https://github.com/denpamusic/PyPlumIO",
"name": "PyPlumIO",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Denis Paavilainen",
"author_email": "denpa@denpa.pro",
"download_url": "https://files.pythonhosted.org/packages/85/4e/e111feef8c8ac1979072f2da5e84087df75af3c4c8b9b9d9da8d7975954f/PyPlumIO-0.2.16.tar.gz",
"platform": null,
"description": "# PyPlumIO is a native ecoNET library for Plum ecoMAX controllers.\n[](https://badge.fury.io/py/PyPlumIO)\n[](https://pypi.python.org/pypi/pyplumio/)\n[](https://github.com/psf/black)\n[](https://github.com/denpamusic/PyPlumIO/actions/workflows/ci.yml)\n[](https://codeclimate.com/github/denpamusic/PyPlumIO/maintainability)\n[](https://codeclimate.com/github/denpamusic/PyPlumIO/test_coverage)\n[](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta)\n\n## Overview\nThis package aims to provide complete and easy to use solution for communicating with climate devices by [Plum Sp. z o.o.](https://www.plum.pl/)\n\n\n\nCurrently it supports reading and writing parameters of ecoMAX automatic pellet boiler controllers, getting service password and sending network information to show on controller's display.\n\nDevices can be connected directly via RS-485 to USB adapter or through network by using RS-485 to Ethernet/WiFi converter.\n\n\n\n## Table of contents\n- [Usage](#usage)\n - [TCP](#tcp)\n - [Serial](#serial)\n - [Values and Parameters](#values-and-parameters)\n - [Reading](#reading)\n - [Writing](#writing)\n - [Callbacks](#callbacks)\n - [Filters](#filters)\n - [Working with Mixers](#working-with-mixers)\n - [Working with Schedules](#working-with-schedules)\n - [Network Information](#network-information)\n- [Protocol](#protocol)\n - [Frame Structure](#frame-structure)\n - [Requests and Responses](#requests-and-responses)\n - [Communication](#communication)\n - [Frame Versioning](#frame-versioning)\n- [Home Assistant Integration](#home-assistant-integration)\n- [Attribution](#attribution)\n- [License](#license)\n\n## Usage\nTo interact with devices, you must first initialize connection by utilizing `pyplumio.open_tcp_connection()` or `pyplumio.open_serial_connection()` methods.\n\nYou can find examples for each supported connection type below.\n\n### TCP\nThis is intended to be used with RS-485 to Ethernet/WiFi converters, which are readily\navailable online or can be custom built using RS-485 to USB converter and ser2net software.\n\n```python\nimport asyncio\nimport pyplumio\n\nasync def main():\n async with pyplumio.open_tcp_connection(\"localhost\", 8899) as connection:\n ecomax = await connection.get_device(\"ecomax\")\n # Do something.\n\t\nasyncio.run(main())\n```\n\n### Serial\nThis is intended to be used with RS-485 to USB adapters, that are connected directly to the device running PyPlumIO.\n\n```python\nimport asyncio\nimport pyplumio\nimport logging\n\n_LOGGER = logging.getLogger(__name__)\n\nasync def main():\n async with pyplumio.open_serial_connection(\"/dev/ttyUSB0\", baudrate=115200) as connection:\n # You can also use optional timeout parameter of get_device method.\n try:\n ecomax = await connection.get_device(\"ecomax\", timeout=10)\n # Do something.\n except asyncio.TimeoutError:\n _LOGGER.error(\"Failed to get device within 10 seconds\")\n\t\nasyncio.run(main())\n```\n\n> NB: Although use of the `async with` statement is preferred, you can open the connection without it:\n\n```python\nimport asyncio\nimport pyplumio\n\nasync def main():\n connection = pyplumio.open_tcp_connection(\"localhost\", 8899)\n await connection.connect()\n ecomax = await connection.get_device(\"ecomax\")\n # Do something.\n await connection.close()\n\t\nasyncio.run(main())\n```\n\n### Values and Parameters\nData can be immutable (Values) or mutable (Parameters). They can be accessed via \n`AsyncDevice.get_value(name: str, timeout: float | None = None)` and `AsyncDevice.get_parameter(name: str, timeout: float | None = None)` methods.\n\nEach device supports different attributes and parameters, you can check all available values and parameters by looking at `AsyncDevice.data` attribute.\n\n### Reading\nInteraction with the device is mainly done through async getter methods.\nFor example you can read current feed water temperature by awaiting for `AsyncDevice.get_value(\"heating_temp\")`.\n\nThe following example will print out current feed water temperature and close the connection.\n```python\nimport asyncio\nimport pyplumio\n\nasync def main():\n async with pyplumio.open_tcp_connection(\"localhost\", 8899) as connection:\n ecomax = await connection.get_device(\"ecomax\")\n print(await ecomax.get_value(\"heating_temp\"))\n \nasyncio.run(main())\n```\n\n### Writing\nYou can change controller parameters by awaiting `AsyncDevice.set_value(name: str, value: int, timeout: float | None = None)` or\nby getting parameter via `AsyncDevice.get_parameter(name: str, timeout: float | None = None)` method and calling `set(name, value)`.\nIn examples below, we'll set target temperature to 65 degrees Celsius (~ 150 degrees Fahrenheit) using both methods.\n```python\nimport pyplumio\n\nasync def main():\n async with pyplumio.open_tcp_connection(\"localhost\", 8899) as connection:\n ecomax = await connection.get_device(\"ecomax\")\n await ecomax.set_value(\"heating_target_temp\", 65)\n```\n\n```python\nimport pyplumio\n\nasync def main():\n async with pyplumio.open_tcp_connection(\"localhost\", 8899) as connection:\n ecomax = await connection.get_device(\"ecomax\")\n target_temp = await ecomax.get_parameter(\"heating_target_temp\")\n target_temp.set(65)\n```\n\nFor a binary parameters, that can only have \"0\" or \"1\" value, you can also use string\nliterals \"on\", \"off\" or use `turn_on()`, `turn_off()` methods of the parameter instance.\n```python\nimport pyplumio\n\nasync def main():\n async with pyplumio.open_tcp_connection(\"localhost\", 8899) as connection:\n ecomax = await connection.get_device(\"ecomax\")\n await ecomax.set_value(\"boiler_control\", \"on\")\n```\n\n```python\nimport pyplumio\n\nasync def main():\n async with pyplumio.open_tcp_connection(\"localhost\", 8899) as connection:\n ecomax = await connection.get_device(\"ecomax\")\n boiler = await ecomax.get_parameter(\"boiler_control\")\n boiler.turn_on() # or boiler.turn_off()\n```\n\nEach parameter has a range of acceptable values. PyPlumIO will raise `ValueError` if value is not within the acceptable range.\nYou can check allowed range by reading `min_value` and `max_value` attributes of parameter object. Both `min_value` and `max_value` are inclusive.\n```python\nimport pyplumio\n\nasync def main():\n async with pyplumio.open_tcp_connection(\"localhost\", 8899) as connection:\n ecomax = await connection.get_device(\"ecomax\")\n target_temp = await ecomax.get_parameter(\"heating_target_temp\")\n print(target_temp.min_value) # Prints minimum allowed target temperature.\n print(target_temp.max_value) # Prints maximum allowed target temperature.\n```\n\n### Callbacks\nIt's possible to register a callback, that will be called every time a data with\nthe certain name is received (e. g. heating_temp), using `AsyncDevice.subscribe(name, callback)` function, register callback that will be called only once using `AsyncDevice.subscribe_once(name, callback)` function or remove existing callback by calling `AsyncDevice.unsubscribe(name, callback).`\n```python\nimport asyncio\nimport pyplumio\n\nasync def my_callback(value) -> None:\n print(f\"Heating Temperature: {value}\")\n\nasync def main():\n async with pyplumio.open_tcp_connection(\"localhost\", 8899) as connection:\n ecomax = await connection.get_device(\"ecomax\")\n ecomax.subscribe(\"heating_temp\", my_callback)\n # Wait until disconnected (forever)\n connection.wait_until_done()\n\nasyncio.run(main())\n```\n\n### Filters\nCallbacks can be improved by using built-in filters `aggregate(callback, seconds)`, `on_change(callback)`,\n`debounce(callback, min_calls)` `delta(callback)`, and `throttle(callback, seconds)`.\n\nYou can find examples on how to use them below:\n```python\nimport pyplumio\nfrom pyplumio.helpers.filters import aggregate, debounce, delta, on_change, throttle\n\nasync def main():\n async with pyplumio.open_tcp_connection(\"localhost\", 8899) as connection:\n ecomax = await connection.get_device(\"ecomax\")\n \n # Callback \"first_callback\" will be awaited on every received frame\n # that contains \"heating_temp\" regardless of whether value is\n # changed or not.\n ecomax.subscribe(\"heating_temp\", first_callback)\n \n # Callback \"second_callback\" will be awaited only if the\n # \"heating_temp\" value is changed since last call.\n ecomax.subscribe(\"heating_temp\", on_change(second_callback))\n \n # Callback \"third_callback\" will be awaited once the \"heating_temp\"\n # value is stabilized across three received frames.\n ecomax.subscribe(\"heating_temp\", debounce(third_callback, min_calls=3))\n\n # Callback \"fourth_callback\" will be awaited once in 5 seconds.\n ecomax.subscribe(\"heating_temp\", throttle(fourth_callback, seconds=5))\n\n # Callback \"fifth_callback\" will be awaited with the sum of values\n # accumulated over the span of 5 seconds. Works with numeric values only.\n ecomax.subscribe(\"fuel_burned\", aggregate(fifth_callback, seconds=5))\n\n # Callback \"sixth_callback\" will be awaited with difference between\n # values in the last and current calls.\n ecomax.subscribe(\"heating_temp\", delta(sixth_callback))\n\n # Throttle callback can be chained with others.\n # Callback \"seventh_callback\" will be awaited on value change but no\n # sooner that 5 seconds.\n ecomax.subscribe(\"heating_temp\", throttle(on_change(seventh_callback), seconds=5))\n\n```\n\n### Working with Mixers\nIf your ecoMAX controller support mixers, you can access them via `mixers` property\nthrough `AsyncDevice.get_value(\"mixers\")` call.\n\nResult of this call will be a list of `Mixer` instances.\n`Mixer` class inherits `AsyncDevice` and provides access to getter/setter functions and\ncallback support.\n\nEach device supports different attributes and parameters for mixers, you can check all\navailable values and parameters by looking at `Mixer.data` attribute.\n\n```python\nimport asyncio\nimport pyplumio\n\nfrom pyplumio.helpers.filters import on_change\n\nasync def my_callback(mixer_pump_status: bool) -> None:\n print(f\"Mixer Pump Working: {mixer_pump_status}\")\n\nasync def main():\n async with pyplumio.open_tcp_connection(\"localhost\", 8899) as connection:\n ecomax = await connection.get_device(\"ecomax\")\n mixers = await ecomax.get_value(\"mixers\")\n\n # Get single mixer from the list.\n mixer = mixers[0]\n mixer = await mixer.get_value(\"temp\")\n await mixer.set_value(\"mix_target_temp\", 50)\n mixer.subscribe(\"mixer_pump\", on_change(my_callback))\n\n # Print all available mixer data.\n print(mixer.data)\n\n # Wait until disconnected (forever)\n connection.wait_until_done()\n\nasyncio.run(main())\n```\n\n### Working with Schedules\nYou can set device schedule, enable/disable it and change associated parameter.\n\nTo disable the schedule, turn off \"schedule_{schedule_name}_switch\" parameter, by using\n`AsyncDevice.set_value` method, to enable it turn in on.\n\n```python\n await ecomax.set_value(\"schedule_heating_switch\", \"off\")\n await ecomax.set_value(\"schedule_heating_switch\", \"on\")\n```\n\nTo change associated parameter value, use `AsyncDevice.set_value`\nfunction with \"schedule_{schedule_name}_parameter\".\n\n```python\n await ecomax.set_value(\"schedule_heating_parameter\", 10)\n```\n\nTo set the schedule, you can use `set_state`, `set_on` or `set_off` functions and call\n`commit` to send changes to device.\n\nThis example sets nighttime mode for Monday from 00:00 to 07:00 and switches back to daytime\nmode from 07:00 to 00:00.\n\n```python\nheating_schedule = (await ecomax.get_value(\"schedules\"))[\"heating\"]\nheating_schedule.monday.set_off(start=\"00:00\", end=\"07:00\")\nheating_schedule.monday.set_on(start=\"07:00\", end=\"00:00\")\nheating_schedule.commit()\n```\n\nFor clarity sake, you might want to use `STATE_NIGHT` and `STATE_DAY`\nconstants from `pyplumio.helpers.schedule` with set state.\n```python\nheating_schedule.monday.set_state(STATE_NIGHT, \"00:00\", \"07:00\")\n```\n\nYou may also omit one of the boundaries.\nThe other boundary is then set to the end or start of the day.\n`heating_schedule.monday.set_on(start=\"07:00\")` is equivalent to\n`heating_schedule.monday.set_on(start=\"07:00\", end=\"00:00\")` and `heating_schedule.monday.set_off(end=\"07:00\")` is\nequivalent to `heating_schedule.monday.set_off(start=\"00:00\", end=\"07:00\")`.\n\nThis can be used to set state for a whole day: `heating_schedule.monday.set_on()`\n\nTo set schedule for all days you can iterate through Schedule object:\n```python\nheating_schedule = (await ecomax.get_value(\"schedules\"))[\"heating\"]\n\nfor weekday in heating_schedule:\n weekday.set_on(\"00:00\", \"07:00\")\n weekday.set_off(\"07:00\", \"00:00\")\n\nheating_schedule.commit()\n```\n\nFollowing example showcases most of the methods described above:\n```python\nimport pyplumio\n\nfrom pyplumio.helpers.schedule import STATE_DAY, STATE_NIGHT\n\nasync def main():\n async with pyplumio.open_tcp_connection(\"localhost\", 8899) as connection:\n ecomax = await connection.get_device(\"ecomax\")\n heating_schedule = (await ecomax.get_value(\"schedules\"))[\"heating\"]\n\n # Turn heating schedule on.\n await ecomax.set_value(\"schedule_heating_switch\", \"on\")\n\n # Drop heating temperature by 10 degrees during nighttime.\n await ecomax.set_value(\"schedule_heating_parameter\", 10)\n\n for weekday in heating_schedule:\n weekday.set_state(STATE_DAY, \"00:00\", \"00:30\")\n weekday.set_state(STATE_NIGHT, \"00:30\", \"09:00\")\n weekday.set_state(STATE_DAY, \"09:00\", \"00:00\")\n\n # There will be no nighttime on sunday.\n heating_schedule.sunday.set_state(STATE_DAY)\n \n heating_schedule.commit()\n\nasyncio.run(main())\n```\n\n### Network Information\nYou can send ethernet and wireless network information to the ecoMAX controller to show on it's\nLCD. It serves information purposes only and can be omitted.\n```python\nimport pyplumio\n\nasync def main():\n ethernet = pyplumio.ethernet_parameters(\n ip=\"10.10.1.100\",\n netmask=\"255.255.255.0\",\n gateway=\"10.10.1.1\",\n )\n wireless = pyplumio.wireless_parameters(\n ip=\"10.10.2.100\",\n netmask=\"255.255.255.0\",\n gateway=\"10.10.2.1\",\n ssid=\"My SSID\",\n encryption=pyplumio.WLAN_ENCRYPTION_WPA2,\n signal_quality=100,\n )\n async with pyplumio.open_tcp_connection(\n host=\"localhost\",\n port=8899,\n ethernet_parameters=ethernet,\n wireless_parameters=wireless,\n ) as connection:\n # Do something.\n```\n\n## Protocol\nPlum devices use RS-485 standard for communication. Each frame consists of header (7 bytes),\nmessage type (1 byte), message data (optional), CRC (1 byte) and frame end delimiter (1 byte).\nThe minimum frame size therefore is 10 bytes.\n\nProtocol supports unicast and broadcast frames. Broadcast frames will always have their\nrecipient address set to `0x00`, while unicast messages will have specific device address.\necoMAX controller address is `0x45`, ecoSTER panel address is `0x51`.\n\n### Frame Structure\n- Header:\n - [Byte] Frame start delimiter. Always `0x68`.\n - [Unsigned Short] Byte size of the frame. Includes CRC and frame end delimiter. \n - [Byte] Recipient address.\n - [Byte] Sender address.\n - [Byte] Sender type. PyPlumIO uses EcoNET type `48`.\n - [Byte] ecoNET version. PyPlumIO uses version `5`.\n- Body:\n - [Byte] Frame type.\n - [Byte*] Message data (optional).\n - [Byte] Frame CRC.\n - [Byte] Frame end delimiter. Always `0x16`.\n\n### Requests and Responses\nPyPlumIO splits frames into requests, responses and messages.\nSee [requests.py](https://github.com/denpamusic/PyPlumIO/blob/main/pyplumio/frames/requests.py),\n[responses.py](https://github.com/denpamusic/PyPlumIO/blob/main/pyplumio/frames/responses.py) and\n[messages.py](https://github.com/denpamusic/PyPlumIO/blob/main/pyplumio/frames/messages.py)\nfor a list of supported frame types.\n\nFor example, we can request list of editable parameters from the ecoMAX controller by sending\nframe with frame type `49` and receive response with frame type `177` that contains requested parameters.\n\n### Communication\nThe controller constantly sends `ProgramVersionRequest[type=64]` and `CheckDeviceRequest[type=48]`\nrequests to every known device on the network and broadcasts `RegulatorDataMessage[type=8]` message, that contains basic controller data.\n\nInitial exchange between ecoMAX controller and PyPlumIO library can be illustrated with following diagram:\n\n> NB: device network address is listed in square brackets.\n\n```\necoMAX[0x45] -> Broadcast[0x00]: RegulatorDataMessage[type=8] Contains basic ecoMAX data.\necoMAX[0x45] -> PyPlumIO[0x56]: ProgramVersionRequest[type=64] Program version request.\necoMAX[0x45] <- PyPlumIO[0x56]: ProgramVersionResponse[type=192] Contains program version.\necoMAX[0x45] -> PyPlumIO[0x56]: CheckDeviceRequest[type=48] Check device request.\necoMAX[0x45] <- PyPlumIO[0x56]: DeviceAvailableResponse[type=176] Contains network information.\necoMAX[0x45] -> PyPlumIO[0x56]: SensorDataMessage[type=53] Contains ecoMAX sensor data.\n```\n\n### Versioning\nProtocol has built-in way to track frame versions. This is used to synchronize changes between devices.\nBoth broadcast `RegulatorDataMessage[type=8]` and unicast `SensorDataMessage[type=53]` frames sent by ecoMAX controller contain versioning data.\n\nThis data can be represented with following dictionary:\n```python\nframe_versions: Dict[int, int] = {\n 49: 37,\n 50: 37,\n 54: 1,\n 56: 5,\n 57: 1,\n 61: 40767,\n 80: 1,\n 81: 1,\n 82: 1,\n 83: 1,\n}\n```\nIn this dictionary, keys are frame types and values are version numbers. In example above,\nframe `ParametersRequest[type=49]` has version 37. If we change any parameters either remotely or\non the controller itself, version number will increase, so PyPlumIO will be able to tell that it's\nneed to request list of parameters again to obtain changes.\n```python\nframe_versions: Dict[int, int] = {\n 49: 38, # Note the version number change.\n 50: 37,\n 54: 1,\n 56: 5,\n 57: 1,\n 61: 40767,\n 80: 1,\n 81: 1,\n 82: 1,\n 83: 1,\n}\n```\n\n## Home Assistant Integration\nThere is companion Home Assistant integration that is being co-developed with this package and depends on it. Click button below to check it out.\n\n[](https://github.com/denpamusic/homeassistant-plum-ecomax)\n\n## Attribution\nSpecial thanks to [econetanalyze](https://github.com/twkrol/econetanalyze) project by twkrol for initial information about protocol.\n\n## License\nThis product is distributed under MIT license.\n",
"bugtrack_url": null,
"license": "",
"summary": "PyPlumIO is a native ecoNET library for Plum ecoMAX controllers.",
"version": "0.2.16",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "2f9c07679ac9a90670ba6c77f5446d2a",
"sha256": "7e40c65923d8eac9f1755aedb86365141cb6ddd86d8afcb9a47d49c56e246aa6"
},
"downloads": -1,
"filename": "PyPlumIO-0.2.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2f9c07679ac9a90670ba6c77f5446d2a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 54374,
"upload_time": "2022-08-18T21:30:42",
"upload_time_iso_8601": "2022-08-18T21:30:42.127698Z",
"url": "https://files.pythonhosted.org/packages/6c/91/5de54e0b149076810aa65755f37c3e7a0af1bf1f7a9464bf155dbfaf111c/PyPlumIO-0.2.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "bc66225bb40a390b329e3a77b127d499",
"sha256": "1071a8288c017bf35710ab41cbfaedbc209ee506b76f43cf9815b18630833a63"
},
"downloads": -1,
"filename": "PyPlumIO-0.2.16.tar.gz",
"has_sig": false,
"md5_digest": "bc66225bb40a390b329e3a77b127d499",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 36619,
"upload_time": "2022-08-18T21:30:43",
"upload_time_iso_8601": "2022-08-18T21:30:43.712677Z",
"url": "https://files.pythonhosted.org/packages/85/4e/e111feef8c8ac1979072f2da5e84087df75af3c4c8b9b9d9da8d7975954f/PyPlumIO-0.2.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-08-18 21:30:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "denpamusic",
"github_project": "PyPlumIO",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "pyplumio"
}
JSON
