Survon Base Runtime

This is a Ratatui-based terminal UI application for Survon, an offline modular survival system focused on resilience for off-grid scenarios.

System Architecture

Survon is designed as a modular IoT hub that bridges physical hardware with a unified terminal interface. The system intercepts sensor data and device commands from various sources—USB peripherals, Bluetooth devices, radio modules, and custom IoT hardware—and presents them through a real-time TUI.

Example use cases:

• Remote gate control: An Arduino-based controller sends open/close commands via radio to the Survon hub
• Environmental monitoring: Pressure sensors, temperature gauges, and water flow meters transmit data wirelessly from distributed locations around the homestead
• Equipment status: Monitor well pumps, generators, or greenhouse automation systems through standardized Survon-compatible payloads

The runtime uses a message bus architecture to route events between hardware modules and UI components. Compatible hardware can be built using Survon protocol adapters (or third-party implementations) on microcontrollers like Arduino, ESP32, or similar platforms. These devices broadcast sensor readings and accept commands via radio (LoRa, 433MHz), Bluetooth, or direct serial connection to the Raspberry Pi hub.

All sensor data, control commands, and system events flow through the central message bus, enabling real-time monitoring and control of homestead infrastructure from a single interface.

Architecture Summary

┌───────────────────────────────────────────────────────────┐
│                        Survon Hub                         │
│                                                           │
│  ┌──────────────┐         ┌──────────────┐                │
│  │   Modules    │◄───────►│ Message Bus  │                │
│  │  (Pressure,  │         │ (BusMessage) │                │
│  │   Gate, etc) │         └──────┬───────┘                │
│  └──────────────┘                │                        │
│                                  │                        │
│  ┌───────────────────────────────┼─────────────────────┐  │
│  │        Serial/Transport Manager                     │  │
│  │                                                     │  │
│  │  Inbound:  SspMessage → BusMessage                  │  │
│  │  Outbound: BusMessage → SspMessage                  │  │
│  │                                                     │  │
│  │  Routing Table: device_id → (transport, address)    │  │
│  └───────────────────────┬─────────────────────────────┘  │
└──────────────────────────┼────────────────────────────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
         ┌────▼───┐    ┌───▼────┐   ┌───▼────┐
         │  BLE   │    │ Radio  │   │  USB   │
         └────┬───┘    └───┬────┘   └───┬────┘
              │            │            │
         (Arduino)    (Arduino)    (Arduino)

Installation

Clone and build manually, or use the Survon OS installer for RPi 3B (armhf):

Council System

The Council system is a multi-member advisory system that provides intelligent guidance and decision support for the Survon smart homestead.

Features

• Multi-member Support: Multiple council members with different expertise areas
• Expertise Routing: Queries automatically routed to appropriate advisors
• Consensus Building: Builds consensus from multiple council member responses
• Real-time Communication: Message-based communication with advisors
• CLI Integration: Command-line interface for council management
• UI Interface: Interactive chat interface for council interaction

Quick Start

Via CLI

# Start council chat
./target/release/runtime-base-rust council chat --advisor hardware_expert --query "What is the current system status?"

# Check council status
./target/release/runtime-base-rust council status

# List available advisors
./target/release/runtime-base-rust council advisors list

# Run council tests
./target/release/runtime-base-rust council test --all

Via UI

1. Start the Survon application: ./target/release/runtime-base-rust
2. Press Tab to navigate to council interface
3. Use arrow keys to select advisors
4. Press Enter to send messages
5. Use Esc to return to overview

Available Advisors

Advisor	Expertise	Description
hardware_expert	Device management	Hardware troubleshooting and device management
knowledge_base	Information retrieval	Knowledge base queries and documentation
system_monitor	System health	System performance and health monitoring
security_specialist	Security	Security and access control specialist

Documentation

For complete council system documentation, see:

• Council Usage Guide
• Council Architecture
• Council API Reference

Installation Commands

Clone and build manually, or use the Survon OS installer for RPi 3B (armhf):

curl -sSL https://raw.githubusercontent.com/survon/survon-os/master/scripts/install.sh | bash

• Installer compiles llama-cli from llama.cpp, downloads models (interactive: phi3-mini or custom URL), builds release binary.
• Post-install: Reboot for bash menu; launch app via option 4 (takes over terminal like a full-screen React component).

Mac Development: Configure LE Friend Dongle for Auto-Connect (One-Time)

When developing on macOS, the LE Friend dongle does not auto-connect by default. The Survon OS installer will send the serial commands to the dongle automatically. But, since we're building the Survon Runtime on a Mac and didn't "install" it, we need to reproduce this critical step.

Thankfully, you only need to do this once per dongle. Ensure the LE Friend dongle is plugged in and blinking, and run the following in a terminal to permanently enable auto-connect:

PORT=$(ls /dev/cu.usbserial-* 2>/dev/null | head -n1)
[ -z "$PORT" ] && { echo "No LE Friend found"; exit 1; }
echo "Configuring $PORT ..."
stty -f "$PORT" 57600 raw -echo
(echo -e "AT+HWREGWRITE=0x01,0x01\r"; sleep 1; echo -e "ATZ\r") > "$PORT"
sleep 2
echo "Done — auto-connect enabled forever"

Usage

• Development: cargo run or ./target/release/runtime-base-rust
• Production (post-install): /usr/local/bin/runtime-base-rust or via Survon OS menu option 4
• Config: Edit via menu option 2 (sets ~/.bashrc; source for immediate use)
• The installer downloads a pre-built armv7 binary from GitHub releases (no compilation needed on Pi)

Debug Logging

The application writes logs to ./logs/ directory with separate files for each severity level:

• error.log - Error messages
• warn.log - Warning messages
• info.log - Informational messages
• debug.log - Verbose debug output (only when DEBUG flag is enabled)

To enable debug logging:

# Development
DEBUG=true cargo run

# Production (direct execution)
DEBUG=true /usr/local/bin/runtime-base-rust

Debug logs are useful for troubleshooting issues, especially on embedded devices like Raspberry Pi. Log files are cleared on each startup to prevent disk space issues.

Production Deployment

When running on Survon OS (Raspberry Pi), enable debug logging by setting the environment variable before launch.

Option 1: Via survon.sh menu Edit environment variables (menu option 2) and add:

# In survon.sh menu:
Set ENV_VAR: DEBUG
Value: true

Option 2: Modify survon.sh directly Edit /home/survon/survon.sh option 4 to include the DEBUG flag:

4) # Launch Rust TUI
   cd /home/survon
   DEBUG=true /usr/local/bin/runtime-base-rust
   ;;

Option 3: Custom startup script Create a wrapper script that sets DEBUG conditionally:

#!/bin/bash
# /usr/local/bin/start-survon.sh
DEBUG=true /usr/local/bin/runtime-base-rust

The DEBUG flag works identically in release builds - environment variables are checked at runtime, not compile time.

License

Copyright (c) Sean Cannon

This project is licensed under the MIT license (LICENSE or http://opensource.org/licenses/MIT).