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 reset: Restarts networking and bonding services.
• bonding: Displays MPTCP proxy and MLVPN tunnel status.
• AP start: Activates HostAP (hotspot) on the first Wi-Fi interface.
• AP stop: Stops HostAP and switches the first Wi-Fi interface back to managed client mode.
• AP status: Checks if the wifi interface status is coherent with configuration, if not tries to recover.

VLX_cameraman.sh

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

Manages video encoding pipelines. This service is best utilized in combination with direct hardware interfaces such as USB webcams, native camera modules, or HDMI-in capture cards.

• 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). Combining this service with the suite's Access Point (AP) mode is crucial for achieving optimal performance and reliability when interfacing with devices running rigid or proprietary software, such as GoPro cameras.

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. This module acts as a resilient data pipeline, ensuring real-time location and telemetry data are consistently processed and transmitted regardless of network fluctuations.

• 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. Users can safely update this configuration by editing the file with a standard text editor (e.g., nano config/FrameFlow_user.settings). Since the services dynamically source this file at runtime, simply restarting the relevant service (such as VLX_cameraman or VLX_gps_tracker) is sufficient to apply any changes.

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