Would you be open to an asyncio transport?

[johnnyh1975]

Title: Would you be open to an asyncio transport? (asking before writing anything)

---

@pschmitt
I maintain ha_roomba_plus, a Home Assistant integration built on roombapy, and separately wrote roombapy-prime for the newer cloud protocol. So I have spent a while inside both this library and the async equivalent.

I would like to ask before writing code rather than after: would you be open to roombapy growing an asyncio transport? If the answer is no, or not now, that is a completely fine answer and I will stop there.

What prompted it

My integration has 111 places that exist only to cross the thread boundary this library's paho loop creates:

72x  async_add_executor_job     every command out
27x  run_coroutine_threadsafe   every response back
12x  call_soon_threadsafe       callbacks from the paho thread

Each one is a rule that has to be remembered. Forget call_soon_threadsafe in a callback and you touch Home Assistant's event loop from the wrong thread — which fails intermittently and is miserable to reproduce. I have my own notes-to-self about this, which is how I know I have got it wrong before.

An exception raised inside a paho callback also disappears into the thread rather than surfacing at the call site.

What I think the change actually is

Smaller than it sounds, which is part of why I am asking:

• remote_client.py (~180 lines) is the real work — paho's loop_start() becomes an aiomqtt client, or paho v2 bound to the running loop
• roomba.py: connect / disconnect / send_command / set_preference become coroutines
• The periodic_connection thread disappears rather than being ported — it only serves continuous=False, which Home Assistant never uses
• The message handling stays exactly as it is. It is pure state logic with no I/O, and it is the part that has been stable for years. I would not touch it.

The part that is your call, not mine

roombapy is a Home Assistant core dependency. Anything I propose has to answer what happens to the core roomba integration — either the sync surface stays alongside the async one, or core migrates, and that is not a decision a contributor should make for you.

I can see a version where RoombaFactory gains an async variant and nothing existing changes, but you would know better whether that is worth the maintenance surface.

What I am offering

The work, if you want it, in whatever shape you would accept it — one PR or split up, sync surface preserved or not. I would rather build what you would merge than present something finished and awkward to decline.

And if the answer is that roombapy is fine as it is: also a good answer. It has been reliable for a long time, and "my integration would need less glue" is my problem before it is yours.

[pschmitt]

I’m positive on adding an asyncio transport — I like the idea.

Regarding backwards compatibility, I wouldn’t worry too much about preserving the existing API. Nobody is forced to update the roombapy version used by Home Assistant, and this scope probably warrants a v2 API anyway.

Feel free to proceed with a design/PR.

[johnnyh1975]

@pschmitt
Thanks — that's very helpful, especially the point about backwards compatibility not being a constraint. I've put together a design proposal before touching any code:
roombapy-v2-design.md

Short version of what's in it.

I measured the thread boundary on a real consumer rather than guessing at it. In ha_roomba_plus (78 modules) there are 111 places bridging into or out of roombapy's thread: 72 async_add_executor_job, 27 run_coroutine_threadsafe, 12 call_soon_threadsafe. 49 of the 72 wrap a roombapy call; the other 23 are CPU-bound rendering that belongs in an executor regardless. All 39 of the run_coroutine_threadsafe/call_soon_threadsafe sites exist purely because register_on_message_callback delivers on paho's thread. So an async library removes 88 of the 111.

For the transport I'd propose aiomqtt. I checked it's genuinely thread-free at runtime — it drives paho through loop.add_reader/add_writer and loop_read/loop_write/loop_misc, no loop_start(), no Thread; the only run_in_executor is the one blocking connect() inside __aenter__. I ran it against the repo's own CI broker config (mosquitto 2.0.18, the .github/workflows/mosquitto certs and password file) with exactly the current TLS posture — PROTOCOL_TLS, CERT_NONE, DEFAULT:!DH, OP_LEGACY_SERVER_CONNECT, tls_insecure. Connect, subscribe, publish, receive, and bad-credential rejection all behave.

Scope is smaller than it looks: remote_client.py is replaced, four methods on Roomba become coroutines, the periodic_connection thread goes away. dict_merge, decode_topics, update_state_machine and the master_state shape stay exactly as they are — that's the field-proven part and there's no reason for the rewrite to touch it.

Two things I ran into while reading, both written up in the doc:

Auth failures are currently silent. A rejection arrives via on_connect and just leaves roomba_connected False, so the caller polls a flag. Under aiomqtt it raises. I've proposed connect() either succeeding or raising, with RoombaAuthError alongside the existing RoombaConnectionError — which inverts test_roomba_connect_error from a flag check to a pytest.raises.

subscribe() and publish() discard paho's return code. When the client isn't connected paho answers MQTT_ERR_NO_CONN and no packet leaves at all, but both calls return as if they'd worked — so you get a subscription that reports nothing forever, or a command that never reaches the robot, with nothing saying so. publish("cmd", ...) is the path every command takes. Checking the return code is free and needs no protocol change. (PUBACK confirmation would need QoS 1, which is a separate field question — I haven't verified these robots ack at QoS 1.) This predates the async work, so happy to send it as a small standalone fix against main first if you'd prefer.

Questions, roughly in the order they block things:

1. Packaging. Breaking roombapy 2.0, a parallel module (roombapy.aio), or a separate distribution? You said compatibility isn't a concern, which points at the first — but it decides whether a consumer can run old and new side by side during a transition, so I'd rather confirm than assume.
2. Is aiomqtt acceptable as a dependency? It pulls paho anyway, so it's a wrapper rather than a second transport stack. If you'd rather not, the fallback is an asyncio.to_thread facade over the existing client — but that keeps the paho thread, so exceptions still vanish into it and the calls aren't cancellable.
3. Branch. Should this target main, or would you like a v2 branch? At ~800 lines it's feasible as one PR, but a target branch would let the transport, the discovery/getpassword rewrite and the typing be reviewed separately.
4. Are discovery.py and getpassword.py in scope? Both still do blocking socket I/O and neither goes through MQTT. HA's async-dependency rule says there are no exceptions, and these are exactly the calls an integration makes during config flow — so I'd include them, but it's more surface than the MQTT swap alone.
5. RoombaFactory — drop it (with no thread to set up, the constructor is enough), or keep it for import compatibility?
6. Reconnect — keep it with the caller for 2.0 as it is today, or would you rather the library owned it with backoff from the start?
7. Typed state. RoombaMessage = dict[str, Any] # For now it's untyped — I'd like to take that comment up on its offer, but additively: master_state keeps returning dict[str, Any], and a set of TypedDicts (ReportedState, CleanMissionStatus, Capabilities, …) is exported alongside, plus a typed reported view for callers who opt in. TypedDict rather than dataclasses on purpose — it is the dict at runtime, no parsing, no second representation, and total=False describes exactly what a delta payload is. Nothing changes shape and no caller breaks. Worth having? Same PR or separate?
8. Vendor error texts — a question, not an offer. A related project of mine carries iRobot's own fault texts from the app's locale packs: 112 codes with title and explanation in eight languages. 48 overlap with ROOMBA_ERROR_MESSAGES, and where both have an entry the vendor's is more actionable — code 6 is "Clean Cliff Sensors" rather than "Stuck near a cliff", code 7 "Left wheel sensor issue" rather than "Left wheel error". Two caveats I'd rather state than gloss over: the source is the newer app, so whether those 48 mean exactly the same thing on the older robots is plausible but unverified; and the strings are iRobot's, so shipping them under MIT is your call. Entirely fine if the provenance is a non-starter.

Happy to start on whichever piece you'd like to see first, or to adjust the shape before any of it exists.