Skip to content

Add push notification support for WG4-series thermostats - #691

Open
adamjernst wants to merge 1 commit into
robbinjanssen:mainfrom
adamjernst:wg4-push-updates
Open

Add push notification support for WG4-series thermostats#691
adamjernst wants to merge 1 commit into
robbinjanssen:mainfrom
adamjernst:wg4-push-updates

Conversation

@adamjernst

Copy link
Copy Markdown
Contributor

Refs #226 (partially: WG4 only).

What

Adds push updates for WG4-series thermostats so consumers such as Home Assistant can react to changes within seconds instead of polling.

  • OJMicroline.subscribe(listener) -> unsubscribe. The first subscriber starts a background task that waits for notifications and dispatches each updated Thermostat to every listener (plain or coroutine functions). Failures are retried with exponential backoff (1 s up to 5 min); a failing listener is logged and does not affect the others. The task stops when the last subscriber leaves or the client is closed.
  • OJMicrolineAPI gains supports_notifications: bool and async get_notifications() -> list[Thermostat], keeping the core client simple and the transport details in the per-model classes as discussed in Add support for notification streams #226.
  • WG4API implements it. WD5 and WG5 report unsupported and raise OJMicrolineError (WD5 has a SignalR hub, see the POC in Add support for notification streams #226, and can be added in a follow-up).
  • _request accepts a per-request timeout so the long-poll can outlast the default 30 s.
  • README section and tests (coverage stays at 100%).

How the WG4 cloud does it

GET /api/notification?sessionid=... on mythermostat.info is a long-poll: it blocks until a thermostat changes and returns {"SequenceNr": n, "Action": 2, "Thermostat": {...full api/thermostat payload...}}, or after roughly a minute returns Action 0 with a null thermostat. Notifications are queued per session, and only once that session has called api/thermostats, so WG4API.get_notifications() re-fetches (and returns) every thermostat whenever the session id changes, which also covers the periodic re-login.

Testing

Verified live against two UWG4 thermostats: both delivered on subscribe, a setpoint change made through the API arrived in about 2 s, periodic temperature reports arrive every 25-60 s per thermostat, a forced mid-stream re-login re-subscribed and re-delivered both thermostats, and unsubscribing cleared the task.

Refs robbinjanssen#226.

The WG4 cloud delivers change notifications by long-polling
GET /api/notification?sessionid=...: the request blocks until a
thermostat changes (Action 2, full thermostat payload) or the server
gives up after about a minute (Action 0, null thermostat). Notifications
are queued per session and only once that session has fetched the
thermostat list.

- Add supports_notifications and get_notifications() to the
  OJMicrolineAPI protocol. WG4API implements it with the long-poll and
  re-subscribes (re-fetching every thermostat) whenever the session id
  changes, e.g. after the periodic re-login. WD5 and WG5 report
  unsupported and raise OJMicrolineError.
- Add OJMicroline.subscribe(listener) -> unsubscribe. The first
  subscriber starts a background task that logs in, waits for
  notifications and dispatches them to every listener (sync or async),
  retrying failures with exponential backoff. The task stops when the
  last subscriber leaves or the client is closed.
- Allow a per-request timeout override so the long-poll can outlast
  the default 30 second request timeout.
- Document the feature in the README and cover it with tests.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Eer1ZnSZ8sz5oh8pq3AQT2
@codecov

codecov Bot commented Sep 10, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (d1701a2) to head (02d0984).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff            @@
##              main      #691   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           10        10           
  Lines          522       608   +86     
  Branches        67        79   +12     
=========================================
+ Hits           522       608   +86     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@robbinjanssen robbinjanssen added the new-feature New features or options. label Sep 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

new-feature New features or options.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants