Version 0.2.7

LiteBeam Network

LiteBeam is a self-hosted digital signage orchestration platform. It is designed to deploy, monitor, and monetize distributed display networks within a private local network, with minimal hardware overhead and maximum reliability.

Platform Overview

The LiteBeam architecture consists of two main components:

The Local Server: A Flask/Python application running on a dedicated machine at the location. Administrators manage locations, media assets, and campaigns through its web admin panel.
The Edge Player: A lightweight Python script running on each display (Raspberry Pi). It communicates with the local server via REST API to pull content, report telemetry, and execute commands.

Network Layout

Router 172.16.<ID>.1

│

Server 172.16.<ID>.201 ← DHCP reserved

│

Players 172.16.<ID>.100–200 ← DHCP pool

Architecture diagram — place docs-architecture.png in /static/img/

offline_pin Offline Resilience

Edge players download and cache all media locally. If the server is unreachable, the player will seamlessly continue broadcasting the last known campaign loop until the connection is restored.

System Requirements

Server

OS: Ubuntu 22.04 LTS or 24.04 LTS (minimized install is fine).
Hardware: Any x86-64 or ARM64 machine. A low-power mini-PC is ideal for on-site use.
Network: Connected to the LiteBeam router via ethernet, with a DHCP reservation at 172.16.<ID>.201.
Internet: Required during installation (to download the server package and dependencies). Not required for ongoing operation.

Edge Player (each display)

OS: Raspberry Pi OS Lite (64-bit), Debian 11/12, or Ubuntu 20.04+.
Hardware: Raspberry Pi 3B+ or later. Minimum 2GB RAM, 16GB storage.
Dependencies: python3, vlc, and Pillow — all installed automatically by the player installer.

Network Scheme

Every LiteBeam deployment is identified by a Client ID — a number from 1 to 254. This ID defines the private subnet used by all devices at that location:

Subnet: 172.16.<ID>.0/24
Router: 172.16.<ID>.1
Server: 172.16.<ID>.201 (DHCP-reserved by MAC address)
Players: 172.16.<ID>.100–200 (DHCP pool)

The server's IP is pinned via a DHCP reservation in the router so it never changes. Players are assigned addresses automatically and always know the server is at .201.

1. Router Setup

Any retail router (Asus, TP-Link, Netgear, etc.) works. Before the tech arrives on-site, configure the router at the office:

Set the router's LAN IP to 172.16.<ID>.1, subnet mask 255.255.255.0.
Set the DHCP pool to 172.16.<ID>.100 – 172.16.<ID>.200.
Add a DHCP reservation: server MAC address → 172.16.<ID>.201.
Configure WiFi SSID as litebeam-<ID> if players will use wireless.

The router ships to the location pre-configured. The tech plugs it in, connects the server by ethernet, and proceeds to the server install.

2. Server Installation

The server machine should be running Ubuntu LTS (minimized is fine) and connected to the LiteBeam router via ethernet. The router's DHCP reservation will assign it 172.16.<ID>.201.

SSH into the server and run one command — no files need to be transferred beforehand:

server — bash


                    curl -fsSL https://litebeam.timnetworks.net/server_install.sh | sudo bash

Or with wget:


                    wget -qO- https://litebeam.timnetworks.net/server_install.sh | sudo bash

The installer will:

Detect the Client ID automatically from the server's DHCP-assigned IP (172.16.<ID>.201). The tech confirms with Enter.
Download the LiteBeam server package.
Install system dependencies (Python 3, pip, gunicorn, npm).
Extract the application to /opt/litebeam-server/.
Bundle frontend assets (Tailwind CSS, fonts) for fully offline operation.
Create and start a systemd service (litebeam-server).

When complete, the admin panel is available at http://172.16.<ID>.201:8182 from any device on the same router.

key First Login

Default credentials are admin@litebeam.local / change_me. Change these immediately after first login. On a brand-new install, run sudo -u litebeam venv/bin/python init_db.py from /opt/litebeam-server if the panel shows no data.

Updating the Server

Re-run the bootstrap script. It detects the existing install, backs up the database, applies the new files, and restarts the service. The Client ID is preserved.

Server Management Commands

sudo systemctl status  litebeam-server   # check status
sudo systemctl restart litebeam-server   # restart
sudo journalctl -u litebeam-server -f    # live logs

3. Player Installation

Each Raspberry Pi acts as a display player. Connect it to the LiteBeam router (ethernet or WiFi) and run the client installer — no files need to be on the device beforehand:

pi@raspberrypi — bash


                    curl -fsSL https://litebeam.timnetworks.net/client_install.sh | bash

The installer will:

Detect the active 172.16.<ID>.x address and propose the Client ID. The tech confirms with Enter.
Optionally configure WiFi (SSID, password, WPA standard, country code) via wpa_supplicant.
Install VLC, Python dependencies, and set up a virtual environment.
Write player_config.json with the correct server address.

Then register the player as a system service (run as root):


                    curl -fsSL https://litebeam.timnetworks.net/client_enable.sh | sudo bash

On first heartbeat the device will appear in the admin panel under Devices with status Pending. Assign it to a Location and Campaign from the admin interface.

Campaigns & Playlists

A Campaign dictates what content is displayed on a screen. LiteBeam supports two primary layout modes: Standard Fullscreen and Dynamic Menu Boards.

Standard Fullscreen

Upload MP4s, MOVs, JPGs, or PNGs. The system compiles them into a seamless playlist. Images adhere to a global duration (e.g., 10 seconds), while videos play until completion before advancing.

LiteBeam eliminates the need to upload static images every time a price changes. The Menu Board engine allows you to:

Upload a background image (e.g., a chalkboard or branded graphic).
Define grid slots (0–29) for item names and prices.
Select typography (Sans Serif, Serif, Bold) and hex color codes.

How it works: The edge player receives the JSON configuration and uses the Pillow imaging library to render a high-resolution frame locally on the device. This ensures crisp text and zero server-side rendering bottlenecks.

Retail Media Network (RMN)

Monetize your screens without manual scheduling. The Vendor Advertisement engine allows you to grant limited portal access to third-party brands (Vendors).

When a Vendor uploads an advert, they (or you) set a Target Frequency (e.g., 4 Plays Per Hour). The LiteBeam edge player uses a mathematical interleaving algorithm to automatically inject the advert into the active campaign at the correct interval — pausing the main playlist, playing the ad, then resuming.

Remote Management

Physical access to displays is rarely required. From the Admin Dashboard, operators can dispatch commands that the edge player picks up during its next heartbeat cycle (every ~10 seconds).

Reboot: Executes a hard system reboot (sudo reboot) on the host OS.
Restart App: Kills the active Python process, prompting the systemd daemon to instantly restart the application.
Clear Cache: Deletes all locally downloaded media and forces the player to re-fetch assets from the server.

Logs & Telemetry

Every player reports live system status back to the local server.

Heartbeats: If a player misses heartbeats for 120 seconds, its status changes to Offline in the dashboard.
System Logs: Playback errors, download failures, and cache clears are streamed to the device's detail page, color-coded by severity (INFO, WARN, ERROR).
Proof-of-Play: Every time a vendor ad or campaign video finishes playing, a tracking event fires to the server, generating auditable CSV reports for advertisers.