Writing#

Setters#

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

Set a parameter value.

Parameters:

  • name (str) – Name of the parameter

  • value (int | float | bool | Literal["on"] | Literal["off"]) – New value for the parameter

  • timeout (float, optional) – Wait this amount of seconds for confirmation, defaults to None

  • retries (int, optional) – Try setting parameter for this amount of times, defaults to 5

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 will get the result represented by the 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 | bool | Literal['off'] | Literal['on'], timeout: float | None = None, retries: int = 5) → None#

Set a parameter value without waiting for the result.

Parameters:

  • name (str) – Name of the parameter

  • value (int | float | bool | Literal["on"] | Literal["off"]) – New value for the parameter

  • 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

  • retries (int, optional) – Try setting parameter for this amount of times, defaults to 5

Returns:

True if parameter was successfully set, False otherwise.

Return type:

bool

You can’t access result, when using non-blocking setter as task is done in the background. You will, however, still get error message in the log in case of failure.

ecomax.set_nowait("heating_target_temp", 65)

Parameters#

It’s possible to get the Parameter object and then modify it using it’s own setter methods. When using the parameter object, you don’t need to pass the parameter name.

from pyplumio.helpers.parameter import Parameter


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

Each parameter has a range of allowed 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 properties of the parameter object. Both values are inclusive.

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

Binary Parameters#

For binary parameters, you can also use boolean True or False, string literals “on” or “off” or special turn_on() and turn_off() methods.

async pyplumio.helpers.parameter.BinaryParameter.turn_on(self) → bool#

Set a parameter value to ‘on’.

Returns:

True if parameter was successfully turned on, False otherwise.

Return type:

bool

pyplumio.helpers.parameter.BinaryParameter.turn_on_nowait(self) → None#

Set a parameter value to ‘on’ without waiting.

async pyplumio.helpers.parameter.BinaryParameter.turn_off(self) → bool#

Set a parameter value to ‘off’.

Returns:

True if parameter was successfully turned off, False otherwise.

Return type:

bool

pyplumio.helpers.parameter.BinaryParameter.turn_off_nowait(self) → None#

Set a parameter value to ‘off’ without waiting.

One such parameter is “ecomax_control” that allows you to switch the ecoMAX 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 a parameter object.

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

If you simply want to turn on or off the ecoMAX controller there’s, handy shortcut built-in the controller object itself.

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

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

Writing Examples#

The following example opens the connection, enables the controller without waiting for result and tries to set a target temperature, outputting 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())