feat: introduce an adhoc connection mode

[wooshcz]

The intent of this PR is to make a proposal to rethink the current "periodic" connection mode, I do not expect this PR to be merged in the current state, I mostly want to start a discussion here. I'm aware that my implementation is not really backwards compatible with regards to folks that rely on the current periodic connection behavior.

I feel like the current "periodic" mode behaves like continuous with added retry mechanism in a loop, so this PR re-purposes and renames the "periodic" connection mode into a "temporary" connection mode which will close the connection to Roomba after the configurable "delay" timeout expires.

The motivation for this is to be able to use the Home Assistant's Roomba component to control the robot while de-prioritising the sensor updates. Their states will get updated as long as the current MQTT connection is kept open.

This was tested locally and works as expected with Roomba 690 model and Home Assistant 2026.7.2. This particular Roomba model has a quirk where as long as there is an active MQTT connection, all lights on the robot remain on (I'm not sure if this behavior is present on other models). This is something I wanted to fix and the effort ended up as this PR.

Do you feel like this could be somehow incorporated into this library? Obviously I'm open to any suggestions.

[wooshcz]

Hey @pschmitt : any thoughts about this one? 😊

[pschmitt]

Thanks for the proposal.

I’d prefer this to be implemented as an additional connection mode rather than repurposing the existing "periodic" mode, since changing its behavior might break existing configs.

This might also be a good opportunity to replace the "continuous" boolean with an explicit connection mode, for example "continuous", "periodic", and "temporary", while keeping the current API working for backwards compatibility.

[wooshcz]

This might also be a good opportunity to replace the "continuous" boolean with an explicit connection mode, for example "continuous", "periodic", and "temporary", while keeping the current API working for backwards compatibility.

Thanks, that sounds completely reasonable to me. I'm happy to give this a go and I can update the PR over the coming days.

How would we go about releasing this in sync with HA component release? Also I assume we would have to somehow migrate folks from the current boolean parameter into the new enum after they upgrade to the new version of roombapy. Is that something that's handled on the level of the HA component or does the lib need to handle both and remain backwards compatible forever? Nevermind, it's in the docs. The config entry of the component can be migrated.

[Copilot]

Pull request overview

This PR proposes a new connection-mode model for Roombapy by replacing the existing boolean continuous flag with a string-based mode, and introducing an “adhoc/temporary” connection behavior intended to reduce persistent MQTT connections (e.g., to avoid keeping lights on) while still allowing periodic sensor updates.

Changes:

• Replaces continuous: bool with mode: str in Roomba/RoombaFactory, and adjusts connection logic accordingly.
• Adds an adhoc connection handler thread to periodically connect/disconnect.
• Adds “ensure connected before publish” logic in send_command() and set_preference().

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
roombapy/roomba.py	Introduces mode-based connection logic, adds adhoc connection handler, and updates publish paths to connect on demand.
roombapy/roomba_factory.py	Updates factory API to pass mode into Roomba construction instead of continuous.

Comments suppressed due to low confidence (3)

roombapy/roomba.py:200

• _init_adhoc_handler() can still start new adhoc reconnect/disconnect cycles after a manual disconnect() because it only checks conn_mode. If stop_connection is meant to represent a user-requested shutdown, gate adhoc handler startup on it to avoid reconnecting after disconnect().

        if self.conn_mode != "adhoc":
            return

roombapy/roomba.py:327

• Same issue as send_command(): using roomba_connected here can trigger repeated reconnect attempts because the flag is only updated asynchronously. Check the MQTT client connection state instead before trying to connect.

        # Make sure we're connected before publishing
        if not self.roomba_connected:
            self._connect()

roombapy/roomba.py:245

• In adhoc mode, unexpected disconnects (error is not None) return before _init_adhoc_handler() runs, so the adhoc reconnect cycle won’t restart after an error. Consider calling _init_adhoc_handler() before returning from the error branch (it’s a no-op for non-adhoc modes).

        self.log.info(
            "Disconnected from Roomba %s", self.remote_client.address
        )
        self._init_adhoc_handler()

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[wooshcz]

@pschmitt : I think the PR should now be ready for a review. The existing connection modes should be working and are unchanged.

The last remaining outstanding issue which will probably show up in CI as well is:

PLR0913 Too many arguments in function definition (6 > 5)
  --> roombapy/roomba_factory.py:12:9
   |
11 |     @staticmethod
12 |     def create_roomba(
   |         ^^^^^^^^^^^^^
13 |         address: str,
14 |         blid: str,
   |

Would you like me to suppress the rule on this line?