iobroker.anthbot-genie 0.0.7 → 0.0.8

package/README.md

@@ -1,37 +1,155 @@
-# Anthbot Genie ioBroker Adapter
+# ioBroker.anthbot-genie
 
-Local scaffold for an unofficial Anthbot Genie ioBroker adapter.
+![Logo](admin/anthbot-genie.png)
+
+![Test and Release](https://github.com/reloxx13/ioBroker.anthbot-genie/workflows/Test%20and%20Release/badge.svg)
+![Automerge Dependabot](https://github.com/reloxx13/ioBroker.anthbot-genie/workflows/Automerge%20Dependabot/badge.svg)
+[![NPM version](https://img.shields.io/npm/v/iobroker.anthbot-genie.svg)](https://www.npmjs.com/package/iobroker.anthbot-genie)
+[![Downloads](https://img.shields.io/npm/dm/iobroker.anthbot-genie.svg)](https://www.npmjs.com/package/iobroker.anthbot-genie)
+![GitHub release](https://img.shields.io/github/v/release/reloxx13/ioBroker.anthbot-genie)
+![License](https://img.shields.io/github/license/reloxx13/ioBroker.anthbot-genie)
+![ioBroker phase](https://img.shields.io/badge/ioBroker%20phase-testing-yellow)
+[![ioBroker forum](https://img.shields.io/badge/ioBroker-forum-blue)](https://forum.iobroker.net/topic/84392/test-adapter-anthbot-genie-v0.0.x-npm-github)
 
-Current scope:
+[![NPM](https://nodei.co/npm/iobroker.anthbot-genie.png?downloads=true)](https://nodei.co/npm/iobroker.anthbot-genie/)
 
-- Anthbot cloud login
-- device discovery
-- region and IoT endpoint lookup
-- polling of mower property and service shadows
-- writable control states for the main mower commands
-- zone metadata and zone-start commands
+Unofficial ioBroker adapter for [Anthbot Genie robotic lawn mowers](https://de.anthbot.com/products/genie-mahroboter).
+
+The adapter connects to the Anthbot cloud account, discovers bound mowers, reads cloud and IoT shadow data, and exposes status, settings, mower commands, zone data, and raw diagnostic payloads in ioBroker.
+
+This adapter is currently in testing. Please report feedback and test results in the [ioBroker forum Test Adapter anthbot-genie v0.0.x npm/GitHub thread](https://forum.iobroker.net/topic/84392/test-adapter-anthbot-genie-v0.0.x-npm-github).
+
+An example ioBroker Blockly with conditions for mower automation is available in the [Blockly automation example](https://forum.iobroker.net/topic/84392/test-adapter-anthbot-genie-v0.0.x-npm-github/2?_=1777117406598).
 
-Exposed per mower:
+## Features
+
+- Anthbot cloud login with encrypted password storage in ioBroker native config
+- Automatic discovery of mowers bound to the configured Anthbot account
+- Region and IoT endpoint lookup per mower
+- Polling of property and service shadows
+- Status states for connection, online state, battery, mower status, charging state, mowing time, mowing area, rain handling, cutting height, and voice volume
+- Writable control states for cutting height, voice volume, custom mowing direction, and rain settings
+- Command states for full mowing, stop, return to dock, refresh, manual zone mowing, and automatic zone mowing
+- Manual and automatic zone metadata as JSON states
+- Raw property, service, and area payloads for troubleshooting
+
+## Requirements
+
+- ioBroker with js-controller `>= 6.0.11`
+- ioBroker admin `>= 7.6.20`
+- Node.js `>= 20`
+- Anthbot account with at least one bound Genie mower
+- Internet access from the ioBroker host to the Anthbot cloud and AWS IoT endpoint
 
-- `info.*`
-- `metrics.*`
-- `controls.*`
-- `commands.*`
-- `zones.*`
-- `raw.*`
+## Configuration
 
-## Manual zone mowing
+Open the adapter instance configuration in ioBroker Admin and set:
+
+| Setting | Description | Default |
+| --- | --- | --- |
+| Anthbot account username | Username or email address of the Anthbot account | empty |
+| Anthbot account password | Anthbot account password, stored encrypted by ioBroker | empty |
+| Area code | Phone or account area code, for example `49` for Germany | `49` |
+| API host | Anthbot cloud API host | `api.anthbot.com` |
+| Poll interval in seconds | Polling interval for mower data. The adapter enforces at least 10 seconds. | `30` |
+
+After saving the configuration, start or restart the adapter instance.
+
+## States
+
+The adapter creates one device tree per mower serial number:
+
+```text
+anthbot-genie.<instance>.<serial>.*
+```
+
+### Info
+
+| State | Type | Description |
+| --- | --- | --- |
+| `info.connection` | boolean | Global adapter cloud connection state |
+| `<serial>.info.alias` | string | Mower alias from Anthbot |
+| `<serial>.info.model` | string | Mower model/category |
+| `<serial>.info.region` | string | Anthbot/AWS IoT region |
+| `<serial>.info.endpoint` | string | IoT endpoint used for shadow access |
+| `<serial>.info.online` | boolean | Online state reported by the mower |
+| `<serial>.info.charging` | boolean | Whether the mower is currently charging |
+| `<serial>.info.lastServiceCommand` | string | Last reported service command |
+| `<serial>.info.lastPoll` | string | ISO timestamp of the last successful poll |
+
+### Metrics
+
+| State | Type | Unit | Description |
+| --- | --- | --- | --- |
+| `<serial>.metrics.batteryLevel` | number | `%` | Battery level |
+| `<serial>.metrics.mowerStatus` | string | | Normalized mower status |
+| `<serial>.metrics.robotStatusRaw` | string | | Raw robot status |
+| `<serial>.metrics.cuttingHeight` | number | `mm` | Current cutting height |
+| `<serial>.metrics.voiceVolume` | number | `%` | Current voice volume |
+| `<serial>.metrics.mowingTime` | number | `s` | Reported mowing time |
+| `<serial>.metrics.mowingArea` | number | `m2` | Reported mowing area |
+| `<serial>.metrics.customMowingDirection` | number | `deg` | Custom mowing direction |
+| `<serial>.metrics.customMowingDirectionEnabled` | boolean | | Custom mowing direction enabled |
+| `<serial>.metrics.rainPerceptionEnabled` | boolean | | Rain perception enabled |
+| `<serial>.metrics.rainContinueTime` | number | `s` | Delay before continuing after rain |
+
+### Controls
+
+Writable control states update mower settings through the Anthbot IoT service shadow.
+
+| State | Type | Range | Description |
+| --- | --- | --- | --- |
+| `<serial>.controls.mowHeight` | number | `30..70 mm`, 5 mm steps | Set cutting height |
+| `<serial>.controls.voiceVolume` | number | `0..100 %` | Set voice volume |
+| `<serial>.controls.customMowingDirection` | number | `0..180 deg` | Set custom mowing direction |
+| `<serial>.controls.customMowingDirectionEnabled` | boolean | `true`/`false` | Enable or disable custom mowing direction |
+| `<serial>.controls.rainPerceptionEnabled` | boolean | `true`/`false` | Enable or disable rain perception |
+| `<serial>.controls.rainContinueTimeHours` | number | `0..8 h` | Set rain continue time in hours |
+
+### Commands
+
+Command states are writable. Button states are reset to `false` after execution. Zone command states are reset to an empty string after execution.
+
+| State | Type | Description |
+| --- | --- | --- |
+| `<serial>.commands.startFullMow` | boolean | Start full mowing |
+| `<serial>.commands.stopMow` | boolean | Stop all mower tasks |
+| `<serial>.commands.returnToDock` | boolean | Return to the charging dock |
+| `<serial>.commands.requestRefresh` | boolean | Request all mower properties and refresh states |
+| `<serial>.commands.zoneMow` | string | Start mowing one or more manual zones |
+| `<serial>.commands.autoZoneMow` | string | Start mowing one or more automatic zones |
+
+### Zones
+
+| State | Type | Description |
+| --- | --- | --- |
+| `<serial>.zones.manual` | JSON string | Known manual/custom zones |
+| `<serial>.zones.auto` | JSON string | Known automatic/region zones |
+| `<serial>.zones.activeManualIds` | JSON string | Currently active manual zone IDs |
+
+### Raw data
+
+| State | Type | Description |
+| --- | --- | --- |
+| `<serial>.raw.property` | JSON string | Raw property shadow payload |
+| `<serial>.raw.service` | JSON string | Raw service shadow payload |
+| `<serial>.raw.areaDefinition` | JSON string | Raw area definition payload |
+
+## Zone Mowing
 
 The adapter exposes the mower's manual/custom zones in:
 
-- `<instance>.<serial>.zones.manual`
+```text
+<instance>.<serial>.zones.manual
+```
 
-This state contains a JSON array with the known manual zones. Use the `id` or
-the exact `name` from that list to start mowing.
+This state contains a JSON array with known zones. Use the `id` or the exact `name` from that list to start mowing.
 
 Write the selection to:
 
-- `<instance>.<serial>.commands.zoneMow`
+```text
+<instance>.<serial>.commands.zoneMow
+```
 
 Accepted values:
 
@@ -40,18 +158,60 @@ Accepted values:
 - multiple zones as comma-separated IDs or names: `3,5,Back yard`
 - multiple zones as a JSON array: `[3,5,"Back yard"]`
 
-After a valid write, the adapter sends `custom_area_mow_start` with the matched
-manual zone IDs and clears `commands.zoneMow` again.
+After a valid write, the adapter sends `custom_area_mow_start` with the matched manual zone IDs and clears `commands.zoneMow` again.
+
+Automatic zones work similarly through:
+
+```text
+<instance>.<serial>.zones.auto
+<instance>.<serial>.commands.autoZoneMow
+```
+
+For automatic zones, the adapter resolves the selected zone IDs or names to the zone coordinates and sends `region_mow_start`.
+
+## Troubleshooting
+
+### Adapter does not connect
+
+- Check username, password, and area code.
+- Confirm that the mower is visible in the Anthbot app with the same account.
+- Increase the adapter log level to `debug` and restart the instance.
+- Check `anthbot-genie.<instance>.info.connection`.
 
-Notes:
+### No mower objects are created
 
-- this is based on the public Home Assistant integration logic from `vincentjanv/anthbot_genie_ha`
-- this project is unofficial and not affiliated with or endorsed by Anthbot; see `NOTICE.md`
-- it is a local first version, not a published ioBroker adapter yet
-- the password is stored in encrypted native config
+- The Anthbot account must have at least one bound mower.
+- Check the adapter log for `No Anthbot devices found for this account`.
+- Verify that the ioBroker host has internet access.
+
+### Commands do not work
+
+- Check whether status polling works first.
+- Verify that the target state is under the correct mower serial number.
+- For zone commands, compare the written value with the IDs and names in `zones.manual` or `zones.auto`.
+- Check `raw.service` and the adapter log for command errors.
+
+## Legal Notice
+
+This project is unofficial and is not affiliated with, endorsed by, sponsored by, or approved by Anthbot.
+
+Anthbot and Genie names, marks, and logos belong to their respective owners. See [NOTICE.md](NOTICE.md) for details.
+
+## Credits
+
+Special credit to the Home Assistant Anthbot Genie project, which made the Anthbot cloud flow and command mapping much easier to understand:
+
+- `vincentjanv/anthbot_genie_ha`
+- <https://github.com/vincentjanv/anthbot_genie_ha>
+
+This ioBroker adapter is an independent project, but it builds on public API research and implementation ideas from that Home Assistant integration.
 
 ## Changelog
 
+### 0.0.8
+
+- Add consumable channels and values ​​to the adapter definition.
+
 ### 0.0.7
 
 - Add Dependabot automerge configuration.
@@ -82,20 +242,10 @@ Notes:
 
 - Initial local adapter scaffold for Anthbot Genie.
 
-## Credits
-
-Special credit to the Home Assistant Anthbot Genie project that made the
-cloud flow and command mapping much easier to understand:
-
-- `vincentjanv/anthbot_genie_ha`
-- https://github.com/vincentjanv/anthbot_genie_ha
-
-This ioBroker adapter scaffold is an independent local project, but it
-directly builds on the public API research and implementation approach from
-that Home Assistant integration.
-
 ## License
 
+MIT License
+
 Copyright (c) 2026 reloxx13
 
-MIT License. See [LICENSE](LICENSE) for details.
+See [LICENSE](LICENSE) for details.

package/io-package.json

@@ -1,8 +1,21 @@
 {
   "common": {
     "name": "anthbot-genie",
-    "version": "0.0.7",
+    "version": "0.0.8",
     "news": {
+      "0.0.8":{
+        "en": "Add consumable channels and values to the adapter definition.",
+        "de": "Verbrauchskanäle und Werte zur Adapterdefinition hinzugefügt.",
+        "ru": "Добавлены каналы потребляемых материалов и значения в определение адаптера.",
+        "pt": "Adicionar canais de consumíveis e valores à definição do adaptador.",
+        "nl": "Consumable-kanalen en waarden toegevoegd aan de adapterdefinitie.",
+        "fr": "Ajouter des canaux de consommables et des valeurs à la définition de l'adaptateur.",
+        "it": "Aggiungi canali di consumo e valori alla definizione dell'adattatore.",
+        "es": "Agregar canales de consumibles y valores a la definición del adaptador.",
+        "pl": "Dodaj kanały materiałów eksploatacyjnych i wartości do definicji adaptera.",
+        "uk": "Додайте канали расходных материалов и значения в определение адаптера.",
+        "zh-cn": "将消耗品通道和值添加到适配器定义中。"
+      },
       "0.0.7": {
         "en": "Add Dependabot automerge configuration and update repository metadata.",
         "de": "Dependabot-Automerge-Konfiguration hinzugefügt und Repository-Metadaten aktualisiert.",

package/main.js

@@ -228,6 +228,7 @@ class AnthbotGenieAdapter extends utils.Adapter {
         const definitions = [
             ["info", "channel", t("Info", "Informationen"), null],
             ["metrics", "channel", t("Metrics", "Messwerte"), null],
+            ["consumable", "channel", t("Consumable", "Verbrauchsmaterial"), null],
             ["controls", "channel", t("Controls", "Steuerung"), null],
             ["commands", "channel", t("Commands", "Befehle"), null],
             ["zones", "channel", t("Zones", "Zonen"), null],
@@ -251,6 +252,9 @@ class AnthbotGenieAdapter extends utils.Adapter {
             "info.charging": { type: "boolean", role: "indicator.working", read: true, write: false, name: t("Charging", "Lädt") },
             "info.lastServiceCommand": { type: "string", role: "text", read: true, write: false, name: t("Last service command", "Letzter Servicebefehl") },
             "info.lastPoll": { type: "string", role: "date", read: true, write: false, name: t("Last poll", "Letzte Abfrage") },
+            "consumable.station": { type: "number", role: "value.usage.station", unit: "%", read: true, write: false, name: t("Station lifetime", "Station Lebensdauer") },
+            "consumable.cameras": { type: "number", role: "value.usage.cameras", unit: "%", read: true, write: false, name: t("Cameras lifetime", "Kameras Lebensdauer") },
+            "consumable.blades": { type: "number", role: "value.usage.blades", unit: "%", read: true, write: false, name: t("Blades lifetime", "Klingen Lebensdauer") },
             "metrics.batteryLevel": { type: "number", role: "value.battery", unit: "%", read: true, write: false, name: t("Battery level", "Akkustand") },
             "metrics.mowerStatus": { type: "string", role: "value", read: true, write: false, name: t("Mower status", "Mäherstatus") },
             "metrics.robotStatusRaw": { type: "string", role: "text", read: true, write: false, name: t("Raw robot status", "Rohstatus des Roboters") },
@@ -353,6 +357,12 @@ class AnthbotGenieAdapter extends utils.Adapter {
             "info.charging": isCharging(data),
             "info.lastServiceCommand": serviceCommand,
             "info.lastPoll": new Date().toISOString(),
+
+            // 2026-04-26: The cloud API misspells "percent" as "pecent" in the robot_maintenance object, so we need to use the wrong spelling here to get the data until it's fixed upstream.
+            "consumable.station": typeof data.robot_maintenance?.ccp_pecent === "number" ? data.robot_maintenance.ccp_pecent : null,
+            "consumable.cameras": typeof data.robot_maintenance?.cl_pecent === "number" ? data.robot_maintenance.cl_pecent : null,
+            "consumable.blades": typeof data.robot_maintenance?.rc_pecent === "number" ? data.robot_maintenance.rc_pecent : null,
+
             "metrics.batteryLevel": typeof data.elec === "number" ? data.elec : null,
             "metrics.mowerStatus": generalMowerStatus(data),
             "metrics.robotStatusRaw": rawRobotStatus(data) || "",
@@ -364,15 +374,18 @@ class AnthbotGenieAdapter extends utils.Adapter {
             "metrics.customMowingDirectionEnabled": isCustomDirectionEnabled(data),
             "metrics.rainPerceptionEnabled": rainPerceptionEnabled,
             "metrics.rainContinueTime": rainContinueTime,
+
             "controls.mowHeight": cutterHeight,
             "controls.voiceVolume": typeof data.volume === "number" ? data.volume : null,
             "controls.customMowingDirection": customDirection,
             "controls.customMowingDirectionEnabled": isCustomDirectionEnabled(data),
             "controls.rainPerceptionEnabled": rainPerceptionEnabled,
             "controls.rainContinueTimeHours": typeof rainContinueTime === "number" ? Math.round(rainContinueTime / 3600) : null,
+
             "zones.manual": JSON.stringify(compactZonePayload(manualZoneList)),
             "zones.auto": JSON.stringify(compactZonePayload(autoZoneList)),
             "zones.activeManualIds": JSON.stringify(activeManualZoneIds(data)),
+
             "raw.property": JSON.stringify(context.lastReported || {}),
             "raw.service": JSON.stringify(context.lastService || {}),
             "raw.areaDefinition": JSON.stringify(context.areaDefinition || {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iobroker.anthbot-genie",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Unofficial ioBroker adapter for Anthbot Genie mowers",
   "author": "reloxx13",
   "license": "MIT",