Repository navigation
Releases
FPP-Backup 0.3.1
A security and maintenance release: fewer dependencies, no known vulnerabilities, and releases you can verify.
Simpler install
- No Rust toolchain needed. SD cards are now found with macOS's own
diskutil, using the same rule the BeagleBoard Imaging Utility uses (a physical whole disk that macOS reports as removable or ejectable).tools/setup_bb_imager.shand its ~790 Rust dependencies are gone. Flashing itself is unchanged. - Card builds use an Alpine-based container, built fresh on every run, so its packages are always the current, patched ones. A test build of the same card with the old and new containers produced identical files.
Fixes
- The ColorLight check no longer stops on a controller log line with an unusual or impossible timestamp. These include fractions of a second Python 3.9 can't parse, impossible dates, and Feb 29 read in a non-leap year.
- Saving a malformed fleet policy from the Settings page now shows an error, instead of the request getting no answer.
Security
- No open vulnerabilities at any severity in the card-builder container. The previous Debian-based one carried about 100 that Debian hasn't fixed yet.
- Verifiable releases. Starting with this one, each release includes a source archive and SBOMs (software bills of materials), all signed with build provenance. Check a download with
gh attestation verify FPP-Backup-v0.3.1.tar.gz -R SRipaldi/FPP-Backup. Releases are immutable once published. - CI checks on every change: CodeQL (extended security queries), unit tests on Python 3.9 and 3.13 and on macOS, ShellCheck, hadolint, and fuzzing of the parsers for controller logs, release notes, settings and policies. Weekly scans cover the container's dependencies and the repository's OpenSSF Scorecard. CI uses no third-party GitHub Actions; its tools are pinned by version and SHA-256.
- SECURITY.md now sets out how to report a vulnerability and the response timeline.
tools/check_public.pychecks commits, PRs and releases for an installation's own names and addresses, secrets and personal data before anything is published.--install-hookssets it up for every commit and push.
Upgrading
Pull the new version (or clone --branch v0.3.1) and restart the UI server. You can delete work/bin/bb-imager-cli and work/bb-imager-src/; nothing uses them any more.
Full changes: v0.3.0...v0.3.1
FPP-Backup 0.3.0
Upgrade controllers in place
The Fleet page can now upgrade controllers to a newer FPP release without rebuilding their SD cards. Use Upgrade… on a controller's row, or Upgrade all….
- Two kinds of upgrade, the same ones FPP's About page offers:
- FPP update: the controller fetches the new release from GitHub and rebuilds FPP. It keeps its current operating system.
- OS upgrade: replaces the controller's whole system with the release's OS image.
The dialog recommends one based on what the release notes say.
- One controller at a time, player last. The run stops at the first problem, so a bad release can affect only one controller.
- Waits for the show. Nothing starts while the show plays, or if a playlist is due before the upgrade could finish.
- Checks each controller afterwards. Before upgrading, it records the version, outputs, sequences, playlists, network, settings, warnings and ColorLight receiver. After the reboot it compares them, and it can back the controller up first.
- Controllers without internet access get the OS image from this Mac. The image is checked against GitHub's SHA-256, uploaded through the player and deleted afterwards.
- Old OS images left in controllers' Uploads folders (1–1.3 GB each) can be listed and deleted.
tools/upgrade.py recheck --hosts <name>re-runs the comparison later, for example after a power cycle.
Handling FPP's unreliable restarts
In the first live upgrades, every controller reached the new version, but FPP's restart afterwards wasn't always clean. The tool now handles what we saw:
- FPP's startup times out on the first boot after an OS upgrade: the tool reboots once more.
- An FPP update takes FPP's player service down to finish: the tool treats this as a normal restart and always reboots at the end.
- A controller stays off the network, or FPP doesn't start: the message says the upgrade probably worked and tells you to power-cycle the controller, then run
recheck. - "Plugins must be reinstalled" after an OS upgrade: shown as a separate check with a note that this is expected.
Hardening
- Hostnames that devices announce on the network must be valid before they're used in file paths.
- OS images must be plain
.fpposfiles from github.com. - A
.snykfile keeps Snyk scans out of local data (snapshots/holds controller passwords). Snyk's infrastructure-as-code scan is turned off for this folder, since there's nothing for it to check here.
Notes
- If a controller's last backup is older than 24 hours, the dialog offers to back it up first. Take the backup: it's what you'd rebuild a card from if an upgrade goes wrong.
- An OS upgrade sometimes needs a power cycle to finish. When it does, the tool says so.
- Tests:
python3 -m unittest discover -s testsruns 33 tests against a simulated controller.
Full changes: v0.2.1...v0.3.0
FPP-Backup 0.2.1
A maintenance release. No app changes — it picks up Dependabot's updates to the card-image builder's base image.
Changed
- Builder base image: the
tools/builderDockerfile's debian base was bumped to the current digest (via Dependabot, #1 and #2), so card images built from here include the latest debian security patches. Only affects building card images; the Mac-side app is unchanged.
Upgrading
Run git fetch --tags && git checkout v0.2.1, or download the source zip below. Nothing needs migrating. If you've already built card images on v0.2.0 and don't need to rebuild them, there's nothing to do.
Not affiliated with or endorsed by the Falcon Player project.
FPP-Backup 0.2.0
Adds monitoring for ColorLight receiver cards.
New: Show > ColorLight
If a controller drives LED panels through a ColorLight receiver card (such as a 5A-75), the app now finds it and checks it every 5 minutes while the app is running. It only reads from the controllers.
A ColorLight card needs a steady gigabit link to its controller. When a cable, jack or coupler is bad, the link keeps dropping and coming back, sometimes at 100 Mbps, and the panel freezes. fppd only looks for the card when it starts. If it starts while the link is down, the panel stays dark until fppd is restarted. The new page shows, for each card:
- Link now: whether the link is up and at what speed. 100 Mbps is flagged, because the card needs gigabit.
- Receiver: whether fppd found the card when it last started, with the card's firmware and panel size.
- Steady for: time since the last link drop.
- Link drops: counts for the last hour, day and week; charts of drops per day and by hour of day; and a list of recent drops with how long each lasted. Drops bunched in the warm part of the day point to heat on a connector.
- Card restarts: worked out from the card's own uptime, so a card that lost power shows up.
- Sends: slow, failed or dropped frames.
Every controller with an enabled ColorLight output is picked up; nothing is set up per show. Problems also appear on the Dashboard and in the notification bell, and you get a notice when the link is steady again. History is kept for 14 days on the Mac, longer than FPP keeps its own logs. From the command line: tools/colorlight.py [--host <name>].
So far this has been used on one Raspberry Pi 4 running FPP 10.3 with a ColorLight 5A-75. Reports from other setups are welcome, especially a BeagleBone, a USB network adapter, or two cards on one controller.
Upgrading
Run git fetch --tags && git checkout v0.2.0, or download the source zip below. Then restart the app. Nothing needs migrating.
Known limits
Same as 0.1.0:
- Only BeagleBone Black card images have been built and booted. Raspberry Pi and BB64 images are untested.
- Password support hasn't been tried against a real FPP with its UI password on.
- Plugins aren't carried onto a rebuilt card.
- Backups have no schedule.
- The web UI is for the Mac it runs on only. Backups and card images contain secrets. See SECURITY.md.
Not affiliated with or endorsed by the Falcon Player project.
FPP-Backup 0.1.0
The first public release of FPP-Backup, a local web app and command-line tools for backing up, monitoring and rebuilding the controllers of an FPP (Falcon Player) light show from a Mac.
It's in use on an 11-controller show (Raspberry Pi 4, BeagleBone Black with KulpLights capes, PocketBeagle 2; FPP 8.5.1 and 10.3). Versions before 1.0 may still change how things work between releases.
What it does
- Back up every controller's configuration, and optionally its sequences, music and video, through your player. Backing up only reads from the controllers. Media backups are incremental: unchanged files are linked from the previous backup, so a repeat backup takes seconds.
- Keep the fleet consistent: compare every controller against a policy (time zone, time server, location, gateway, services and anything else you choose) and fix the differences in a click.
- Check the show will play: find sequences missing from a controller, or an older render of one. With xLights running on the Mac, push the right version as FPP Connect would.
- Watch a running show: a Live page shows whether each remote is playing the same sequence at the same point as the player.
- Rebuild or upgrade a controller onto a fresh SD card: turn a backup into a ready-to-boot card image, on the same or a newer FPP version. The app then flashes the card, reads it back to check it, and checks the controller after it boots. The controller comes up with its old hostname, address, settings, outputs and sequences, with no setup steps.
- Get told when something changes: controllers going offline, remotes dark during a show, policy differences, missing sequences and new FPP releases.
- Controllers with a UI password work too: passwords are kept in the macOS Keychain. Controllers your player doesn't list can be added by address.
Requirements
- A Mac; flashing cards needs macOS. Python 3.9 or newer, with no packages to install.
- Network access to your FPP player.
- To build card images: Rancher Desktop or another Docker engine, plus Rust once to build the SD card detector.
- To push sequences: xLights on the same Mac, with its automation port turned on.
See the README to install and set it up.
Known limits
- Only BeagleBone Black card images have been built and booted so far. Raspberry Pi and BB64 images use the same code but are untested.
- Password support hasn't yet been tried against a real FPP with its UI password on.
- Plugins aren't carried onto a rebuilt card (their settings are); reinstall them from FPP's plugin page.
- Backups run when you start them; there's no schedule yet.
- Security: the web UI is for the Mac it runs on only. Backups and built card images contain your controllers' passwords and Wi-Fi keys: never share them. xLights' automation port has no password, so turn it on only while pushing. See SECURITY.md.
Not affiliated with or endorsed by the Falcon Player project.