Blink(1) FastAPI API

Мини‑API для управления устройством Blink(1) через blink1-tool с токен‑авторизацией.

Переменные окружения

• BLINK_API_TOKEN (обязательно) — токен для запросов
• BLINK_ENABLE_DOCS — 1 чтобы включить /docs
• BLINK1_TOOL_PATH — путь к бинарю blink1-tool (по умолчанию blink1-tool)
• BLINK_COMMAND_TIMEOUT_S — таймаут вызова blink1-tool (секунды)
• BLINK_DRY_RUN — 1 чтобы не трогать железо (для разработки)
• BLINK_EVENTS_MAXLEN — сколько последних событий хранить в памяти

Авторизация: Authorization: Bearer <token> или X-API-Token: <token>.

Эндпоинты

• GET /healthz — без авторизации
• POST /v1/color — установить цвет (color или rgb, опционально fade_ms)
• POST /v1/off — выключить
• POST /v1/pattern/pulse — пульсация (rgb, on_ms, off_ms, count)
• GET /v1/devices — сырой вывод blink1-tool --list
• GET /v1/state — последняя команда/цвет
• GET /v1/events — последние события (кольцевой буфер)

Примеры запросов

export TOKEN="..."

curl -X POST "http://127.0.0.1:8000/v1/color" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"color":"red","fade_ms":150}'

curl -X POST "http://127.0.0.1:8000/v1/pattern/pulse" \
  -H "X-API-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rgb":{"r":0,"g":255,"b":0},"count":5,"on_ms":120,"off_ms":120}'

Docker Compose (Ubuntu)

1. Скопируй .env.example → .env и заполни BLINK_API_TOKEN (и CLOUDFLARED_TOKEN, если используешь туннель).
2. Подключи Blink(1) по USB к хосту.
3. Запусти из корня репозитория (где лежит docker-compose.yml):

docker compose up -d --build

API будет доступен локально на http://127.0.0.1:8000 (и через Cloudflare Tunnel, если настроен). Если порт занят — поменяй BLINK_API_PORT в .env (например на 8001).

Если ты находишься в другой папке (например, cd blink_api), запускай так:

docker compose --project-directory .. --env-file ../.env up -d --build

Как это устроено

• blink1-tool собирается в Docker из исходников (в Ubuntu 24.04 нет пакета blink1-tool в apt)
• зависимости Python ставятся через uv (uv sync --frozen --no-dev)

Доступ к USB

В docker-compose.yml включён privileged: true и проброшен /dev/bus/usb. Если хочешь ужесточить — можно заменить на точечный devices: для /dev/hidrawX (зависит от системы/порта).

Cloudflare Tunnel (cloudflared)

В docker-compose.yml cloudflared включается профилем tunnel:

docker compose --profile tunnel up -d --build

В Cloudflare Zero Trust используй “token mode”:

• Создай туннель в Cloudflare Zero Trust и привяжи hostname к сервису http://api:8000
• Вставь токен в .env как CLOUDFLARED_TOKEN

Альтернатива — конфиг‑файл: см. cloudflared/config.yml.example.

Идеи событий и схем подсветки

События для отслеживания

• CI/CD: build started/succeeded/failed, deploy started/succeeded/rolled back
• Мониторинг: host down/up, high CPU/RAM/disk, errors rate, latency SLO
• Бизнес: “новый заказ”, “платёж не прошёл”, “очередь растёт”, “нет консьюмера”
• Безопасность: много 401/403, подозрительные IP, смена токена, перезапуск контейнера

Схемы подсветки

• green — всё ок / сервис healthy
• yellow — деградация / предупреждение (SLO на грани)
• red — инцидент / алерт
• blue — деплой в процессе
• purple — ручной режим / maintenance
• Пульсация (pulse) — “идёт процесс”, короткие вспышки — “событие произошло”