Add support for UWG4 thermostats

README.md

@@ -20,8 +20,7 @@ Asynchronous Python client for communicating with a OJ Microline Thermostat.
 
 ## About
 
-A python package with which you control your OJ Microline Thermostat. Currently it supports reading temperatures
-and various details about the thermostat(s) and setting the thermostat to another regulation mode.
+A Python package to control OJ Microline thermostats. It currently supports the WD5 series (OWD5, MWD5) and WG4 series (UWG4, AWG4).
 
 ## Installation
 
@@ -33,11 +32,10 @@ pip install ojmicroline-thermostat
 
 ### Thermostat
 
-This set represents the current state of your thermostat.
+This object represents the current state of a thermostat.
 
 | Variable | Type | Description |
 | :------- | :--- | :---------- |
-| `thermostat_id` | int | The unique identifier for this thermostat. |
 | `model` | string | The model name for this thermostat. |
 | `serial_number` | string | The serial number for this thermostat. |
 | `software_version` | string | The currently installed software version. |
@@ -46,37 +44,56 @@ This set represents the current state of your thermostat.
 | `name` | string | The name of the thermostat. |
 | `online` | boolean | Indicates if the thermostat is connected to the network. |
 | `heating` | boolean | Indicates if the thermostat is currently heating/is on. |
+| `regulation_mode` | integer | The currently set regulation mode of the thermostat, see below. |
+| `supported_regulation_modes` | list | The regulation modes this thermostat supports. |
+| `min_temperature` | integer | The lowest temperature the thermostat can be set to. |
+| `max_temperature` | integer | The highest temperature the thermostat can be set to. |
+| `manual_temperature` | integer | If the regulation mode is set to manual mode, the thermostat will target this temperature. |
+| `comfort_temperature` | integer | If the regulation mode is set to comfort mode, the thermostat will target this temperature. |
+| `comfort_end_time` | datetime | If the regulation mode is set to comfort mode, it will end at this time. |
+| `last_primary_mode_is_auto` | boolean | Unknown |
+
+These fields are only available on WD5-series thermostats; for others, they may be `None`:
+
+| Variable | Type | Description |
+| :------- | :--- | :---------- |
+| `thermostat_id` | int | The unique identifier for this thermostat. |
 | `adaptive_mode` | boolean | If on then then the thermostat automatically changes heating start times to ensure that the required temperature has been reached at the beginning of any specific event. |
 | `vacation_mode` | boolean | If on then the thermostat regulates the heating of your home to a minimum while you are away on holiday, thus saving energy and money. |
 | `open_window_detection` | boolean | If on then the thermostat shuts off the heating for 30 minutes if an open window is detected. |
-| `last_primary_mode_is_auto` | boolean | Unknown |
 | `daylight_saving_active` | boolean | If on, the "Daylight Saving Time" function of the thermostat will automatically adjust the clock to the daylight saving time for the "Region" chosen. |
-| `regulation_mode` | integer | The currently set regulation mode of the thermostat, see below. |
 | `sensor_mode` | integer | The currently set sensor mode of the thermostat, see below. |
-| `temperature_floor` | integer | The temperature measured by the floor. sensor |
+| `temperature_floor` | integer | The temperature measured by the floor sensor. |
 | `temperature_room` | integer | The temperature measured by the room sensor. |
-| `min_temperature` | integer | The minimum set temperature for the thermostat. |
-| `max_temperature` | integer | The maximum set temperature for the thermostat. |
-| `temperatures` | object | The currently set temperatures for each regulation mode, see below. |
+| `boost_temperature` | integer | If the regulation mode is set to boost mode, the thermostat will target this temperature. |
 | `boost_end_time` | datetime | If the regulation mode is set to boost mode, it will end at this time. |
-| `comfort_end_time` | datetime | If the regulation mode is set to comfort mode, it will end at this time. |
+| `vacation_temperature` | integer | If the regulation mode is set to vacation mode, the thermostat will target this temperature. |
 | `vacation_begin_time` | datetime | Vacation mode will be set to on when this date time passes. |
 | `vacation_end_time` | datetime | Vacation mode will be set to off when this date time passes. |
