opentherm_app.py

import asyncio
from lib import s8, s16, f88, send_syslog

try:
    from opentherm_rp2 import opentherm_exchange

except ImportError:
    # dummy implementation so it loads on non-pico for unit tests
    async def opentherm_exchange(msg_type: int, data_id: int, data_value: int, timeout_ms: int = 1000) -> tuple[int, int, int]:
        raise NotImplementedError("await opentherm_exchange not implemented on this platform")  # pragma: nocover


MSG_TYPE_READ_DATA = 0
MSG_TYPE_WRITE_DATA = 1
MSG_TYPE_INVALID_DATA = 2
MSG_TYPE_READ_ACK = 4
MSG_TYPE_WRITE_ACK = 5
MSG_TYPE_DATA_INVALID = 6
MSG_TYPE_UNKNOWN_DATA_ID = 7

DATA_ID_STATUS = 0
DATA_ID_TSET = 1
DATA_ID_PRIMARY_CONFIG = 2
DATA_ID_SECONDARY_CONFIG = 3
DATA_ID_COMMAND = 4
DATA_ID_ASF_FAULT = 5
DATA_ID_RBP_FLAGS = 6
DATA_ID_COOLING_CONTROL = 7
DATA_ID_TSETCH2 = 8
DATA_ID_TROVERRIDE = 9
DATA_ID_TSP_COUNT = 10
DATA_ID_TSP_DATA = 11
DATA_ID_FHB_COUNT = 12
DATA_ID_FHB_DATA = 13
DATA_ID_MAX_REL_MODULATION = 14
DATA_ID_MAX_CAPACITY_MIN_MODULATION = 15
DATA_ID_TRSET = 16
DATA_ID_REL_MOD_LEVEL = 17
DATA_ID_CH_PRESSURE = 18
DATA_ID_DHW_FLOW_RATE = 19
DATA_ID_DAY_TIME = 20
DATA_ID_DATE = 21
DATA_ID_YEAR = 22
DATA_ID_TRSETCH2 = 23
DATA_ID_TR = 24
DATA_ID_TBOILER = 25
DATA_ID_TDHW = 26
DATA_ID_TOUTSIDE = 27
DATA_ID_TRET = 28
DATA_ID_TSTORAGE = 29
DATA_ID_TCOLLECTOR = 30
DATA_ID_TFLOWCH2 = 31
DATA_ID_TDHW2 = 32
DATA_ID_TEXHAUST = 33
# ID 35 not in OT v2.2 but defined in v4.2 spec section 5.3.3:
# HB: fan speed setpoint in Hz (RPM/60), LB: actual fan speed in Hz (RPM/60)
DATA_ID_BOILER_FAN_SPEED = 35

DATA_ID_TDHWSET_BOUNDS = 48
DATA_ID_MAXTSET_BOUNDS = 49
DATA_ID_HCRATIO_BOUNDS = 50

DATA_ID_TDHWSET = 56
DATA_ID_MAXTSET = 57
DATA_ID_HCRATIO = 58

DATA_ID_REMOTE_OVERRIDE_FUNCTION = 100
DATA_ID_OEM_DIAGNOSTIC_CODE = 115
DATA_ID_POWER_CYCLES = 97
DATA_ID_BURNER_STARTS = 116
DATA_ID_CH_PUMP_STARTS = 117
DATA_ID_DHW_PUMP_STARTS = 118
DATA_ID_DHW_BURNER_STARTS = 119
DATA_ID_BURNER_OPERATION_HOURS = 120
DATA_ID_CH_PUMP_OPERATION_HOURS = 121
DATA_ID_DHW_PUMP_OPERATION_HOURS = 122
DATA_ID_DHW_BURNER_OPERATION_HOURS = 123
DATA_ID_OPENTHERM_VERSION_PRIMARY = 124
DATA_ID_OPENTHERM_VERSION_SECONDARY = 125
DATA_ID_PRIMARY_VERSION = 126
DATA_ID_SECONDARY_VERSION = 127

REMOTE_COMAND_BLOR = 1  # boiler lock out reset command
REMOTE_COMAND_CHWF = 2  # CH water filling command


