Getting on the network

The controller connects on demand. It brings the link up only while something needs it and drops it when nothing does. This saves power and RF airtime, but it also means a disconnected idle device is usually correct, not broken.

Transport

On the ESP32-S3-ETH, wired Ethernet is auto-detected and preferred — DHCP, just plug in. WiFi is the automatic fallback if there’s no link. Sparkle Motion is WiFi only.

What keeps it connected

The link comes up when any of these is true, and goes away when none are:

• the web config app is open,
• Art-Net or sACN is the active input,
• Art-Net or sACN output is enabled,
• zone sync is on and a network is available to it (an offline zone syncs over a direct radio link instead — see below).

So if you’re running the built-in pattern engine with no network DMX and no browser open, the device is meant to be offline. Reopen the web UI or enable a network feature and it reconnects within moments.

Setting up WiFi

Enter WiFi credentials from the OLED, or from the web UI once you can reach it some other way (over Ethernet, say).

A brand-new WiFi-only device with no credentials and no wired link brings up its own setup access point so you can reach it with nothing else on hand. The network is named after the device — OMNA-xk4p, where xk4p is a short id derived from the device’s MAC (letters and digits only; the letters o, i, l and u never appear, so a 0 or 1 in an id is always the digit) — so several fresh units on a bench stay distinct. The OLED’s setup QR screen shows the network name, password, and address; join it, open the web app, and enter your network’s credentials. A unit with no screen at all brings up the same access point on its own — it’s the one onboarding path that needs nothing else attached.

If you already have an Omna set up, there’s a faster path that needs no phone or laptop at all: on the new device’s OLED choose Get WiFi from Omna, and on any existing device choose Adopt Device. The two find each other over a direct radio link (ESP-NOW) and the new unit picks up the WiFi and fleet credentials on the spot.

The device remembers several networks (up to ten), most-recently-used first. When more than one saved network is in range it joins the strongest, so the same controller roams between, say, a shop bench and a venue without re-entering anything. Manage the saved list — including forgetting a network — under Network in the web UI or on the OLED.

Finding the device

Once it’s connected, mDNS advertises it, so you can reach the web app by name instead of chasing an IP. If mDNS doesn’t work on your network, use the IP from the OLED status screen.

One device: http://omna.local goes straight to it.

Several devices: they don’t fight over omna.local. Exactly one of them owns that name at a time, and visiting http://omna.local shows a small lobby — a list of every Omna on the network — so you can pick the one you want. (With a single device the lobby is skipped and you land straight on its UI.)

Every device is also reachable directly, regardless of which one owns omna.local, at a stable per-device name built from a short device id derived from its MAC — shown on the OLED and in the web UI:

• omna-xk4p.local — always reaches that exact device.
• omna-<your-name>.local — additionally, if you set a friendly device name in the web UI. The name is lowercased into the hostname and only letters, digits, and hyphens are kept, so Stage-Left becomes omna-stage-left.local (a space would simply be dropped).

So omna.local is the “whichever / show me the list” entry point, and omna-xk4p.local is the “this exact device, every time” entry point. The web UI tells you which one you’re on — a You’re on chip in the header (showing your device name if you’ve set one, otherwise the device id), and a Reachable At list on the Network tab showing every name that currently points at the device you’re viewing.

Who owns omna.local

The devices elect the owner among themselves over the local network, settled over about a second so a single dropped packet can’t cause flapping. Each device carries a disposition — Prefer, Auto, or Standby, set on the Network/Zone tab — and the election runs Prefer over Auto over Standby, with the lowest hardware address breaking ties. Mark one unit Prefer and it reliably owns omna.local whenever it’s present. A freshly adopted device starts in Standby, so a unit you’ve just added never grabs the name from your established rig. If the owner drops off, another device takes omna.local within roughly a minute; meanwhile every device stays reachable at its own omna-<id>.local the whole time, so you are never locked out.

Fleet and zone are different things

Fleet is discovery and identify only. One device surfaces the others so you can find them and blink-identify them. It doesn’t sync patterns.

Zone sync replicates pattern and motion. A leader drives the followers in its zone, the followers are locked to the leader’s pattern (you edit on the leader), and everything stays phase-locked so motion matches across devices.

Zone sync doesn’t actually need the network. If there’s no WiFi or Ethernet to be had — a field, a rented hall, a router that died mid-show — devices in a zone link to each other directly over a built-in radio protocol (ESP-NOW) and keep syncing exactly the same way. The switch is automatic in both directions: a freshly booted device gives an expected network about eight seconds to appear before falling back (or falls back immediately if it has no stored WiFi and no wired link), and it returns to the network transport whenever one comes back. Wired devices bridge the two automatically: an Ethernet-connected device relays zone sync onto the radio link, so offline satellites stay locked to a wired zone with no configuration. Devices meet on a radio channel derived from the zone’s name; the web UI’s Zone tab shows the current link (“Zone Link”) and the channel an offline zone will use, right under the Zone ID field. One note: the .local names need an IP network — on the direct radio link the lights stay in sync, and you reach a device’s web UI over its own setup access point or use the OLED.

A zone’s current leader also publishes a name for the zone itself — omna-<zone>.local, e.g. omna-stage.local for a zone named stage. It always resolves to whoever leads that zone right now, so it keeps working across a leadership handoff. (If a zone happens to share a name with a device, the Network/Zone tab flags the clash, since both would answer to the same .local address.)

Turn zone sync on only when you want devices to mirror each other. To just locate independent devices, fleet is enough.

When the link drops

An idle controller showing disconnected is expected; it reconnects on demand. To keep the web server reachable, keep its page open or reopen omna.local. If WiFi credentials are wrong or missing, the OLED stays reachable so you can fix them.

That’s Getting Started. Next: the Web Config App tour.