First Run Onboarding

First-run onboarding

Lodor-NextUI connects to your server entirely on the device, using NextUI's on-screen keyboard. No JSON editing, no computer. The first open of Tools → Lodor runs the wizard automatically; Setup / Re-pair in the Lodor menu re-runs it any time. Pressing B backs out of every step — you're never trapped.

Before you start

1. Connect Wi-Fi in NextUI Settings. NextUI owns the radio; Lodor only rides an already-connected link. If Wi-Fi isn't up, the network steps will tell you to connect it first (honestly — it never fakes a connection).
2. Your RomM server must be 4.8.0 or newer (device pairing shipped in stock RomM at 4.8.0).
3. Know how you'll reach the server — home network / public URL, Tailscale, or Cloudflare Access. See Reaching your RomM server.

Steps

Open Tools → Lodor. The wizard runs in order; every step is re-enterable, so a failed step just retries with your last input prefilled.

1. "How will you reach RomM?" — pick Tailscale (sign in with QR) or Home network / public URL.
   • Tailscale: the device shows a QR code on screen (plus the raw URL as a fallback). Scan it with your phone, sign in to your Tailscale account, and approve the device. When it connects, the wizard continues. The device is now on your private Tailscale network — no auth-key files, no computer.
   • Home network / public URL: continues straight to the server address.
2. Server protocol — pick https (recommended) or http.
   • Tailscale note: a server published with tailscale serve is HTTPS-only — pick https and use the full Tailscale name, e.g. https://romm.your-tailnet.ts.net. Plain http:// to a tailscale serve host is refused and looks like a network error.
3. Server address — type your RomM host, e.g. romm.example.com (no https:// prefix needed; a pasted full URL has the scheme stripped for you). On a retry the field is prefilled with your last-entered address, so a typo is a two-key edit, not a full retype.
4. Port — optional. Leave blank for the default (443 for https, 80 for http).
5. TLS certificate (https only) — Verify (recommended) or Skip verification (self-signed certs only).
   • Address, port, and TLS choice are saved to config.json immediately. This step is offline — it doesn't need Wi-Fi.
6. Pairing code — this step needs Wi-Fi. In RomM's web UI, generate a pairing code (an 8-character code). Codes are single-use and expire in about 60 seconds — get the device to this screen first, then generate the code and type it. Lodor exchanges the code for a device token and validates it against the server.
7. Device name — name this handheld (defaults to "TrimUI Brick" / "TrimUI Smart Pro"). This registers the device with RomM so cross-device save history knows which device a save came from.
8. Lodor pulls your library (game stubs + collections), then: "Connected! Your library is syncing. Open it from the NextUI menu."

"Where should RomM games go?" — you'll only ever see this prompt if the card carries an older beta's separate-folders layout. On a fresh card (or any card without that residue) merge mode is applied silently: RomM games mix into your own Roms/ folders, tracked by a safety manifest, and your own files are never modified. If prompted, Mix them into my folders is recommended; Keep them in separate folders preserves the old quarantine layout.

Honest results (what you'll actually see)

Lodor never shows a fake "success." Each step reports the engine's real result:

What happened	What you see
Paired OK	"Paired." → continues to device name
Paired but the token is missing some sync permissions	"Paired — but the token is missing some sync permissions. Re-generate it in RomM with all scopes." (pairing still succeeds; regenerate for full sync)
Code wrong or expired	The server's actual reason (e.g. "Pairing failed: invalid or expired code") + a retry. Generate a fresh code and try again.
Server unreachable	"Couldn't reach your server — check the address and Wi-Fi" + a retry
Wi-Fi not connected	"Connect Wi-Fi in NextUI Settings first, then re-run Lodor setup"
Tailscale sign-in didn't complete	"Try again, or use Home / public URL" — nothing is half-configured

A detailed log is written to Tools/<platform>/Lodor.pak/last-sync.log if you need to dig in. It never contains your token or pairing code.

Re-running setup

Open Tools → Lodor → Setup / Re-pair any time — after changing servers, mis-pairing, or a revoked pairing. Re-pairing replaces the stored token; it does not wipe your downloaded games or saves. If the server ever revokes or expires this device's pairing, the Lodor menu shows a "! Pairing expired — re-pair" banner at the top; selecting it runs the same wizard.

After onboarding — day to day

Games are just games: open them from the normal NextUI menu. A game that isn't on the card yet downloads on launch with a real progress bar, then boots; if the download fails, it stays in your library and relaunching retries. Saves pull before you play and push after you quit — no menus needed.

• Game Manager — at the top of your games list (also Tools → Lodor → Game Manager). Pick a system, pick a game, then: Download now, Delete from card (the game returns to a cloud stub in your library — saves and box art are kept), Sync save now, Server saves (restore an older save version), Details. Browsing works offline.
• Continue — a collection with your recent games from all your devices, so you can pick up on this device what you started on another.
• Sync now — fast: pushes pending saves, pulls fresh saves for games on your card, and updates Recently Played. Takes seconds.
• Refresh library (full, slow) — re-mirrors your whole RomM catalog and collections. Run after adding games to your server — big libraries take a while.
• Remove Lodor from this card — clean uninstall: removes exactly what Lodor's manifest owns; downloaded games are kept unless you choose otherwise, saves never touched.
• Search library / Download queue / Download BIOS / Recent activity / Switch user / box-art toggle / RomM games placement (mixed / separate) / Tailscale status / Tailscale: Reconnect / Tailscale: Reset & forget.