ESPHome device wizard

[matthiasdebaat]

Updates

• 21 Jul 2026 Minimizable banner, button and chip fixes, copy pass away from "proxy"
• 27 Jul 2026 Copy and layout pass on rows, banner, and reminder card

What this is

A concept for how a multi-purpose ESPHome device introduces itself after being added to Home Assistant. One piece of hardware, four things it can do where we help the users configure it.

More info about this opportunity can be found on this roadmap item OpenHomeFoundation/roadmap#191.

The prototype lives on the real HA device page so the wizard shows up in context, not as a standalone screen. A persistent banner ("Setup your ESPHome device") sits above the device cards and opens a checklist dialog.

Try prototype

CleanShot.2026-06-29.at.17.03.06.mp4

The four capabilities

To demonstrate its behavior we are using a reference device called "Connect Proxy" that surfaces these four capabilities:

• Bluetooth proxy: extends BT range, on by default
• Stream audio: use the device as a media player, with a nudge toward Music Assistant for multi-room
• Extend connectivity: add Zigbee, Thread, or Z-Wave via a plugged-in adapter
• Control a device over serial: AV receivers, amps, etc. over RS-232

Key design decisions

Checklist over linear wizard. Setup isn't a forced sequence. It's a hub of four independent flows you complete at your own pace, with progress saved. The banner copy adapts ("Setup" to "Continue setup") as you go. Is a checklist the right mental model, or does it feel like unfinished homework?

State-aware, not aspirational. Each capability reflects what the hardware is actually doing. No speaker plugged in? Audio is blocked with a reason. ZBT-2 detected? Connectivity skips ahead to "Detected, set up." We don't offer flows the hardware can't deliver. How aggressively should we show blocked items vs. just hide them?

The Music Assistant suggestion. Audio works out of the box, but we steer users toward Music Assistant as the better option. It's a deliberate suggestion inside a setup flow. Helpful or distracting?

The banner as permanent furniture. It stays on the device page after setup is done. Should it go away once everything's configured, collapse, or stay as an entry point?

What to poke at

• Does setup on the device page read clearly, or does it compete with the device cards?
• The four capabilities vary a lot in effort: flipping a toggle vs. forming a Z-Wave network. Should the checklist treat them equally, or show that difference?
• Copy tone and naming: "capabilities," the language inside each flow.

[teetow]

I love it, honestly.

It's not clear to me exactly how, but I assume this can be re-visisted at any later point in time? My thinking is, it looks like a first-time wizard that can be dismissed for "later." If I do that, where do I find it again?

[matthiasdebaat]

I have not figured this out yet. I have the review later button that (for now in my mind) minimize the box. I have not figured out yet where to minimize it, as it would be somewhere else on the page. Right now I think as a smaller card below the Device info card where you have the option to continue.

What do you think of this?

Side note: we really need to rework this device page.

[elcaptain]

yes, i mentioned that too. why would someone need to minimize it?

[matthiasdebaat]

My thinking: for example, if you only want to use Bluetooth proxy and Extend connectivity, you might want to hide this banner. Yet we should have an option to show it again when you want to add something else, for example Stream audio.

[GeorgeZ83]

Looking great, nice job!

Off topic: seeing BT proxy on by default, made me wonder why we don't have that enabled in the Voice PE firmware.

[matthiasdebaat]

Off topic: seeing BT proxy on by default, made me wonder why we don't have that enabled in the Voice PE firmware.

Good question! Based on a memory long time ago, I think it has to do with the available bandwidth on the ESP. Will check and get back to you.

[matthiasdebaat]

Yes, confirming that its a memory issue of the ESP.

[felinusfish]

LGTM!

[elcaptain]

nice, with the check marks on the right, it doesn't feel like a checklist at all, but a normal status. Like this i wouldn't feel any pressure to check everything off (and i normally do).
here is what else i noticed:

• what does the "review later" button do? i would think hide the card, but you said it's permanent.
• BL: for consistency should "turn off" button be a ghost button (with outline) like the "configure" buttons?
• audio: not sure about the yellow check mark when MA is not set up. more distracting than helpful.
• audio: "active" chip, does not look active with the grey colour. i'd make it green and "recommended" a different colour.
• audio: clicking "install MA" does not start the installation but opens a screen that just repeats the information from before. maybe skip it?
• audio: once MA is installed I may not know where to find it. add a link to open the UI?
• copy: "start setup" shows even if BL proxy is already set up. so it has already been started (should change to "configure" when everything is set up?)
• copy: coherency: BL proxy, but not Serial proxy? or "control a device over BL" and "control a device over serial"
• copy inconsistency: connect proxy on device page, esphome proxy in modal

[matthiasdebaat]

Thanks! Will update the outline button, chips, MA link and will check the copy with @googanhiem.

BL: for consistency should "turn off" button be a ghost button (with outline) like the "configure" buttons?

I don't have a strong opinion about this one. Will update it to outline.

audio: not sure about the yellow check mark when MA is not set up. more distracting than helpful.

We have been changing this one quite a bit. As we want to communicate that it is working, but there is a better option. What would you do?

audio: clicking "install MA" does not start the installation but opens a screen that just repeats the information from before. maybe skip it?

I lean towards changing the button label to learn more.

copy: "start setup" shows even if BL proxy is already set up. so it has already been started (should change to "configure" when everything is set up?)

