pyWorxCloud

This is a PyPI module for communicating with Worx Cloud mowers, primarily developed for use with Home Assistant, but I try to keep it as widely usable as possible.

The module are compatible with cloud enabled devices from these vendors

Documentation

The documentation have been moved to the Wiki
Additional project docs:

• Migration Guide
• Changelog

Testing

Run tests locally with:

python -m pip install -e . pytest
bash scripts/prepare_test_fixtures.sh
pytest -q

The fixture prepare script copies JSON sample files from code-ref/data-samples to tests/fixtures/data-samples when available.

Sample validation

Run python scripts/verify_data_samples.py (or rely on tests/test_data_samples.py) to ensure every code-ref/data-samples fixture contains the minimal payload/cfg/dat structure (id, conn, and uuid/mac). This keeps the fixtures aligned with DeviceHandler/EventHandler expectations even as you add new samples.

You can also run python scripts/dump_mapping.py to print the decoded snapshot for each fixture (status, schedules, rain delay, module data, etc.) so you can visually compare the raw JSON against the values DeviceHandler exposes. The script now scans both http.json and mqtt.json fixtures (including multi-document MQTT exports) so you can inspect how either transport influences the decoded output.

Data mapping

DeviceHandler now keeps the raw cfg/dat dictionaries alongside the richer surface model that mirrors what is described in code-ref. Highlights include:

• schedules["slots"] retains every slot that was present in sc.slots or sc.d, so protocol 1 devices with more end-of-day runs can be inspected.

• slot-first schedule generation that captures each configured run (legacy d arrays and protocol 1 slots) along with calculated end times, party-mode awareness, and time-extension handling.

• complete rain-delay state tracking (raw counter, active flag, remaining minutes) plus module status/configuration (ACS, Off Limits shortcuts, etc.).

• real-time updates of lock state, battery/blade statistics, orientation, GPS hooks, and module-specific metadata so MQTT and API consumers stay synchronized.

The fixture-driven tests/test_device_decode.py now asserts that the raw payloads, module data, and rain delay flags survive the round-trip, making regressions obvious as the refactor continues.

Networking helpers

pyworxcloud.utils.requests now builds a shared requests.Session configured with an HTTPAdapter/Retry pair targeting 429, 500, 502, 503 and 504 so every API call benefits from exponential retries without duplicating session setup. Use the exported create_session() when you need to decorate or instrument this session (see scripts/session_trace.py), while the default GET/POST helpers continue working without additional configuration.

Command timeout configuration

WorxCloud accepts a command_timeout argument (seconds) that controls how long MQTT command calls wait for a matching mower response before raising TimeoutException.

from pyworxcloud import WorxCloud

cloud = WorxCloud("user@example.com", "secret", "worx", command_timeout=15.0)