Iris hub manual
A copy of the Help tab on your hub's own page, for hub software 1.7.6. The hub's copy always matches the version you are running; this one is refreshed with each release. New hub? Start with the setup guide.
Getting Started
Welcome to OmniRemote Iris! Here is the full setup flow from unboxing to control:
Setup Overview
Dashboard Layout (6 Tabs)
| Tab | Purpose |
|---|---|
| Dashboard | Overview stats: rooms, devices, blasters, scenes at a glance. |
| Rooms | Room-centric hub. Click a room to manage its Devices, Blasters, Scenes, Remote/Builder, and Physical Remotes. |
| Catalog | Device Catalog (IR code databases) and Button Catalog (icons, themes, streaming service buttons). |
| IR Tools | Test Catalog codes, Learn new IR codes, IR Debugger for troubleshooting signals. |
| Help | The Help tab on the hub (this manual). Setup guides, workflow diagrams, FAQ, and troubleshooting. |
| Settings | General config, System info, and Danger Zone (start over / factory reset). |
Choose the setup guide that matches your use case:
🏠 Iris Standalone
Use Iris as a standalone IR hub with the web UI or mobile app. No Home Assistant required.
View Guide →🌐 Iris + Home Assistant
Connect Iris to Home Assistant for full smart home integration with automations and dashboards.
View Guide →📱 Phone + Broadlink Only
Use the OmniRemote Android app directly with a Broadlink RM device. No Iris hub needed.
View Guide →Iris Standalone Setup Guide
Use Iris as a standalone IR control hub with the built-in web interface or mobile app.
Flow
Step 1: Flash the SD Card
- 1Download the latest OmniRemote Iris image from your account at omniremote.us.
- 2Flash the
.img.xzfile to a microSD card (8GB+) using Raspberry Pi Imager or balenaEtcher. - 3Insert the SD card into your Raspberry Pi and power it on.
Step 2: Connect to WiFi
- 1On first boot, Iris creates a WiFi hotspot: OmniRemote-Setup.
- 2Connect to the hotspot from your phone or laptop and open
http://192.168.4.1. - 3Enter your home WiFi credentials and license key, then click Connect.
- 4Iris reboots and joins your WiFi. The LED turns solid green when ready.
Step 3: Activate Your License
- 1If you entered your license during WiFi setup, activation happens automatically.
- 2Otherwise, open the Iris dashboard and enter your email + license key on the activation page.
- 3Activation requires a one-time internet connection. After that, Iris works fully offline.
Step 4: Create a Room & Add Devices
- 1Go to the Rooms tab and click + Add Room. Name it (e.g., "Living Room") and pick an icon.
- 2Inside the room, go to Devices and click + Add Device. Browse the Catalog or create a blank device.
- 3Use IR Tools → Learn to teach custom IR codes, or import from the Device Catalog.
Step 5: Build a Remote & Create Scenes
- 1Inside the room, go to Remote/Builder to create a custom remote layout.
- 2Create Scenes to send multiple IR commands in scene (e.g., "Movie Night" = TV on + receiver on + set input to HDMI).
Iris + Home Assistant Setup Guide
Connect Iris to Home Assistant for automations, dashboards, and voice control via Alexa/Google.
Flow
Prerequisites
- ✓Iris is set up and activated (see Standalone guide).
- ✓Home Assistant is running on the same network.
- ✓An MQTT broker (Mosquitto) is installed in Home Assistant. Go to HA → Settings → Add-ons → Mosquitto.
Step 1: Install the HA Integration
- 1Open HACS in Home Assistant. Go to Integrations → search for OmniRemote.
- 2Click Install. Restart Home Assistant when prompted.
- 3Go to HA → Settings → Devices & Services → Add Integration → OmniRemote.
Step 2: Discover Iris
- 1The integration auto-discovers Iris hubs via mDNS. Your hub should appear automatically.
- 2If not discovered, manually enter the Iris IP address and WebSocket port (default: 8081).
- 3Click Submit. All your devices and commands appear as HA entities.
Step 3: Enable MQTT Sync
- 1In the Iris web UI, go to Settings → General.
- 2Set the MQTT Broker field to your HA's Mosquitto address (e.g.,
homeassistant.local). - 3Enable Sync with Home Assistant and click Save Settings.
- 4Devices, rooms, and scenes now sync bidirectionally between Iris and HA.
Step 4: Use in HA
- 1Your IR devices appear as
remote.omniremote_*entities. Use them in automations, scripts, and dashboards. - 2Send IR commands via the
remote.send_commandservice. - 3Scenes from Iris are available as HA scenes. Run them from dashboards or voice assistants.
Phone + Broadlink Only Setup Guide
Use the OmniRemote Android app directly with a Broadlink RM device. No Iris hub required.
Flow
Step 1: Install the App
- 1Download the OmniRemote app from the Google Play Store (free).
- 2Open the app and allow local network permissions when prompted.
Step 2: Discover Your Broadlink
- 1Ensure your Broadlink RM device is powered on and connected to your WiFi.
- 2In the app, go to Settings → Blasters and tap Discover.
- 3Your Broadlink device should appear in the list. Tap to add it.
Step 3: Add Devices & Learn Codes
- 1Add your IR devices (TV, AC, receiver, etc.) in the app.
- 2Learn IR codes by pointing your physical remote at the Broadlink device and pressing buttons.
- 3Create custom remote layouts in the app to control everything from your phone.
Upgrading to Iris Later
- ↑If you later purchase an Iris hub, the app detects it automatically.
- ↑Your devices and codes can be synced to Iris. The Broadlink device becomes an additional blaster managed by Iris.
Room Management
Rooms are the central organizing unit in Iris. Everything lives inside a room.
Flow
Creating a Room
- 1Go to the Rooms tab and click + Add Room.
- 2Enter a name (e.g., "Living Room", "Bedroom") and choose an icon.
- 3Click a room card to enter it. Inside you will find sub-tabs: Devices, Blasters, Scenes, Remote/Builder, and Physical Remotes.
Inside a Room
| Sub-tab | What It Does |
|---|---|
| Devices | IR devices assigned to this room. Add, edit, import codes, learn new commands. |
| Blasters | IR blasters (Broadlink or GPIO) that serve this room. |
| Scenes | Multi-step automations (e.g., "Movie Night" sends power on + input HDMI + dim lights). |
| Remote/Builder | Visual grid-based remote layout for this room. Drag-and-drop button placement. |
| Physical Remotes | BLE remotes paired to this room. Map physical buttons to IR commands. |
Device Setup
Devices represent IR-controlled equipment (TVs, receivers, AC units, etc.).
Option A: Import from Catalog
Option B: Learn from Scratch
Step-by-Step
- 1Go to a Room → Devices and click + Add Device. Name it (e.g., "Samsung TV") and select a device type.
- 2To import codes: open the Catalog tab, find your brand/model, test a code, then import into your device.
- 3To learn codes: go to IR Tools → Learn, select the device, name the command, and press the button on your physical remote.
- 4You will hear a double beep on successful learn. Repeat for all buttons you need.
Remote Builder
Build custom touchscreen remote layouts for each room with a visual grid editor.
Flow
Step-by-Step
- 1Enter a room and click the Remote/Builder sub-tab.
- 2Set the grid dimensions (e.g., 4 columns x 8 rows).
- 3Click a grid cell to add a button. Choose from the Button Catalog (streaming icons, transport controls) or create a custom button.
- 4Assign each button to a Device + Command (e.g., Samsung TV → power).
- 5Style buttons: pick colors, shapes (circle, rounded-rect, pill), and add shadows.
- 6Click Preview to test the layout, then Save.
Button Sources
| Source | Description |
|---|---|
| Button Catalog | Pre-built buttons with icons for streaming services (Netflix, Hulu, etc.), transport controls, and navigation. |
| Custom | Create your own button with custom label, emoji icon, and color. |
| Upload | Upload a custom icon image (PNG/SVG) for the button face. |
Physical Remote Pairing (BLE)
Pair Bluetooth Low Energy remotes so physical button presses trigger IR commands automatically.
Flow
Supported Remotes
Any BLE HID remote should work: Amazon Fire TV remotes, Roku remotes (BLE models), Apple TV Siri Remote, generic BLE media remotes, Bluetooth keyboards, and game controllers.
Step 1: Scan & Pair
- 1Enter a room and go to the Physical Remotes sub-tab.
- 2Put your BLE remote in pairing mode (usually hold the home/pairing button for 5 seconds).
- 3Click Scan for Remotes. Your remote appears in the list with its name and signal strength.
- 4Click Pair next to your remote. Wait for the "Paired" confirmation.
Step 2: Configure Buttons
- 1After pairing, click Configure to open the button mapping panel.
- 2Select a profile (Fire TV, Roku, Apple TV, or Generic) to pre-populate standard button names.
- 3For each button, select a Target Device and Command from your learned IR codes.
- 4Example: Map the remote's "Volume Up" button to your Receiver's "vol_up" IR command.
Step 3: Test & Save
- 1Click Test Mode in the config panel. The indicator bar turns green.
- 2Press buttons on your physical remote. The panel shows which key code was detected and which IR command would fire.
- 3Click Save. The BLE daemon monitors your remote automatically. The remote auto-reconnects on wake.
Blaster Setup
Blasters are the IR transmitters that actually send signals to your devices. Iris supports GPIO IR and Broadlink RM devices.
Flow
Step-by-Step
- 1Enter a room and go to the Blasters sub-tab.
- 2Click Discover to scan the network for Broadlink devices, or click Add by IP to enter an address manually.
- 3The built-in GPIO IR transmitter is always available as a blaster option.
- 4Test connectivity by sending a test IR signal from the blaster.
- 5Devices in the room will use the assigned blaster to send IR commands.
Multiple Rooms
Place a Broadlink RM blaster in each room for independent IR coverage. The GPIO IR transmitter on the Pi provides coverage for the room where the hub is physically located.
Scene Setup
Scenes let you trigger multiple IR commands in scene with a single tap.
Flow
Step-by-Step
- 1Enter a room and go to the Scenes sub-tab. Click + Add Scene.
- 2Name the scene (e.g., "Movie Night", "Good Morning").
- 3Add actions: select a Device and Command for each step. Example: TV → power, Receiver → power, Receiver → input_hdmi1.
- 4Insert Wait delays between actions if devices need time to power on before receiving the next command.
- 5Save the scene. Run it from the Dashboard, from a Remote button, or via Home Assistant.
Frequently Asked Questions
Go to Rooms → select a room → Devices → + Add Device. You can import IR codes from the Catalog or learn them from a physical remote.
Go to the Catalog tab, find your brand/model, and click Test on any code. Iris sends the IR signal through your blaster so you can verify it controls your device before importing.
Broadlink blasters must be on the same VLAN/subnet as Iris for discovery. If your IoT devices are on a separate VLAN, either place the Broadlink on the same VLAN as Iris, or add the blaster by IP and ensure inter-VLAN routing allows UDP traffic on port 80.
Go to a Room → Physical Remotes → Scan. Put your BLE remote in pairing mode and click Pair. Then configure button mappings.
Go to a Room → Remote/Builder sub-tab. Set the grid size, add buttons from the Button Catalog or create custom ones, assign each to a device command, and save.
Go to a Room → Scenes → + Add Scene. Add a series of device commands with optional wait delays between them.
Solid green = ready. Blinking green = sending IR. Solid blue = learning mode. Blinking red = no WiFi. Solid red = error. See the Troubleshooting section for the full reference.
Start over (Settings → Danger Zone) erases devices, rooms, scenes and learned codes but keeps WiFi, your license activation and users. Factory reset erases everything and reboots into the setup hotspot, like a fresh flash — from Danger Zone, by holding the hardware reset button for 10 seconds, or by re-flashing the SD card. Both offer a backup download first. Your license key stays valid and can be activated again.
SSH into the Pi (enable it first under Settings → SSH, which also shows the password): ssh pi@<hub-hostname>.local. View logs: journalctl -u omniremote -f. Export: journalctl -u omniremote -n 500 --no-pager > /tmp/iris-log.txt.
Yes. Each hub has a unique Hub ID and operates independently. They all appear in the mobile app and Home Assistant.
Absolutely. Iris works 100% standalone with its built-in web dashboard and mobile app. Home Assistant integration is optional and free.
Troubleshooting
LED Status Reference
| LED Pattern | Meaning |
|---|---|
| Solid Green | Online and ready |
| Blinking Green | Processing / Sending IR |
| Solid Blue | Learning mode active |
| Blinking Blue | Waiting for IR signal during learn |
| Solid Red | Error state |
| Blinking Red | No network connection |
| Purple Pulse | Firmware update in progress |
| Off | Hub powered off or booting |
Buzzer Sounds Reference
| Sound | Meaning |
|---|---|
| Single short beep | Command sent successfully |
| Double short beep | IR code learned successfully |
| Long beep | Error or timeout |
| Rising tone | Hub booted and ready |
| Falling tone | Hub shutting down |
| Triple beep | Factory reset triggered |
GPIO Pinout
| GPIO Pin | Function | Notes |
|---|---|---|
| GPIO 18 | IR Transmitter (TX) | 38kHz carrier, connect to IR LED circuit |
| GPIO 7 | IR Receiver (RX) | Connect to TSOP38238 or similar |
| GPIO 22 | Status LED | RGB or single color LED |
| GPIO 27 | Buzzer (optional) | Passive buzzer for audio feedback |
| 3.3V / 5V | Power | IR LED circuit uses 5V, receiver uses 3.3V |
| GND | Ground | Common ground for all peripherals |
Refer to the wiring guide at omniremote.us/support for circuit diagrams.
Start over vs. Factory reset
- 1Start over (Settings → Danger Zone): erases devices, rooms, scenes, layouts, blasters and learned codes. Keeps WiFi, license activation, users and settings.
- 2Reset WiFi only (hardware button): hold 5 seconds until one long beep, then let go. The hub forgets its network and reboots into the amber setup hotspot; license, users and devices are kept.
- 3Factory reset (Danger Zone, or hold the hardware reset button for 10 seconds until three beeps): erases everything and reboots into the amber setup hotspot, like a fresh flash. Re-run setup and activation; the license key stays valid.
- 4Re-flash the SD card: same as a factory reset, and the only way to change the image version.
Log Export
- 1Enable SSH under Settings → SSH (the password shown there is unique to this hub), then
ssh pi@<hub-hostname>.local. - 2View live logs:
journalctl -u omniremote -f - 3Export last 500 lines:
journalctl -u omniremote -n 500 --no-pager > /tmp/iris-log.txt - 4Copy to your computer:
scp pi@omniremote.local:/tmp/iris-log.txt .
Common Issues
| Problem | Possible Cause | Solution |
|---|---|---|
| IR codes not sending | IR LED not wired correctly | Check GPIO 18 wiring. Use IR Tools → Debugger to test. |
| IR codes not learning | Receiver not detecting signal | Point remote directly at IR receiver. Check GPIO 7 wiring. |
| Web UI not loading | Iris not on network | Check LED status. Try accessing by IP instead of hostname. |
| MQTT not connecting | Wrong broker address or credentials | Verify broker IP in Settings. Check Mosquitto is running. |
| BLE remote not detected | Remote not in pairing mode | Hold pairing button 5+ seconds. Check Bluetooth is enabled on Pi. |
| BLE buttons not triggering IR | Missing button mappings | Open Configure on the remote and map buttons to IR commands. |
| License activation fails | No internet or wrong key | Verify internet connectivity. Double-check license key from purchase email. |
| Broadlink not discovered | Different subnet or locked device | Ensure Broadlink and Iris are on the same WiFi. Try Broadlink app first to unlock. |
Support & Contact
Need help? We're here for you.
- Online Support: omniremote.us/support
- Email: support@omniremote.us
omniremote.us · Patent Pending · OmniRemote™ is a trademark of One Eye Enterprises LLC