# Custom exceptions for OpenTherm protocol responses
class DataInvalidError(Exception):
    """Raised when the boiler responds with DATA-INVALID (msg_type=6).
    This indicates the data ID is recognized but the data is unavailable or invalid."""
    pass


class UnknownDataIdError(Exception):
    """Raised when the boiler responds with UNKNOWN-DATAID (msg_type=7).
    This indicates the boiler does not support or recognize this data ID."""
    pass


async def opentherm_exchange_retry(msg_type: int, data_id: int, data_value: int, timeout_ms: int = 1000, max_retries: int = 10):
    """Attempt an OpenTherm exchange with retry logic.

    OT spec 4.3.1: master must wait 100ms minimum between conversations.
    The inter-message delay is applied after each exchange completes.
    """
    retry_count = 0
    while True:
        try:
            result = await opentherm_exchange(msg_type, data_id, data_value, timeout_ms)
            # OT spec 4.3.1: 100ms minimum gap after conversation ends
            await asyncio.sleep_ms(100)
            return result
        except (DataInvalidError, UnknownDataIdError):
            # Valid protocol responses per OT spec 4.4.1/4.4.2 - do not retry
            await asyncio.sleep_ms(100)
            raise
        except Exception:
            # OT spec 4.3.1: 100ms gap even after failed conversation
            await asyncio.sleep_ms(100)
            if retry_count >= max_retries:
                raise
            retry_count += 1


def _check_response_type(r_msg_type: int, expected_type: int, r_data_id: int, expected_data_id: int):
    """Check response message type and data ID, raising appropriate exceptions for errors.

    Per OpenTherm spec sections 4.4.1/4.4.2, DATA-INVALID and UNKNOWN-DATAID are
    valid protocol responses that should not be retried.

    Args:
        r_msg_type: Received message type from boiler
        expected_type: Expected message type (e.g., MSG_TYPE_READ_ACK)
        r_data_id: Received data ID from boiler
        expected_data_id: Expected data ID that was requested
    """
    if r_msg_type == MSG_TYPE_DATA_INVALID:
        raise DataInvalidError(f"Boiler returned DATA-INVALID for data ID {expected_data_id}")
    elif r_msg_type == MSG_TYPE_UNKNOWN_DATA_ID:
        raise UnknownDataIdError(f"Boiler does not support data ID {expected_data_id}")

    if r_msg_type != expected_type:
        msg = f"Expected msg_type {expected_type}, got {r_msg_type} for data ID {expected_data_id}"
        send_syslog(f"ERROR: {msg}")
        raise ValueError(msg)

    if r_data_id != expected_data_id:
        msg = f"Expected data_id {expected_data_id}, got {r_data_id}"
        send_syslog(f"ERROR: {msg}")
        raise ValueError(msg)


async def status_exchange(
    ch_enabled=False,
    dhw_enabled=False,
    cooling_enabled=False,
    otc_enabled=False,
    ch2_enabled=False,
) -> dict:
    data = 0
    data |= 0x0100 if ch_enabled else 0
    data |= 0x0200 if dhw_enabled else 0
    data |= 0x0400 if cooling_enabled else 0
    data |= 0x0800 if otc_enabled else 0
    data |= 0x1000 if ch2_enabled else 0

    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_STATUS, data
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_STATUS)

    result = dict(
        fault=True if r_data & 0x01 else False,
        ch_active=True if r_data & 0x02 else False,
        dhw_active=True if r_data & 0x04 else False,
        flame_active=True if r_data & 0x08 else False,
        cooling_active=True if r_data & 0x10 else False,
        ch2_active=True if r_data & 0x20 else False,
        diagnostic_event=True if r_data & 0x40 else False,
    )
    return result


async def send_primary_configuration(memberid_code: int):
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_WRITE_DATA, DATA_ID_PRIMARY_CONFIG, memberid_code & 0xFF
    )
    _check_response_type(r_msg_type, MSG_TYPE_WRITE_ACK, r_data_id, DATA_ID_PRIMARY_CONFIG)


async def send_primary_opentherm_version(version: float):
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_WRITE_DATA, DATA_ID_OPENTHERM_VERSION_PRIMARY, int(version * 256)
    )
    _check_response_type(r_msg_type, MSG_TYPE_WRITE_ACK, r_data_id, DATA_ID_OPENTHERM_VERSION_PRIMARY)


