OmniRemote

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

Flash SD Card → Connect WiFi/BLE → Activate License → Create Room → Add Devices → Build Remote → Control!

Dashboard Layout (6 Tabs)

TabPurpose
DashboardOverview stats: rooms, devices, blasters, scenes at a glance.
RoomsRoom-centric hub. Click a room to manage its Devices, Blasters, Scenes, Remote/Builder, and Physical Remotes.
CatalogDevice Catalog (IR code databases) and Button Catalog (icons, themes, streaming service buttons).
IR ToolsTest Catalog codes, Learn new IR codes, IR Debugger for troubleshooting signals.
HelpThe Help tab on the hub (this manual). Setup guides, workflow diagrams, FAQ, and troubleshooting.
SettingsGeneral 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

Flash Image → Boot Pi → Connect to OmniRemote-Setup WiFi → Enter Home WiFi → Hub Reboots → Open Browser to IP:8765 → Activate License → Ready!

Step 1: Flash the SD Card

  1. 1Download the latest OmniRemote Iris image from your account at omniremote.us.
  2. 2Flash the .img.xz file to a microSD card (8GB+) using Raspberry Pi Imager or balenaEtcher.
  3. 3Insert the SD card into your Raspberry Pi and power it on.

Step 2: Connect to WiFi

  1. 1On first boot, Iris creates a WiFi hotspot: OmniRemote-Setup.
  2. 2Connect to the hotspot from your phone or laptop and open http://192.168.4.1.
  3. 3Enter your home WiFi credentials and license key, then click Connect.
  4. 4Iris reboots and joins your WiFi. The LED turns solid green when ready.

Step 3: Activate Your License

  1. 1If you entered your license during WiFi setup, activation happens automatically.
  2. 2Otherwise, open the Iris dashboard and enter your email + license key on the activation page.
  3. 3Activation requires a one-time internet connection. After that, Iris works fully offline.

Step 4: Create a Room & Add Devices

  1. 1Go to the Rooms tab and click + Add Room. Name it (e.g., "Living Room") and pick an icon.
  2. 2Inside the room, go to Devices and click + Add Device. Browse the Catalog or create a blank device.
  3. 3Use IR Tools → Learn to teach custom IR codes, or import from the Device Catalog.

Step 5: Build a Remote & Create Scenes

  1. 1Inside the room, go to Remote/Builder to create a custom remote layout.
  2. 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

Install HA Integration → Iris Auto-Discovered → Enable MQTT Sync in Settings → Devices Appear in HA → Use HA or Iris Dashboard

Prerequisites

  1. ✓Iris is set up and activated (see Standalone guide).
  2. ✓Home Assistant is running on the same network.
  3. ✓An MQTT broker (Mosquitto) is installed in Home Assistant. Go to HA → Settings → Add-ons → Mosquitto.

Step 1: Install the HA Integration

  1. 1Open HACS in Home Assistant. Go to Integrations → search for OmniRemote.
  2. 2Click Install. Restart Home Assistant when prompted.
  3. 3Go to HA → Settings → Devices & Services → Add Integration → OmniRemote.

Step 2: Discover Iris

  1. 1The integration auto-discovers Iris hubs via mDNS. Your hub should appear automatically.
  2. 2If not discovered, manually enter the Iris IP address and WebSocket port (default: 8081).
  3. 3Click Submit. All your devices and commands appear as HA entities.

Step 3: Enable MQTT Sync

  1. 1In the Iris web UI, go to Settings → General.
  2. 2Set the MQTT Broker field to your HA's Mosquitto address (e.g., homeassistant.local).
  3. 3Enable Sync with Home Assistant and click Save Settings.
  4. 4Devices, rooms, and scenes now sync bidirectionally between Iris and HA.

Step 4: Use in HA

  1. 1Your IR devices appear as remote.omniremote_* entities. Use them in automations, scripts, and dashboards.
  2. 2Send IR commands via the remote.send_command service.
  3. 3Scenes from Iris are available as HA scenes. Run them from dashboards or voice assistants.

Room Management

Rooms are the central organizing unit in Iris. Everything lives inside a room.

