diff --git a/plugwise/__init__.py b/plugwise/__init__.py index 0139bba0d..c4c14f76e 100644 --- a/plugwise/__init__.py +++ b/plugwise/__init__.py @@ -38,7 +38,7 @@ class Smile(SmileComm): - """The Plugwise SmileConnect class.""" + """The main Plugwise Smile API class.""" # pylint: disable=too-many-instance-attributes, too-many-public-methods @@ -91,7 +91,7 @@ def __init__( self.smile_zigbee_mac_address: str | None = None async def connect(self) -> Version | None: - """Connect to Plugwise device and determine its name, type and version.""" + """Connect to the Plugwise Gateway and determine its name, type, version, and other data.""" result = await self._request(DOMAIN_OBJECTS) # Work-around for Stretch fw 2.7.18 if not (vendor_names := result.findall("./module/vendor_name")): @@ -186,7 +186,7 @@ async def connect(self) -> Version | None: async def _smile_detect(self, result: etree, dsmrmain: etree) -> None: """Helper-function for connect(). - Detect which type of Smile is connected. + Detect which type of Plugwise Gateway is being connected. """ model: str = "Unknown" if (gateway := result.find("./gateway")) is not None: @@ -260,7 +260,10 @@ async def _smile_detect(self, result: etree, dsmrmain: etree) -> None: async def _smile_detect_legacy( self, result: etree, dsmrmain: etree, model: str ) -> str: - """Helper-function for _smile_detect().""" + """Helper-function for _smile_detect(). + + Detect which type of legacy Plugwise Gateway is being connected. + """ return_model = model # Stretch: find the MAC of the zigbee master_controller (= Stick) if (network := result.find("./module/protocols/master_controller")) is not None: @@ -305,15 +308,15 @@ async def _smile_detect_legacy( return return_model async def full_xml_update(self) -> None: - """Helper-function used for testing.""" + """Perform a first fetch of the Plugwise server XML data.""" await self._smile_api.full_xml_update() def get_all_gateway_entities(self) -> None: - """Helper-function used for testing.""" + """Collect the Plugwise Gateway entities and their data and states from the received raw XML-data.""" self._smile_api.get_all_gateway_entities() async def async_update(self) -> PlugwiseData: - """Update the various entities and their states.""" + """Update the Plughwise Gateway entities and their data and states.""" data = PlugwiseData(devices={}, gateway={}) try: data = await self._smile_api.async_update() diff --git a/plugwise/helper.py b/plugwise/helper.py index 7281730e5..a51ae02ea 100644 --- a/plugwise/helper.py +++ b/plugwise/helper.py @@ -275,7 +275,6 @@ def __init__(self) -> None: self.smile_type: str self.smile_version: version.Version | None self.smile_zigbee_mac_address: str | None - self.therms_with_offset_func: list[str] = [] self._zones: dict[str, GwEntityData] = {} SmileCommon.__init__(self) diff --git a/plugwise/legacy/smile.py b/plugwise/legacy/smile.py index d5be6832e..3f08e2634 100644 --- a/plugwise/legacy/smile.py +++ b/plugwise/legacy/smile.py @@ -34,7 +34,7 @@ class SmileLegacyAPI(SmileLegacyData): - """The Plugwise SmileLegacyAPI class.""" + """The Plugwise SmileLegacyAPI helper class for actual Plugwise legacy devices.""" # pylint: disable=too-many-instance-attributes, too-many-public-methods @@ -83,7 +83,7 @@ def __init__( self._previous_day_number: str = "0" async def full_xml_update(self) -> None: - """Perform a first fetch of all XML data, needed for initialization.""" + """Perform a first fetch of the Plugwise server XML data.""" self._domain_objects = await self.request(DOMAIN_OBJECTS) self._locations = await self.request(LOCATIONS) self._modules = await self.request(MODULES) @@ -92,24 +92,23 @@ async def full_xml_update(self) -> None: self._appliances = await self.request(APPLIANCES) def get_all_gateway_entities(self) -> None: - """Collect the gateway entities from the received raw XML-data. + """Collect the Plugwise gateway entities and their data and states from the received raw XML-data. - Run this functions once to gather the initial device configuration, - then regularly run async_update() to refresh the device data. + First, collect all the connected entities and their initial data. + Collect and add switching- and/or pump-group entities. + Finally, collect the data and states for each entity. """ - # Gather all the devices and their initial data self._all_appliances() - - # Collect and add switching- and/or pump-group devices if group_data := self._get_group_switches(): self.gw_entities.update(group_data) - # Collect the remaining data for all entities self._all_entity_data() async def async_update(self) -> PlugwiseData: - """Perform an incremental update for updating the various device states.""" - # Perform a full update at day-change + """Perform an full update update at day-change: re-collect all gateway entities and their data and states. + + Otherwise perform an incremental update: only collect the entities updated data and states. + """ day_number = dt.datetime.now().strftime("%w") if ( day_number # pylint: disable=consider-using-assignment-expr @@ -129,7 +128,6 @@ async def async_update(self) -> PlugwiseData: raise DataMissingError( "No (full) Plugwise legacy data received" ) from err - # Otherwise perform an incremental update else: try: self._domain_objects = await self.request(DOMAIN_OBJECTS) diff --git a/plugwise/smile.py b/plugwise/smile.py index 94bfebcfb..cd2ed0dca 100644 --- a/plugwise/smile.py +++ b/plugwise/smile.py @@ -93,45 +93,47 @@ def __init__( self.smile_name = smile_name self.smile_type = smile_type self.smile_version = smile_version + self.therms_with_offset_func: list[str] = [] SmileData.__init__(self) async def full_xml_update(self) -> None: - """Perform a first fetch of all XML data, needed for initialization.""" + """Perform a first fetch of the Plugwise server XML data.""" self._domain_objects = await self.request(DOMAIN_OBJECTS) self._get_plugwise_notifications() def get_all_gateway_entities(self) -> None: - """Collect the gateway entities from the received raw XML-data. + """Collect the Plugwise gateway entities and their data and states from the received raw XML-data. - Run this functions once to gather the initial configuration, - then regularly run async_update() to refresh the entity data. + First, collect all the connected entities and their initial data. + If a thermostat-gateway, collect a list of thermostats with offset-capability. + Collect and add switching- and/or pump-group entities. + Finally, collect the data and states for each entity. """ - # Gather all the entities and their initial data self._all_appliances() if self._is_thermostat: - if self.smile(ADAM): - self._scan_thermostats() - # Collect a list of thermostats with offset-capability self.therms_with_offset_func = ( self._get_appliances_with_offset_functionality() ) + if self.smile(ADAM): + self._scan_thermostats() - # Collect and add switching- and/or pump-group devices if group_data := self._get_group_switches(): self.gw_entities.update(group_data) - # Collect the remaining data for all entities self._all_entity_data() async def async_update(self) -> PlugwiseData: - """Perform an incremental update for updating the various device states.""" + """Perform an full update: re-collect all gateway entities and their data and states. + + Any change in the connected entities will be detected immediately. + """ self.gw_data: GatewayData = {} self.gw_entities: dict[str, GwEntityData] = {} self._zones: dict[str, GwEntityData] = {} try: await self.full_xml_update() self.get_all_gateway_entities() - # Set self._cooling_enabled - required for set_temperature, + # Set self._cooling_enabled - required for set_temperature(), # also, check for a failed data-retrieval if "heater_id" in self.gw_data: heat_cooler = self.gw_entities[self.gw_data["heater_id"]]