async def send_primary_product_version(type: int, version: int):
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_WRITE_DATA, DATA_ID_PRIMARY_VERSION, ((type & 0xff) << 8) | (version & 0xff)
    )
    _check_response_type(r_msg_type, MSG_TYPE_WRITE_ACK, r_data_id, DATA_ID_PRIMARY_VERSION)


async def read_secondary_configuration() -> dict:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_SECONDARY_CONFIG, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_SECONDARY_CONFIG)

    result = dict(
        dhw_present=True if r_data & 0x0100 else False,
        control_type="onoff" if r_data & 0x0200 else "modulating",
        cooling_config=True if r_data & 0x0400 else False,
        dhw_config="storage" if r_data & 0x0800 else "instantaneous",
        low_off_and_pump_control=True if not (r_data & 0x1000) else False,
        ch2_supported=True if r_data & 0x2000 else False,
        memberid_code=r_data & 0xFF,
    )
    return result


async def read_secondary_opentherm_version() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_OPENTHERM_VERSION_SECONDARY, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_OPENTHERM_VERSION_SECONDARY)
    return f88(r_data)


async def read_secondary_product_version() -> tuple[int, int]:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_SECONDARY_VERSION, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_SECONDARY_VERSION)
    return r_data >> 8, r_data & 0xff


async def control_ch_setpoint(setpoint: float):
    if not (setpoint >= 0 and setpoint <= 100):
        msg = f"Invalid CH setpoint {setpoint}, must be 0-100"
        send_syslog(f"ERROR: {msg}")
        raise ValueError(msg)

    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_WRITE_DATA, DATA_ID_TSET, int(setpoint * 256)
    )
    _check_response_type(r_msg_type, MSG_TYPE_WRITE_ACK, r_data_id, DATA_ID_TSET)


async def read_ch_setpoint() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TSET, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TSET)
    return f88(r_data)


async def control_ch2_setpoint(setpoint: float):
    if not (setpoint >= 0 and setpoint <= 100):
        msg = f"Invalid CH2 setpoint {setpoint}, must be 0-100"
        send_syslog(f"ERROR: {msg}")
        raise ValueError(msg)

    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_WRITE_DATA, DATA_ID_TSETCH2, int(setpoint * 256)
    )
    _check_response_type(r_msg_type, MSG_TYPE_WRITE_ACK, r_data_id, DATA_ID_TSETCH2)


async def read_dhw_setpoint_range() -> tuple[int, int]:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TDHWSET_BOUNDS, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TDHWSET_BOUNDS)

    return s8(r_data & 0xFF), s8(r_data >> 8)


async def control_dhw_setpoint(setpoint: float):
    if not (setpoint >= 0 and setpoint <= 100):
        msg = f"Invalid DHW setpoint {setpoint}, must be 0-100"
        send_syslog(f"ERROR: {msg}")
        raise ValueError(msg)

    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_WRITE_DATA, DATA_ID_TDHWSET, int(setpoint * 256)
    )
    _check_response_type(r_msg_type, MSG_TYPE_WRITE_ACK, r_data_id, DATA_ID_TDHWSET)


async def read_dhw_setpoint() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TDHWSET, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TDHWSET)
    return f88(r_data)


async def control_room_setpoint(setpoint: float):
    if not (setpoint >= -40 and setpoint <= 127):
        msg = f"Invalid room setpoint {setpoint}, must be -40 to 127"
        send_syslog(f"ERROR: {msg}")
        raise ValueError(msg)

    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_WRITE_DATA, DATA_ID_TRSET, int(setpoint * 256)
    )
    _check_response_type(r_msg_type, MSG_TYPE_WRITE_ACK, r_data_id, DATA_ID_TRSET)


async def read_room_setpoint() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TRSET, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TRSET)
    return f88(r_data)


async def control_room_setpoint_ch2(setpoint: float):
    if not (setpoint >= -40 and setpoint <= 127):
        msg = f"Invalid room setpoint CH2 {setpoint}, must be -40 to 127"
        send_syslog(f"ERROR: {msg}")
        raise ValueError(msg)

    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_WRITE_DATA, DATA_ID_TRSETCH2, int(setpoint * 256)
    )
    _check_response_type(r_msg_type, MSG_TYPE_WRITE_ACK, r_data_id, DATA_ID_TRSETCH2)


