From fbd33b8419f69f22cccce53835c992df3073c5b4 Mon Sep 17 00:00:00 2001
From: hermes-home <hermes-home@hal9000.home>
Date: Tue, 4 Aug 2026 16:11:14 +0000
Subject: [PATCH] =?UTF-8?q?Add=20README:=20=D1=83=D1=81=D1=82=D0=B0=D0=BD?=
 =?UTF-8?q?=D0=BE=D0=B2=D0=BA=D0=B0,=20CLI,=20watchdog,=20=D1=80=D0=B5?=
 =?UTF-8?q?=D0=B3=D0=B8=D0=BE=D0=BD=D1=8B,=20D4H=20fix?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ad51e31
--- /dev/null
+++ b/README.md
@@ -0,0 +1,89 @@
+# domestic-scripts
+
+Домашние скрипты Hermes. Пока — интеграция с умными устройствами **PetKit** (кормушка и автопоилка).
+
+## Структура
+
+| Файл | Назначение |
+|---|---|
+| `petkit_cli.py` | Основной CLI — статус, кормление, управление фонтаном, дамп |
+| `petkit_food_check.py` | Watchdog уровня корма — для cron-уведомлений |
+| `petkit_raw.py` | Прямой HTTP-запрос к API PetKit (отладка, без парсинга) |
+| `petkit_roster.py` | Сырой вывод `device_roster` — какие устройства на аккаунте |
+
+## Установка / настройка
+
+```bash
+# venv (изолированный, не трогаем систему)
+cd domestic-scripts
+python3 -m venv .venv
+.venv/bin/pip install petkitaio
+
+# креды — создать .env рядом со скриптами (НЕ коммитим!)
+cat > .env <<'EOF'
+PETKIT_EMAIL=ваш@email
+PETKIT_PASSWORD=пароль
+PETKIT_REGION=Russian Federation
+EOF
+```
+
+`.env` и `.venv` в `.gitignore` — в репо не попадают.
+
+## CLI (`petkit_cli.py`)
+
+```bash
+.venv/bin/python petkit_cli.py status      # статус всех устройств
+.venv/bin/python petkit_cli.py feed 10     # покормить 10 г (первый фидер)
+.venv/bin/python petkit_cli.py fountain smart  # фонтан: режим smart/normal
+.venv/bin/python petkit_cli.py dump        # полный дамп данных (после обработки)
+```
+
+## Watchdog корма (`petkit_food_check.py`)
+
+Следит за датчиком уровня корма `state.food` фидера:
+
+- `food: 2` — достаточно
+- `food: 1` — на исходе → **алерт «НА ИСХОДЕ»**
+- `food: 0` — почти пусто → **алерт «ПОЧТИ ПУСТО»**
+- возврат к `2` после долива → **«корм долили» (сброс)**
+
+Логика:
+- Алертит **только при переходе** состояния (не спамит при каждом запуске).
+- Последний уровень хранится в `.food_state` (runtime, в `.gitignore`).
+- Печатает в stdout: **пусто** = тихий прогон, **непусто** = событие для уведомления.
+
+### Cron (watchdog no_agent)
+Обёртка `~/./scripts/petkit-food-check.sh` вызывает скрипт в фоне. Крон каждые 4ч:
+непустой stdout → уведомление в чат; пустой → тишина. Фиксируется через `cronjob no_agent=true`.
+
+## ⚠️ Важно про модели PetKit
+
+### Семейный (вторичный) аккаунт
+Учётка PetKit рассчитана на один активный вход. Использование API **выкидывает из мобильного приложения**. Решение — завести **family share** на вторичный аккаунт и логиниться им. Устройства должны быть расшарены на этот аккаунт (в приложении: основная учётка → Family).
+
+### Регионы
+Регистр регионов задаётся по имени страны (например `Russian Federation` → сервер `api-ru.petkit.cn`). Неверный регион даёт ошибку `PetKit Error 125: Unregistered e-mail`.
+
+### Поддержка типов (фидер D4H)
+Библиотека `petkitaio` классифицирует фидеры по списку `FEEDER_LIST` в
+`.venv/.../petkitaio/constants.py`. По умолчанию там нет типа **`D4H`** (YumShare Solo / D4-серия) —
+из-за этого фидер молча игнорируется (`feeders: {}`), хотя в облаке есть.
+
+**Фикс:** добавить `D4H` в `FEEDER_LIST`:
+```python
+FEEDER_LIST = ['D3', 'D4', 'D4s', 'D4H', 'Feeder', 'FeederMini']
+```
+> Правка в venv слетает при переустановке `petkitaio`. Если обновили пакет — повторить.
+
+### Уровень корма
+Поле уровня находится в `data['state']['food']`. `feedState` содержит статистику кормлений
+(суммарные граммы, число раз, время кормёжек).
+
+## Устройства (текущие)
+
+| Устройство | Облачный id | Тип |
+|---|---|---|
+| YUMSHARE SOLO WITH CAMERA (фидер) | 300027445 | D4H |
+| EVERSWEET 3 PRO (UVC) (фонтан) | 400081877 | W5 |
+
+> id могут отличаться на другои аккаунте — уточняйте через `petkit_cli.py status`.