Skip to main content

Documentation

Mobile and PWA

4 min readEdit on GitHub

The control server UI is mobile-first and installable as a Progressive Web App on iOS and Android. Once installed, it runs chromeless — no browser address bar, app-switcher icon, splash screen.

Why install it?

You're going to want the lights controllable from wherever you're standing during a shoot — at the camera, behind the talent, at the audio desk. Phone in your pocket beats walking back to a laptop. The PWA is the path of least friction.

Installing on iOS (Safari)

  1. Open http://lights.local:5000 in Safari (Chrome/Firefox on iOS don't expose Add to Home Screen)
  2. Tap the Share button (square with arrow)
  3. Scroll down → Add to Home Screen
  4. Confirm the name and tap Add

The app icon appears on your Home Screen. Opening it launches the UI in standalone mode — no Safari chrome, just the control surface.

Installing on Android (Chrome)

  1. Open http://lights.local:5000 in Chrome
  2. Either:
    • Tap the Install app prompt if it appears at the bottom of the screen
    • Or open the ⋮ menu → Install app / Add to Home screen
  3. Confirm

Same result: standalone launcher icon, chromeless UI.

What works offline

The service worker (/sw.js) caches the UI shell — HTML, CSS, JS, icons, fonts. That means:

  • The app opens instantly even on a flaky connection
  • You'll see the layout and previously-loaded data without a network round-trip

What does not work offline:

  • Sending commands to fixtures (requires the Pi)
  • Live channel values, status, scene activation, chat
  • Anything that hits the /api/* endpoints

In practice: if the Pi is unreachable, the UI loads but every action will spinner or error. Treat it as a thin client.

Mobile UX

The interface was rebuilt in v2.12 for one-handed phone use:

  • 44px touch targets on every interactive element (Apple HIG minimum)
  • 16px input font size to prevent iOS focus zoom (anything under 16px triggers Safari's auto-zoom)
  • Safe-area insets respected — content doesn't slide under the notch, home indicator, or rounded corners
  • Horizontal-scroll tabs row — tab labels overflow gracefully on narrow screens; scrollbar hidden on desktop where it isn't needed
  • Full-screen modals on phones — scene editor, group editor, etc. expand to fill the viewport
  • Edge-to-edge chat composer — the chat input docks to the bottom safe-area on small screens

Tab Persistence on Mobile

Same as desktop — the active tab is in the URL as ?tab=<name>. Useful if you want a Home Screen shortcut that opens directly to a specific tab. On iOS you can edit the bookmark URL after Add to Home Screen to include ?tab=cuelists, for example, and the launcher icon will jump straight there.

Updating the Installed App

After deploying new code (bash scripts/deploy.sh), the service worker will re-fetch the shell on next launch. If you're seeing stale UI:

  • iOS: Settings → Safari → Advanced → Website Data → search lights.local → delete. Reopen the app.
  • Android: Long-press the app icon → App info → Storage → Clear cache.

Or just hard-refresh in a normal browser tab (⌘⇧R / Ctrl⇧R) before relying on the installed app.

Files

For the curious — the PWA is wired up by these endpoints on the control server:

  • /manifest.json — name, icons, theme color, display mode
  • /icon.svg — single SVG icon (scaled to all sizes by the browser)
  • /sw.js — service worker, shell caching
  • Apple meta tags in <head> — apple-mobile-web-app-capable, apple-mobile-web-app-status-bar-style, etc.

See also: Control-Server for the rest of the UI capabilities.

Was this page helpful?