Setup and operation

Complete Bridge guide

This guide starts with an unpowered bare board and ends with learned infrared profiles, per-zone routing, backup and signed online updates managed by RoonPilot.

IR Bridge 1.0.0 · RoonPilot 2.0.2

Use the official Web Installer for a first or clean installation after checking the wiring below. Already paired Bridges can be updated manually from RoonPilot.

Open Bridge Web Installer

Watch the complete IR Bridge video

1. What the Bridge does

RoonPilot IR Bridge is an optional ESP32-S3 companion for equipment that Roon cannot control directly. RoonPilot remains the user interface; the Bridge receives authenticated volume, mute and power actions and emits the learned commands of the original infrared remote.

Use native Roon / endpoint volume when it already controls the intended hardware correctly. The Bridge is an optional alternative for functions the endpoint does not expose. Playback, playlists and Live Radio still belong to Roon; the Bridge does not carry music.

Routing is selected per Roon zone. One zone can use native Roon volume, a second can control a DAC through infrared, and another can deliberately have volume control disabled. Disabling Bridge & Bluetooth turns off Bridge scanning, Bluetooth and all Bridge background work after RoonPilot restarts.

Switching the feature off retains saved pairings, routes and profiles. Until it is re-enabled and RoonPilot restarts, zones whose stored route is External IR or Disabled temporarily use native Roon behaviour. If the feature is on but an assigned Bridge is missing, RoonPilot instead fails closed: it does not silently send that volume or power action through Roon.

The complete Bridge interface follows RoonPilot's global English/German setting. Physical identities and user-defined zone, equipment and profile names remain exactly as entered.

There is no second product to administer.

RoonPilot manages the Bridge master switch, encrypted BLE scan and pairing, optional Wi-Fi provisioning, live transport health, IR profiles, guided learning, command tests, per-zone routing, on-screen Power/Mute controls, a combined setup backup and signed online updates. The Bridge itself has no cloud account or everyday web interface.

Profiles per BridgeUp to 8
Saved BridgesUp to 4
Active routesEvery required group member
CommandsVolume ±, mute, power on/off
Primary linkEncrypted BLE
FallbackAuthenticated local Wi-Fi

Terms at a glance

TermMeaning
Paired / savedRoonPilot and the Bridge have exchanged encrypted keys; the saved Bridge may currently be off or out of range.
ConnectedAn active BLE or authenticated Wi-Fi control path exists now.
Automatic zone controlThe selected Roon zone, or every physical member of its group, determines the required Bridge routes.
Maintenance selectionManage temporarily opens another saved Bridge for learning, diagnostics or updates; it does not change the zone route.
IR profileA named learned command set kept in RoonPilot's library and deployable to several Bridges.
Zone routeOne zone's choice of native Roon volume, a Bridge/profile or disabled volume.
Wi-Fi fallbackOptional local networking provisioned over encrypted BLE; it extends range and is preferred for firmware transfer.

2. Hardware and safe wiring

The validated build uses the Waveshare ESP32-S3-Zero with 4 MB flash and 2 MB PSRAM, an AZ-Delivery KY-022/CHQ1838 receiver, the Adafruit High Power Infrared LED Emitter 5639 and USB power.

Disconnect USB before changing any wire. Read the actual S, +, −, V+, GND and SIG labels on your delivered modules. Compatible KY-022 boards do not always expose their pins in the same physical order.
RoonPilot IR Bridge wiring diagram: both modules powered from the 3V3 output; 5V is an input
Both modules use the 3V3 output, including the Adafruit High Power Infrared LED Emitter 5639.
Bridge connectionDestinationPurpose
5VBoard power input onlyLeave unused when powering the board via USB; do not use it to supply modules
3V3 outputAdafruit 5639 V+3.3 V supply for the high-power IR emitter
GPIO4Transmitter SIG / S3.3 V IR modulation signal
3V3 outputKY-022 +3.3 V receiver supply; keeps its digital output inside the ESP32 input domain
GPIO5KY-022 S / OUTDemodulated IR receive signal
GNDBoth modulesMandatory common ground

The ESP32-S3-Zero's 5V pin is a power input, not a 5 V output. Connect every module's positive supply lead to the board's regulated 3V3 output, including V+ on the Adafruit high-power IR emitter. Power the board via USB using a stable 5 V / 1 A or better supply. The Adafruit module has its own transistor driver; GPIO4 provides only the control signal. Keep bursts short, share ground between all modules and keep the ESP32 ceramic antenna clear of modules, wiring and metal.

