retro-home

This repository manages the software, configuration, and deployment for the Retro Home base unit, a Raspberry Pi device that serves as the core of the Retro communication system.

The overall Retro project aims to facilitate communication enhanced with AI-powered transcription and agentic features tailored for older adults. This retro-home component is responsible for running key on-device software, interfacing with hardware, and connecting securely to the broader Retro ecosystem (cloud services, telephony infrastructure, companion apps, and the paired retro-handset).

Key On-Device Software Components

This repository handles the deployment and management of several core functional components running directly on the Raspberry Pi:

• SIP Client: Manages VoIP calls and signaling connections (Implemented using Baresip).
• Audio Engine: Manages audio streams, routing between interfaces (handset, speakerphone, external), and local processing (e.g., echo cancellation, gain control).
• Hardware Interface: Bridges physical hardware events (GPIO buttons, sensors) to the system, typically via the local message bus.
• Local Message Bus: Facilitates inter-process communication between components (Implemented using Mosquitto).
• Web Applications: Two SvelteKit apps:
  • Onboarding App: Minimal app to guide the user through Wi-Fi setup, service claim, and handset pairing.
  • Main App: Full-featured UI and backend logic for calls, settings, and interactions.
• Kiosk Browser: Renders the appropriate web app in fullscreen (Implemented using Chromium).
• Provisioning Services: Handles specific, often transient, setup tasks like Wi-Fi provisioning and handset pairing.
• Local Data Storage: Manages persistent data on the device, utilizing ElectricSQL for application data synced with the cloud, alongside local mechanisms for configuration.

Directory Layout

/opt/
  ├── app/                # Main SvelteKit app (post-onboarding)
  ├── onboarding/         # Minimal onboarding UI
  ├── sip/                # Baresip config, wrappers, launch helpers
  ├── io/                 # Long-running hardware daemons (GPIO handlers, audio interfaces)
  ├── scripts/            # One-shot utilities and boot-time entrypoints (e.g. Chromium launcher)
  └── identity/           # Secure identity artifacts (PSK, serials, etc)

Process Management

• systemd is used for:

  • Core OS services (e.g. Mosquitto)
  • One-shot provisioning units (e.g. Wi-Fi setup, first-boot hooks)
  • Top-level orchestration target (home.target) for startup order

• pm2 is used for:

  • Chromium kiosk (launched via a script that switches between onboarding and main UI)
  • SvelteKit apps (onboarding and main)
  • Hardware daemons in io/
  • Baresip (to simplify respawning, logs, etc)

Justfile Tasks

The repo uses a justfile to standardize commands based on the system's lifecycle phases. Each phase has corresponding tasks to build, sync, and manage components. All tasks are flat and explicitly scoped to individual assets to allow granular control.

Manufacturing

just setup-ssh             # Configure SSH and local access
just provision-device      # Generate serial and initial PSK for the device

App Build

just build-app             # Build main SvelteKit app (UI/backend)
just build-onboarding      # Build onboarding SvelteKit app

Sync to Device

just sync-app              # Sync built main app to /opt/app
just sync-onboarding       # Sync built onboarding app to /opt/onboarding
just sync-config-baresip   # Sync baresip config to ~/.baresip
just sync-config-mosquitto # Sync mosquitto config to /etc/mosquitto/
just sync-runtime-buttons  # Sync GPIO hardware interface script
just sync-runtime-audio    # Sync audio-related daemon scripts
just sync-script-launchers # Sync chromium and entrypoint scripts

Service Activation & Management

# --- Systemd (Core OS Services & PM2 Daemon Boot) ---
just systemd-enable-services # Enable systemd services (e.g., mosquitto) & pm2 daemon for auto-start on boot
just systemd-status          # Show systemd unit status (e.g., systemctl status mosquitto pm2-*)
just systemd-logs            # View journal logs for systemd units (e.g., mosquitto, pm2 daemon startup)

# --- PM2 (Application Processes) ---
just pm2-start             # Start/restart applications managed by pm2 (apps, baresip, etc.) *now*
just pm2-save              # Save current pm2 process list for auto-resurrection on boot (by pm2 daemon)
just pm2-status            # Show status of all pm2-managed application processes
just pm2-logs              # Tail logs for all pm2-managed application processes
just pm2-stop-all          # Stop all pm2-managed application processes
just pm2-restart-all       # Restart all pm2-managed application processes

Onboarding

just start-onboarding      # Launch onboarding flow manually (runs Chromium + SvelteKit app)
just reset-onboarding      # Clear Wi-Fi and auth to re-enter onboarding

Pairing & Post-Onboarding