async def control_room_temperature(setpoint: float):
    if not (setpoint >= -40 and setpoint <= 127):
        msg = f"Invalid room temperature {setpoint}, must be -40 to 127"
        send_syslog(f"ERROR: {msg}")
        raise ValueError(msg)

    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_WRITE_DATA, DATA_ID_TR, int(setpoint * 256)
    )
    _check_response_type(r_msg_type, MSG_TYPE_WRITE_ACK, r_data_id, DATA_ID_TR)


async def read_room_temperature() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TR, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TR)
    return f88(r_data)


async def control_cooling(signal: float):
    if not (signal >= 0 and signal <= 100):
        msg = f"Invalid cooling signal {signal}, must be 0-100"
        send_syslog(f"ERROR: {msg}")
        raise ValueError(msg)

    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_WRITE_DATA, DATA_ID_COOLING_CONTROL, int(signal * 256)
    )
    _check_response_type(r_msg_type, MSG_TYPE_WRITE_ACK, r_data_id, DATA_ID_COOLING_CONTROL)


async def read_maxch_setpoint_range() -> tuple[int, int]:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_MAXTSET_BOUNDS, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_MAXTSET_BOUNDS)

    return s8(r_data & 0xFF), s8(r_data >> 8)


async def control_maxch_setpoint(setpoint: float):
    if not (setpoint >= 0 and setpoint <= 100):
        msg = f"Invalid max CH setpoint {setpoint}, must be 0-100"
        send_syslog(f"ERROR: {msg}")
        raise ValueError(msg)

    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_WRITE_DATA, DATA_ID_MAXTSET, int(setpoint * 256)
    )
    _check_response_type(r_msg_type, MSG_TYPE_WRITE_ACK, r_data_id, DATA_ID_MAXTSET)


async def read_maxch_setpoint() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_MAXTSET, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_MAXTSET)
    return f88(r_data)


async def read_extra_boiler_params_support() -> dict:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_RBP_FLAGS, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_RBP_FLAGS)

    dhw_setpoint = None
    if r_data & 0x0100:
        if r_data & 0x01:
            dhw_setpoint = "rw"
        else:
            dhw_setpoint = "ro"

    maxch_setpoint = None
    if r_data & 0x200:
        if r_data & 0x02:
            maxch_setpoint = "rw"
        else:
            maxch_setpoint = "ro"

    result = dict(dhw_setpoint=dhw_setpoint, maxch_setpoint=maxch_setpoint)
    return result


async def read_fault_flags() -> dict:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_ASF_FAULT, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_ASF_FAULT)

    result = dict(
        service_required=True if r_data & 0x0100 else False,
        blor_enabled=True if r_data & 0x0200 else False,
        low_water_pressure=True if r_data & 0x0400 else False,
        flame_fault=True if r_data & 0x0800 else False,
        air_pressure_fault=True if r_data & 0x1000 else False,
        water_over_temp=True if r_data & 0x2000 else False,
        oem_code=r_data & 0xFF,
    )
    return result


async def read_oem_long_code() -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_OEM_DIAGNOSTIC_CODE, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_OEM_DIAGNOSTIC_CODE)
    return r_data


async def read_relative_modulation_level() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_REL_MOD_LEVEL, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_REL_MOD_LEVEL)
    return f88(r_data)


async def read_ch_water_pressure() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_CH_PRESSURE, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_CH_PRESSURE)
    return f88(r_data)


async def read_dhw_flow_rate() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_DHW_FLOW_RATE, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_DHW_FLOW_RATE)
    return f88(r_data)


async def read_boiler_flow_temperature() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TBOILER, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TBOILER)
    return f88(r_data)


async def read_boiler_flow_temperature_ch2() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TFLOWCH2, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TFLOWCH2)
    return f88(r_data)


async def read_dhw_temperature() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TDHW, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TDHW)
    return f88(r_data)


async def read_dhw2_temperature() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TDHW2, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TDHW2)
    return f88(r_data)


async def read_exhaust_temperature() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TEXHAUST, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TEXHAUST)
    return s16(r_data)


async def read_fan_speed() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_BOILER_FAN_SPEED, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_BOILER_FAN_SPEED)
    return (r_data & 0xff) * 60


