docs: document known intermittent cloud telemetry gaps

Author: Maksym Shtembuliak

CHANGELOG.md

@@ -183,13 +183,24 @@ the GitHub release body should be rendered from the matching version section her
 
 ### Docs
 
+- Documented the unresolved intermittent cloud-telemetry issue in both READMEs,
+  including how to distinguish it from intentional HA-only operation and what
+  evidence to collect during an outage.
 - Added safe instructions for manually testing the unreleased `main` branch
   without creating a tag or GitHub release.
 - Updated device-learning and proxy-capture guides for the current menu names,
   trust boundaries, and recovery behavior.
 - Added a Kevolt / Deye-compatible advanced-controls guide covering explicit
   opt-in, read-back guarantees, and deliberately excluded service operations.
 
+### Known issues
+
+- Intermittent vendor-cloud telemetry gaps remain under investigation on some
+  **Cloud + Home Assistant** setups, even while local readings continue. The
+  fixes above do not establish that these gaps are resolved; see the
+  [README guidance](https://github.com/groove-max/ha-eybond-local/blob/main/README.md#known-cloud-telemetry-issue) and
+  [issue #13](https://github.com/groove-max/ha-eybond-local/issues/13).
+
 ## [0.3.0-beta.4] - 2026-08-25
 
 ### Added

README.md

@@ -22,6 +22,8 @@ It reads live inverter data over your local network. On supported models it can
 
 > **Note:** The integration is actively developed. Some inverters work fully, some work in read-only mode, and some need a Support Archive before support can be added.
 
+> **Known issue:** On some setups, vendor-cloud updates can pause while Home Assistant readings continue. This is under investigation; see [Known cloud telemetry issue](#known-cloud-telemetry-issue).
+
 ---
 
 ## Is this integration for my inverter?
@@ -50,9 +52,9 @@ cloud. See the full, always-current list in the
   owned runtime connection.
 - Reads inverter, battery, PV, load, and grid data locally.
 - Creates normal Home Assistant sensors, numbers, selects, switches, and buttons.
-- Keeps the vendor app working alongside Home Assistant by default, or lets you
-  point a collector at Home Assistant only — a reversible, explicit action that
-  is never done silently.
+- Keeps the collector's vendor-cloud endpoint by default for use alongside Home
+  Assistant, or lets you point it at Home Assistant only — a reversible, explicit
+  action that is never done silently.
 - Lets you choose control access:
   - **Read-only** — monitoring only.
   - **Auto** — enable verified controls when the device match is confident.
@@ -315,13 +317,35 @@ Use these issue templates:
 | Manual setup cannot verify the collector | Keep the setup flow open and retry with the collector reachable. For an inbound collector, enable background discovery and continue when its identified session appears. |
 | Only the collector device appears | Runtime detection has not identified the inverter yet. Check **Poll Context** and follow [Runtime Detection and Entities](docs/user/RUNTIME_AND_INVERTER.md); create a Support Archive if no driver binds. |
 | Sensors stay unavailable | Check that the collector and Home Assistant are on the same network and that the collector has stable Wi-Fi. |
-| Vendor app stopped showing live data | If you pointed the collector at Home Assistant only, that disconnects it from its cloud by design. Use **Restore previous collector endpoint** to bring the vendor app back. |
+| Vendor app stopped showing live data | Check the connection profile: **Home Assistant only** intentionally disconnects the cloud. If you still use **Cloud + Home Assistant**, see the [known cloud telemetry issue](#known-cloud-telemetry-issue) below. |
 | Vendor app works, but Home Assistant says unavailable | The collector may have reconnected to its cloud faster than it reconnected locally. Wait a few minutes and check Wi-Fi stability. |
 | A setting changes back immediately | The inverter rejected the value or did not confirm it. Check diagnostics, avoid changing the same setting from the vendor app at the same time, and retry after the collector is stable. |
 | Remote setup is needed | Use [Remote / NAT setup guide](docs/user/REMOTE_SETUP.md). Prefer VPN over public port forwarding when possible. |
 | Controls are missing | Keep **Auto** mode for normal use. If monitoring works but controls are missing, run device learning if offered, or create a Support Archive. Use **Full Control** only if you understand the risk. |
 | An unconfigured collector connects later | Enable the persistent **EyeBond Local — Discovery** entry. It publishes identified, unconfigured collector sessions without creating a placeholder device. |
 
+### Known cloud telemetry issue
+
+Some users report that, in **Cloud + Home Assistant**, the vendor app stops
+updating or shows the collector offline while local Home Assistant readings
+continue. Cloud updates may return on their own. This is a known issue under
+investigation; we have not yet confirmed its cause or a general fix.
+
+This is different from **Home Assistant only**, where cloud disconnection is
+intentional. Neither a longer polling interval nor a restart is a confirmed
+general fix for the intermittent problem.
+
+If it happens, create a [Support Archive](docs/user/SUPPORT_ARCHIVE.md) during
+the outage, before restarting or switching modes if possible. Add it to
+[issue #13](https://github.com/groove-max/ha-eybond-local/issues/13) or your
+existing support issue, together with:
+
+- the installed version and, for a manual test build, its commit;
+- when the problem started, your time zone, and the cloud's last data timestamp;
+- whether Home Assistant readings still change and when cloud updates resume.
+
+You do not need to delete the integration or reset the collector to report this.
+
 ---
 
 ## Documentation

README.uk.md

@@ -22,6 +22,8 @@
 
 > **Примітка:** Інтеграція активно розвивається. Частина інверторів підтримується повністю, частина — лише для читання, а для частини потрібен архів підтримки.
 
+> **Відома проблема:** На деяких системах оновлення в хмарі виробника можуть зупинятися, хоча показання Home Assistant продовжують змінюватися. Ми досліджуємо це; подробиці — у [розділі про хмарну телеметрію](#відома-проблема-хмарної-телеметрії).
+
 ---
 
 ## Чи підходить ця інтеграція для мого інвертора?
@@ -50,9 +52,9 @@ SmartValue для Home Assistant, підключення EyeBond Wi-Fi-коле
   належне цьому запису з’єднання.
 - Читає дані інвертора, батареї, PV, навантаження та мережі локально.
 - Створює звичайні сутності Home Assistant: сенсори, числа, списки вибору, перемикачі та кнопки.
-- За замовчуванням застосунок виробника працює разом із Home Assistant, або можна
-  спрямувати колектор лише на Home Assistant — це оборотна, явна дія, яка ніколи
-  не виконується непомітно.
+- За замовчуванням залишає адресу хмари виробника для роботи разом із Home
+  Assistant, або дозволяє спрямувати колектор лише на Home Assistant — це
+  оборотна, явна дія, яка ніколи не виконується непомітно.
 - Дає вибрати рівень керування:
   - **Лише читання** — тільки моніторинг.
   - **Автоматично** — перевірене керування вмикається саме.
@@ -325,13 +327,36 @@ Modbus-пристрої можуть оновлюватися частіше, н
 | Ручне налаштування не може підтвердити пристрій | Не закривайте майстер і повторіть спробу, коли пристрій доступний. Для вхідного підключення увімкніть фонове виявлення й продовжте, коли з’явиться ідентифікована сесія. |
 | З’явився лише пристрій колектора | Визначення інвертора ще не завершилося. Перевірте **Poll Context** і відкрийте [Визначення інвертора та сутності](docs/user/RUNTIME_AND_INVERTER.md); якщо драйвер не визначиться, створіть архів підтримки. |
 | Сенсори недоступні | Перевірте, що колектор і Home Assistant у тій самій мережі, а Wi-Fi колектора стабільний. |
-| Застосунок виробника перестав показувати дані | Якщо ви спрямували колектор лише на Home Assistant, це навмисно відключає його від хмари. Скористайтеся дією **Відновити попередню адресу колектора**, щоб повернути застосунок виробника. |
+| Застосунок виробника перестав показувати дані | Перевірте режим підключення: **Лише Home Assistant** навмисно відключає хмару. Якщо ви й далі використовуєте **Хмара + Home Assistant**, дивіться [відому проблему хмарної телеметрії](#відома-проблема-хмарної-телеметрії) нижче. |
 | Застосунок виробника працює, а Home Assistant показує недоступність | Колектор міг швидше відновити зв'язок із хмарою, ніж локально з Home Assistant. Зачекайте кілька хвилин і перевірте Wi-Fi. |
 | Налаштування одразу повертається назад | Інвертор відхилив значення або не підтвердив зміну. Не змінюйте той самий параметр у застосунку виробника одночасно й повторіть після стабілізації колектора. |
 | Потрібне віддалене підключення | Дивіться [посібник з віддаленого підключення / NAT](docs/user/REMOTE_SETUP.md). За можливості використовуйте VPN замість відкриття порту в інтернет. |
 | Немає керування | Для нормального використання залишайте **Автоматично**. Якщо моніторинг працює, але керування відсутнє, запустіть навчання пристрою, якщо воно доступне, або створіть архів підтримки. **Повне керування** використовуйте лише якщо розумієте ризик. |
 | Неналаштований колектор підключиться пізніше | Увімкніть постійний запис **EyeBond Local — Discovery**. Він покаже ідентифіковану сесію колектора, не створюючи тимчасовий пристрій. |
 
+### Відома проблема хмарної телеметрії
+
+Деякі користувачі повідомляють, що в режимі **Хмара + Home Assistant** застосунок
+виробника перестає оновлювати дані або показує колектор офлайн, хоча локальні
+показання Home Assistant продовжують змінюватися. Хмарні оновлення можуть
+відновитися самостійно. Проблема відома й досліджується. Її причину та
+універсальне виправлення ще не підтверджено.
+
+Це відрізняється від режиму **Лише Home Assistant**, у якому відключення хмари
+навмисне. Ні збільшення інтервалу опитування, ні перезапуск не є підтвердженим
+універсальним вирішенням періодичних збоїв.
+
+Якщо це сталося, створіть [архів підтримки](docs/user/SUPPORT_ARCHIVE.md) під час
+збою, за можливості до перезапуску чи перемикання режиму. Додайте його до
+[issue #13](https://github.com/groove-max/ha-eybond-local/issues/13) або вашого
+наявного звернення разом із такими відомостями:
+
+- встановлена версія, а для ручної тестової збірки — також коміт;
+- час початку проблеми, ваш часовий пояс і час останніх даних у хмарі;
+- чи продовжують змінюватися показання Home Assistant і коли відновиться хмара.
+
+Для повідомлення про цей збій не потрібно видаляти інтеграцію чи скидати колектор.
+
 ---
 
 ## Документація

docs/README.md

@@ -8,6 +8,7 @@ release work; they are not required to use the integration.
 ## User guides
 
 - [Main README](../README.md) — installation, setup, connection settings, troubleshooting, and support flow
+- [Known cloud telemetry issue](../README.md#known-cloud-telemetry-issue) — cloud updates may pause while local readings continue; current status and useful support evidence
 - [Testing the unreleased main branch](../README.md#testing-the-unreleased-main-branch) — manual installation of a maintainer-requested test build
 - [Setup and Discovery](user/SETUP_AND_DISCOVERY.md) — collector-first setup, scan results, address confirmation, background discovery, and manual setup
 - [Runtime Detection and Entities](user/RUNTIME_AND_INVERTER.md) — driver detection, Fast and Full protocol checks, polling, controls, and entity availability