mirror of
https://github.com/Cogential/frametanium.git
synced 2026-10-17 15:00:28 +02:00
CogentialandClaude Opus 5.5
6c27fd8fc2
- Frametanium is in its own list (installer mode): updating downloads the release bundle and runs install.sh, which now installs the headset app and its tile too and, when the service runs it, restarts the service from a timer of its own a few seconds later - release.yml builds the headset app on an ARM64 runner and publishes frametanium-steam-frame-arm64.tar.gz (tools/bundle.sh); deploy.sh uses the same bundle and install.sh - Built-in ports' library art is fetched at install (GitHub card + the project's icon) instead of shipping box art - Built-in Banjo-Kazooie (Lighthouse), installing over the Banjo_Kazooie tile; a repo the user added before it became built-in isn't listed twice - Frametanium can't remove itself Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VHDaz86aayqMULHsjByEmT
80 lines
5.2 KiB
Markdown
80 lines
5.2 KiB
Markdown
# Frametanium for the Steam Frame
|
|
|
|
Installs and updates Steam Frame apps and ports straight from their GitHub releases, like Obtainium: add any repo,
|
|
and Frametanium keeps it up to date. Works from the headset or a browser.
|
|
|
|
- **Add any GitHub repo** by typing `owner/name` (or pasting a link) on the headset's on-screen keyboard, from the
|
|
browser page, or by picking a suggestion made for the Frame. The built-in ports (Ship of Harkinian, 2 Ship 2
|
|
Harkinian, Starship, Lighthouse, OpenCE) are there from the start.
|
|
- **Discover new Frame apps:** every 12 hours (or on demand) it searches GitHub for Steam Frame projects (the
|
|
`steam-frame` topic, "steam frame" in names and descriptions, and the community's
|
|
[awesome-steam-frame](https://github.com/kosantosbik/awesome-steam-frame) list) and shows the ones whose latest
|
|
release has a download it can install, with ones you haven't seen marked **New**. Pick one to look at and add it,
|
|
or hide it. Without a GitHub token, GitHub allows 60 lookups an hour, so each search checks a batch (keeping some
|
|
for update checks) and the next search carries on; results are cached and only rechecked when a repo changes.
|
|
- **Picks the right download:** ARM64 Linux builds (`aarch64`/`arm64`, "steamframe"); checksums, Windows, macOS,
|
|
Android and x86 files are passed over. You can choose another one when adding. Zips, tarballs (gz/xz/bz2/zst),
|
|
AppImages and single programs all work.
|
|
- **Two ways to install,** picked from the download unless you choose:
|
|
- *Library app:* unpacked into `~/devkit-game/<name>`, given a `run.sh` (its own, or one that starts the ARM64
|
|
program it finds), added to the Steam library with art (the repo's GitHub card, and the project's icon or the owner's avatar),
|
|
fetched when it's installed.
|
|
- *Its installer:* when the download has `install.sh` (or `contrib/install.sh`, `setup.sh`), it's unpacked into
|
|
`~/.local/share/frametanium/apps/<id>` and that script runs, for tools such as SteamVR overlays. Removing the app
|
|
runs its uninstaller when it has one.
|
|
- **Install, update, update all, or pick any version.** Pre-releases are skipped unless you turn them on for an app
|
|
(they're on for apps that only have pre-releases).
|
|
- **Keeps your stuff:** saves live outside the install folder, ROMs placed next to `run.sh` are carried over, and
|
|
the previous install is kept for a **one-step rollback**.
|
|
- Won't touch an app that's running. Only add apps you trust: their programs and installers run as your user.
|
|
|
|
## Use it
|
|
- **In the headset:** open **Frametanium** in the library. D-pad to choose, **A** open an app (install/update,
|
|
versions, previous version, pre-releases, remove), **Y** add an app, **X** discover new apps, **Select** update all, **Start** check for
|
|
updates, **B** back/close.
|
|
- **From a phone or PC:** `http://<frame-ip>:8643` (add apps, edit name/install style/program, remove).
|
|
|
|
Updates are checked every 6 hours and on demand.
|
|
|
|
**Frametanium updates itself:** it's in its own list. Updating it downloads its latest
|
|
[release](https://github.com/Cogential/frametanium/releases), reinstalls the service and the headset app, and
|
|
restarts the service a few seconds later (reopen the headset app to get the new one).
|
|
|
|
## Files
|
|
- `catalog.json`: the built-in ports.
|
|
- `suggestions.json`: apps offered on the Add screen.
|
|
- `~/.config/frametanium/discover.json`: discovered projects you've seen or hidden; `~/.cache/frametanium/discover.json`
|
|
caches what each search found.
|
|
- `~/.config/frametanium/catalog.json` on the Frame: the apps you added and changes to built-in ones
|
|
(`{"id": "soh", "hidden": true}` hides one; adding its repo again brings it back).
|
|
- `~/.config/frametanium/installed.json`: installed versions.
|
|
|
|
## Private repos
|
|
GitHub only shows releases of private repos to signed-in users. Either make the port repos public (they contain no
|
|
ROMs), or save a token in the web page's Settings: a fine-grained token limited to those repos with read-only
|
|
**Contents** access is enough. It's stored in `~/.config/frametanium/config.json` (mode 600) and never sent back
|
|
to the page.
|
|
|
|
## Install
|
|
On the Frame: download `frametanium-steam-frame-arm64.tar.gz` from the latest release, unpack it and run
|
|
`sh install.sh`. It installs the service and adds the Frametanium app to the library.
|
|
|
|
Or from a computer that can SSH into the Frame:
|
|
|
|
```sh
|
|
app/build-arm64.sh # cross-compiles the headset app into dist/app
|
|
./deploy.sh [host] # host defaults to frame.local
|
|
```
|
|
|
|
Releases: push a tag `v*`; `.github/workflows/release.yml` builds the headset app on an ARM64 runner and publishes
|
|
the bundle (`tools/bundle.sh`).
|
|
Uninstall: `systemctl --user disable --now frametanium.service` and remove Frametanium from the library.
|
|
|
|
## Notes
|
|
- The service listens on port 8643 on your network. Set `password` in `~/.config/frametanium/config.json` to require
|
|
one in the browser (the headset app connects locally and doesn't need it).
|
|
- Standard-library Python only. The headset app is C + SDL2 with the public-domain
|
|
[font8x8](https://github.com/dhepper/font8x8).
|
|
- Testing on another architecture: `FRAMETANIUM_EXEC_WRAPPER=qemu-aarch64-static` (with `QEMU_LD_PREFIX`) runs
|
|
ARM64 AppImages for unpacking; `FRAMETANIUM_GAMES` changes the install folder.
|