Printable Bridge enclosure

The project includes a printable body, lid, IR-emitter cover and two alternative foot lengths. Use one complete set of four equal feet. The photographs show the tested external and internal arrangement; they do not replace electrical inspection.

Download all STL files

ZIP with all five STL files. For printing, choose one set of four matching feet: long or short.

Complete the wiring and supervised open-board tests before closing the housing. Use a USB-C cable with a short connector housing whenever possible; if its plug is still too long, install four copies of the longer fuss_1x_drucken_4x.stl foot. Disconnect USB before fitting the lid, align the Adafruit emitter and optional learning receiver with their openings, keep wires free of the antenna and contacts, then repeat IR range and temperature checks on the closed enclosure. The separate print and enclosure guide contains the full assembly outline and model dimensions.

Bridge status LED colours

The small RGB LED is on the ESP32-S3-Zero. It is off during normal operation. Use RoonPilot's Bridge page for ongoing connection status; a dark LED does not mean the Bridge is powered off or disconnected.

LED patternMeaning
Slowly pulsing blueA pairing window is open.
Two short blue flashesEncrypted Bluetooth pairing succeeded.
Repeated short blue pulses for about 1.5 secondsIdentify Bridge was requested in RoonPilot.
Pulsing orangeThe Bridge is waiting for or recording an IR signal during learning.
Two short green flashesTwo matching IR captures were stored. After pulsing violet: firmware accepted; restart follows.
Two short red flashesIR learning failed or timed out. After pulsing violet: firmware transfer or verification failed.
Pulsing violetFirmware is being transferred or verified. Do not remove power.

After a short confirmation the LED turns off again or resumes showing an open pairing window. Cancelling IR learning ends the orange pattern without a red error signal.

3. First Factory installation

  1. Complete and inspect the wiring with USB disconnected. For the very first board test, disconnect the IR modules if their pin labels are not yet certain.
  2. Open the Bridge Web Installer in a current desktop Chrome or Edge. Firefox, Safari, iPhone and iPad cannot use the required Web Serial interface.
  3. Connect the Bridge board directly by USB. Close Arduino Serial Monitor, ESP-IDF Monitor and every other program using the port.
  4. In the Web Installer device chooser, select USB JTAG/serial debug unit (COM…) on Windows or USB JTAG/serial debug unit (cu.usbmodem…) on macOS. The name before the parentheses is what matters. No operating-system lookup is required first; the open chooser immediately detects a device after it is disconnected and reconnected. USB serial denotes a classic ESP32 there and is not the Bridge. Keep only the Bridge connected by USB during installation.
  5. Confirm the correct hardware, the complete erase and the firmware license, then start the installer. Keep USB connected until installation and restart have completed.
A Factory installation erases the complete Bridge. Identity, BLE bond, Wi-Fi fallback and all learned IR profiles are removed. The installer requests the required erase itself; do not perform a separate erase first. Before reinstalling an existing Bridge, synchronize its latest profiles to RoonPilot's library and create a complete backup under System → Configuration backup. The Bridge need not stay online during export. Pair the newly installed Bridge and select it explicitly as a restore target; see section 8.

After a successful Factory installation, the Bridge creates a new random identity in the form RPB-XXXX-XXX and permits its first encrypted pairing. The RGB LED slowly pulses blue while pairing is open.

4. Pair the Bridge with RoonPilot

  1. Open RoonPilot’s local web interface and select IR Bridge.
  2. Enable Bridge & Bluetooth, save and allow RoonPilot to restart. When disabled, no Bridge Bluetooth stack is started.
  3. Select Scan for Bridges. Compare the displayed RPB-… identity with the Bridge you intend to control.
  4. Select that identity and confirm pairing in RoonPilot. Do not pair an unknown nearby device.
  5. Wait for Encrypted and bonded, the installed Bridge version and Ready. Two short blue LED flashes confirm success; the LED then switches off.
  6. Run Test connection before learning profiles.

No accessible BOOT button is required for everyday pairing. If one side later loses its bond, power-cycle the Bridge three times within 15 seconds. The Bridge removes only its bond and opens pairing for five minutes; its identity and IR profiles remain intact.

