- Python 56.9%
- Java 36.2%
- JavaScript 6.9%
| .agents | ||
| .claude/skills | ||
| .cursor/skills | ||
| .forgejo | ||
| android | ||
| device | ||
| docs | ||
| linux-hub | ||
| simulator | ||
| .gitattributes | ||
| .gitignore | ||
| AGENTS.md | ||
| ARCHITECTURE.md | ||
| CLAUDE.md | ||
| GITFLOW.md | ||
| README.md | ||
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. Ссылка на публичный репозиторий
- Репозиторий: https://git.rznz.dev/rznz/signal-lost
- Архитектура: ARCHITECTURE.md
- Процесс разработки: GITFLOW.md и AGENTS.md
- Журнал AI-промптов:
docs/prompts/
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 pytestcd 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.