Writing

Setters

async pyplumio.devices.Device.set(self, name: str, value: int | float | Literal['on', 'off'] | bool, retries: int = 5, timeout: float | None = None) → bool

Set a parameter value.

Parameters:

name (str) – Name of the parameter
value (int | float | bool | Literal["off", "on"]) – New value for the parameter
retries (int, optional) – Try setting parameter for this amount of times, defaults to 5
timeout (float, optional) – Wait this amount of seconds for confirmation, defaults to None

Returns:

True if parameter was successfully set, False otherwise.

Return type:

bool

Raises:

asyncio.TimeoutError – when waiting past specified timeout
ValueError – when a new value is outside of allowed range
TypeError – when found data is not valid parameter

When using blocking setter, you’ll get the result represented by a boolean value. True if write was successful, False otherwise.

result = await ecomax.set("heating_target_temp", 65)
if result:
    print("Heating target temperature was successfully set.")
else:
    print("Error while trying to set heating target temperature.")

pyplumio.devices.Device.set_nowait(self, name: str, value: int | float | Literal['on', 'off'] | bool, retries: int = 5, timeout: float | None = None) → None

Set a parameter value without waiting for the result.

Parameters:

name (str) – Name of the parameter
value (int | float | bool | Literal["off", "on"]) – New value for the parameter
retries (int, optional) – Try setting parameter for this amount of times, defaults to 5
timeout (float, optional) – Wait this amount of seconds for confirmation. As this method operates in the background without waiting, this value is used to determine failure when retrying and doesn’t block, defaults to None

When using non-blocking setter, you can’t access the result as task is done in background. However, you’ll still get error log message in case of a failure.

ecomax.set_nowait("heating_target_temp", 65)

Parameters

For the parameters, it’s possible to retrieve the Parameter object and then modify it via it’s own setter method.

class pyplumio.helpers.parameter.Parameter(device: Device, description: ParameterDescription, values: ParameterValues | None = None, index: int = 0): Represents a base parameter.

When using the parameter object directly, you don’t need to pass the parameter name to the setter method.

Numbers

Numbers are parameters that have numerical value associated with them.

from pyplumio.helpers.parameter import Number

ecomax = await conn.get("ecomax")
heating_target: Number = ecomax.get("heating_target_temp")
result = heating_target.set(65)

Each number has an unique range of allowed values. PyPlumIO will raise ValueError if value isn’t within acceptable range.

You can check allowed range boundaries by reading min_value and max_value properties of the parameter object. Please note, that both values are inclusive.

from pyplumio.helpers.parameter import Number

ecomax = await connection.get("ecomax")
target_temp: Number = await ecomax.get("heating_target_temp")
print(target_temp.min_value)  # Minimum allowed target temperature.
print(target_temp.max_value)  # Maximum allowed target temperature.

Switches

Switches are parameters that could only have two possible states: on or off.

Thus, for switches, you can use Python’s boolean keywords True or False, string literals “on” or “off” or special turn_on() and turn_off() methods.

async pyplumio.helpers.parameter.Switch.turn_on(self) → bool

Set a switch value to ‘on’.

Returns:: True if parameter was successfully turned on, False otherwise.
Return type:: bool

pyplumio.helpers.parameter.Switch.turn_on_nowait(self) → None: Set a switch value to ‘on’ without waiting.

async pyplumio.helpers.parameter.Switch.turn_off(self) → bool

Set a switch value to ‘off’.

Returns:: True if parameter was successfully turned off, False otherwise.
Return type:: bool

pyplumio.helpers.parameter.Switch.turn_off_nowait(self) → None: Set a switch value to ‘off’ without waiting.

Good example of a switch is “ecomax_control” that allows you to switch the ecoMAX controller on or off.

# Set an ecomax_control parameter value to "on".
result = await ecomax.set("ecomax_control", "on")

If you want to use turn_on() method, you must first get the parameter object.

from pyplumio.helpers.parameter import Switch

# Get an ecomax_control parameter and turn it on.
ecomax_control: Switch = await ecomax.get("ecomax_control")
result = await ecomax_control.turn_on()

If you simply want to switch the ecoMAX controller on or off, there’s a handy built-in way to do that.

# Turn on the controller.
await ecomax.turn_on()

# Turn off the controller.
await ecomax.turn_off()

Writing Examples

The following example opens a connection, enables the controller without waiting for the result and tries to set a target temperature, outputting the result to the terminal.

import asyncio

import pyplumio

async def main():
    """Turn on the controller and set target temperature."""
    async with pyplumio.open_tcp_connection("localhost", 8899) as conn:
        # Get the ecoMAX device.
        ecomax = await conn.get("ecomax")

        # Turn on controller without waiting for the result.
        ecomax.turn_on_nowait()

        # Set heating temperature to 65 degrees.
        result = await ecomax.set("heating_target_temp", 65)
        if result:
            print("Heating temperature is set to 65.")
        else:
            print("Couldn't set heating temperature.")



asyncio.run(main())