One Bridge is currently owned and managed by one RoonPilot. Pairing it with a different controller is a deliberate ownership change, not simultaneous sharing.

RoonPilot scan and encrypted pairing screen with a documentation-only Bridge identity
RoonPilot shows the unique Factory identity before bonding. The screenshot uses dummy data; the real identity belongs to the freshly installed Bridge.

Saved is not the same as found

Saved IR Bridges is the persistent inventory of up to four pairings. Pair a Bridge contains only units heard during the last ten-second BLE scan. “1 found” can therefore correctly appear beside “2 / 4” saved. When a unit returns to BLE range, press Scan for Bridges again. Absence from the last discovery list erases neither pairing nor Wi-Fi control.

Two paired Bridges but only one heard in the last BLE scan
Example: Living Room continues over Wi-Fi beyond BLE range. A fresh scan is needed to show it in the discovery list after it comes back. Open full-size diagram.

Automatic zone control and Manage

The selected Roon zone always determines the required IR routes. For a group, this includes every assigned Bridge of its physical members. Manage opens a different saved Bridge only for maintenance, learning, diagnostics or update; it never changes a zone route. There is at most one BLE link but multiple separately authenticated Wi-Fi paths. Before Manage or Scan takes the BLE link, RoonPilot verifies that active IR routes remain reachable and refuses an unsafe switch. Select Return to zone control afterwards; idle maintenance selection expires after five minutes.

The selected Roon zone determines the target Bridge and IR profile
The zone route is independent of the temporary maintenance selection and of the current radio path.
Living Room IR travels over Wi-Fi while Office is managed over BLE
One BLE link, two simultaneous targets: the zone remains controllable through its own verified Wi-Fi path. IR commands never move to the maintenance Bridge. Open full-size diagram.

5. Optional Wi-Fi fallback

BLE remains the preferred link. If the Bridge must sit in another room, enable Allow Wi-Fi fallback while BLE is connected and bonded. RoonPilot then transfers its current 2.4 GHz credentials and a fresh 256-bit application key once through the encrypted BLE connection.

  1. Enable the switch and confirm provisioning.
  2. Wait for Connected and verified, the Bridge IP address and signal level.
  3. Use Test Wi-Fi path to force an authenticated Wi-Fi command even while BLE is available.

Commands use AES-256-GCM authentication and replay protection. A retry cannot silently produce a second IR action. Failed credentials are not retained, BLE remains the recovery path, and disabling fallback prevents the Bridge Wi-Fi radio from starting after reboot. RoonPilot and Bridge must be on the same local network without client isolation.

The Bridge has no separate setup access point. Its active transport and both signal readings are shown on the RoonPilot Bridge page; the device Quick Menu also reports Bridge status.

RoonPilot Bridge status with preferred BLE and an enabled authenticated Wi-Fi fallback
BLE remains preferred even after Wi-Fi has been provisioned. This single status card makes the active path, Bridge address, signal and protection visible and provides a forced Wi-Fi test.

A fluctuating dBm reading alone does not trigger a handover. RoonPilot keeps a working path stable, changes to provisioned Wi-Fi only after repeatedly confirmed trouble and does not immediately switch back when BLE range returns. An IR command with an uncertain outcome is not blindly replayed.

Four phases from stable BLE through Wi-Fi fallback to a verified return to BLE
“Ready via Wi-Fi” describes the current command path. Pairing, profile and Roon-zone assignment remain unchanged. Open full-size diagram.

6. Create and learn an IR profile

With multiple Bridges, only one needs an IR receiver. This learning Bridge can capture profiles for every zone. RoonPilot stores them independently of that Bridge and deploys them to the chosen target Bridge when you save a zone route, even if the target has no receiver.

  1. Under IR profiles, create a uniquely named profile such as RME ADI-2 DAC and save it on RoonPilot. No Bridge is needed yet. Keep the usual 38 kHz carrier and 33% duty unless the equipment requires something else.
  2. Select that profile and any learning Bridge with an IR receiver. It need not be the eventual target Bridge. Learning reserves it so it cannot send normal IR commands until learning ends.
  3. Choose Learn beside Volume up. The learning Bridge LED pulses orange while it waits.
  4. Aim the original remote at the KY-022 and press the requested key once, briefly and cleanly.
  5. Repeat the same press when requested. The Bridge accepts only matching captures.
  6. Two short green flashes mean that the command was analysed and stored; two red flashes mean timeout, mismatch or failure.
  7. Learn the remaining required buttons and use Save on RoonPilot to commit the confirmed commands to its persistent library. Discard learning leaves the library profile unchanged. Test the real equipment only after learning has ended and the zone route has deployed the profile; normal IR sends are blocked during learning. An unfinished learning session expires automatically after at most ten minutes.