Fair point. Will discuss this with the developers, as this would be a generic wizard for all kinds of ESPHome devices. Some might have not configured anything yet.

[googanhiem]

My suggested copy changes:

Small change to intro text to explain it can do all these things at once, also want to avoid using proxy as much as possible:

Setup your Connect device
This adapter unlocks four simultaneous capabilities in Home Assistant. Set them up now, or come back to this checklist any time.

Slightly friendly language... part of me wants to move away from the proxy terminology, but can't thing of anything better (Changing it to something like Bridge would be a bigger OHF decision)

Add nearby Bluetooth devices into Home Assistant. Adding multiple Bluetooth proxies allows for better connectivity with devices across your home.

The text box for MA is great text, just want to better explain the trade offs above.

Stream audio from Home Assistant (including announcements, media, or radio); just note this audio will be unsynchronized with other players. For synchronized whole-home audio, use Music Assistant.

This is the way I explain it in the draft marketing copy I'm working on. Just note there is no thread capability in the immediate future.

Connect anywhere
Network connectivity for Zigbee or Z-Wave
Plug a Connect ZBT-2 or ZWA-2 into the USB port to enable Zigbee or Z-Wave connectivity over Ethernet or Wi-Fi. Get your antenna in an optimal location for better device responsiveness.

Add serial devices into Home Assistant, allowing for control of A/V receivers and multi-zone amplifiers.

[matthiasdebaat]

Thanks for all the feedback. I did a new iteration, recording below.

What changed:

• "Review later" now minimize the banner to a compact "Setup your Connect device" card above the Device info card, with a "Configure" button to reopen the wizard.
• "Turn off" is now an outlined button, matching the "Configure" buttons.
• Chips: the "active" chip is now full green, similar to the green check. I kept the "recommended" chip a separate color since it is a suggestion, not a state.
• "Install Music Assistant" skips the repeated info screen and goes straight to installing when a speaker is connected. I also added a link to open Music Assistant after install.
• Primary button now always shows "Configure", so it no longer implies setup has or has not started.
• Copy pass across the banner, flows and descriptions using our copywriter's text, moving away from "proxy" language. "Extend connectivity" is now "Connect anywhere".

One I am keeping as is: the yellow check mark on audio when Music Assistant is not set up. I could not find a better way to signal "this works, but there is a better option" for now, so open to ideas if anyone has one.

CleanShot.2026-07-21.at.11.38.38.mp4

[abmantis]

Great design! The only part I am not a fan of is the "Setup your connect" being persistent section on the top-left.
I breaks the familiarity of the Device page, since users always expect the Device info section there, followed by the "Related" section. Also, once I setup the device I don't see the need for it to be so prominent on the device page. Maybe we can minimize it further into the Device Info section (just a row with 4 icons and the Configure button?)

[mkerstner]

Correct me if I'm wrong @matthiasdebaat but the idea behind keeping it that prominent is to provide visibility on new / unlocked functionality of your device.
I believe it's one of those issues when/where to show if something still can be configured and thus new functionality enabled.
That's basically the idea behind this wizard / check-list approach to be "prominent" and make user's aware that there still is something their device could do, as setup is not 100% finished.

[matthiasdebaat]

Yes, like @mkerstner said we want to be able to let the user continue with other functionality later in time.

I played a bit positioning this card, for example below the Device info. I picked this spot as it transitions the best without shuffling the page. Yet I don't have a strong opinion about this one.

Alternative is to make the card even smaller with a simpler design for the functionality. What do you think?

[abmantis]

I get that the idea is to make the "new functionality available" visible, but that should be only while it is actually a new device where setup is missing.

If I get a device for my speakers, after I set it up as a audio streamer, setup is 100% done from the user point of view. At that point, the setup wizard should be in a less prominent position, since setup is finished for the purpose of that device.

[matthiasdebaat]

If I get a device for my speakers, after I set it up as a audio streamer, setup is 100% done from the user point of view.

I would argue that we can’t be sure when the user thinks he is done. As we run on assumptions and haven’t researched this, I want to keep the options open for the user. Besides that, it helps surface use cases the user might not have considered.

[matthiasdebaat]

Another iteration, here is what changed:

• Connectivity: the row now reads "Connect a Zigbee or Z-Wave adapter" to make the action clearer.
• Audio: the row now reads "Stream audio via Sendspin".
• Banner: title is now "Set up your ESPHome proxy", with "Set up" and "Later" buttons.
• Reminder card: replaced the badges with a single line of copy, retitled it "Set up 3 more capabilities", changed the link to "Set up", and moved it above Controls.

CleanShot.2026-07-27.at.16.42.16.mp4

[abmantis]

I am still not a huge fan of the "Set up 3 more capabilities" being in the place where the main entities usually are, and taking so much prominent space with no real information.
Unless we expect that the majority of these devices will have the 4 capabilities utilized simultaneously, after setup that could be just a button in the Device info section, .

The rest of the design is great!

[mkerstner]

I do like the more subtle approach in this latest version, still showing the additional features to be unlocked for this device without being too pushy. Of course we can always argue best positioning to target all use cases/users. But after all, that would be an easy iteration if needed, e.g. to place it below Device Info. It's something new - I guess we can experiment to be more verbose about it at this stage and collect further feedback / adjust if needed going forward.

[matthiasdebaat]

Yes agreed. We can move it below device info too.