# 🐍 Python-инструменты компонентов

Некоторые компоненты содержат вспомогательные Python-скрипты в `Components/<имя>/tools/`
(визуализаторы, мониторы) — например, [`HMMD-mmWave/tools/radar_view.py`](Sensors/Movement/HMMD-mmWave/tools/radar_view.py)
(радар-экран) или [`PIR_sensor_AM312/tools/timeline_view.py`](Sensors/Movement/AM312/tools/timeline_view.py)
(таймлайн событий движения). Они не собираются PlatformIO и не входят в прошивку — это отдельные
программы, которые запускаются на компьютере (не на ESP32) и читают данные из Serial-порта, пока
плата подключена.

Каждый такой набор скриптов лежит рядом со своим `requirements.txt` в той же папке `tools/`.
**Обязательного требования использовать именно uv нет** — подойдёт любой из двух способов ниже,
результат одинаковый. uv быстрее и не тянет системный Python, поэтому он в приоритете, но
классический `venv` работает без дополнительной установки чего-либо.

Оба варианта ниже выполняются из папки конкретного инструмента, например:

```bash
cd Components/HMMD-mmWave/tools
```

## Вариант A — uv (Recommended)

[uv](https://docs.astral.sh/uv/) — менеджер пакетов/окружений для Python. Сам создаёт и
переиспользует виртуальное окружение — отдельно вызывать `venv`/`activate` не нужно.

Установка (один раз на компьютер, если ещё не стоит):

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh   # Linux/macOS
# или: pipx install uv / см. docs.astral.sh/uv/getting-started/installation
```

Запуск скрипта:

```bash
uv venv                          # создаёт .venv в текущей папке (один раз)
uv pip install -r requirements.txt
uv run python3 radar_view.py /dev/ttyUSB0
```

`uv run` сам находит и использует `.venv` рядом — активировать его вручную не обязательно.
Если предпочитаете классический `source`-стиль, `uv venv` создаёт обычное venv-окружение,
и подходит Вариант B ниже (шаги 2–3), просто окружение уже создано через uv.

## Вариант B — классический venv + pip

Ничего дополнительно устанавливать не нужно — `venv` идёт в комплекте с Python 3.

```bash
python3 -m venv .venv
source .venv/bin/activate        # Linux/macOS; на Windows: .venv\Scripts\activate
pip install -r requirements.txt
python3 radar_view.py /dev/ttyUSB0
```

Деактивировать окружение после работы: `deactivate`.

## Важно в обоих случаях

- `.venv/` — локальная папка, создаётся отдельно для каждого `tools/`. В git не коммитится
  (см. `.gitignore`) — на новой машине окружение создаётся заново командами выше.
- Порт (`/dev/ttyUSB0`, на Windows — `COM3` и т.п.) должен совпадать с тем, что показывает
  `pio device monitor` — Serial-порт может слушать только одна программа одновременно: закройте
  `pio device monitor`/Serial Monitor перед запуском Python-скрипта.
- Требуемые версии пакетов зафиксированы в `requirements.txt` каждого инструмента — не общие
  для всего репозитория, у разных компонентов они независимы.