Known NEC and Extended NEC signals retain protocol and repeat information; unknown signals remain available as lossless raw timing. Duty is the on-time percentage of each carrier cycle—not press duration and not the number of repeats. The 33% default means that a 38 kHz LED carrier is on for roughly 8.7 µs of each 26.3 µs cycle.

Power has two separate slots. On RoonPilot, a short press sends Power on; a long press sends Power off. Learn or verify both slots independently, even if the original remote uses the same physical button.
Named IR profile in RoonPilot's library and a learning Bridge selector
The library profile remains on RoonPilot; any paired Bridge with an IR receiver may be selected for capture.
Four steps from creating a profile through learning to deployment on other Bridges
Only completing learning saves the confirmed captures on RoonPilot. The eventual target Bridge is assigned separately in the zone route. Open full-size diagram.

7. Route each zone

Open Zone Management and choose one volume path for every visible zone:

  • Roon / endpoint volume sends the endpoint’s native absolute or dB volume command.
  • External IR Bridge sends Volume up/down from the selected profile.
  • Disabled deliberately discards volume actions.

Set the encoder step count separately for every zone. 2 Steps means two complete learned IR button presses for each RoonPilot detent. It does not mean one artificially held command. On the validated RME profile, two physical 0.5 dB increments therefore produce exactly one 1.0 dB RoonPilot detent.

Mute and Power can also be enabled per zone. Play/Pause, Previous and Next remain native Roon actions. Because incremental infrared does not report an absolute value, the display shows a relative + / − action counter instead of inventing a volume number.

If an assigned Bridge becomes unreachable while Bridge control remains enabled, RoonPilot marks that path offline; it does not silently replace the intended IR volume or power command with a native Roon command.

For External IR Bridge, select a paired Bridge and a named profile from RoonPilot's library. Save automatically transfers and verifies that profile on the target Bridge before activating the route. The same library profile can be assigned to several Bridges; their numeric profile slots are independent.

Roon groups and several Bridges

A selected Roon group does not replace its members' saved routes. RoonPilot resolves every physical output and may therefore send native numeric volume, native dB volume, relative Roon commands and IR commands through several Bridges during the same ring movement. All Bridges required by the group are monitored; one unreachable Bridge marks only its own member OFFLINE and never causes a silent fallback to another profile.

The first ring detent opens the on-device group mixer without changing volume. Further turning controls the complete group. Tap one of the large member rows to adjust only that output, or tap the group heading to return to all members. The round display offers up to three individually selectable rows; whole-group turning still processes every eligible output.

Roon group combining native numeric volume, dB volume and one infrared Bridge
There is at most one BLE link, while several authenticated Wi-Fi paths may operate in parallel for the same group. Open full-size diagram.
RoonPilot whole-group volume mixer
Whole-group control keeps the Roon group name and each output's honest unit visible.
RoonPilot group mixer with one output selected
After a row is tapped, the ring changes only that physical output.

When several members use the same physical Bridge, RoonPilot deliberately sends one IR action per detent to that Bridge rather than duplicating it. Use independent Bridges for independent IR targets. See the complete Roon group and group-mixer guide for mixed units, display limits, failure handling and a worked example.

Example routeWiiM Ultra → RME ADI-2 DAC

Music transport still goes through Roon and WiiM. Only volume, mute and power are routed to the Bridge, so the RME performs the analogue/hardware level change itself. This preserves the DAC’s Auto Ref Level behaviour and avoids substituting Roon digital attenuation for the RME volume control.

Per-zone routing table combining native Roon, external IR and disabled volume
Every row is independent. The example uses two IR-controlled zones, one native Roon endpoint and one deliberately disabled volume path.

8. Back up and restore the setup