Flow

Create Room (with icon) → Add Devices to Room → Add Blaster to Room → Create Scenes → Build Remote Layout → Map Physical Remote

Creating a Room

  1. 1Go to the Rooms tab and click + Add Room.
  2. 2Enter a name (e.g., "Living Room", "Bedroom") and choose an icon.
  3. 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-tabWhat It Does
DevicesIR devices assigned to this room. Add, edit, import codes, learn new commands.
BlastersIR blasters (Broadlink or GPIO) that serve this room.
ScenesMulti-step automations (e.g., "Movie Night" sends power on + input HDMI + dim lights).
Remote/BuilderVisual grid-based remote layout for this room. Drag-and-drop button placement.
Physical RemotesBLE 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

Browse Catalog → Test Code with Blaster → Create Device & Import → Assign to Room → Learn Additional Codes

Option B: Learn from Scratch

Create Device → Import from Catalog (inline) → Learn Custom Codes → Assign to Room

Step-by-Step

  1. 1Go to a Room → Devices and click + Add Device. Name it (e.g., "Samsung TV") and select a device type.
  2. 2To import codes: open the Catalog tab, find your brand/model, test a code, then import into your device.
  3. 3To learn codes: go to IR Tools → Learn, select the device, name the command, and press the button on your physical remote.
  4. 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

Select Room → Open Builder → Set Grid Size → Add Buttons (Catalog/Custom/Upload) → Style Buttons (Color/Shape/Shadow) → Preview → Save Layout

Step-by-Step

  1. 1Enter a room and click the Remote/Builder sub-tab.
  2. 2Set the grid dimensions (e.g., 4 columns x 8 rows).
  3. 3Click a grid cell to add a button. Choose from the Button Catalog (streaming icons, transport controls) or create a custom button.
  4. 4Assign each button to a Device + Command (e.g., Samsung TV → power).
  5. 5Style buttons: pick colors, shapes (circle, rounded-rect, pill), and add shadows.
  6. 6Click Preview to test the layout, then Save.

Button Sources

SourceDescription
Button CatalogPre-built buttons with icons for streaming services (Netflix, Hulu, etc.), transport controls, and navigation.
CustomCreate your own button with custom label, emoji icon, and color.
UploadUpload 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

Scan for BLE Devices → Put Remote in Pairing Mode → Click Pair → Configure Buttons → Select Profile (Fire TV/Roku/etc) → Map Each Button to Device+Command → Test Mode → Save

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

  1. 1Enter a room and go to the Physical Remotes sub-tab.
  2. 2Put your BLE remote in pairing mode (usually hold the home/pairing button for 5 seconds).
  3. 3Click Scan for Remotes. Your remote appears in the list with its name and signal strength.
  4. 4Click Pair next to your remote. Wait for the "Paired" confirmation.

Step 2: Configure Buttons

  1. 1After pairing, click Configure to open the button mapping panel.
  2. 2Select a profile (Fire TV, Roku, Apple TV, or Generic) to pre-populate standard button names.
  3. 3For each button, select a Target Device and Command from your learned IR codes.
  4. 4Example: Map the remote's "Volume Up" button to your Receiver's "vol_up" IR command.

Step 3: Test & Save

  1. 1Click Test Mode in the config panel. The indicator bar turns green.
  2. 2Press buttons on your physical remote. The panel shows which key code was detected and which IR command would fire.
  3. 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

Scan Network or Add by IP → Blaster Found → Test Connectivity → Assign to Room → Use as IR Source for Devices

Step-by-Step

  1. 1Enter a room and go to the Blasters sub-tab.
  2. 2Click Discover to scan the network for Broadlink devices, or click Add by IP to enter an address manually.
  3. 3The built-in GPIO IR transmitter is always available as a blaster option.
  4. 4Test connectivity by sending a test IR signal from the blaster.
  5. 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

Create Scene in Room → Add Actions (Device+Command) → Add Wait Delays → Save → Run from Dashboard or Remote

