pyworxcloud

What it is and what it does

pyworxcloud is an async-first Python client for the Worx Cloud API (Positec Landroid), designed primarily for Home Assistant but usable in any async application. It handles authentication, device discovery, real-time status updates via MQTT, and remote control of cloud-enabled Worx lawn mowers from multiple vendors. The library abstracts away protocol differences between mower generations, exposing a unified interface for scheduling, automatic scheduling configuration, firmware updates, and device state monitoring.

The package uses aiohttp for async HTTP requests and paho-mqtt for real-time device communication, with configurable timeouts for both API and MQTT operations. It normalizes schedule data across protocol versions, supports CRUD operations on mowing schedules, and tracks detailed device state including battery, blade statistics, GPS, and rain-delay conditions. Recent versions emphasize fixture-driven testing and comprehensive data mapping to keep the API surface aligned with actual device capabilities.

Use it for:

• Integrate Worx lawn mower control into Home Assistant or other home automation platforms for remote scheduling and monitoring.
• Build a custom dashboard or mobile app that displays mower status, battery level, and location in real time via MQTT.
• Automate mowing schedules based on weather, soil conditions, or grass type using the automatic scheduling API.
• Monitor multiple Worx devices across different vendors from a single Python application with unified device discovery.
• Trigger mower commands (start, stop, return to dock) from external events or scripts using the async command interface.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Async Python client library for communicating with Worx Cloud lawn mowers via REST API and MQTT, supporting device control, scheduling, and status monitoring.

Yes. The package is actively maintained, has low install friction, carries no known vulnerabilities, and uses a permissive MIT license. It is well-suited for anyone needing to control Worx Cloud mowers programmatically. The async-first design and comprehensive device abstraction make it a solid choice for Home Assistant integration or custom automation. The main consideration is that it requires Python 3.9+ and mandatory async code, which is not a blocker for modern projects.

Install

pyworxcloud on PyPI

pip install pyworxcloud

uv add pyworxcloud

poetry add pyworxcloud

Installing pyworxcloud

Before you install

Low install friction with a pure-Python wheel and active maintenance. Last release 33 days ago; repository shows recent activity and is not archived. Five runtime dependencies (aiohttp, paho-mqtt, requests, tzdata, urllib3) are all widely used and stable.

License in practice

MIT license is permissive; you can use, modify, and distribute this package freely with minimal restrictions, making it suitable for both personal and commercial projects.

Quickstart

import asyncio
from pyworxcloud import WorxCloud

async def main():
    cloud = WorxCloud("user@example.com", "secret", "worx")
    await cloud.authenticate()
    await cloud.connect()
    for _, device in cloud.devices.items():
        print(device.name, device.online)
    await cloud.disconnect()

asyncio.run(main())

Requires Python 3.9 or later; async/await syntax is mandatory (no sync fallback for core operations).

Verify before relying

• Whether all cloud-enabled Worx vendors listed in the wiki are actively supported or if some have been deprecated.
• Performance characteristics when managing multiple devices or handling high-frequency MQTT updates.
• Whether automatic scheduling features work consistently across all supported mower protocols.

Package facts

Evidence: pyworxcloud-6.4.2-py3-none-any.whl

Tags

More Python Modules packages