After learning and testing IR commands, open System → Configuration backup and select Create Backup. One JSON file contains RoonPilot settings, zone routes, HTTP Power actions, each named IR profile once and separate assignments to Bridges. The learned pulse data has checksums. Profiles also persist in a RoonPilot-side library.

Creating a backup reads the permanent profile library on RoonPilot, not the live Bridges. An offline Bridge therefore neither delays the download nor makes the file partial. Changes that have not yet synchronized from a Bridge may be absent. A known older Bridge copy produces a warning; the library version remains authoritative.

Wi-Fi credentials, Roon authorization, transport keys and BLE bonds are excluded. There is no separate backup step under Maintenance, and a compatible configuration backup can be imported while Bridge & Bluetooth is off. After Factory installation or board replacement, pair the Bridge again and choose it in the restore dialog. One profile can be transferred to several Bridges, with a new local profile ID on each. Zone routes require an explicit target and never assume the old numeric ID is still valid. See the backup and restore guide.

An offline Bridge does not abort restore. RoonPilot restores its settings and profile library, continues with available Bridges and lists unconfirmed transfers for later completion. An IR route without a verified current assignment stays unchanged. When the Bridge is reachable again, repeat the import or transfer the restored library profile and save the affected route.

RoonPilot System page with Create Backup and restore controls
One file contains controller settings, library profiles and Bridge assignments. Offline restore targets are deferred, not treated as a failed controller restore.
Diagram showing one backup file with independent profiles and separate Bridge assignments
Already synchronized profiles stay in the file even if their Bridge is temporarily offline.

9. Signed online updates

After the first Factory installation, normal Bridge updates are managed from RoonPilot’s IR Bridge → Bridge firmware update card—no USB access and no local BIN selection are normally required.

  1. When the Bridge feature is enabled, RoonPilot may check the HTTPS manifest after startup and at most once every 24 hours. Update checking and the once-per-day device notice are separate settings.
  2. The page shows installed and available Bridge versions. A visible status-bar notice links directly to the update card; the device notice is dismissible and waits until important interaction has finished.
  3. Installation never starts automatically. Select Download and install and confirm it explicitly.
  4. RoonPilot validates channel, project, board, protocol range, required controller version, size, SHA-256, ESP32-S3 target and embedded version before transfer.
  5. Authenticated Wi-Fi is preferred for the transfer. If normal Bridge Wi-Fi is off but BLE is bonded, RoonPilot may provision and enable Wi-Fi temporarily, transfer the image and restore the previous off state after the Bridge reconnects. Encrypted BLE remains the slower recovery path when Wi-Fi cannot be used.
  6. The Bridge independently checks order, size, SHA-256 and its RSA-3072 signature before activating the inactive A/B partition.
  7. Success is reported only after the Bridge reconnects and reports the requested version. ESP-IDF rollback remains available if the new application cannot confirm its start.

If Bridge & Bluetooth is disabled, RoonPilot performs no Bridge scan, update request, web notice or display notice. The normal RoonPilot firmware update channel remains independent.

Signed online Bridge update managed by RoonPilot
Installed and available versions, daily checks, device notices and manual installation are all controlled from RoonPilot. The local image path remains a recovery tool.

10. Troubleshooting

No serial device in the installer

Use a data-capable cable, close serial monitors, connect directly without a hub, then hold BOOT while inserting USB and release it after the port appears.

Bridge is not found

Confirm Bridge & Bluetooth is enabled and saved. For a previously paired Bridge, use the three-power-cycle recovery and scan during the five-minute blue pairing window.

Learning times out

Check KY-022 pin labels, use 3.3 V, reduce sunlight, move the original remote closer and use two clean presses of equal length.

Wrong volume increment

First verify one learned command with Test. Then check the zone’s independent step count; do not compensate for a bad recording with a larger number.

Wi-Fi fallback does not connect

Provision while BLE is bonded, use 2.4 GHz, keep both devices on the same LAN and disable AP/client isolation. BLE must remain available after a failed first test.

An update is not offered

Check that the Bridge feature and Bridge update check are enabled, then use the manual check on the update card. An older unsigned test build may first require a wired migration.

Infrared still needs line of sight or useful reflections. If a connected Bridge does not operate the equipment, check emitter placement and the learned command before changing the zone step count.

Build your own Bridge step by step

Install only when the wiring has been checked.

Open Bridge Web Installer