Files
Sketches/breath_button_monitor/breathmonitor_v3 with server/README_RU.md
T

22 KiB
Raw Blame History

BreathMonitor — автономный прибор + Java/SQLite сервер

Комплект для развёртывания · 24 октября 2026 года
Адрес API и сайта уже задан: https://breathmonitor.shineup.me

Это исходники готовой первой интеграционной версии, а не подтверждённая сборка для конкретной платы: Java-код и парсер рассчитаны на JDK 17, но .ino требуется собрать в Arduino IDE с исходными библиотеками и проверить на физическом ESP32-S3. Интернет в среде сборки отсутствовал, поэтому готовый исполняемый JAR с SQLite JDBC не вложен: server/build.sh соберёт его Gradle, скачав зависимости из Maven Central.

Содержимое

firmware/breathmonitor_lvgl.ino       — изменённый скетч (исходный UI, измерения, RTC)
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 статистика
deploy/Caddyfile.fragment              — пример секции для Caddy
deploy/breathmonitor.service           — пример службы systemd

1. Изменения прибора

  • Без постоянного Wi-Fi. После загрузки радиомодуль выключен. Операция TIME → SYNC NOW подключает известную сеть, синхронизирует NTP+RTC, выключает Wi-Fi. ONLINE → UPLOAD делает то же самое для передачи журналов. Wi-Fi → TEST проверяет доступность сети и отключает модуль.
  • До восьми сохранённых 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 → ACCOUNT: ввести логин и пароль учётной записи сайта, затем PAIR или сразу UPLOAD. Введённый пароль живёт в RAM до авторизации; хранится отдельный токен устройства в Preferences. После перезагрузки пароль не нужен.
  • ONLINE → REUPLOAD очищает только индекс отправленных размеров /sync.state, не сами журналы. При следующем UPLOAD прибор повторно отправит все дневные файлы (сервер не дублирует циклы).
  • Передача 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. Первое подключение прибора

  1. Установить обновлённую прошивку без стирания FFat/Preferences.
  2. SETTINGS → Wi-Fi → SCAN: выбрать свою сеть, ввести пароль, дождаться успешной проверки. Сеть сохранится.
  3. SETTINGS → TIME → SYNC NOW: получить точное время и выключить Wi-Fi. После NTP аппаратные часы продолжают работать автономно.
  4. SETTINGS → ONLINE → ACCOUNT → LOGIN: ввести тот же логин, что создали командой create-user.
  5. PASSWORD: ввести пароль аккаунта; PAIR — одноразово получить токен (или просто ONLINE → UPLOAD, и привязка выполнится при первой выгрузке).
  6. Сделать несколько циклов дыхания и нажать ONLINE → UPLOAD. Увидеть сообщение Done: ... uploaded. Через браузер обновить страницу статистики.
  7. Последующие загрузки выполняются одним нажатием 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. Известные ограничения первой версии

  1. .ino пока не прошёл аппаратную компиляцию, прошивку и испытания на вашей конкретной плате. Исходный LVGL UI, сенсор, IMU и аудио сохранены, но реальный тест кнопок, Wi-Fi и FFat обязателен.
  2. Серверный Java-класс синтаксически компилируется; двоичный тест CRC и декодирования цикла пройден. Полный тест запуска SQLite/JDBC требует загрузки зависимостей Gradle из Maven Central.
  3. Для простоты передаётся целиком изменившийся суточный файл (а не только его добавленный хвост); при типичном размере десятки КБ это нормально. Загрузка ограничена 16 МиБ на файл.
  4. Если текущий дневной файл физически повреждён или содержит неполную запись, отправка этого файла отклоняется; прибор не удаляет файл автоматически. Нужна ручная диагностика через LOG LIST/USB.
  5. При недостоверных часах события попадают в undated.bin. Автоматически приписывать им выдуманную дату нельзя: их можно учесть в общей сумме, но не привязать надёжно к календарному дню без дополнительной информации.
  6. Суточная дата задаётся фиксированным UTC-смещением в настройках прибора (автоматический переход на летнее/зимнее время пока не предусмотрен).
  7. Изменение времени/смещения суток не переименовывает уже записанные файлы. В случае некорректного времени возможен дневной файл с неправильной датой; хранящиеся в каждой записи UTC и флаг доверия дают возможность дальнейшей коррекции.
  8. Устройства на одном аккаунте считаются вместе. Разные физические устройства должны иметь разные ID ESP32. В первой версии прибор рассчитан на одного владельца: после успешной привязки вход в другой аккаунт с того же прибора заблокирован, чтобы не загрузить личную историю прежнего владельца в чужой аккаунт. Для передачи устройства другому человеку нужно сначала экспортировать/архивировать журналы и безопасно сбросить локальное хранилище и Preferences (реализация безопасного сброса — отдельная задача).
  9. Регистрация пользователей выполняется администратором через CLI; самостоятельная регистрация на сайте не реализована.
  10. В 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 / не выгружено / ошибка последней передачи» и веб-функцию загрузки журнала вручную с компьютера. Это облегчит восстановление и сопровождение приборов, когда пользователей станет больше.