Wi-Fi spool

Сервис читает вывод mosquitto_sub, выбирает из сообщений scan_results только точки с SSID RONAVI_MCNS5 и сохраняет их в PostgreSQL.

Запуск

sudo apt install mosquitto-clients
python3 -m pip install -r requirements.txt
cp .env.example .env
python3 wifi_spool.py

Предварительно создайте пользователя и базу PostgreSQL:

CREATE USER wifi_spool WITH PASSWORD 'change-me';
CREATE DATABASE wifi_spool OWNER wifi_spool;

Таблицы и индексы сервис создаёт автоматически. Скопируйте пример настроек и укажите в .env реальные пароли и параметры подключения:

cp .env.example .env

Файл .env автоматически загружается при запуске и исключён из Git. Любую настройку также можно передать через окружение; значение из окружения имеет приоритет над .env:

WIFI_SPOOL_MQTT_PASSWORD='secret' \
WIFI_SPOOL_POSTGRES_HOST='localhost' \
WIFI_SPOOL_POSTGRES_PORT='5432' \
WIFI_SPOOL_POSTGRES_DATABASE='wifi_spool' \
WIFI_SPOOL_POSTGRES_USER='wifi_spool' \
WIFI_SPOOL_POSTGRES_PASSWORD='change-me' \
python3 wifi_spool.py

Доступные настройки находятся в settings.py; каждая переопределяется одноимённой переменной окружения с префиксом WIFI_SPOOL_.

Для проверки одной или нескольких заранее сохранённых строк:

python3 wifi_spool.py --stdin < messages.txt

Структура БД

• bssids: уникальные BSSID (id, bssid);
• access_point_coordinates: координаты точки доступа (bssid_id, точные location_x/location_y); для точки без известных координат оба значения равны NULL;
• agents: уникальные агенты (id, agent_name);
• scan_results: ссылка bssid_id, целые location_x/location_y, целый signal_level, ссылка agent_id и дата сбора collected_at с часовым поясом.

collected_at заполняется автоматически текущим временем сервера PostgreSQL.

Повторное обнаружение BSSID не создаёт дубликат в bssids, но создаёт новую строку измерения в scan_results. Имена агентов также не дублируются: в scan_results хранится только числовой идентификатор агента.

При первом запуске после установки сервис загружает access_point_coordinates.csv в таблицу access_point_coordinates. BSSID из файла также добавляются в справочник bssids. Повторный запуск безопасен: существующие координаты обновляются, дубликаты не создаются. Формат файла — bssid;x;y; пустые x и y сохраняются как NULL.

Каждое исходное MQTT-сообщение с message_kind = scan_results дополнительно сохраняется без изменений в отдельный файл вида scan_results-20260830T154059.123456Z-<id>.txt. По умолчанию файлы находятся в /var/lib/wifi-spool/raw. Путь можно изменить настройкой:

WIFI_SPOOL_SAVE_RAW_SCAN_RESULTS=true
WIFI_SPOOL_RAW_SCAN_RESULTS_DIR=/var/lib/wifi-spool/raw

Другие типы MQTT-сообщений в этот архив не записываются. Очистка старых файлов автоматически не выполняется. Чтобы полностью отключить сохранение сырых данных, установите WIFI_SPOOL_SAVE_RAW_SCAN_RESULTS=false и перезапустите сервис.

Установка как сервис Debian

На чистом Debian запустите установщик из корня проекта:

chmod +x deploy/install.sh
sudo ./deploy/install.sh

Установщик:

• устанавливает python3-venv и mosquitto-clients;
• создаёт системного пользователя wifi-spool без возможности входа;
• устанавливает приложение и виртуальное окружение в /opt/wifi-spool;
• создаёт настройки /etc/wifi-spool/wifi-spool.env с правами 0640;
• устанавливает и включает unit wifi-spool.service.

При потере MQTT-соединения keepalive обнаруживает разрыв, а mosquitto_sub переподключается. Если MQTT-клиент или Python-процесс завершится, systemd перезапустит сервис через 5 секунд без ограничения числа попыток. При потере PostgreSQL ошибка записи завершает процесс, после чего новый процесс заново подключается к базе. Поэтому восстановление работает и после длительного отключения сети или базы данных.

