Proposal: pick up the deferred WebSocket investigation (ADR-007)

[mrdjtoto]

Who I am

Hi! I'm a Home Assistant user and software engineer, and I recently got Mitsubishi units at home — so I'm very interested in helping improve this integration. I'm the author of #172 and #173. Full transparency on how I work: I use Claude Code to write the code, and everything gets tested locally on my own HA instance (real MELCloud Home account, 3 ATA units) before I push anything.

Proposal

I'd like to pick up the WebSocket investigation that was deferred in ADR-007.

The ADR documents the v1.1 findings (inconsistent message delivery, only one device receiving updates, routing mechanism not understood) and lays out a clear investigation path:

1. Deep packet analysis of the WebSocket protocol
2. Understand the message routing mechanism
3. Identify device subscription requirements
4. Determine the authentication model
5. Test reliability at scale (multiple devices/buildings)

What I'm offering

Investigation only, at first — no implementation PR until the protocol is understood and we agree it meets the ADR's bar (≥99% delivery, graceful fallback to polling, proper reconnection handling):

• Run the mobile app through mitmproxy (the repo's existing RE tooling) and capture the WebSocket handshake, token exchange, and message flow against my real account
• Document the protocol in docs/api/ following the style of the existing API references (scrubbed captures only)
• Reproduce and characterize the "only one device receives updates" issue from the v1.1 investigation — with 3 ATA units on one account I should be able to observe the routing behavior directly
• Report findings back in this issue before any code is written

Questions

• Is there anything from the v1.1 investigation beyond what's in ADR-007 and docs/archive/research/ that would save me time (captures, notes, dead ends)?
• Any preference on where protocol documentation should land?

If the investigation confirms the protocol can be made reliable, I'd follow up with a design proposal here before opening an implementation PR.

🤖 Issue drafted with Claude Code

[andrew-blake]

Hi @mrdjtoto thanks for reaching out. As you can probably tell, I'm a heavy Claude Code user too!

I'd welcome contributions for WebSocket support. It's the natural evolution of this integration now that basic polling support exists in HA 2026.7.

When I first performed the API research, I used Claude to drive the Chrome DevTools MCP to inspect the web browser network traffic. Since then I've switched the API to use the Mobile App API backend as it appears to be more reliable, but didn't look at the time to see whether MITM proxy supports / captures websocket push updates.

docs/research/REVERSE_ENGINEERING.md

Might be worth starting to look at that doc. Let me know how you get on!

[mrdjtoto]

hi @andrew-blake, thank you for your answer.
I could see you use Claude as well. I can imagine how useful it has been for this good job you created and I am thankful you wanted o share it.

I've already sarted to set up claude to investigate about websocket, starting from what you documented. At first glance, the plan should sound like that:

The investigation will be Claude-driven, with everything verified against my real setup (3 ATA units, HA 2026.7.1 on an always-on home server).
I started from docs/research/REVERSE_ENGINEERING.md, ADR-007 and the archived v1.1 research, and already ran a first read-only probe with my own account's tokens. Early findings:

• The legacy WS infrastructure is still alive: ws.melcloudhome.com resolves and behaves like an AWS API Gateway WebSocket (500 on bare connect, 502 on an invalid hash).
• GET /ws/token still exists on the legacy web host, but returns 401 with a mobile-BFF bearer token — it wants web-session auth. The mobile BFF has no /ws/token at the obvious paths (404), so it's an open question whether the mobile app uses WS at all or something else (e.g. native push).

Planned steps — investigation only, no integration code until we agree on findings:

1. Replicate the legacy web auth (still in git history pre-ADR-017) to obtain a /ws/token hash, then attach a passive, receive-only listener and log messages while I exercise my 3 units from the app. With three units on one account I should be able to reproduce (or rule out) the v1.1 "only one device receives updates" routing bug.
2. Long-run monitoring (24h+) from my always-on server to characterise delivery reliability, as the old research doc called for.
3. mitmproxy capture of the official iOS app to answer your open question directly — and yes, mitmproxy captures WebSocket frames natively, so tools/mitmproxy/ should work as-is for that.

Deliverable: findings written up on #174 (protocol notes + reliability data), then we decide together if and how to implement.

I'll keep you updated, thank you for the opportinity!

[andrew-blake]

Sounds great. I'd recommend registering for a new MELCloud Home user account for development / HA purposes and then invite it to control each of your devices (Device -> ... -> Advanced Controls -> Share Product). That way, if you accidentally trigger a rate limit MELCloud Home won't block your main account.

[mrdjtoto]

Hi @andrew-blake,

good news on your open question: mitmproxy does capture the WebSocket, and I think the auth story is simpler than we feared. I did an iOS mitmproxy capture (your Phase 1 flow) plus a static look at the app, and the realtime path turns out to be reproducible with the mobile-BFF bearer the integration already holds — no parallel web session needed. Details below, all level-1 (observed live on my 3 ATA units, read-only unless noted).

1. The app's realtime IS a WebSocket (not native push)

Static analysis of the app (it's a .NET 9 MAUI Blazor Hybrid) shows a WebSocketDispatcher (Connect / ReConnect / Disconnect / ReceiveLoop, driven by auth state) and a shared WebSocketMessages model with messageType /unitStateChanged — i.e. the same protocol we see on the wire. It bundles System.Net.WebSockets.Client, no SignalR. So realtime is a raw WS, and there's an OutgoingMessageType too (the app also sends on it).

2. The WS token comes from the mobile BFF — no web session required

This is the key finding vs. the old ADR-007 notes. The app gets its WS credential from an AWS Lambda Function URL, authenticated with the mobile-BFF Bearer:

GET https://6x2dgdulg7omjsxalnhmo4ynba0dcgwk.lambda-url.eu-west-1.on.aws/
Authorization: Bearer <mobile-BFF access_token>
→ 200 {"hash": "<uuid>", "userId": "<uuid>"}

then wss://ws.melcloudhome.com/?hash=<hash> → HTTP 101 (AWS API Gateway WS). Same {hash,userId} shape as the old web /ws/token, but reached with the bearer instead of a Cognito cookie session.

Verified end-to-end with the integration's own stored token: Lambda (Bearer) → hash → wss://…/?hash= → 101 connected. So a WS client can ride the existing MELCloudHomeAuth bearer + refresh — nothing new to authenticate.

One question for you here: that Lambda URL looks like a fixed, hardcoded endpoint — I couldn't see it returned dynamically by /config or /context (the app seems to carry it in its bundled config), and it resolved identically for two different accounts, so it's not per-user. Do you happen to know if it's stable environment config we can rely on? My plan would be to hardcode it alongside ws.melcloudhome.com and treat any failure (404 / non-200 / handshake error) as a signal to fall back to polling, so a URL change degrades gracefully rather than breaking the integration — but if you'd rather source it differently, I'll follow your lead.

3. Capture gotcha worth adding to the RE doc

auth.melcloudhome.com is certificate-pinned — login won't go through mitmproxy (TLS handshake refused; app shows a generic error). mobile.bff.melcloudhome.com and the WS token Lambda are not pinned. Workaround that worked: log in with the proxy OFF, then enable the proxy — the app reuses the valid token and all BFF + WS-token traffic is then interceptable. Happy to PR a short "Phase 3: WebSocket" section to REVERSE_ENGINEERING.md documenting this + the token flow, and to share an anonymised HAR via your anonymize_har.py.

4. Message shape

Per-unit delta pushes, only the changed setting names:

[{"messageType": "unitStateChanged",
  "Data": {"id": "<uuid>", "unitType": "ata",
           "settings": [{"name": "SetTemperature", "value": "…"}]}}]

Observed names: Power, OperationMode, SetTemperature, SetFanSpeed, Vane*, InStandbyMode, plus server-pushed RoomTemperature and ActualFanSpeed. Values are strings — same coercion caveat as the REST settings. True
out-of-band changes (from the MELCloud app and from HA) both propagate, for all units — the v1.1 "only one device updates" bug did not reproduce for me.

5. Reliability (resilient listener, over 22 hours)

• Uptime ~99.9% (total downtime ~77s over ~80,900s)
• 759 messages, from all 3 units throughout (169 / 309 / 281 across units); 0 errors
• 11 disconnects — almost all at exactly 7200s connection age: the AWS API Gateway WS 2-hour hard cap, not flakiness. Reconnect (fresh hash + handshake) ~7s each, messages resume immediately.

Net: treat the 2-hourly drop as normal and reconnect → effectively continuous.

6. Proposed approach (keen on your steer)

• New api/websocket.py dispatcher + a get_ws_token() on the client (reusing the existing bearer/refresh); connect loop with backoff and hash re-fetch on reconnect.
• Wire into the coordinator as an opt-in, experimental accelerator over the existing polling — on a unitStateChanged delta, trigger a coordinator refresh (simple v1; in-place delta apply as a later optimisation). If the WS drops or the token endpoint ever changes, it degrades silently to polling.
• An ADR superseding 007 (and updating 018's out-of-band limitation) to record the decision + the BFF-native auth path.

I can put this on a branch and dogfood it on my own HA before raising anything — and I'll hold it until you've had a chance to look at the current PRs (#172/#173). Does the opt-in-accelerator shape sound right to you, and would you prefer the RE-doc/HAR contribution as a separate small PR first?

[andrew-blake]

Great findings!

Yes, can you create the docs/har PR first please ?

[andrew-blake]

Thanks @mrdjtoto, the #175 capture pinned down the login flow and frame shape nicely. The thing ADR-007 got stuck on was the routing — "only one device receives updates, inconsistent which one" — and that's the bit we still can't see, so if you're up for a few more captures, these are the ones that would help most:

1. Multi-device routing — this is the important one. With one socket open, toggle each of your 3 ATA units in turn. Does the single socket get unitStateChanged deltas for all three, or only one (and is it consistent which)? Everything else is secondary to knowing this.

2. The full socket lifecycle — the docs: web BFF + real-time WebSocket capture notes #175 capture only shows frames coming from the server, nothing going to it after the 101. Could you capture from the handshake through a longer idle period, so we can see whether the client sends any subscribe frame, and what the keepalive ping/pong and idle timeout look like?

3. A few different setting types — we've only seen Power so far, and it's a boolean true on the socket but the string "False" in /api/user/context. Before anyone writes a parser, could you grab SetTemperature, OperationMode, SetFanSpeed and a vane change over the socket so we know the type and casing of each?

4. The mobile credential path — the integration logs in as the mobile client (Lambda URL, bearer), but docs: web BFF + real-time WebSocket capture notes #175 is the web path (/ws/token, cookie). A mitmproxy capture of the mobile app's {hash,userId} fetch plus its socket would confirm the two really are the same rather than us assuming.

5. Reconnection / token expiry — what does the server send on close, and what happens when the hash expires mid-socket? That's the bit we'd need for graceful fallback, and it ties into the token-contention question already in your doc.

One note: the token-contention question isn't really a HAR thing — it's the debug logs (api.websocket, coordinator, api.auth) you've already got running, which is the right place to catch it.

One heads-up for whenever you capture these — anonymize_har.py only catches plain-text IDs, so anything base64/encoded (like the nonce and request_uri in #175) needs scrubbing by hand before committing.

If the first one comes back showing all units on one socket reliably, that clears ADR-007's main objection and we can start talking about implementation. Thanks again for picking this up.

[mrdjtoto]

Happy to keep capturing. On the important one (multi-device routing): the debug
logs from dogfooding already give a strong preliminary answer. With a single
socket open I'm getting unitStateChanged deltas for all three of my ATA units —
each unit's UUID shows up independently (90eebe7e, 98aa9642, b88bd26d), not just
one. So at least for the passive RoomTemperature pushes it's routing to all
units on the one socket. I'll still do the deliberate test: one socket open,
toggle each unit in turn, and confirm each produces its own delta so we know
control changes route per-unit too.

For the rest:

• Full socket lifecycle: I'll capture handshake -> long idle with mitmproxy so we
  see both directions (the docs: web BFF + real-time WebSocket capture notes #175 HAR only had server->client), and report any
  client subscribe frame, the ping/pong cadence, and the idle timeout.
• Setting types: I'll grab SetTemperature, OperationMode, SetFanSpeed and a vane
  change over the socket so we have the type + casing of each before anyone
  writes a parser.
• Mobile credential path: mitmproxy capture of the app's {hash,userId} fetch plus
  its socket, to confirm mobile and web really are the same.
• Reconnection / token expiry: the server's close frame and what happens when the
  hash expires mid-socket.

And noted re anonymize_har.py only catching plaintext — I'll hand-scrub anything
base64/encoded before committing (that's exactly what bit #175).

On the token-contention question (agreed, a debug-log thing, not a HAR one): I
traced it from the api.websocket/coordinator/api.auth logs. It's the WS branch's
own new options update listener firing on the token-persist data write, which
reloads the entry on every refresh and races the rotating refresh token. Fixed
on my WS branch by gating the reload to real options changes; it'll be in the WS
PR.

[mrdjtoto]

Update on the captures — most of it is done, and I've pushed the results into #175.

#1 Multi-device routing (the important one) — done, and it clears ADR-007's
objection. With a single socket open I toggled each of my 3 ATA units in turn;
each change produced a unitStateChanged delta for that unit only, matched by id,
no cross-talk. All three units are served on the one socket, consistently.

#3 Setting value types — done (Chrome DevTools HAR, committed anonymized to #175).
Over the socket the values are natively typed / enum-ints, unlike /context which
stringifies them:
- SetTemperature: number (int or float; 0.5 steps) [/context: "26"]
- OperationMode: int enum — 3=Cool, 4=Fan [/context: "Cool"]
- SetFanSpeed: int enum — 0=Auto [/context: "Auto"]
- ActualFanSpeed: STRING — "1","2","3"
- VaneVerticalDirection / VaneHorizontalDirection: int enum — 6/7 = swing
- Power: boolean true/false [/context: "False"]
Two gotchas for a parser: socket sends typed values but REST sends strings, and
the socket is inconsistent with itself (SetFanSpeed int vs ActualFanSpeed string).

#4 Mobile credential — done. mitmproxy on the mobile app: the Lambda fetch returns
{"hash": "", "userId": ""} with hash == userId, identical to the web
/ws/token and to the hash the integration itself obtains. So mobile, web and the
integration share one per-user credential (≈ the userId), confirmed rather than
assumed.

#2 Socket lifecycle — mostly. No client→server frames at all — no subscribe
frame; the client just opens ?hash= and receives. Handshake negotiates
permessage-deflate, no subprotocol.

#2/#5 the gaps (ping/pong, close frame) — I couldn't get these cleanly.
iOS doesn't route the wss socket through a manual HTTP proxy, and mitmproxy's
WireGuard mode relays this particular socket unreliably (it dies with close_code
1006 abnormal-close storms, with or without stripping permessage-deflate).
Chrome doesn't surface WS control frames either. So ping/pong and the server's
close code aren't observable with the usual tools — but they don't affect the
client: the integration drives its own keepalive (aiohttp heartbeat=30s) and
treats any close as reconnect-with-backoff (from dogfooding: reconnects at the
~2h API Gateway cap in a few seconds). I documented the tooling limits + a
capture_ws.py addon in the RE guide in #175 for whoever tries next.

Separately, on the token-contention question (which as you said is a debug-log
thing, not a HAR one): I root-caused it. It's the WS branch's own new options
update listener — a token refresh writes entry.data, HA fires the listener, and
it reloads the whole entry every refresh, which races the rotating refresh token.
On main _persist_tokens writes entry.data but nothing reloads, so it's a
regression the WS branch introduces, not a pre-existing bug. Fixed on my branch
by gating the reload to real options changes.

[andrew-blake]

Thanks for this write up. I'm OOO for the next week but will take a look when I return.

[andrew-blake]

Back to close this out — everything since landed while this thread was quiet.

Your routing captures above cleared ADR-007's core objection, and the rest held up: implementation merged in #176 (follow-ups #181, #183, #185, #187), and my ~12.5h guest-account soak confirmed the socket is device-type agnostic (587 deltas across 7 units on one socket, including 130 from an Ecodan heat pump) with clean ~2h reconnects throughout. ADR-019 supersedes ADR-007.

Shipped in v2.4.0-beta.1 as "Real-time updates", on by default with an opt-out, currently soaking in beta.2 ahead of stable. Thanks for driving this end to end.