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) into:

• High-availability bonding routers
• Multi-camera streaming encoders
• Real-time telemetry trackers

---

Architecture

The suite operates via:

• A main installation entry point
• Modular configuration scripts
• Runtime service managers

Process control is handled via systemd.

Core Structure

Component	Description
VLX_FrameFlow.sh	Main interactive installer and manager
config/	Configuration templates and maintenance scripts
modules/	Core logic (storage, system, network, package management)
~/.frameflow_profile	User-specific runtime configuration

---

Installation

Prerequisites

• Fresh Debian-based OS
  • Raspberry Pi OS Lite (64-bit)
  • Armbian

Setup

Clone the repository and run the installer as root:

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

---

Management Script

VLX_FrameFlow.sh

The main script provides an interactive menu with the following functions:

Option	Function	Description
1	Install OS on Storage	Wizard to clone the running OS to high-speed storage (NVMe / SSD / eMMC). Handles GPT partitioning and bootloader configuration. Warning: wipes target drive
2	Configure System	Full installation: updates repositories, installs dependencies (FFmpeg, MPTCP, GPSD, MediaMTX), removes GUI bloatware, creates the service user, configures firewall
3	Reconfigure Network	Re-applies UFW rules, MPTCP settings, and kernel forwarding parameters
4	Update Interfaces	Scans hardware for new Wi-Fi/LTE adapters and regenerates systemd-networkd and hostapd configurations
5	User Management	Creates or updates the dedicated service user and configures password-less sudo for runtime scripts
6	Update Suite	Pulls latest code from the repository and updates binaries (MediaMTX)

---

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.

---

VLX_netflow.sh

sudo ./VLX_netflow.sh <profile_name>

Switches the network stack between predefined modes:

• normal
  Standard Wi-Fi client mode (managed)

• ap-bonding
  Activates HostAP (hotspot) and MPTCP bonding across all available WAN interfaces

---

VLX_cameraman.sh

./VLX_cameraman.sh <ID> <start|stop|status> <srt|rtsp>

Manages video encoding pipelines:

• Captures video from V4L2 devices
• Streams via FFmpeg to the configured destination

Parameters

• ID
  Integer camera identifier (maps to configuration)

• Protocol

  • srt → MPEG-TS over SRT
  • rtsp → RTSP streaming

---

VLX_mediamtx.sh

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

Manages the local MediaMTX server.

Functions:

• Acts as relay/proxy for local streams
• Restreams to remote endpoints
• Dynamically injects FFmpeg commands into frameflow.yml
• Handles complex SRT StreamID authentication strings

---

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

~/.frameflow_profile

This file contains all runtime environment variables.

---

General Paths

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

---

Network & Wi-Fi

Variable	Description
AP_PASSWORD	WPA2 passphrase for the generated Access Point

---

Streaming Endpoints

Variable	Description
RTSP_URL	Base RTSP target URL (e.g. rtsps://server:port/path)
SRT_URL	Base SRT URL. Supports publish: StreamID auth

Example:

srt://host:port?streamid=publish:stream_name:user:pass

---

Hardware Mapping

Variable	Description
ENABLED_DEVICES	Total number of cameras
AUDIODEV	Regex for default USB audio device
VIDEODEV_x	Optional explicit video device for camera x
AUDIODEV_x	Optional specific audio device for camera x

If unset, automatic detection is used.

---

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 installed package list to /root/pkg.list

• Cache Cleaning
  Clears APT cache to conserve disk space

---

License

GNU General Public License v3.0