VLX FrameFlow

High-Availability Streaming & Telemetry Suite for SBCs

VLX FrameFlow is a modular suite of shell scripts designed to transform Debian-based Single Board Computers (SBCs) and VPS into:

• High-availability bonding routers (Client & Server)
• Multi-camera streaming encoders
• Real-time telemetry trackers

---

Architecture

The suite operates via a main installation entry point, modular configuration scripts, and runtime service managers. Process control is handled via systemd.

The suite uses a multi-protocol bonding architecture: UDP traffic is routed exclusively via MLVPN, and TCP traffic is aggregated using MPTCP with Shadowsocks-libev and v2ray-plugin acting as a transparent proxy.

Core Structure

Component	Description
VLX_FrameFlow.sh	Main interactive installer and manager supporting CLIENT and SERVER roles.
config/	Configuration templates and maintenance scripts.
modules/	Core logic (storage, system, network, package management).
tests/	Unit and integration tests.
config/FrameFlow_user.settings	User-specific runtime configuration.

---

Installation

Prerequisites

• A fresh Debian-based OS (e.g., Raspberry Pi OS Lite 64-bit, Armbian, Ubuntu on VPS).
• Root privileges are required for the installation process.

Setup

Clone the repository and run the installer as root:

git clone https://github.com/viruslox/VLX_FrameFlow.git
cd VLX_FrameFlow
./VLX_FrameFlow.sh

---

Management Script

VLX_FrameFlow.sh

The main script provides an interactive menu. The primary choice allows selecting the installation role or updating the suite:

1. CLIENT (SBC/Field Unit) - Automated, heavy installation.
2. SERVER (VPS/Relay Node) - Interactive, conservative installation.
3. Update Suite, user ownership and sudoers.
4. Exit.

CLIENT Menu

• Install OS on Storage: Clone running OS to high-speed storage.
• Configure System: Full setup (FFmpeg, MPTCP, GUI bloatware removal, user config).
• Reconfigure System network: Re-apply network features and firewall.
• Update network interfaces: Regenerate networkd and hostapd profiles.
• Create/Reconfigure FrameFlow user.
• Install and configure Client components: MLVPN and Shadowsocks.
• Complete Clean Up / Roll back: Reverts client configurations.

SERVER Menu

• Install and configure Server components: MLVPN and Shadowsocks setup with firewall prompts.
• Complete Clean Up / Roll back: Safely uninstalls server components and UFW rules.

---

Runtime Tools

All runtime scripts are intended to be executed by the dedicated service user (default: frameflow). They rely on systemd-run --user for lifecycle and process management.

Network Flow Control

These commands can be run via the main manager script to switch modes and control networking.

./VLX_FrameFlow.sh <command>

Available commands:

• server_start / server_status / server_stop: Manage server components.
• client_start / client_status / client_stop: Manage client components.
• client_restart: Restarts networking and bonding services.
• bonding_status: Displays MPTCP proxy and MLVPN tunnel status.
• accesspoint_start: Activates HostAP (hotspot) on the first Wi-Fi interface.
• accesspoint_stop: Stops HostAP and switches the first Wi-Fi interface back to managed client mode.
• network_restart: Restarts network dispatcher, flushes routes cache.

VLX_cameraman.sh

./VLX_cameraman.sh <VxAy> <start|stop|status>

Manages video encoding pipelines:

• Captures video and audio dynamically via v4l2-ctl and arecord (bypassing static settings files).
• Streams via FFmpeg using SRT protocol (redirects UDP to 10.1.10.1 via MLVPN on Client).

Parameters:

• VxAy: Video index (x) and audio index (y). E.g., V0A1, or V1A0 for no audio.

VLX_mediamtx.sh

./VLX_mediamtx.sh <start|stop|status>

Manages the local MediaMTX server (SRT protocol only).

Functions:

• Acts as a relay/proxy for local streams.
• Restreams to remote endpoints via SRT.
• Dynamically injects FFmpeg commands into frameflow.yml.

VLX_gps_tracker.sh

./VLX_gps_tracker.sh <start|stop|status>

Manages GPS and telemetry services:

• Controls gpsd.
• Auto-detects USB / serial GPS hardware.
• Reads TPV data via gpspipe.
• Pushes JSON telemetry to the configured API endpoint.

---

Configuration

config/FrameFlow_user.settings

This file contains all runtime environment variables. It is generated during the user setup process. Note: Settings-based hardware mapping for video/audio devices has been deprecated in favor of dynamic CLI arguments (VxAy).

General Paths

Variable	Description
VLXsuite_DIR	Installation directory (default: /opt/VLX_FrameFlow).
MEDIAMTX_DIR	MediaMTX binary directory.

Network & Security

Variable	Description
MLVPN_VPS_IP	The remote server IP for MLVPN and Shadowsocks bonding.
AP_PASSWORD	WPA2 passphrase for the generated Access Point. Automatically generated if left empty.

Streaming Endpoints

Variable	Description
SRT_URL	Base SRT URL. Supports publish: StreamID auth.

Example:

srt://10.1.10.1:8890?streamid=publish:stream_name:user:pass

Telemetry (GPS)

Variable	Description
GPSPORT	gpsd local port (default: 1198).
API_URL	Remote HTTP/HTTPS telemetry endpoint.
AUTH_TOKEN	Bearer token for API authentication.

---

Maintenance

A cron job (@reboot) executes:

config/FrameFlow_maintenance.sh

Maintenance Tasks

• Journal Cleanup: Vacuums systemd journals older than 15 days or larger than 500 MB.
• Package Backup: Dumps the installed package list to /root/pkg.list.
• Cache Cleaning: Clears APT cache to conserve disk space.

---

Testing

The repository includes a suite of unit and integration tests located in the tests/ directory.

To run the tests:

# Make the test scripts executable (if not already)
chmod +x tests/*.sh

# Run the full test suite
bash -c 'for test in tests/*.sh; do bash $test; done'

Tests cover critical functionality such as network profile creation, user setup, argument validation, and rollback procedures.

---

License

GNU General Public License v3.0