pygrouw 0.1.1__tar.gz

pygrouw-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesper B
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pygrouw-0.1.1/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include reverse_engineered *.md

pygrouw-0.1.1/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: pygrouw
+Version: 0.1.1
+Summary: Python BLE library for Grouw robotic mowers using the Daye Power protocol
+Author: Jesper B
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Bjorkan/pyGrouw
+Project-URL: Issues, https://github.com/Bjorkan/pyGrouw/issues
+Keywords: bluetooth,ble,grouw,mower,home-assistant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak>=0.21.1
+Requires-Dist: bleak-retry-connector>=3.6.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# pyGrouw
+
+Python library for local Bluetooth Low Energy communication with Grouw robotic
+mowers that use the Daye Power app protocol (`com.dayepower.dayeappleaf`).
+
+This package contains the device/protocol code intended to be used by Home
+Assistant integrations and other Python applications. It has no Home Assistant
+runtime dependency.
+
+## Status
+
+The library currently targets the DYM-era Grouw mower generation observed in
+the Daye Power APK and redacted real-hardware captures.
+
+Durable protocol and reverse-engineering notes live in
+[reverse_engineered/index.md](reverse_engineered/index.md).
+
+Supported protocol helpers:
+
+- DYM status, start/resume, pause/stop, dock, session start, and auth query
+  payload encoding.
+- DYM status and auth/PIN notification parsing.
+- APK-shaped BlueKey debug payload encoding and parsing helpers for protocol
+  research.
+- Optional BLE discovery helpers that match the Home Assistant integration's
+  supported name/service UUID filters.
+- Serialized BLE request flow using `bleak` and `bleak-retry-connector`.
+
+Not yet supported:
+
+- Cloud or Wi-Fi control.
+- Settings writes for rain, schedules, multi-area, PIN change, or firmware
+  update.
+
+## Installation For Development
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python3 -m pip install -e ".[test]"
+pytest -q
+```
+
+## Usage
+
+Applications should resolve a connectable BLE device themselves, then pass it
+to the client. Home Assistant integrations should use Home Assistant's
+Bluetooth manager and inject the resolved device.
+
+```python
+from pygrouw import GrouwBleMower, GrouwBleMowerClient
+
+client = GrouwBleMowerClient(
+    address="AA:BB:CC:DD:EE:FF",
+    name="Robot Mower_DYM",
+    pin="1234",
+    device_provider=lambda: ble_device,
+)
+mower = GrouwMower(client)
+
+state = await mower.async_update()
+await mower.async_start()
+```
+
+`device_provider` may be synchronous or asynchronous. It must return a
+connectable `bleak.backends.device.BLEDevice` or `None`.
+
+For standalone scripts, the library also exposes optional discovery helpers:
+
+```python
+from pygrouw import GrouwBleMower, GrouwBleMowerClient, discover_devices
+
+devices = await discover_devices(timeout=5)
+client = await GrouwBleMowerClient.from_discovery(
+    address=devices[0].address,
+    pin="1234",
+)
+mower = GrouwMower(client)
+
+state = await mower.async_update()
+```
+
+Home Assistant integrations should still prefer Home Assistant's Bluetooth
+manager over calling these scanning helpers from inside Home Assistant.
+
+## Home Assistant Development
+
+When testing an unpublished editable library inside Home Assistant:
+
+```bash
+pip3 install -e ../pyGrouw
+hass --skip-pip-packages pygrouw
+```
+
+That follows Home Assistant's guidance for standalone API/protocol libraries:
+protocol-specific code lives outside the integration and package releases are
+eventually published to PyPI from tagged source releases.
+
+## Release Publishing
+
+GitHub Actions runs tests for pull requests and pushes to `main`. Published
+GitHub releases also run the full test/build/check flow before uploading to
+PyPI.
+
+PyPI publishing is configured for Trusted Publishing. On PyPI, create a
+Trusted Publisher for this project with:
+
+- Repository owner: `Bjorkan`
+- Repository name: `pyGrouw`
+- Workflow name: `publish.yml`
+- Environment name: `pypi`
+
+If `pygrouw` does not exist on PyPI yet, create a pending publisher from your
+PyPI account sidebar under **Publishing**. If the project already exists, open
+the project on PyPI, go to **Manage project** -> **Publishing**, and add the
+GitHub Actions publisher there.
+
+Before publishing a release, update `version` in `pyproject.toml`, merge to
+`main`, create a matching tag, and publish a GitHub Release from that tag. The
+publish workflow requires the release tag to match the package version, with or
+without a `v` prefix. For version `0.1.0`, both `0.1.0` and `v0.1.0` are valid.
+
+## Dependency Updates
+
+Renovate is configured in `renovate.json`. The GitHub workflow runs Renovate
+at `00:00` UTC, and can also be started manually from the Actions tab.
+
+Add a repository secret named `RENOVATE_TOKEN` with permission to create
+branches and pull requests. Do not use the default `GITHUB_TOKEN` for Renovate:
+pull requests created with it do not reliably trigger the normal PR checks.

pygrouw-0.1.1/README.md

@@ -0,0 +1,130 @@
+# pyGrouw
+
+Python library for local Bluetooth Low Energy communication with Grouw robotic
+mowers that use the Daye Power app protocol (`com.dayepower.dayeappleaf`).
+
+This package contains the device/protocol code intended to be used by Home
+Assistant integrations and other Python applications. It has no Home Assistant
+runtime dependency.
+
+## Status
+
+The library currently targets the DYM-era Grouw mower generation observed in
+the Daye Power APK and redacted real-hardware captures.
+
+Durable protocol and reverse-engineering notes live in
+[reverse_engineered/index.md](reverse_engineered/index.md).
+
+Supported protocol helpers:
+
+- DYM status, start/resume, pause/stop, dock, session start, and auth query
+  payload encoding.
+- DYM status and auth/PIN notification parsing.
+- APK-shaped BlueKey debug payload encoding and parsing helpers for protocol
+  research.
+- Optional BLE discovery helpers that match the Home Assistant integration's
+  supported name/service UUID filters.
+- Serialized BLE request flow using `bleak` and `bleak-retry-connector`.
+
+Not yet supported:
+
+- Cloud or Wi-Fi control.
+- Settings writes for rain, schedules, multi-area, PIN change, or firmware
+  update.
+
+## Installation For Development
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python3 -m pip install -e ".[test]"
+pytest -q
+```
+
+## Usage
+
+Applications should resolve a connectable BLE device themselves, then pass it
+to the client. Home Assistant integrations should use Home Assistant's
+Bluetooth manager and inject the resolved device.
+
+```python
+from pygrouw import GrouwBleMower, GrouwBleMowerClient
+
+client = GrouwBleMowerClient(
+    address="AA:BB:CC:DD:EE:FF",
+    name="Robot Mower_DYM",
+    pin="1234",
+    device_provider=lambda: ble_device,
+)
+mower = GrouwMower(client)
+
+state = await mower.async_update()
+await mower.async_start()
+```
+
+`device_provider` may be synchronous or asynchronous. It must return a
+connectable `bleak.backends.device.BLEDevice` or `None`.
+
+For standalone scripts, the library also exposes optional discovery helpers:
+
+```python
+from pygrouw import GrouwBleMower, GrouwBleMowerClient, discover_devices
+
+devices = await discover_devices(timeout=5)
+client = await GrouwBleMowerClient.from_discovery(
+    address=devices[0].address,
+    pin="1234",
+)
+mower = GrouwMower(client)
+
+state = await mower.async_update()
+```
+
+Home Assistant integrations should still prefer Home Assistant's Bluetooth
+manager over calling these scanning helpers from inside Home Assistant.
+
+## Home Assistant Development
+
+When testing an unpublished editable library inside Home Assistant:
+
+```bash
+pip3 install -e ../pyGrouw
+hass --skip-pip-packages pygrouw
+```
+
+That follows Home Assistant's guidance for standalone API/protocol libraries:
+protocol-specific code lives outside the integration and package releases are
+eventually published to PyPI from tagged source releases.
+
+## Release Publishing
+
+GitHub Actions runs tests for pull requests and pushes to `main`. Published
+GitHub releases also run the full test/build/check flow before uploading to
+PyPI.
+
+PyPI publishing is configured for Trusted Publishing. On PyPI, create a
+Trusted Publisher for this project with:
+
+- Repository owner: `Bjorkan`
+- Repository name: `pyGrouw`
+- Workflow name: `publish.yml`
+- Environment name: `pypi`
+
+If `pygrouw` does not exist on PyPI yet, create a pending publisher from your
+PyPI account sidebar under **Publishing**. If the project already exists, open
+the project on PyPI, go to **Manage project** -> **Publishing**, and add the
+GitHub Actions publisher there.
+
+Before publishing a release, update `version` in `pyproject.toml`, merge to
+`main`, create a matching tag, and publish a GitHub Release from that tag. The
+publish workflow requires the release tag to match the package version, with or
+without a `v` prefix. For version `0.1.0`, both `0.1.0` and `v0.1.0` are valid.
+
+## Dependency Updates
+
+Renovate is configured in `renovate.json`. The GitHub workflow runs Renovate
+at `00:00` UTC, and can also be started manually from the Actions tab.
+
+Add a repository secret named `RENOVATE_TOKEN` with permission to create
+branches and pull requests. Do not use the default `GITHUB_TOKEN` for Renovate:
+pull requests created with it do not reliably trigger the normal PR checks.