just start-pairing         # Trigger handset pairing flow
just test-pairing          # Debug/test pairing server and AP logic

Main App

just start-app      # Runs Chromium + SvelteKit app

Dev Utilities

just ssh                 # SSH into the Pi (shortcut)

---

Phase 0: Manufacturing/Pre-Setup

Goal: Prepare the physical hardware with the base operating system image before any device-specific configuration begins. This phase typically occurs in a controlled environment before the device is shipped or handed over for detailed setup.

• Base OS Installation:
  • Flash the designated version of the base operating system (e.g., Raspberry Pi OS Lite) onto the storage medium (SD card).
  • Configure hostname, timezone, locale, and initial user during OS installation.
  • Enable SSH and set up initial user credentials.

Phase 1: Initial Device Configuration

Goal: Configure the device's basic identity, access, and OS parameters after the base OS is flashed. (Run once during initial provisioning).

• Development/Access Environment:
  • Configure initial SSH access (e.g., copy SSH public key via ssh-copy-id, create ~/.ssh/config alias retro.home).
• Device Identity Generation:
  • Generate software-based unique identifiers (e.g., PSK based on hardware ID) if not done/provided in Phase 0.
  • Securely store these identifiers (e.g., in /opt/identity/).
  • Make identifiers available securely for later phases (e.g., via environment file or permissions).

Phase 2: Software Installation & Updates

Goal: Install and subsequently update all necessary software components, configurations, and drivers. (Run initially after Phase 1 and repeatedly for ongoing maintenance and feature releases).

• System Package Management:
  • Install/Upgrade essential OS packages via apt (e.g., zsh, git, curl, python3-pip, python3-gpiozero, nodejs, network utils, build tools).
  • Install/Upgrade core services via apt (e.g., mosquitto, baresip).
• Runtimes & Tools:
  • Install/Upgrade language runtimes/managers (e.g., bun).
  • Install/Upgrade global tools (e.g., pm2).
• Drivers & Hardware Config:
  • Install/Update specific hardware drivers (e.g., ReSpeaker setup using pip, git clone, dfu.py).
  • Apply/Update system hardware configurations (e.g., modify /boot/firmware/config.txt for display, audio, interfaces; configure ALSA settings).
• Shell Environment:
  • Install/Configure user shell enhancements (e.g., oh-my-zsh, themes, plugins in .zshrc).
• Application Deployment:
  • Build the SvelteKit app locally (cd app && bun install && bun run build).
  • Copy built artifacts to the remote application directory (e.g., /opt/app/).
  • Do the same for the onboarding app (/opt/onboarding/).
• Configuration Deployment:
  • Copy/Update Baresip configuration files to /opt/sip/.
  • Copy/Update Mosquitto configuration file to /etc/mosquitto/conf.d/.
• Runtime Deployment:
  • Copy io/ Python/Bun daemons to /opt/io/
  • Copy one-shot provisioning utilities to /opt/scripts/

Phase 3: Service Activation (Automatic on Boot)

Goal: Ensure all necessary services start automatically when the device powers on using the currently installed configuration. (Runs every boot).

• Process Management:
  • Services managed by pm2 (App, Onboarding, Browser, Baresip, Hardware Interface) are configured for persistence (pm2 save).
  • System services (Mosquitto, home.target) are enabled via systemctl enable.

Phase 4: User Onboarding (First Use / Factory Reset)

Goal: Guide the user through connecting the device to their network and associating it with the service. (Runs when the user first sets up the device or after a factory reset).

• Network Connection: Connect the device to the local Wi-Fi network, typically guided by the device's own screen and the onboarding app.
• Service Association: Link the physical device to the user's household/account within the broader service ecosystem (e.g., via a claim code or QR confirmed by an authorized user in a companion app or portal).
• Household Setup: Associate family and friend contacts and define their roles/permissions (managed via the companion app/web portal, potentially initiated during onboarding).
• Telephony Configuration: Assign or confirm the device's primary phone number.

Phase 5: System Formalization (Post-Onboarding)

Goal: Finalize device configuration, backend authentication, and peripheral pairing after user setup is complete. (Triggered automatically after successful user onboarding in Phase 4).

• Device Authentication: Securely authenticate the device to the backend by exchanging its unique identifiers (PSK/Serial generated in Phase 1) for operational authentication tokens (e.g., JWTs). This token is used for all subsequent API interactions.
• Peripheral Pairing (Handset):
  • Temporarily launch Wi-Fi AP mode via hostapd
  • Handset connects and receives credentials over a local pairing channel (MQTT or HTTP)
  • Both devices reboot and rejoin the real network
• Service Registration: Register with cloud services (e.g., SIP registry, ElectricSQL).