Create more reliable update from Zaptec on changes #189
Description
Based on finding in #183 (comment) to solve #176, it shows that data is slow to get update from the Zaptec cloud, and more importantly, it can return data which is outdated. This is a challenge for the user as the user will either see data which is slow to update or values jumping back and forth between NEW -> OLD -> NEW.
Below I have some example tracking the changes of ChargerMaxCurrent to highlight the issues. This issue is not limited to this single parameter only, but is a general challenge of how to reliably getting updates from Zaptec cloud when changes are made.
The objective of this issue to discuss how we can better adopt the API interface logic in the HA integration to the current behavior of the cloud.
Case 1
In this example the max charger current is first set by the user. A service bus push is received, but it does not contain an update of the ChargerMaxCurrent. This parameter is not updated until the polling of the charger state is done.
If we implement very infrequent polling (like 1 hour) and does not do forced polls after a command, this means that it will take up to the length of a poll interval to properly update the values of changed parameters.
# Polling state
18:09.783 [zaptec.api] Polling state for Charger[f40861] (Sol)
18:09.877 [zaptec.api] ChargerMaxCurrent = 32.000 (2025-07-06T12:14:14.543)
# Setting max current
18:34.470 [zaptec.number] Setting ZaptecSettingNumber.charger_max_current to <float> 15.0 (in f40861)
18:34.470 [zaptec.api] Settings {'maxChargeCurrent': 15.0}
# Getting notified from service bus
# NOTE That the service bus does not contain `ChargerMaxCurrent` events
18:35.235 [zaptec.api] --- Subscription: {'DeviceId': 'xxx', 'DeviceType': 4, 'ChargerId': 'xxx', 'StateId': '511 (ChargerMinCurrent)', 'Timestamp': '2025-07-06T11:35:56.453', 'ValueAsString': '5.000'}
18:35.256 [zaptec.api] --- Subscription: {'DeviceId': 'xxx', 'DeviceType': 4, 'ChargerId': 'xxx', 'StateId': '711 (IsEnabled)', 'Timestamp': '2023-07-12T13:29:38.207', 'ValueAsString': '1'}
# Forced polling to which gets the correct state value
18:35.800 [zaptec.api] Polling state for Charger[f40861] (Sol)
18:35.907 [zaptec.api] ChargerMaxCurrent = 15.000 (2025-07-06T12:18:34.74)
18:35.908 [zaptec.api] >>> Updating Charger[f40861].charger_max_current (ChargerMaxCurrent) = <float> 15.0 (was 32.0)
18:35.959 [zaptec] number.sol_charger_max_current = <float> 15.0 from Charger[f40861]Case 2
In this example it can be seen that the data returned from Zapec cloud is returning old data, which in turn cause data in the integration to bounce between old and new values. The actual value won't get properly updated until the next poll is run, which can be significant. In this setup the poll interval is 60 seconds, and here it takes 62 seconds from the user setting a value until its updated.
# Scheduled poll of state
35:41.483 [zaptec.api] Polling state for Charger[f40861] (Sol)
35:41.579 [zaptec.api] ChargerMaxCurrent = 0.000 (2025-07-06T12:35:40.643)
# Setting max current to 32
36:02.881 [zaptec.number] Setting ZaptecSettingNumber.charger_max_current to <float> 32.0 (in f40861)
36:02.881 [zaptec.api] Settings {'maxChargeCurrent': 32.0}
# Forced poll by integration to get the latest state
# NOTE: Return old value, so the parameter is set to 0
36:04.200 [zaptec.api] Polling state for Charger[f40861] (Sol)
36:04.316 [zaptec.api] ChargerMaxCurrent = 0.000 (2025-07-06T12:35:40.643)
37:04.323 [zaptec.api] >>> Updating Charger[f40861].charger_max_current (ChargerMaxCurrent) = <float> 0.0 (was 32.0)
# Service bus notifications -- Notice that `ChargerMaxCurrent` is not present
36:04.533 [zaptec.api] --- Subscription: {'DeviceId': 'xxx', 'DeviceType': 4, 'ChargerId': 'xxx', 'StateId': '511 (ChargerMinCurrent)', 'Timestamp': '2025-07-06T12:33:30.473', 'ValueAsString': '12.000'}
36:04.554 [zaptec.api] --- Subscription: {'DeviceId': 'xxx', 'DeviceType': 4, 'ChargerId': 'xxx', 'StateId': '523 (ChargerOfflineCurrent)', 'Timestamp': '2025-07-06T09:40:54.727', 'ValueAsString': '12.000'}
36:04.576 [zaptec.api] --- Subscription: {'DeviceId': 'xxx', 'DeviceType': 4, 'ChargerId': 'xxx', 'StateId': '712 (IsStandAlone)', 'Timestamp': '2023-07-12T13:31:40.253', 'ValueAsString': '0'}
# Next scheduled poll of state updates the value
37:04.781 [zaptec.api] Polling state for Charger[f40861] (Sol)
37:04.897 [zaptec.api] ChargerMaxCurrent = 32.000 (2025-07-06T12:36:03.673)
37:04.897 [zaptec.api] >>> Updating Charger[f40861].charger_max_current (ChargerMaxCurrent) = <float> 32.0 (was 0.0)Mitigations
Potential ideas to mitigate the current behavior:
-
Implement timestamped updates of parameters. State and service bus updates have timestamps. Make a system that refuses to update the parameter value if the timestamp is older than the cache. What other parameters exists that doesn't have time stamp and do they change during use?
-
If service bus does not provide an update within a certain time, run a forced poll of the state. This is to ensure that the parameter is updated when a change is made. How can we know that the service bus update is complete?
-
If the poll doesn't provide an update, reschedule a new poll fairly quickly (like in seconds, not minutes). A useful input here is if we know something about how long time it takes for a change to propagate before the data is available in Zaptec cloud.
-
If having very long poll intervals (10 minutes++), the integration should poll twice on startup with ~10 seconds between. This is because the first poll might not be fully updated for any pending changes and it would be too long time until the next update. Doing it twice mitigates this.