Passion Wave

RotaryKnob · guide

From unflashed hardware to the first action.

You need a desktop computer with Chrome or Edge, a USB data cable, 2.4 GHz Wi-Fi, and administrator access to Home Assistant. The regular installation requires neither a local ESPHome environment nor copied YAML files.

1. Before flashing

Open the guided installer

2. Why the device is flashed twice

An ESP32-S3 drives the display and inputs, while a separate ESP32 acts as the Home Assistant bridge. USB-C orientation exposes one chip at a time. Each wizard stage has a chip-specific image, preventing cross-installation.

3. Immediately after each flash

  1. S3: wait for “Installation complete”, select Next, and connect the 2.4 GHz network in the same dialog.
  2. Bridge restart: after “Installation complete”, close the dialog, unplug USB for two seconds, and reconnect it in the same ESP32 orientation.
  3. Bridge Wi-Fi: use “Open bridge Wi-Fi setup again”, select the ESP32 port, wait up to ten seconds, and choose Connect to Wi-Fi.
  4. Reverse USB-C: after the S3, unplug, rotate the connector 180°, and reconnect it.
  5. Flash the second chip: explicitly select “ESP32” without “S3” for the bridge.

The bridge restart is a required part of the guided path, not a second flash. It ensures that the classic ESP32 leaves the flashing state and starts Improv reliably.

4. Connect Home Assistant

  1. Install the PassionWave beta through HACS and restart Home Assistant.
  2. Power-cycle the RotaryKnob, add PassionWave within 20 minutes and select the matching PassionWave RotaryKnob … and PassionWave RotaryKnob Bridge …. The suffix distinguishes multiple physical RotaryKnobs.
  3. PassionWave uses ESPHome 2026.7 to provision a separate encryption key for each controller and creates both ESPHome entries without a key prompt.
  4. Select the Music Assistant instance, player, visible media, and up to four light slots. V3 requires no blueprints.
Configuration guide

Public factory images contain no shared key. The local user confirms the two processors inside PassionWave, which creates their private keys during setup.

5. Three-minute functional test

EncoderTurn on the media page. Volume should react immediately and smoothly.
TouchOpen weather, lighting, and media. Touches must not trigger the previous page.
MediaTest play/pause, next, previous, and a radio station. Scroll beyond the initial playlist window.
LightingChange brightness, select a light, and start a WLED preset if available.
WeatherCheck current values, daily limits, forecast, and radar.
OTAVerify firmware information and online state on both processor endpoints.

Weather screensaver mapping

The ESP32 reads Home Assistant weather state and forwards it to the S3, which immediately selects one of 15 locally compiled images. No external image request is needed.

clear-nightClear nightcloudyCloudyexceptionalExceptionalfogFoghailHaillightningLightninglightning-rainyLightning, rainypartlycloudyPartly cloudypouringPouringrainyRainysnowySnowysnowy-rainySnowy, rainysunnySunnywindyWindywindy-variantWindy, cloudy

An empty or unknown value uses “partly cloudy” as a deterministic fallback.

Troubleshooting

No serial port is visible

Try another USB data cable and a direct USB port. Restart the browser, then connect the device.

No Wi-Fi prompt appears after flashing the bridge

Close the completed flash dialog, unplug USB for two seconds, reconnect it in the same ESP32 orientation, then use the dedicated Wi-Fi button in installer step 4. Select the ESP32 port and wait up to ten seconds. Do not flash again.

Only one ESPHome endpoint is discovered

Reverse USB-C and reinstall the missing processor. Wait 90 seconds, then search for endpoints again.

The device is offline after entering Wi-Fi

Check 2.4 GHz support, the password, and client isolation. Reopen Wi-Fi setup for the affected chip; the other processor is not modified.

Controls work but Home Assistant does not

Verify that both processor endpoints of the RotaryKnob are connected and that the matching RotaryKnob and bridge were selected in the automation.

Music Assistant lists remain empty

Open Settings → Devices & services → PassionWave → Configure. Verify the selected Music Assistant instance and player, then keep “All automatically” enabled or select visible entries explicitly. V3 does not use a media-library blueprint.

Developers, recovery, and bug reports

Source, reproducible build profiles, checksums, and architecture live in the RotaryKnob repository. Serial flashing remains the recovery path; regular updates are installed separately by OTA.

Report a reproducible problem