How ubopod/ubo_app works
Project type and purpose
• Ubo App is an embedded-device management application for Raspberry Pi (4/5), exposing a local GUI and a gRPC API to control hardware (Wi-Fi, camera, audio, sensors) and system services (Docker, SSH, VS Code).
• It’s packaged as a Python service suite (with systemd templates), integrates a Kivy-based UI, a Redux-inspired event store, pluggable “services” modules, and a web UI (React/TypeScript) served via one of those modules.
File structure
Top-level layout:
• scripts/ & .github/workflows/ – CI/CD, Dockerfiles, Packer definitions, test and deploy scripts
• ubo_app/ – core application code
– main.py, bootstrap.py – application entry & startup
– menu_app/ – Kivy GUI definitions (.kv + Python controllers)
– rpc/ – gRPC server, proto definitions, generator utilities
– services/ – individual feature modules (audio, display, wifi, docker, etc.) following a common “setup → reducer → ubo_handle” pattern
– store/ – central event bus and state management (core, input, services, scheduler, update manager)
– system/ – system-level scripts/templates (hotspot, systemd units, installers)
– utils/ – shared helpers (DBus, threading, network, serialization)
• tests/ – unit, integration, flow-based snapshot tests
• services/090-web-ui/web-app/ – standalone React/TS web frontend with its own build pipeline
README for architectural insights
• Describes a headless-friendly UI + hardware-fallback routes (e.g. QR code, text file)
• Emphasizes gRPC API for remote control
• Mentions Buf/protobuf codegen and web app build steps
• Indicates systemd deployment & packaging under /opt/ubo
Main components & interactions
a. Core Launcher
– Entry point: ubo_app/main.py → bootstrap
– Initializes System Manager (hardware & OS provisioning) and Core Store
b. System Manager (ubo_app/system/system_manager)
– Low-level scripts & templates for OS services (hotspot, docker, sensors)
– Installs/configures systemd units, handles device setup
c. Event Store (ubo_app/store)
– Redux-style “actions → reducer → new state”
– Central dispatch_action and scheduler for sequencing tasks
d. Services (ubo_app/services/…)
– Pluggable modules, each with:
• setup() – register with store
• reducer() – handle state transitions
• ubo_handle() – side-effects (hardware calls via utils)
– Example: wifi manager uses picamera2, network utils, and store events to show QR codes
e. GUI (ubo_app/menu_app)
– Kivy screens (.kv files) bound to Python controllers
– Subscribes to store updates, dispatches UI actions
f. gRPC API (ubo_app/rpc/server.py)
– Exposes store-dispatching methods over network
– Messages generated from .proto files (buf.yaml)
g. Web UI service (services/090-web-ui)
– Hosts React/TS assets via an HTTP endpoint
– Communicates with local store/rpc for real-time display
h. External tools & packaging
– Packer & Docker for test/dev images
– systemd templates for automatic startup on Pi
– Scripts for installation, tests, codegen (uv, poe tasks)
Architectural patterns & design principles
• Modular “service” micro-kernel: each hardware feature lives in its own module, communicates via a shared store
• Unidirectional data flow (Redux) – clear tracing of actions → state → view
• Asynchronous tasks use a shared event loop (asyncio + custom create_task)
• Plugin pattern for discoverable services (setup functions auto-register)
• Separation of concerns: System vs. Core vs. UI vs. RPC layers