140 lines
6.6 KiB
Markdown
140 lines
6.6 KiB
Markdown
# Ignis Core
|
||
|
||
Self-hosted сервер для управления умными лампами WiZ по локальной сети. FastAPI бэкенд с веб-интерфейсом, планировщиком расписаний и REST API для мобильного приложения.
|
||
|
||
## Возможности
|
||
|
||
- **Discovery** -- автоматическое обнаружение ламп WiZ в локальной сети (UDP broadcast). Поддержка нескольких подсетей через `SCAN_NETWORK`.
|
||
- **Группы** -- объединение ламп в именованные группы (спальня, кухня, ...). Хранение в SQLite.
|
||
- **Управление** -- включение/выключение, яркость, цветовая температура, RGB-цвет, 35+ встроенных сцен.
|
||
- **Расписания** -- одноразовые таймеры и cron-задачи через APScheduler с персистентным хранилищем.
|
||
- **Веб-интерфейс** -- SPA на Vue 3 + Tailwind, встроен в сервер как статика.
|
||
- **API** -- REST API с авторизацией по API-ключу для мобильных клиентов.
|
||
|
||
## Быстрый старт
|
||
|
||
```bash
|
||
# Клонировать
|
||
git clone https://git.akokos.ru/artem.kokos/ignis-core.git
|
||
cd ignis-core
|
||
|
||
# Виртуальное окружение
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
|
||
# Зависимости
|
||
pip install -r requirements.txt
|
||
|
||
# Конфигурация
|
||
cp .env.example .env
|
||
# Отредактировать .env -- указать API-ключ и таймзону
|
||
|
||
# Запуск
|
||
uvicorn main:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
Сервер будет доступен на `http://<ip>:8000`. Веб-интерфейс -- на корневом URL.
|
||
|
||
## Конфигурация (.env)
|
||
|
||
```env
|
||
# API-ключ для авторизации (если не задан -- авторизация отключена)
|
||
IGNIS_API_KEY=your-secret-key
|
||
|
||
# Таймзона для расписаний (по умолчанию Asia/Novosibirsk)
|
||
APP_TIMEZONE=Asia/Almaty
|
||
|
||
# Подсети для сканирования (через запятую, по умолчанию -- автоопределение)
|
||
SCAN_NETWORK=192.168.1.0/24
|
||
|
||
# Уровень логирования
|
||
LOG_LEVEL=INFO
|
||
```
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
ignis-core/
|
||
├── main.py -- точка входа FastAPI, lifespan
|
||
├── requirements.txt -- зависимости
|
||
├── .env -- конфигурация (не в git)
|
||
├── static/
|
||
│ └── index.html -- веб-интерфейс (Vue 3 SPA)
|
||
├── app/
|
||
│ ├── core/
|
||
│ │ ├── database.py -- async SQLAlchemy, SQLite
|
||
│ │ ├── discovery.py -- UDP-сканирование сети WiZ
|
||
│ │ ├── scheduler.py -- APScheduler + jobstore
|
||
│ │ └── state.py -- in-memory состояние (устройства, группы)
|
||
│ ├── models/
|
||
│ │ ├── device.py -- модели Device, Group (SQLAlchemy + Pydantic)
|
||
│ │ └── schedule.py -- модель ScheduleTask
|
||
│ ├── drivers/
|
||
│ │ └── wiz.py -- UDP-драйвер протокола WiZ
|
||
│ └── api/
|
||
│ ├── deps.py -- авторизация (X-API-Key)
|
||
│ └── routes/
|
||
│ ├── devices.py -- CRUD устройств и групп
|
||
│ ├── control.py -- управление лампами
|
||
│ └── schedules.py -- расписания (once, cron)
|
||
└── ignis.db -- SQLite база (создаётся автоматически)
|
||
```
|
||
|
||
## API
|
||
|
||
Авторизация: заголовок `X-API-Key`.
|
||
|
||
### Устройства и группы
|
||
|
||
| Метод | Путь | Описание |
|
||
|--------|--------------------------|------------------------------|
|
||
| GET | `/devices` | Все обнаруженные лампы |
|
||
| GET | `/devices/groups` | Все группы |
|
||
| GET | `/devices/scenes` | Доступные сцены WiZ |
|
||
| POST | `/devices/groups` | Создать группу |
|
||
| DELETE | `/devices/groups/{id}` | Удалить группу |
|
||
| POST | `/devices/rescan` | Пересканировать сеть |
|
||
|
||
Создание группы (JSON body):
|
||
```json
|
||
{"id": "bedroom", "name": "Спальня", "macs": ["a8bb50aabbcc", "a8bb50ddeeff"]}
|
||
```
|
||
|
||
### Управление
|
||
|
||
| Метод | Путь | Описание |
|
||
|-------|----------------------------------|------------------------|
|
||
| POST | `/control/device/{id}` | Управление лампой |
|
||
| POST | `/control/group/{id}` | Управление группой |
|
||
| POST | `/control/device/{id}/blink` | Мигнуть лампой |
|
||
| GET | `/control/device/{id}/status` | Статус лампы |
|
||
| GET | `/control/group/{id}/status` | Статус группы |
|
||
|
||
Query-параметры управления: `state` (bool), `brightness` (int, 10--100), `temp` (int, 2700--6500), `scene` (string), `r`/`g`/`b` (int, 0--255).
|
||
|
||
### Расписания
|
||
|
||
| Метод | Путь | Описание |
|
||
|--------|-----------------------|-------------------------|
|
||
| POST | `/schedules/once` | Одноразовый таймер |
|
||
| POST | `/schedules/cron` | Повторяющаяся задача |
|
||
| GET | `/schedules/tasks` | Все активные задачи |
|
||
| DELETE | `/schedules/{job_id}` | Отменить задачу |
|
||
|
||
## Стек
|
||
|
||
- **FastAPI** -- async HTTP-сервер
|
||
- **SQLAlchemy 2.0** -- async ORM, SQLite через aiosqlite
|
||
- **APScheduler** -- планировщик с персистентным хранилищем
|
||
- **WiZ Protocol** -- UDP-управление лампами (порт 38899)
|
||
- **Vue 3 + Tailwind** -- встроенный веб-интерфейс
|
||
|
||
## Клиенты
|
||
|
||
- Веб-интерфейс -- встроен в сервер (`static/index.html`)
|
||
- [Ignis App](https://git.akokos.ru/artem.kokos/ignis_app) -- мобильное приложение (Flutter)
|
||
|
||
## Лицензия
|
||
|
||
Частный проект.
|