При первой установке сервис намеренно не запускается, пока не будут заменены пароли в конфигурации:

sudo nano /etc/wifi-spool/wifi-spool.env
sudo systemctl start wifi-spool

У пользователя PostgreSQL должны быть права на создание и изменение таблиц в целевой базе. Основные команды управления:

sudo systemctl status wifi-spool
sudo systemctl restart wifi-spool
sudo systemctl stop wifi-spool
sudo journalctl -u wifi-spool -f

Для обновления кода повторно запустите sudo ./deploy/install.sh. Существующий файл настроек не перезаписывается, сервис перезапускается автоматически.

Веб-интерфейс тепловой карты

Второй сервис wifi-spool-web строит тепловую карту по локальным координатам location_x и location_y. Каждая координата отображается квадратом 1×1, цвет которого соответствует уровню signal_level за выбранный временной интервал. Границы сетки фиксируются по min(x), max(x), min(y), max(y) для всего выбранного периода. На обеих осях используется единый масштаб: квадрат 1×1 имеет одинаковую ширину и высоту, а сетка растягивается на максимально доступную область. В интерфейсе можно:

• задать общий диапазон даты и времени в заголовке;
• изменить границы тепловой карты по X и Y в веб-интерфейсе;
• увидеть максимальный signal_level в каждой точке на общей карте;
• выбрать одного или нескольких агентов и увидеть среднее дневных максимумов;
• выбрать одну или несколько точек доступа BSSID и увидеть среднее значение;
• оценить качество по единой шкале: красный ниже −75 dBm, жёлтый от −75 до −70 dBm, зелёный выше −70 dBm.

Настройки веб-сервиса находятся в /etc/wifi-spool/wifi-spool.env:

# Для доступа с других компьютеров локальной сети
WIFI_SPOOL_WEB_HOST=0.0.0.0
WIFI_SPOOL_WEB_PORT=8080
WIFI_SPOOL_WEB_DEFAULT_DATE_RANGE_MINUTES=1440
WIFI_SPOOL_WEB_MAP_MIN_X=-150
WIFI_SPOOL_WEB_MAP_MAX_X=-70
WIFI_SPOOL_WEB_MAP_MIN_Y=40
WIFI_SPOOL_WEB_MAP_MAX_Y=110

Эти четыре границы используются как начальные значения при открытии страницы; пользователь может изменить их в панели управления перед построением карты.

Логика вкладок

• Общая карта. Данные ограничиваются выбранным периодом, координатами и отмеченными BSSID. Для каждой пары координат показывается максимальный signal_level среди всех подходящих измерений (MAX).
• По агентам. Данные ограничиваются выбранными агентами, периодом и координатами. Сначала для каждого календарного дня и пары координат выбирается максимальный signal_level. Затем для каждой пары координат вычисляется среднее значение полученных дневных максимумов. Именно оно отображается на карте.
• По точкам доступа. Данные ограничиваются выбранными BSSID, периодом и координатами. Для каждой пары координат вычисляется средний signal_level среди всех подходящих измерений (AVG).

Если в списке ничего не отмечено, вкладка использует все элементы своего типа: всех агентов или все точки доступа соответственно.

После изменения настроек:

sudo systemctl restart wifi-spool-web

Открыть панель можно по адресу http://IP_СЕРВЕРА:8080. Проверка состояния API:

curl http://127.0.0.1:8080/health
sudo systemctl status wifi-spool-web
sudo journalctl -u wifi-spool-web -f

Веб-интерфейс не содержит встроенной авторизации. При доступе не только из доверенной локальной сети рекомендуется закрыть порт файрволом либо поставить перед сервисом Nginx с HTTPS и авторизацией.

Удаление сервисов

Удалить оба сервиса, каталог /opt/wifi-spool и системного пользователя:

sudo ./deploy/uninstall.sh

Конфигурация /etc/wifi-spool/wifi-spool.env по умолчанию сохраняется, чтобы её можно было использовать при повторной установке. Удалить также настройки:

sudo ./deploy/uninstall.sh --purge

Скрипт удаления не изменяет базу PostgreSQL и не удаляет таблицы с накопленными данными.