23 KiB
BreathMonitor — автономный прибор + Java/SQLite сервер
Комплект для развёртывания · 24 октября 2026 года
Адрес API и сайта уже задан: https://breathmonitor.shineup.me
Это рабочая интеграционная версия: сервер собирается локально на JDK 17 через Gradle, а JAR переносится на VPS без сборки на VPS. Прошивка проверена сборкой и загружена на подключённую ESP32-S3.
Содержимое
firmware/firmware.ino — изменённый скетч (UI, измерения, RTC, OTA)
firmware/ISRG_Root_X1_reference.pem — копия публичного корневого сертификата (он уже встроен в .ino)
server/BreathServer.java — один Java-класс: API, SQLite, HTTPS через Caddy, веб-сайт
server/RecordFixtureTest.java — тест бинарного формата/CRC32 без JDBC
server/build.gradle — зависимости SQLite JDBC, SLF4J и сборка jar
server/build.sh — Gradle package
server/start.sh — запуск и админ-команды
server/web/ — независимая HTML/CSS/JavaScript статистика
server/src/main/resources/firmware/ — стабильная 1.1 и тестовая 1.2 прошивки внутри JAR
deploy/Caddyfile.fragment — пример секции для Caddy
deploy/breathmonitor.service — пример службы systemd
1. Изменения прибора
- Без постоянного Wi-Fi. После загрузки радиомодуль выключен. Операция
TIME → SYNC NOWподключает известную сеть, синхронизирует NTP+RTC, выключает Wi-Fi.ONLINE → UPLOADделает то же самое для передачи журналов.Wi-Fi → TESTпроверяет доступность сети и отключает модуль. - На главном экране Wi-Fi не показывается. В
SETTINGSдыхание, счётчики и звуковые напоминания продолжаются; сверху видны текущая фаза, её длительность и кнопкаPAUSE/RESUME. Надписи легенды: слеваEXHALE, справаINHALE; процент заряда расположен справа от значка батареи. - До восьми сохранённых SSID и паролей перенесены из старой прошивки без изменения ключей
manual-wifi. - Если известные Wi-Fi недоступны, открывается список сетей; после выбора/ввода пароля ранее запрошенная операция продолжается автоматически.
- Журнал по дням:
/logs/20261024.binи т. п., записи по 32 байта, версия 1 + CRC32. Запись только в конец, существующие дневные файлы продолжаются после перезагрузки./logs/undated.bin— события при недостоверном времени. /events.binиз исходной прошивки не удаляется. При первом запуске записи переносятся в дневные файлы, успешный перенос фиксируется/migration.done. При аварийном выключении перенос пробуется снова; старый исходный файл остаётся. Неверные CRC в старом файле пропускаются, но остаются в оригинале для диагностики.- Автоформатирование FFat отключено (
FFat.begin(false)). Если FFat не монтируется, прибор показывает на экране подтверждениеFORMAT FFat; форматирование выполняется только после явного нажатия и удаляет локальные журналы. ONLINEсодержит толькоUPLOAD(отправляет сегодняшний файл) иSETTINGS. Вложенные настройки:ACCOUNT,TIME,Wi-Fi,FIRMWARE.ACCOUNT → CHANGE ACCOUNTсначала предупреждает об удалении локальных данных. Старые данные и настройки заменяются только после успешной авторизации нового аккаунта; при отмене или ошибке ничего не меняется. Серверный аккаунтivanсоздан с паролем1.FIRMWAREпоказывает установленную, стабильную1.1и тестовую1.2; перед OTA обновлением требуется подтверждение. Бинарники доступны на/firmware/manifest.jsonи внутри JAR.- Передача HTTPS в отдельной FreeRTOS-задаче; измерения и обновление LVGL продолжаются в основном цикле. Отправляется зафиксированный на момент начала передачи размер файла: новые записи попадут в следующую синхронизацию.
- Публичный ключ SSL не выключен: прошивка доверяет ISRG Root X1. Caddy должен получить совместимый сертификат Let's Encrypt. При смене удостоверяющего центра нужно обновить доверенный сертификат в прошивке.
USB CDC: доступны LOG INFO, LOG LIST, LOG DOWNLOAD 20261024, LOG DOWNLOAD undated, LOG DOWNLOAD LEGACY. LOG DOWNLOAD без указания даты больше не поддерживается. Бинарные данные передаются HEX-строками между LOG BEGIN ... и LOG END.
Важно при прошивке: используйте тот же раздел/Partition Scheme, который содержал исходный FFat, и не выбирайте Erase All Flash. Перепрошивка с изменением разметки может стереть старые журналы. До прошивки сделайте резервную копию /events.bin через исходную команду LOG DOWNLOAD.
2. Установка Java + SQLite (Ubuntu)
На сервере с Caddy и доступом в интернет:
sudo apt update
sudo apt install -y openjdk-17-jdk gradle
# Скопируйте папку server в /opt/breathmonitor/server
cd /opt/breathmonitor/server
chmod +x build.sh start.sh
./build.sh
Сборка создаёт target/breathmonitor-1.0.0.jar. Это самодостаточный shaded JAR, включающий SQLite JDBC и SLF4J. Другой процесс базы данных не нужен.
Для первого запуска от текущего пользователя:
cd /opt/breathmonitor/server
./start.sh create-user aidar
# Введите пароль длиной 1–63 символа
./start.sh create-user anna
./start.sh
Админ-команда сброса пароля:
./start.sh reset-password aidar
Сброс пароля отзывает все веб-сессии и токены привязанных устройств; пароль и привязку придётся ввести заново.
По умолчанию:
- Java-сервер слушает только
127.0.0.1:8090, так что он не доступен напрямую из интернета. - База данных находится в
server/data/statistics.db, журналы вserver/data/logs/<login>/<device-id>/<login>_YYYYMMDD.bin. - Файлы фронтенда читаются из
server/web. - Значения настраиваются переменными
BREATH_PORT,BREATH_BIND,BREATH_DATA_DIR,BREATH_WEB_DIR,PUBLIC_ORIGIN.
Служба systemd
Для постоянного запуска рекомендуется отдельный системный пользователь и каталог данных:
sudo useradd --system --user-group --no-create-home --shell /usr/sbin/nologin breathmonitor || true
sudo mkdir -p /var/lib/breathmonitor
sudo chown -R breathmonitor:breathmonitor /var/lib/breathmonitor
sudo chown -R root:root /opt/breathmonitor/server
sudo cp /opt/breathmonitor/deploy/breathmonitor.service /etc/systemd/system/
sudo systemctl daemon-reload
# Сначала создайте пользователей, используя то же BREATH_DATA_DIR и от имени breathmonitor:
sudo -u breathmonitor env BREATH_DATA_DIR=/var/lib/breathmonitor bash -c 'cd /opt/breathmonitor/server && ./start.sh create-user aidar'
sudo systemctl enable --now breathmonitor
sudo journalctl -u breathmonitor -n 70 --no-pager
Не создавайте сначала пользователей в server/data/, а потом не переключайтесь на /var/lib/breathmonitor: это разные базы данных. При необходимости перенесите каталог данных до запуска службы.
3. Caddy / HTTPS / DNS
Настройте DNS-запись A (и при необходимости AAAA) для breathmonitor.shineup.me на адрес вашего сервера. В вашем существующем Caddyfile добавьте блок из deploy/Caddyfile.fragment, не перезаписывая остальные сайты. Прибор всегда использует https://breathmonitor.shineup.me — адрес уже в .ino.
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -i https://breathmonitor.shineup.me/api/health
Ответ должен быть HTTP 200 и {"ok":true}. Затем откройте сайт в браузере, войдите под созданным логином и паролем.
Текущая версия Caddy сама использует стандартный Let's Encrypt. Это важно, поскольку ROOT_CA прошивки содержит только ISRG Root X1; другой TLS-издатель может не пройти проверку. Если у вас уже есть отдельный wildcard-сертификат, сначала проверьте его цепочку доверия и при необходимости обновите ROOT_CA.
4. Первое подключение прибора
- Установить обновлённую прошивку без стирания FFat/Preferences.
SETTINGS → Wi-Fi → SCAN: выбрать свою сеть, ввести пароль, дождаться успешной проверки. Сеть сохранится.SETTINGS → TIME → SYNC NOW: получить точное время и выключить Wi-Fi. После NTP аппаратные часы продолжают работать автономно.SETTINGS → ONLINE → ACCOUNT → LOGIN: ввести тот же логин, что создали командойcreate-user.PASSWORD: ввести пароль аккаунта;PAIR— одноразово получить токен (или простоONLINE → UPLOAD, и привязка выполнится при первой выгрузке).- Сделать несколько циклов дыхания и нажать
ONLINE → UPLOAD. Увидеть сообщениеDone: ... uploaded. Через браузер обновить страницу статистики. - Последующие загрузки выполняются одним нажатием
UPLOAD; пароль повторно не вводится.
На приборах с заводским/сброшенным RTC перед защищённой отправкой автоматически выполняется NTP. Если отсутствует интернет/NTP, файлы продолжают сохраняться локально; при неудачной синхронизации не удаляются.
5. Формат API (для отладки)
| Метод и путь | Назначение | Авторизация |
|---|---|---|
GET /api/health |
проверка сервера | нет |
POST /api/device/login |
login\npassword\nDEVICEID → 64 шестнадцатеричных символа токена |
пароль пользователя |
PUT /api/device/upload?date=20261024 |
сырое тело .bin, заголовки Authorization: Bearer TOKEN и X-Device-ID: <12 hex> |
токен устройства |
POST /api/login |
логин в браузере | пароль пользователя; cookie с Secure/HttpOnly |
GET /api/me |
профиль | cookie |
GET /api/stats |
личная статистика | cookie |
GET /api/leaderboard |
открытый рейтинг только согласившихся | нет |
POST /api/privacy |
тело true или false, включение публичного рейтинга |
cookie + проверка Origin |
POST /api/logout |
выход | cookie + проверка Origin |
Сервер проверяет каждую 32-байтную запись и CRC32. Если файл уже существует, новая версия обязана полностью содержать старый файл как начальный префикс. Повторная отправка идентичной версии не добавляет циклы; изменение/уменьшение журнала отклоняется с HTTP 409. После проверки файл атомарно заменяется, а суточная статистика пересчитывается и записывается в SQLite через UPSERT. Для разных устройств одного пользователя файлы лежат в отдельных папках.
6. Конфиденциальность, администрирование, резервные копии
- По умолчанию все аккаунты приватные; другие люди не видят их результаты. Пользователь может включить публичный рейтинг в личном кабинете. В рейтинг попадают только агрегированные показатели, не подробные записи.
- Password storage: PBKDF2-HMAC-SHA256 с солью и 210 тыс. итераций. Веб-сессии и токены устройств в БД хранятся как SHA-256-хеши. Базовые ограничения на перебор логина — до 12 попыток с IP за минуту (для публичного большого проекта позже нужен усиленный anti-abuse перед Caddy).
- Важно делать резервные копии и
statistics.db(с учётом SQLite WAL), иdata/logs/. При работающем сервере лучше снимать транзакционный SQLite backup, а не просто копировать открытый файл базы без-wal. - Долговременное сохранение FFat зависит от носителя и состояния питания. Базовую защиту обеспечивают append-only журналы, контроль CRC и серверные копии; для критичных данных нужен дополнительный журнал транзакций/резервирование.
- Сайт не утверждает, что измеряет здоровье или качество медитации. Он показывает только события, зафиксированные прибором.
7. Известные ограничения первой версии
.inoпока не прошёл аппаратную компиляцию, прошивку и испытания на вашей конкретной плате. Исходный LVGL UI, сенсор, IMU и аудио сохранены, но реальный тест кнопок, Wi-Fi и FFat обязателен.- Серверный Java-класс синтаксически компилируется; двоичный тест CRC и декодирования цикла пройден. Полный тест запуска SQLite/JDBC требует загрузки зависимостей Gradle из Maven Central.
- Для простоты передаётся целиком изменившийся суточный файл (а не только его добавленный хвост); при типичном размере десятки КБ это нормально. Загрузка ограничена 16 МиБ на файл.
- Если текущий дневной файл физически повреждён или содержит неполную запись, отправка этого файла отклоняется; прибор не удаляет файл автоматически. Нужна ручная диагностика через
LOG LIST/USB. - При недостоверных часах события попадают в
undated.bin. Автоматически приписывать им выдуманную дату нельзя: их можно учесть в общей сумме, но не привязать надёжно к календарному дню без дополнительной информации. - Суточная дата задаётся фиксированным UTC-смещением в настройках прибора (автоматический переход на летнее/зимнее время пока не предусмотрен).
- Изменение времени/смещения суток не переименовывает уже записанные файлы. В случае некорректного времени возможен дневной файл с неправильной датой; хранящиеся в каждой записи UTC и флаг доверия дают возможность дальнейшей коррекции.
- Устройства на одном аккаунте считаются вместе. Разные физические устройства должны иметь разные ID ESP32. В первой версии прибор рассчитан на одного владельца: после успешной привязки вход в другой аккаунт с того же прибора заблокирован, чтобы не загрузить личную историю прежнего владельца в чужой аккаунт. Для передачи устройства другому человеку нужно сначала экспортировать/архивировать журналы и безопасно сбросить локальное хранилище и Preferences (реализация безопасного сброса — отдельная задача).
- Регистрация пользователей выполняется администратором через CLI; самостоятельная регистрация на сайте не реализована.
- В
ONLINE → REUPLOADудаляется только локальный индекс выгрузок. Если сервер получил отличающуюся старую историю, он вернёт HTTP 409: безопаснее исследовать конфликт, чем автоматически переписать старые данные.
8. Проверки до ежедневного использования
- Питание OFF/ON посреди дня → количество 32-байтных записей в текущем файле увеличивается, записи не исчезают.
- Переход через полночь по настроенному времени → создаётся новый датированный файл.
- Сохранённая Wi-Fi сеть недоступна → устройство предлагает список сетей и затем продолжает именно TIME/UPLOAD.
- Отключение интернет-кабеля во время отправки → файл на приборе остаётся, повторная синхронизация работает.
- Повторный
UPLOADбез новых циклов → нет дублей статистики. - Появление новых циклов во время отправки → в следующей синхронизации сервер получает расширенный файл.
- Сброс часов RTC → новые события идут в
undated.binдо синхронизации. - Новый пользователь/новый токен → доступ только к своим файлам, публичный рейтинг по умолчанию пустой.
- Перед прошивкой заранее выгрузить старый
/events.binпо USB и сравнить запись после миграции.
Локальный тест Java без JDBC
cd server
javac --release 21 BreathServer.java RecordFixtureTest.java
java RecordFixtureTest
Ожидаемый ответ: PASS: 32-byte little-endian event, duration and CRC32 validation.
После первого запуска я рекомендую следующий этап: сделать диагностический экран «свободно FFat / не выгружено / ошибка последней передачи» и веб-функцию загрузки журнала вручную с компьютера. Это облегчит восстановление и сопровождение приборов, когда пользователей станет больше.