pygrouw-0.1.1/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pygrouw"
+version = "0.1.1"
+description = "Python BLE library for Grouw robotic mowers using the Daye Power protocol"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Jesper B" }]
+keywords = ["bluetooth", "ble", "grouw", "mower", "home-assistant"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+]
+dependencies = [
+    "bleak>=0.21.1",
+    "bleak-retry-connector>=3.6.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Bjorkan/pyGrouw"
+Issues = "https://github.com/Bjorkan/pyGrouw/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pygrouw = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

pygrouw-0.1.1/reverse_engineered/app_identity.md

@@ -0,0 +1,80 @@
+# App Identity And BLE Discovery
+
+Last updated: 2026-06-26.
+
+## Daye APK Identity
+
+```text
+Package:      com.dayepower.dayeappleaf
+Version:      2.0.1
+Version code: 117
+Flutter app:  romow_bluetooth
+BLE library:  flutter_blue_plus
+```
+
+BLE names found in the APK:
+
+```text
+Robot Mower_DYM
+RobotMower_DYM
+Robot_Mower-
+```
+
+The app contains UI/routes for Bluetooth connection, mower control, mower
+status, mower settings, firmware update, working-time settings, multi-area
+mowing, rain mowing, rain delay, ultrasound, back-to-station, and go-to-work.
+
+## UUIDs Found In The App
+
+```text
+49535343-1E4D-4BD9-BA61-23C647249616
+49535343-fe7d-4ae5-8fa9-9fafd205e455
+00002902-0000-1000-8000-00805f9b34fb
+```
+
+`00002902-0000-1000-8000-00805f9b34fb` is the standard Client
+Characteristic Configuration descriptor.
+
+## FlutterBluePlus Signals
+
+Strings found in the APK include:
+
+```text
+service_uuid
+characteristic_uuid
+writeAndNotify
+writeAll
+writeFinalChunk
+allow_long_write
+blueWriteAndNotification
+BmWriteCharacteristicRequest
+BmSetNotifyValueRequest
+OnDiscoveredServices
+OnCharacteristicReceived
+OnCharacteristicWritten
+```
+
+## Home Assistant Discovery Impact
+
+The integration should match:
+
+```text
+Service UUID: 49535343-fe7d-4ae5-8fa9-9fafd205e455
+Local names:  Robot Mower_DYM*, RobotMower_DYM*, Robot_Mower*
+```
+
+The integration uses characteristic
+`49535343-1E4D-4BD9-BA61-23C647249616` for write and notify.
+
+## Manual Corroboration
+
+The Grouw 17941/17947 manual says users should select `RobotMower_DYM` from the
+Bluetooth device list in the app and enter the mower PIN. This supports the
+current discovery aliases.
+
+The Grouw 18739/18740 CLEVR manual describes a different IoT generation:
+`robotic-mower connect`, 2.4 GHz Wi-Fi, Bluetooth 4.0, manual pairing as
+`Mower_XXXXXX`, and factory PIN `0000`.
+
+Do not add `Mower_XXXXXX` discovery to this DYM integration without separate
+hardware captures for that generation.

pygrouw-0.1.1/reverse_engineered/ble_write_flow.md

@@ -0,0 +1,156 @@
+# BLE Write And Notification Flow
+
+Last updated: 2026-06-26.
+
+Findings from `MainLogic::writeAndNotify` (`0x461eb4`),
+`MainLogic::blueWriteAndNotification` (`0x461fa4`), and related Daye app
+classes.
+
+## Connection Sequence
+
+When the Daye app sees `BluetoothDevice.connectionState == connected`,
+`MainLogic` awaits `BluetoothDevice::requestMtu` before showing the success
+toast and calling `discoverServices`.
+
+The bundled FlutterBluePlus implementation requests MTU 512 with a 15-second
+timeout.
+
+## Write/Notify Sequence
+
+1. `Helper::writeAndNotify` resolves `MainLogic` through GetIt and forwards
+   the payload, callback, and optional flags.
+2. `MainLogic::writeAndNotify` checks the connection-type sentinel.
+3. `MainLogic::blueWriteAndNotification` cancels the existing `resultListen`
+   subscription.
+4. It subscribes to `onValueReceived` on the write characteristic.
+5. It writes the command bytes with `BluetoothCharacteristic::write`.
+6. On notification, it calls `Helper::parseBlueResult`.
+7. The parsed one-based byte map is passed to the callback closure.
+
+`Helper::writeAndNotify` signature:
+
+```text
+writeAndNotify(payload, callback, {
+  canBack,
+  errorTip,
+  noLimitNotify,
+  notifyType,
+  showTip,
+})
+```
+
+## `notifyType`
+
+When `notifyType` is supplied, `blueWriteAndNotification` formats received byte
+index 3, the fourth byte, as a padded hex string and compares it to
+`notifyType` before invoking the callback.
+
+This byte index is the same position as the DYM response command byte.
+
+Observed `BlueKey::queryInfo` call sites:
+
+```text
+MowerStatusLogic::changeWorkType
+  Helper.writeAndNotify(BlueKey.queryInfo, callback,
+                        canBack: true, showTip: false)
+  No notifyType filter. Callback reads byte13 for work-mode display.
+
+DeviceLogic::initDeviceInfo
+  Helper.writeAndNotify(BlueKey.queryInfo, callback,
+                        notifyType: "0x80", errorTip: "Get info error")
+  Callback reads byte5 battery and byte9-byte15 device/version fields.
+```
+
+This supports that app-side query/info handling can wait for response command
+`0x80`, but does not prove that all DYM and BlueKey response fields share the
+same semantics.
+
+## State Classes
+
+### MainState
+
+```text
+0x08  connectType
+0x0c  area
+0x10  robotPin
+0x14  type
+0x18  deviceName
+0x1c  deviceAddress
+0x20  loading
+0x24  startTime
+0x28  isOpenAuto
+0x2c  haveBlueControll
+```
+
+### MowerStatusState
+
+```text
+0x08  disConnect
+0x0c  workType
+0x10  mowerControl
+0x14  timer
+```
+
+### DeviceState
+
+```text
+0x08  connectType
+0x0c  currentIndex
+0x10  pageController
+0x14  deviceInfo
+0x18  batteryImage
+0x1c  timer
+```
+
+### ChangePinState
+
+```text
+0x08  oldPin
+0x0c  newPin
+0x10  reNewPin
+```
+
+### MowerSettingState
+
+```text
+0x08  hour
+0x0c  min
+0x10  mowInTheRain
+0x14  boundaryCut
+0x18  ultrasound
+0x1c  helixSet
+0x20  led
+0x24  timer
+0x28  requestTimer
+```
+
+### MultiAreaMowingState
+
+```text
+0x08  area2Per
+0x0c  area2Dis
+0x10  area3Per
+0x14  area3Dis
+0x18  timer
+0x1c  requestTimer
+```
+
+### WorkingTimeSettingState
+
+```text
+0x08  data
+0x0c  type
+0x10  day
+0x14  startHour
+0x18  startMinute
+0x1c  workHour
+0x20  workMinute
+0x24  workMinuteList
+0x28  startHourController
+0x2c  startMinuteController
+0x30  workHourController
+0x34  workMinuteController
+0x38  dayController
+0x3c  timer
+0x40  requestTimer
+```