7.0 KiB
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
Безопасный порядок обновления:
- Локально собрать и проверить JAR.
- Передать только JAR во временный файл на VPS через
rsync. - Сделать копию текущего JAR и проверить права.
- Атомарно заменить JAR, не удаляя
/var/lib/breathmonitor. - Перезапустить только
breathmonitor.service. - Проверить
systemctl status breathmonitorиcurl https://breathmonitor.shineup.me/api/health. - 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.