OmniRemote

Iris troubleshooting

Most problems are one of the first three. Start with what the ring is doing: the lights and sounds guide names every state.

During setup

Typed the wrong WiFi password

The hub restarts and can't get online: you hear a falling two-tone and the logo never appears on the ring. Hold the button on the HAT for 5 seconds until you hear one long beep, then let go. That erases its WiFi settings only and restarts it into setup mode (amber), so you can start again at step 4. Don't keep holding: at 10 seconds (three beeps) it becomes a full factory reset. A short press just beeps once to say it's alive.

The ring blinked red right after I tapped Connect

The hub rejected the WiFi name or password before even trying (empty, too long, or unsupported characters). It goes back to amber and the setup page says what to fix. Nothing to reset; just correct it and tap again.

No OmniRemote-Iris-Setup network

It only exists once the ring breathes amber, which is 2–4 minutes after the first power-on (1–2 minutes on later boots). If the ring stays dark and silent after four minutes, power-cycle once. If it still never appears, re-flash the card: the image write was probably interrupted. Also check that the HAT is seated all the way down on the header.

The setup page won't load

Make sure mobile data is off and your phone is still on OmniRemote-Iris-Setup; phones drop no-internet networks silently and fall back to cellular. Then open http://192.168.4.1 directly (type the http://, some browsers force https otherwise). setup.omniremote.us only works while you're on the setup WiFi.

My phone left the setup WiFi before I finished

Normal if you had already tapped Connect: the setup network shuts down within seconds of accepting your settings. If you hadn't, rejoin it; setup mode waits indefinitely.

It joined my WiFi but never finished

You heard the bright rising two-tone and the boot chime, the center beats purple, but the logo never appears. The hub is on your WiFi but can't reach the internet, which it needs once to finish activating. Check that the network has internet access and that a firewall or parental control isn't blocking the new device. On a guest or IoT network, allow the hub outbound.

Reaching the hub

The .local address doesn't resolve

Some Android browsers and older Windows builds don't do .local names. The hub's IP address always works: find it in your router's device or DHCP list as omniremote-iris-XXXX and open http://<ip>:8765. The app doesn't care either way; it discovers hubs itself.

Hub on an IoT or guest network, phone on the main one

.local names and app discovery don't cross network boundaries unless your router forwards mDNS / Bonjour between them. Either turn that on, or reach the hub by IP address and give it a DHCP reservation so the IP never changes. The hub itself only needs outbound internet, not inbound access.

I entered my email during setup but never got the "online" email

It is sent once, the first time the hub reports in after joining your WiFi, so it can take a few minutes after the logo appears. Check spam for a message from omniremote.us. If the hub never finished (see above) it never reported, and no email is sent. Your saved link from the setup page works regardless.

More than one hub

Each has its own network name from its MAC address, so they never collide. Give each a friendly name under Settings on the hub page (the name the app and Home Assistant show); the network name stays as-is so the address you wrote down keeps working.

Ring and sounds

Ring dark, green board light on

Still booting (the first boot takes up to 4 minutes, about a minute after the boot chime on later boots), or the ring indicators were turned off under Settings on the hub page. If the board light is also off, check the power supply and cable; the Pi needs a real 5 V supply, not a laptop port.

Red on the ring

Whole ring blinking red during setup: WiFi name or password rejected; the setup page says what to fix. Only the blade blinking red, later: an error the app or hub page will explain; the ring returns to the logo by itself. Ring filling red, then throbbing: a factory reset is in progress, see below.

Ring breathing amber when it used to show the logo

The hub is back in setup mode, which happens after a 5-second button hold (WiFi reset) or a factory reset. Join OmniRemote-Iris-Setup and run setup again. Your devices and license survive a WiFi reset; a factory reset erases them.

Ring is very dim, or there are no beeps

Brightness, the individual indicators and the buzzer are all adjustable under Settings on the hub page and in the app. Resets always show and sound regardless, so you can never erase a hub silently.

Resets, from gentlest to last resort

Button hold, 5 seconds: WiFi reset

Hold the button on the HAT for 5 seconds until you hear one long beep, then let go. The hub forgets its WiFi and restarts into setup mode (amber). Devices, rooms, scenes, license and users are kept. Use it when you moved, changed your WiFi password, or typed it wrong during setup. A press shorter than 2 seconds only beeps; between 2 and 5 seconds nothing happens.

Start over

Settings → Danger Zone on the hub page. Erases devices, rooms and scenes; keeps WiFi, license and users. The ring shows an orange comet lapping the ring, then a green wink.

Factory reset

Two ways. On the hub page: Settings → Danger Zone, after a backup download and typing the confirmation phrase. On the HAT: hold the button for 10 seconds, past the long beep at 5, until you hear three beeps; it fires right then. Either way everything is erased, including WiFi and users, and the hub is released from your license so you can attach another. From the hub page the ring fills red and throbs until the hub reboots into setup mode. Do this before selling or giving away a hub.

Re-flash the card

If the hub never reaches setup mode, or an update left it in a loop, write the image again from your account. Everything on the card is replaced; your license stays on your account and re-attaches when you sign in on the hub.

Account and license

The hub says it isn't activated

Sign in on the hub page or in the app with the account you bought with; the license attaches on sign-in. Each license covers a set number of hubs, shown on your account page; release an old hub there if you've hit the limit. The hub also needs outbound internet for its periodic license check.

Forgot the password and lost access to the email address too

"Forgot password" on the account page emails a reset code, and the backup code shown when you created the account resets it without email. If neither works, contact support: we'll verify you're the owner with something only you have, such as the license key from your purchase email, the serial on the HAT label, or your order details, then move the account to an address you control.

Can't download the image

Downloads are on your account page once a license is on the account. If you bought a kit, the license is attached when the order is fulfilled. The setup link in your purchase email expires after a week; sign in normally instead.

Still stuck

Write to support with what the ring is doing and what you heard, and the hub's version from Settings if you can reach it. The hub page's Support section can also export a diagnostic bundle you can attach.