Ignis Core

Локальный FastAPI-сервер для управления лампами WiZ.

Что есть

• discovery устройств в локальной сети
• группы устройств
• команды для device/group
• one-shot и cron расписания
• guest/admin/master API-ключи
• event log и базовая статистика
• встроенный UI в static/index.html

Запуск

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn main:app --host 0.0.0.0 --port 8000

UI: http://<host>:8000/

Конфигурация

Минимум:

IGNIS_API_KEY=change-me
APP_TIMEZONE=Asia/Novosibirsk
SCAN_NETWORK=
LOG_LEVEL=INFO
EVENT_LOG_RETENTION_DAYS=30

БД:

IGNIS_DATABASE_URL=sqlite+aiosqlite:///./ignis.db
IGNIS_SYNC_DATABASE_URL=sqlite:///./ignis.db

Замечание по discovery:

• если на хосте есть VPN или несколько интерфейсов, лучше явно задать SCAN_NETWORK
• формат: 192.168.0.0/24 или список через запятую

Авторизация

Заголовок: X-API-Key

Роли:

• master: значение из IGNIS_API_KEY, полный доступ
• admin: ключ из БД, доступ к группам, расписаниям, stats и rescan
• guest: обычное управление и чтение

Сервер работает в fail-closed: если IGNIS_API_KEY не задан, защищённые маршруты недоступны.

API

Основные маршруты:

• GET /devices
• GET /devices/groups
• GET /devices/scenes
• POST /devices/groups
• DELETE /devices/groups/{group_id}
• POST /devices/rescan
• POST /control/device/{device_id}
• POST /control/group/{group_id}
• POST /control/device/{device_id}/blink
• GET /control/device/{device_id}/status
• GET /control/group/{group_id}/status
• POST /schedules/once
• POST /schedules/cron
• GET /schedules/tasks
• DELETE /schedules/{job_id}
• GET /api-keys
• POST /api-keys
• POST /api-keys/revoke
• POST /api-keys/activate
• GET /stats/summary
• GET /stats/log
• GET /auth/me

Текущий контракт для control и schedules использует query-параметры.

Поддерживаемые параметры команд:

• state
• brightness
• scene
• temp
• r, g, b

Примеры:

curl -X POST 'http://localhost:8000/control/device/dev-1?temp=4200' \
  -H 'X-API-Key: change-me'

curl -X POST 'http://localhost:8000/schedules/once?target_id=bedroom&hours_from_now=2&is_group=true&temp=3200' \
  -H 'X-API-Key: change-me'

API keys

• список ключей возвращает публичный key / key_id
• полный секрет возвращается только при создании
• маршруты /api-keys/* доступны только master

Хранилище

Основные таблицы:

• groups
• api_keys
• event_log
• schedules
• apscheduler_jobs

OpenAPI

Актуальная схема лежит в openapi.json.

Перегенерация:

.venv/bin/python -c 'import json, os, pathlib; os.environ.setdefault("IGNIS_API_KEY", "openapi-export"); from main import app; pathlib.Path("openapi.json").write_text(json.dumps(app.openapi(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")'

Тесты

Проверка синтаксиса:

.venv/bin/python -m compileall app tests main.py

Полный прогон:

timeout 120s .venv/bin/python -m unittest discover -s tests -v

Сейчас есть 17 тестов. Покрыты:

• auth и роли
• lifecycle API-ключей
• control/status ошибки и partial success
• валидация scene
• one-shot и cron расписания
• миграция legacy jobs
• агрегация stats без двойного счёта *_requested

Ограничения

• discovery всё ещё основан на переборе IP по подсетям
• UI остаётся монолитным файлом
• control и schedules ещё не переведены на JSON body
• stats пока простые и не заменяют нормальную аналитику