Files

7.0 KiB
Raw Permalink Blame History

AGENTS — BreathMonitor v3

Назначение

Эта папка содержит третью версию автономного ESP32-монитора дыхания и отдельный Java/SQLite-сервер.

  • firmware/ — прошивка для Waveshare ESP32-S3-Touch-AMOLED-2.16.
  • server/ — исходники Java-сервера, Gradle-сборка и веб-интерфейс.
  • deploy/ — шаблон systemd-службы и отдельный фрагмент Caddy.

Обязательные правила

  • Все изменения этого проекта относятся к репозиторию SKETCH, не смешивать их с коммитами SHiNE-product.
  • Основной язык документации и пояснений — русский.
  • Не удалять FFat при обновлении прошивки. Не использовать Erase All Flash, если нужно сохранить локальные журналы.
  • Если при старте появляется STORAGE ERROR, нажимать FORMAT FFat только после проверки/резервирования локальных журналов; без подтверждения прошивка форматирование не выполняет.
  • Перед прошивкой убедиться, что выбрана схема app3M_fat9M_16MB.
  • Не менять формат записей журналов и API без отдельного согласования: сервер проверяет 32-байтные записи, CRC32 и префиксную целостность загрузок.
  • Не хранить пароли, токены, SQLite-базу и реальные серверные секреты в git.

Прошивка

Плата и библиотеки такие же, как у breathmonitor_v2 lvgl. firmware/burn.sh использует библиотеки из:

SHiNE-product/ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/official-demo/examples/Arduino-v3.3.5/libraries

Сборка без загрузки:

cd "SKETCH/breath_button_monitor/breathmonitor_v3 with server/firmware"
NO_UPLOAD=1 ./burn.sh

Загрузка на подключённую плату:

PORT=/dev/ttyACM0 ./burn.sh

Скрипт использует ESP32 core 3.3.5, FQBN с 16 MB Flash, PSRAM OPI и разделом app3M_fat9M_16MB. Перед загрузкой проверить порт командой arduino-cli board list.

Серверная сборка

Сервер всегда собирается локально. VPS не должен запускать Maven, Gradle или компилятор.

cd "SKETCH/breath_button_monitor/breathmonitor_v3 with server/server"
./gradlew --no-daemon clean shadowJar

Требуется JDK 17. Результат:

server/build/libs/breathmonitor-1.0.0.jar

Проверить локально запуск и health можно так:

BREATH_DATA_DIR="$PWD/.local-data" \
BREATH_WEB_DIR="$PWD/web" \
PUBLIC_ORIGIN="https://breathmonitor.shineup.me" \
java -jar build/libs/breathmonitor-1.0.0.jar

Для VPS передаётся только готовый JAR и при необходимости статические файлы web/. Не выполнять на VPS build.sh, gradlew, mvn или компиляцию.

Деплой сервера

Целевой адрес: breathmonitor.shineup.me, VPS: 178.208.90.249. SSH-пользователь текущего тестового контура — player.

Постоянные пути на VPS:

  • приложение: /opt/breathmonitor/server
  • JAR: /opt/breathmonitor/server/build/libs/breathmonitor-1.0.0.jar
  • данные SQLite и журналы: /var/lib/breathmonitor
  • systemd unit: /etc/systemd/system/breathmonitor.service
  • Caddy: /etc/caddy/Caddyfile
  • внутренний HTTP-порт: 127.0.0.1:8090

Безопасный порядок обновления:

  1. Локально собрать и проверить JAR.
  2. Передать только JAR во временный файл на VPS через rsync.
  3. Сделать копию текущего JAR и проверить права.
  4. Атомарно заменить JAR, не удаляя /var/lib/breathmonitor.
  5. Перезапустить только breathmonitor.service.
  6. Проверить systemctl status breathmonitor и curl https://breathmonitor.shineup.me/api/health.
  7. Caddy не перезапускать при обычном обновлении JAR. Перезагрузка Caddy нужна только при изменении его конфигурации.

Пример передачи готового артефакта:

rsync -az server/build/libs/breathmonitor-1.0.0.jar \
  player@178.208.90.249:/tmp/breathmonitor-1.0.0.jar

Дальнейшая замена требует SSH/sudo-доступа и выполняется отдельно от сборки. При недоступном VPS не повторять сборку удалённо и не трогать существующие сервисы.

Первый запуск и аккаунт

Сервис запускается от системного пользователя breathmonitor и использует BREATH_DATA_DIR=/var/lib/breathmonitor.

Создание аккаунта выполняется один раз на VPS с тем же каталогом данных:

sudo -u breathmonitor env BREATH_DATA_DIR=/var/lib/breathmonitor \
  /opt/breathmonitor/server/start.sh create-user aidar

Текущая версия допускает пароль длиной от 1 до 63 символов. Короткие пароли допустимы только для закрытого тестового контура; для публичного использования нужен длинный пароль.

Проверки после обновления

curl -fsS https://breathmonitor.shineup.me/api/health
sudo systemctl is-active breathmonitor
sudo journalctl -u breathmonitor -n 70 --no-pager

После прошивки на приборе проверить Wi-Fi, синхронизацию времени, ONLINE → ACCOUNT, PAIR, затем UPLOAD. Журналы на устройстве не удалять при диагностике; использовать USB-команды LOG INFO, LOG LIST и LOG DOWNLOAD <дата>.

Резервирование

Резервировать нужно SQLite-базу с учётом WAL и каталог журналов:

  • /var/lib/breathmonitor/statistics.db
  • /var/lib/breathmonitor/statistics.db-wal
  • /var/lib/breathmonitor/statistics.db-shm
  • /var/lib/breathmonitor/logs/

Не заменять каталог данных при обновлении приложения и не выполнять rsync --delete по /var/lib/breathmonitor.