Signal Lost — физическо-цифровая квест-система на базе Raspberry Pi (Linux) и Android (Java)
  • Python 56.9%
  • Java 36.2%
  • JavaScript 6.9%
Find a file
2026-10-27 09:43:09 +03:00
.agents feat(issue-14): connect Android operator terminal to hub 2026-10-27 09:43:09 +03:00
.claude/skills docs(issue-1): bootstrap AI development workflow (#2) 2026-09-20 17:51:52 +03:00
.cursor/skills docs(issue-1): bootstrap AI development workflow (#2) 2026-09-20 17:51:52 +03:00
.forgejo docs(issue-1): bootstrap AI development workflow (#2) 2026-09-20 17:51:52 +03:00
android feat(issue-14): connect Android operator terminal to hub 2026-10-27 09:43:09 +03:00
device feat(issue-6): scaffold Android, Raspberry Pi hub, and GPIO HAL modules 2026-10-20 10:19:59 +03:00
docs feat(issue-14): connect Android operator terminal to hub 2026-10-27 09:43:09 +03:00
linux-hub feat(issue-10): broadcast hub state changes over WebSocket 2026-10-27 09:25:32 +03:00
simulator feat(issue-11): add Node-RED physical panel simulator 2026-10-27 09:41:28 +03:00
.gitattributes feat(issue-6): scaffold Android, Raspberry Pi hub, and GPIO HAL modules 2026-10-20 10:19:59 +03:00
.gitignore feat(issue-11): add Node-RED physical panel simulator 2026-10-27 09:41:28 +03:00
AGENTS.md docs(issue-4): replace ESP32 with unified Raspberry Pi controller 2026-10-20 10:06:08 +03:00
ARCHITECTURE.md feat(issue-14): connect Android operator terminal to hub 2026-10-27 09:43:09 +03:00
CLAUDE.md docs(issue-1): bootstrap AI development workflow (#2) 2026-09-20 17:51:52 +03:00
GITFLOW.md docs(issue-1): bootstrap AI development workflow (#2) 2026-09-20 17:51:52 +03:00
README.md feat(issue-14): connect Android operator terminal to hub 2026-10-27 09:43:09 +03:00

Signal Lost

Signal Lost — интерактивная физическо-цифровая квест-система на базе Raspberry Pi (Linux) и Android (Java).

1. Участники проекта

  • Валов Иван Игоревич — @echo1
  • Жуланов Никита Андреевич — @rznz (@roazanas)
  • Щербаков Андрей Сергеевич — @dudll

2. Тема проекта

Signal Lost — физическо-цифровая квест-система на базе Raspberry Pi (embedded Linux) и Android.

Проект представляет собой интерактивный аппаратный стенд в тематике аварийной исследовательской станции. Для восстановления её систем игрокам необходимо совместно использовать физическую панель управления на базе Raspberry Pi и мобильное Android-приложение оператора. Сервис на Raspberry Pi опрашивает физические органы управления по GPIO, управляет индикацией и периферией, исполняет сценарный движок и синхронизирует состояние с Android-клиентом по локальной сети.

3. Задачи проекта

  • Собрать аппаратный стенд на базе Raspberry Pi с подключением кнопок, тумблеров, инкрементального энкодера, светодиодной индикации, дисплея, RFID/NFC, звукового оповещения и сервопривода/замка через GPIO и периферийные шины.
  • Реализовать не менее трёх связанных головоломок в едином сценарии: запуск питания, настройка канала связи и ввод аварийного протокола подтверждения.
  • Разработать на Raspberry Pi (Linux) сервис управления периферией и сценарный движок (Python, FastAPI, GPIO/периферийные драйверы) с конечным автоматом сценария, REST API, передачей событий в реальном времени (WebSocket) и локальным хранением результатов прохождения.
  • Создать Android-приложение на Java (актуальный Android SDK, Android Studio) с терминалом оператора: сюжетными журналами, асимметричными инструкциями, подсказками, таймером сессии и отображением состояния систем станции в реальном времени.
  • Опционально реализовать синхронизацию итоговой статистики прохождения и удалённое администрирование через внешний VPS-сервер без потери автономности локальной игры.
  • Реализовать параметризацию сценариев (изменение кодов, целевых частот и порогов при повторном запуске) без жёсткого кодирования сюжета в драйверах GPIO.
  • Подготовить документацию по архитектуре (ARCHITECTURE.md), сборке стенда, запуску системы и использованным при разработке AI-промптам (docs/prompts/).

4. Ожидаемый результат к декабрю 2026 года

Работающий прототип физическо-цифровой квест-системы с единым сценарием продолжительностью около 10–20 минут и не менее чем тремя связанными головоломками:

  • Raspberry Pi (embedded Linux) считывает физические действия игроков (тумблеры, кнопки, энкодер, датчики), управляет индикацией и исполнительными механизмами, ведёт состояние сценария, предоставляет REST/WebSocket API и сохраняет время прохождения, ошибки и использованные подсказки.
  • Android-приложение (Java) предоставляет оператору сюжетные журналы, схемы, подсказки, таймер и статус узлов в реальном времени.
  • Документация и репозиторий содержат описание архитектуры, спецификацию API и сценариев, инструкции по сборке и развёртыванию, а также журнал AI-промптов.

5. Ссылка на публичный репозиторий

6. Структура репозитория и быстрый старт

Модуль Описание Локальный запуск / проверка
device/ Слой аппаратной абстракции Raspberry Pi (GPIO HAL, распиновка BCM, MockHardwareAdapter для локальной разработки и тестов без физической платы) cd device && uv run pytest
linux-hub/ Сценарный движок и локальный сервер на базе FastAPI (GET /api/v1/health, GET /api/v1/status, POST /api/v1/events, POST /api/v1/session/reset, WebSocket /ws) cd linux-hub && uv run pytest
cd linux-hub && uv run uvicorn signal_lost_hub.app:app --reload
android/ Мобильное приложение терминала оператора на Java (Android SDK 37, Gradle) cd android && ./gradlew testDebugUnitTest assembleDebug
simulator/ Физическая панель без платы: Node-RED + FlowFuse Dashboard, два тумблера, кнопка, индикация и дисплей cd simulator && npm ci && npm start
Панель: http://127.0.0.1:1880/dashboard/panel; проверки: npm test
docs/ Архитектурные решения, инварианты и журнал использованных AI-промптов (docs/prompts/) —

Обновления состояния в реальном времени

После подключения к /ws клиент получает snapshot. После каждого принятого аппаратного события и сброса сессии сервер самостоятельно рассылает state_changed всем подключённым клиентам. Поле data совпадает по структуре с GET /api/v1/status и содержит state_revision; ревизия увеличивается и сохраняет последовательность при сбросе игры. JSON {"type":"ping"} по-прежнему получает ответ pong с текущим состоянием.

Для проверки запустите hub, подключите два WebSocket-клиента к ws://localhost:8000/ws и отправьте событие через POST /api/v1/events: оба клиента должны получить обновление без дополнительных запросов. Медленные клиенты отключаются отдельно и после переподключения получают свежий snapshot.

Hub запускается одним процессом; текущая сессия и ревизия пока хранятся в памяти. При тестировании используйте контекст with TestClient(create_app()) as client:, чтобы запустить и завершить очередь обработки. Подробности протокола и подключения GPIO-производителей описаны в ARCHITECTURE.md.

Симулятор запускается отдельно от FastAPI и работает с MockHardwareAdapter. Нужна WebSocket-рассылка из #10 / PR #12. Установка, импорт flow, HUB_HTTP_URL / HUB_WS_URL и проверка сброса/переподключения описаны в simulator/README.md. Сценарная логика остаётся в hub; инструкции Android-оператора панель не отображает.

Android получает актуальную фазу и операторские статусы из linux-hub через OkHttp (GET /api/v1/status и /ws), сохраняет введённый адрес и восстанавливает связь автоматически. Для эмулятора используйте http://10.0.2.2:8000, для телефона — адрес hub в общей сети или adb reverse. Подключение, разрешение локальной сети Android 17 и сборка APK описаны в android/README.md. Нужен протокол рассылки из PR #12; проверка панели использует PR #13.