async def read_outside_temperature() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TOUTSIDE, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TOUTSIDE)
    return f88(r_data)


async def read_boiler_return_water_temperature() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TRET, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TRET)
    return f88(r_data)


async def read_power_cycles() -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_POWER_CYCLES, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_POWER_CYCLES)
    return r_data


async def read_burner_starts() -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_BURNER_STARTS, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_BURNER_STARTS)
    return r_data


async def read_ch_pump_starts() -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_CH_PUMP_STARTS, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_CH_PUMP_STARTS)
    return r_data


async def read_dhw_pump_starts() -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_DHW_PUMP_STARTS, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_DHW_PUMP_STARTS)
    return r_data


async def read_dhw_burner_starts() -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_DHW_BURNER_STARTS, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_DHW_BURNER_STARTS)
    return r_data


async def read_burner_operation_hours() -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_BURNER_OPERATION_HOURS, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_BURNER_OPERATION_HOURS)
    return r_data


async def read_ch_pump_operation_hours() -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_CH_PUMP_OPERATION_HOURS, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_CH_PUMP_OPERATION_HOURS)
    return r_data


async def read_dhw_pump_operation_hours() -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_DHW_PUMP_OPERATION_HOURS, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_DHW_PUMP_OPERATION_HOURS)
    return r_data


async def read_dhw_burner_operation_hours() -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_DHW_BURNER_OPERATION_HOURS, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_DHW_BURNER_OPERATION_HOURS)
    return r_data


async def read_tsp_count() -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TSP_COUNT, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TSP_COUNT)
    return r_data >> 8


async def read_tsp(index: int) -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TSP_DATA, (index << 8)
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TSP_DATA)
    if r_data >> 8 != index:
        msg = f"TSP index mismatch: expected {index}, got {r_data >> 8}"
        send_syslog(f"ERROR: {msg}")
        raise ValueError(msg)
    return r_data & 0xff


async def read_fhb_count() -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_FHB_COUNT, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_FHB_COUNT)
    return r_data >> 8


async def read_fhb(index: int) -> int:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_FHB_DATA, (index << 8)
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_FHB_DATA)
    if r_data >> 8 != index:
        msg = f"FHB index mismatch: expected {index}, got {r_data >> 8}"
        send_syslog(f"ERROR: {msg}")
        raise ValueError(msg)
    return r_data & 0xff


async def control_remote_command(command: int):
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_WRITE_DATA, DATA_ID_COMMAND, command << 8
    )
    _check_response_type(r_msg_type, MSG_TYPE_WRITE_ACK, r_data_id, DATA_ID_COMMAND)
    if r_data >> 8 != command:
        msg = f"Remote command mismatch: expected {command}, got {r_data >> 8}"
        send_syslog(f"ERROR: {msg}")
        raise ValueError(msg)
    return r_data & 0xff


async def read_remote_override_room_setpoint():
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_TROVERRIDE, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_TROVERRIDE)
    return f88(r_data)


async def read_remote_override_function():
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_REMOTE_OVERRIDE_FUNCTION, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_REMOTE_OVERRIDE_FUNCTION)

    result = dict(manual_change_priority=True if r_data & 0x01 else False,
                  program_change_priority=True if r_data & 0x02 else False)
    return result


async def read_capacity_and_min_modulation():
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_MAX_CAPACITY_MIN_MODULATION, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_MAX_CAPACITY_MIN_MODULATION)

    return r_data >> 8, r_data & 0xff


async def control_max_relative_modulation_level(l: float):
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_WRITE_DATA, DATA_ID_MAX_REL_MODULATION, int(l * 256)
    )
    _check_response_type(r_msg_type, MSG_TYPE_WRITE_ACK, r_data_id, DATA_ID_MAX_REL_MODULATION)


async def read_max_relative_modulation_level() -> float:
    r_msg_type, r_data_id, r_data = await opentherm_exchange_retry(
        MSG_TYPE_READ_DATA, DATA_ID_MAX_REL_MODULATION, 0
    )
    _check_response_type(r_msg_type, MSG_TYPE_READ_ACK, r_data_id, DATA_ID_MAX_REL_MODULATION)
    return f88(r_data)