Reading

Dataset

Device.data: dict[str, T]

You can use this property get a full device dataset.

ecomax = await conn.get("ecomax")
print(ecomax.data)

In a pinch, you can also use this attribute to directly access the data, but this is not recommended, please use getters instead.

Getters

async pyplumio.devices.Device.get(self, name: str, timeout: float | None = None) → T

Get the value by name.

Parameters:

name (str) – Event name or ID
timeout (float, optional) – Wait this amount of seconds for a data to become available, defaults to None

Returns:

An event data

Return type:

T

Raises:

asyncio.TimeoutError – when waiting past specified timeout

This method can be used to get a single item from the device dataset.

The following example will print out current feed water temperature and close the connection.

import asyncio

import pyplumio

async def main():
    """Read the current heating temperature."""
    async with pyplumio.open_tcp_connection("localhost", 8899) as conn:
        # Get the ecoMAX device.
        ecomax = await conn.get("ecomax")

        # Get the heating temperature.
        heating_temp = await ecomax.get("heating_temp")
        print(heating_temp)
        ...


asyncio.run(main())

pyplumio.devices.Device.get_nowait(self, name: str, default: Any | None = None) → Any

Get the value by name without waiting.

If value is not available, default value will be returned instead.

Parameters:

name (str) – Event name or ID
default (T, optional) – default value to return if data is unavailable, defaults to None

Returns:

An event data

Return type:

T, optional

This method can be used to get single item from device dataset without waiting until it becomes available.

The following example will print out current feed water temperature if it is available, otherwise it’ll print 60.

# Print the heating temperature or 60, if property is not available.
heating_temp = ecomax.get_nowait("heating_temp", default=60)
print(heating_temp)

async pyplumio.devices.Device.wait_for(self, name: str, timeout: float | None = None) → None

Wait for the value to become available.

Parameters:

name (str) – Event name or ID
timeout (float, optional) – Wait this amount of seconds for a data to become available, defaults to None

Raises:

asyncio.TimeoutError – when waiting past specified timeout

You can use this method to wait until the value is available and then directly access the attribute under the device object.

The following example will wait until current feed water temperature is available and print it out.

# Wait until the 'heating_temp' property becomes available.
await ecomax.wait_for("heating_temp")

# Output the 'heating_temp' property.
print(ecomax.heating_temp)

Regulator Data

Regulator Data messages are broadcasted by the ecoMAX controller once per second and allow access to some device-specific information that isn’t available elsewhere.

Note

RegData is device-specific. Each ecoMAX controller has different keys and their associated meanings.

It’s represented by a dictionary mapped with numerical keys.

RegData can be accessed via the regdata property.

ecomax = await conn.get("ecomax")
regdata = await ecomax.get("regdata")

# Get regulator data with the 1280 key.
heating_target = regdata[1280]

Reading Examples

The following example make uses of all available methods to get heating current and target temperatures and device state and outputs it to the terminal.

import asyncio

import pyplumio


async def main():
    """Read current temp, target temp and device state from
    the regdata.
    """
    async with pyplumio.open_tcp_connection("localhost", 8899) as conn:
        # Get the ecoMAX device.
        ecomax = await conn.get("ecomax")

        # Get the heating temperature if it is available, or return
        # default value (65).
        heating_temp = ecomax.get_nowait("heating_temp", default=65)

        # Wait for the heating temperature and get it's value.
        heating_target_temp = await ecomax.get("heating_target_temp")

        # Wait until regulator data is available, and grab key 1792.
        await ecomax.wait_for("regdata")
        status = ecomax.regdata[1792]

        print(
            f"Current temp: {heating_temp}, "
            f"target temp: {heating_target_temp}, "
            f"status: {status}."
        )


asyncio.run(main())