Version 0.5

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 signed server release and dependencies). Day-to-day playback does not need it, but StoreKeep sync, software updates and the Order Merchants check-in do.

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.ordermerchants.com/server_install.sh | sudo bash

Or with wget:


                    wget -qO- https://litebeam.ordermerchants.com/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.
Read the signed release manifest, download the newest release, and verify its signature, size and checksum before anything on the machine is changed.
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 https://172.16.<ID>.201:8182 from any device on the same router. The server uses a self-signed certificate, so the browser shows a warning on the first visit: choose Advanced and continue.

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

Since version 0.5.5 the server can update itself from Admin → Updates (see Software Updates). You can also re-run the bootstrap script: it detects the existing install and asks [1] Update (refresh the code, keep accounts, campaigns, devices and menus) or [2] Wipe / Fresh Install (erases everything, including the database). An update backs up the database first, and 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.ordermerchants.com/client_install.sh | bash

The installer will:

Ask for the install mode: [1] Quick uses the site settings stored at the top of the installer file (server address, port, WiFi name) and only asks for the WiFi password; [2] Custom asks for the server IP address, port and WiFi name/password yourself. The WiFi password is never stored in the file.
In both modes, set the locale to US English, the time zone to US Eastern, and the keyboard to a standard US 101-key layout (Shift-4 gives $, the key above Enter gives |). These are not asked.
Join the WiFi network if you gave one (NetworkManager, or wpa_supplicant on older Pi OS; country US). If no server address is set, detect the active 172.16.<ID>.x address and propose the Client ID.
Ask how the TV is mounted: [1] landscape, [2] portrait, turned clockwise (the TV's own logo ends up on the left) or [3] portrait, turned counter-clockwise (logo on the right). Press Enter to keep the current answer. Run the installer again to change it, or set the orientation on the server's Screens page, which wins if both are set.
Install VLC, Python dependencies, and set up a virtual environment.
Write player_config.json with the correct server address.
Register and start the litebeam-player system service, so the player starts by itself on every boot. If display settings changed, it offers to reboot.

On first heartbeat the device will appear in the admin panel under Devices with status Pending. Assign it to a Screen from the device page, and give that screen a campaign.

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).
Fill item names and prices by hand, or sync them from StoreKeep.
Choose how each page looks with Page View (below) and pick the Screen type the menu is designed for.
Select typography (Sans Serif, Serif, Bold) and hex color codes.

How it works: The server turns each menu page into a high-resolution slide image with the Pillow imaging library. Players download the slides and cache them, so text stays crisp and the Raspberry Pi does no rendering work. When you change a price the screens pick up the new slide on their next heartbeat.

Page views

Featured View: a text list of items plus, optionally, one tall featured card with a photo and description. Choose COLUMNS (1 to 4 on a landscape screen, 1 or 2 on a portrait screen) and TEXT SIZE (Small, Medium, Large, X-large). Text sizes are real pixel sizes, so a 4K screen fits more lines than a Full HD one. Auto keeps the classic layout of three columns.
Card View: every item is a white card with a square photo, its name and its price. Choose ROWS, the most rows of cards shown on one screen; the number of columns follows from the screen shape. Auto fits up to 24 cards on one page.
Photos are always shown whole on a plain white backdrop, never cropped or blurred. Items without a photo get a lettered placeholder.
When a category has more items than fit, LiteBeam adds extra pages (tabs) automatically and splits the items evenly between them. Changing ROWS, COLUMNS or TEXT SIZE re-cuts the category.

For manual pages the same settings decide how many item slots the page has (Auto is the classic 30). Slots that would be dropped are flagged before anything is removed.

StoreKeep Menu Sync

If the venue keeps its items and prices in StoreKeep, LiteBeam can build its menu pages from that inventory. Open a menu, choose Connect StoreKeep, enter the StoreKeep address and API key, and press Sync Now.

Every StoreKeep category becomes one or more menu pages with the current names, prices and photos. These synced pages are read-only in the editor; background, page view, rows, columns and text size can still be set per category.
Pages you built by hand stay exactly as they are. A sync never touches them.
Your choices are remembered per category, so a re-sync does not reset backgrounds, views or layout settings.
If a sync fails (for example the internet is down), the pages from the last good sync stay on the screens.
Disconnect switches syncing off and removes the saved key. The pages stay on the screens and become editable.

Syncing is manual for now: press Sync Now after prices change.

Screens & Orientation

A Screen is where a player is installed. Each screen has a resolution (the player reports what its display supports) and an orientation, and a campaign is assigned to it.

Screen type for menus: Full HD or 4K, landscape or portrait. It decides how many cards, columns and lines fit, so the same menu can be laid out for a small TV or a 4K display.
Portrait screens: mount the TV turned clockwise or counter-clockwise and choose that in the player installer (or on the Screens page). The server turns the finished slides to match, so the Raspberry Pi needs no display rotation settings.
Photos and videos are landscape only. Portrait screens are meant for menu boards. When you assign a campaign to a screen it does not suit, the Screens page shows a heads-up; it never blocks you.

Changing a screen's orientation takes effect after the screen has cycled through its playlist once.

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).

Each vendor logs in to a view that shows only their own ads and reports. An advert has a Target Frequency (plays per hour) and a list of devices it runs on. Adverts are delivered to the player together with the playlist and play as part of each loop, and every play is recorded for proof-of-play reports. Exact plays-per-hour scheduling is on the roadmap: today the frequency is stored with the ad, but the player does not yet space ads to match it.

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 (about once a minute).

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.
Update: The player re-fetches its own software 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.

Software Updates

From version 0.5.5 the server updates itself from Admin → Updates. Every release is cryptographically signed; the server downloads it, verifies the signature, size and checksum, and refuses anything that is unsigned, altered or older than what is installed.

Check / Update now: see the newest release and install it with one click.
Go back: return to the previous version if you prefer it.
Automatic updates: switch them on, choose a maintenance window (for example 02:00 to 05:00 in the venue's time zone) and, if needed, pause updates until a date.
Safety net: the database is backed up before every update, and if the new version fails its health check the previous one is restored automatically.
Order Merchants connection: paste the check-in token from the Order Merchants admin panel and the server reports in every few minutes, so support can see that it is online, which version it runs and basic statistics.

Users & Permissions

Admin accounts can do everything. Manager and Staff accounts get a set of capabilities that an admin can change on the Roles & Permissions page: manage screens, campaigns and menus, devices and remote commands, vendor ads, the media library, reports, users, and software updates. Out of the box managers can do everything except manage users; staff can manage campaigns, menus and the media library. Vendor accounts only ever see their own ads and reports.