Step-by-Step

  1. 1Enter a room and go to the Scenes sub-tab. Click + Add Scene.
  2. 2Name the scene (e.g., "Movie Night", "Good Morning").
  3. 3Add actions: select a Device and Command for each step. Example: TV → power, Receiver → power, Receiver → input_hdmi1.
  4. 4Insert Wait delays between actions if devices need time to power on before receiving the next command.
  5. 5Save the scene. Run it from the Dashboard, from a Remote button, or via Home Assistant.

Frequently Asked Questions

Q: How do I add a device?

Go to Rooms → select a room → Devices → + Add Device. You can import IR codes from the Catalog or learn them from a physical remote.

Q: How do I test if catalog codes work?

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.

Q: How do I control devices on a different VLAN?

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.

Q: How do I pair a Bluetooth remote?

Go to a Room → Physical Remotes → Scan. Put your BLE remote in pairing mode and click Pair. Then configure button mappings.

Q: How do I build a custom remote layout?

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.

Q: How do I create a scene?

Go to a Room → Scenes → + Add Scene. Add a series of device commands with optional wait delays between them.

Q: What do the LED patterns mean?

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.

Q: How do I factory reset?

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.

Q: How do I export logs?

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.

Q: Can I use multiple Iris hubs?

Yes. Each hub has a unique Hub ID and operates independently. They all appear in the mobile app and Home Assistant.

Q: Can I use Iris without 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 PatternMeaning
Solid GreenOnline and ready
Blinking GreenProcessing / Sending IR
Solid BlueLearning mode active
Blinking BlueWaiting for IR signal during learn
Solid RedError state
Blinking RedNo network connection
Purple PulseFirmware update in progress
OffHub powered off or booting

Buzzer Sounds Reference

SoundMeaning
Single short beepCommand sent successfully
Double short beepIR code learned successfully
Long beepError or timeout
Rising toneHub booted and ready
Falling toneHub shutting down
Triple beepFactory reset triggered

GPIO Pinout

GPIO PinFunctionNotes
GPIO 18IR Transmitter (TX)38kHz carrier, connect to IR LED circuit
GPIO 7IR Receiver (RX)Connect to TSOP38238 or similar
GPIO 22Status LEDRGB or single color LED
GPIO 27Buzzer (optional)Passive buzzer for audio feedback
3.3V / 5VPowerIR LED circuit uses 5V, receiver uses 3.3V
GNDGroundCommon ground for all peripherals

Refer to the wiring guide at omniremote.us/support for circuit diagrams.

Start over vs. Factory reset

  1. 1Start over (Settings → Danger Zone): erases devices, rooms, scenes, layouts, blasters and learned codes. Keeps WiFi, license activation, users and settings.
  2. 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.
  3. 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.
  4. 4Re-flash the SD card: same as a factory reset, and the only way to change the image version.

Log Export

  1. 1Enable SSH under Settings → SSH (the password shown there is unique to this hub), then ssh pi@<hub-hostname>.local.
  2. 2View live logs: journalctl -u omniremote -f
  3. 3Export last 500 lines: journalctl -u omniremote -n 500 --no-pager > /tmp/iris-log.txt
  4. 4Copy to your computer: scp pi@omniremote.local:/tmp/iris-log.txt .

Common Issues

ProblemPossible CauseSolution
IR codes not sendingIR LED not wired correctlyCheck GPIO 18 wiring. Use IR Tools → Debugger to test.
IR codes not learningReceiver not detecting signalPoint remote directly at IR receiver. Check GPIO 7 wiring.
Web UI not loadingIris not on networkCheck LED status. Try accessing by IP instead of hostname.
MQTT not connectingWrong broker address or credentialsVerify broker IP in Settings. Check Mosquitto is running.
BLE remote not detectedRemote not in pairing modeHold pairing button 5+ seconds. Check Bluetooth is enabled on Pi.
BLE buttons not triggering IRMissing button mappingsOpen Configure on the remote and map buttons to IR commands.
License activation failsNo internet or wrong keyVerify internet connectivity. Double-check license key from purchase email.
Broadlink not discoveredDifferent subnet or locked deviceEnsure Broadlink and Iris are on the same WiFi. Try Broadlink app first to unlock.

Support & Contact

Need help? We're here for you.