fleet/README.md

# fleet

Плейбуки ansible, которые приводят любую малинку парка (Raspberry Pi +
HackRF) в рабочее состояние и управляют ею дальше: домашний Wi-Fi ради
интернета, пакеты, код `hackrf-scanner` со сборкой на месте, паспорт узла,
запуск и остановка сканера, перезагрузка и выключение.
Управление идёт по проводной сети 11.0.0.0/24 (`ansible_host` в инвентаре),
Wi-Fi нужен только на время установки пакетов и перед работой выключается,
потому что адаптер сидит в 2,4 ГГц рядом с приёмником.

## Требования

- управляющая машина: `ansible` с коллекциями `community.general` и
  `ansible.posix`, `rsync`, `sshpass` (только для `bootstrap.yml`),
  рядом лежит каталог `../hackrf-scanner` (переменная `scanner_src`);
- узлы: Raspberry Pi OS Lite (Debian 13, NetworkManager), пользователь `pi`
  с sudo без пароля, статический адрес 11.0.0.x на eth0; на полном образе
  с рабочим столом первый `full-upgrade` по Wi-Fi идёт больше часа;
- `vars/wifi.yml` (в `.gitignore`) по образцу `vars/wifi.yml.example`.

## Новый узел

```bash
nmap -sn 11.0.0.0/24                              # какие узлы в сети
ansible-playbook bootstrap.yml -l node107         # ключ по паролю pi/raspberry
ansible-playbook wifi-on.yml                      # Wi-Fi и проверка интернета
ansible-playbook playbook.yml                     # пакеты, права, имя
ansible-playbook wifi-off.yml                     # Wi-Fi выключен до следующего раза
ansible-playbook deploy.yml                       # код с этой машины, сборка на узле
ansible-playbook env.yml                          # паспорт ~/node.env из инвентаря
```

## Работа

```bash
# 1. расстановка: x, y узлов и server_ip в inventory/hosts.yml
ansible-playbook env.yml --diff                   # 2. паспорта на узлы
# 3. частота и усиления: inventory/group_vars/all/scanner.yml
ansible-playbook scanner-start.yml                # 4. peleng на всех узлах
ansible-playbook scanner-start.yml -e scanner_args="--freq 2437"   # разово поверх
ansible-playbook scanner-stop.yml                 # HackRF свободен (scan, калибровка)
```

`scanner-start.yml` на каждом узле зовёт `node.py start <профиль> <флаги>`:
останавливает прежний peleng и любой процесс, держащий HackRF, переинициализирует
USB и запускает peleng в фоне с логом `/tmp/peleng.log`. Профиль и флаги лежат в
`inventory/group_vars/all/scanner.yml` (`scanner_profile`, `scanner_args`); узлу
можно задать своё значение в `inventory/hosts.yml`, разовый запуск поверх всего
через `-e`. peleng читает паспорт
только при старте, поэтому после `env.yml` нужен повторный `scanner-start.yml`.

Новый узел сначала вписывается в `inventory/hosts.yml`. Смена роутера: правка
`vars/wifi.yml` и `wifi-on.yml`, профиль на узлах обновится.

## Плейбуки

| Плейбук | Что делает |
|---|---|
| `bootstrap.yml` | ключ управляющей машины в `authorized_keys`, вход по паролю |
| `wifi-on.yml` | радио включено, профиль `fleet-wifi` с кредами из `vars/wifi.yml`, подключение, проверка DNS и HTTPS |
| `playbook.yml` | теги `base` (apt, зависимости, plugdev, udev для HackRF, fish), `hostname`, `key` (deploy-ключ Gitea) |
| `wifi-off.yml` | радио выключено, NetworkManager помнит это через перезагрузку |
| `deploy.yml` | `rsync` исходников без `.git` и `build`, ревизия в `~/hackrf-scanner/DEPLOYED`, `cmake` сборка, проверка бинарников |
| `env.yml` | `~/node.env` (`SDR_ID`, `X`, `Y`, `SERVER`) из инвентаря, перезаписывается целиком |
| `scanner-start.yml` | `node.py start`: освободить HackRF, переинициализировать USB, peleng в фоне, `status` |
| `scanner-stop.yml` | `node.py stop`: peleng и любой процесс с HackRF остановлены, проверка `status` |
| `reboot.yml` | перезагрузка с ожиданием возврата, печатает ядро |
| `poweroff.yml` | штатное выключение и ожидание, пока узел пропадёт из сети |

Ограничение по узлам и тегам как обычно: `-l node106`, `--tags base`.

## Инвентарь

`inventory/hosts.yml`: адрес узла в проводной сети, `sdr_id`, серийник HackRF,
координаты x, y в метрах. Общие переменные: `server_ip` (куда узлы шлют замеры),
`scanner_dir` (каталог сканера на узле). Параметры запуска сканера - в
`inventory/group_vars/all/scanner.yml`. Инвентарь главный: `env.yml` перезаписывает паспорт узла,
правки руками на узле до следующего прогона.

## Приёмка

1. Все плейбуки без `failed`, второй прогон подряд `changed=0`.
2. После `wifi-on.yml` каждый узел печатает адрес в домашней сети и
   "интернет есть", после `wifi-off.yml` у `wlan0` нет адреса.
3. На узле `~/hackrf-scanner/build/peleng` и `scan` собраны, `DEPLOYED`
   совпадает с `git describe` на управляющей машине, `hostname` = имя узла.
4. После `scanner-start.yml` каждый узел печатает "peleng запущен" и строку
   замера, после `scanner-stop.yml` статус "не запущен".