-| `offset` | integer | The offset (timezone) set by the thermostat. |
-| `schedule` | Schedule | The schedule the thermostat currently uses. |
+| `frost_protection_temperature` | integer | If the regulation mode is set to frost protection mode, the thermostat will target this temperature. |
+| `schedule` | Schedule | The schedule the thermostat currently uses. (This *could* be supported by WG4-series thermostats, it simply isn't implemented.) |
+
+These fields are only available on WG4-series thermostats; for others, they may be `None`:
+
+| Variable | Type | Description |
+| :------- | :--- | :---------- |
+| `temperature` | integer | The current temperature; the thermostat uses the room sensor or floor sensor based on its configuration. Avoid using this directly; instead, call the `get_current_temperature()` method which also works for WD5-series thermostats. |
+| `set_point_temperature` | integer | The temperature the thermostat is targeting. Avoid using this directly; instead, call the `get_target_temperature()` method which also works for WD5-series thermostats. |
 
 #### Regulation modes
 
 | Integer | Constant | Description |
 | :------- | :--- | :---------- |
 | `1` | `REGULATION_SCHEDULE` | The thermostat follows the configured schedule. |
-| `2` | `REGULATION_COMFORT` | The thermostat is in comfort mode for the next 4 hours. |
+| `2` | `REGULATION_COMFORT` | The thermostat is in comfort mode until `comfort_end_time`. |
 | `3` | `REGULATION_MANUAL` | The thermostat is in manual mode, will not resume schedule unless changed. |
 | `4` | `REGULATION_VACATION` | The thermostat is in vacation mode, it started at `vacation_begin_time` and ends at `vacation_end_time`. |
 | `6` | `REGULATION_FROST_PROTECTION` | The thermostat is set to frost protection, preventing the floor from freezing. |
 | `8` | `REGULATION_BOOST` | The thermostat is in boost mode for 1 hour, using the `max_temperature` as target temperature. |
 | `9` | `REGULATION_ECO` | The thermostat is in eco mode, using the lowest temperature of the `schedule`. |
 
+Keep in mind that certain thermostats only support a subset of these modes; be sure to check the `Thermostat.supported_regulation_modes` field.
+
 #### Sensor modes
 
 | Integer | Constant | Description |
@@ -92,15 +109,15 @@ This set represents the current state of your thermostat.
 | :------- | :--- | :---------- |
 | `login` | `None` | Create a new session at the OJ Microline API. |
 | `get_thermostats` | `None` | Get all thermostats from the OJ Microline API. |
-| `set_regulation_mode` | `resource: Thermostat`, `regulation_mode: int`, `temperature: int \| None = None` | Set the regulation mode based on the input.<br> - `resource`: An instance of a Thermostat model returned by `get_thermostats()`<br> - `regulation_mode`: An integer representing the regulation mode, see "Regulation modes"<br> - `temperature`: An integer representing the temperature, eg: 2500. Only useful when setting the regulation mode to manual or comfort. |
+| `set_regulation_mode` | `resource: Thermostat`, `regulation_mode: int`, `temperature: int \| None = None`, `duration: int = COMFORT_DURATION` | Set the regulation mode based on the input.<br> - `resource`: An instance of a Thermostat model returned by `get_thermostats()`<br> - `regulation_mode`: An integer representing the regulation mode, see "Regulation modes"<br> - `temperature`: An integer representing the temperature, eg: 2500. Only useful when setting the regulation mode to manual or comfort.<br> - `duration`: The duration in minutes to set the temperature for; only applies to comfort mode. |
 
 ## Usage
 
 ```python
 import asyncio
 from time import sleep
 
-from ojmicroline_thermostat import OJMicroline, Thermostat
+from ojmicroline_thermostat import OJMicroline, Thermostat, WD5API
 from ojmicroline_thermostat.const import (
     REGULATION_BOOST,
     REGULATION_COMFORT,
@@ -109,9 +126,6 @@ from ojmicroline_thermostat.const import (
     REGULATION_MANUAL,
     REGULATION_SCHEDULE,
     REGULATION_VACATION,
-    SENSOR_FLOOR,
-    SENSOR_ROOM,
-    SENSOR_ROOM_FLOOR,
 )
 
 REGULATION_MODES = {
@@ -124,21 +138,16 @@ REGULATION_MODES = {
     REGULATION_VACATION: "Vacation",
 }
 
-SENSOR_MODES = {
-    SENSOR_FLOOR: "Floor",
-    SENSOR_ROOM: "Room",
-    SENSOR_ROOM_FLOOR: "Room/Floor",
-}
-
 
 async def main():
     """Show example on using the OJMicroline client."""
     async with OJMicroline(
-        host="ocd5.azurewebsites.net",
-        customer_id=1234,
-        api_key="<app-api-key>",
-        username="<your-username>",
-        password="<your-password>",
+        api=WD5API(
+            customer_id=1234,
+            api_key="<app-api-key>",
+            username="<your-username>",
+            password="<your-password>",
+        ),
     ) as client:
         # Thermostats
         thermostats: list[Thermostat] = await client.get_thermostats()
@@ -149,14 +158,9 @@ async def main():
             print("####################")
             print("- Details:")
             print(f"   Serial Number: {resource.serial_number}")
-            print(f"   Sensor mode: {SENSOR_MODES[resource.sensor_mode]}")
-            print("- Regulation:")
             print(f"   Mode: {REGULATION_MODES[resource.regulation_mode]}")
             print(f"   Temperature: {resource.get_current_temperature()}")
             print(f"   Target temperature: {resource.get_target_temperature()}")
-            print("- Temperatures:")
-            print(f"   Floor: {resource.temperature_floor}")
-            print(f"   Room: {resource.temperature_room}")
             print("")
 
             print(f"- Setting to boost mode")

ojmicroline_thermostat/__init__.py

@@ -9,6 +9,8 @@
 )
 from .models import Thermostat
 from .ojmicroline import OJMicroline
+from .wd5 import WD5API
+from .wg4 import WG4API
 
 __all__ = [
     "Thermostat",
@@ -18,4 +20,6 @@
     "OJMicrolineConnectionException",
     "OJMicrolineResultsException",
     "OJMicrolineTimeoutException",
+    "WD5API",
+    "WG4API",
 ]

ojmicroline_thermostat/const.py

@@ -1,4 +1,5 @@
 """Constants."""
+
 SENSOR_ROOM_FLOOR = 1
 SENSOR_FLOOR = 3
 SENSOR_ROOM = 4
@@ -11,5 +12,6 @@
 REGULATION_BOOST = 8
 REGULATION_ECO = 9
 
-DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%S"
+WD5_DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%S"
+WG4_DATETIME_FORMAT = "%d/%m/%Y %H:%M:%S %z"
 COMFORT_DURATION = 240

ojmicroline_thermostat/models/schedule.py

@@ -1,4 +1,5 @@
 """Schedule model for OJ Microline Thermostat."""
+
 from __future__ import annotations
 
 from dataclasses import dataclass