[RFC] Streamlined Device Onboarding: Active/Passive Bus Discovery with a "Pending Devices" Staging & Management View

[GreenGrassBlueOcean]

Background & Context

This RFC is spun off from the discussion in Issue #229 (comment #5619446957) between @xtimmy86x, @anotherjulien, and @GreenGrassBlueOcean.

The goal is to design an optimal, Home Assistant-compliant onboarding experience for MyHOME SCS installations—especially medium-to-large homes with 50 to 100+ physical bus addresses—without overwhelming users with generic entity clutter.

---

The Problem Statement

When setting up a fresh MyHOME integration on an existing installation:

1. Entity Clutter: An automated scan or bulk import can instantly populate Home Assistant with 50–100+ generic entities (light.light_1, cover.cover_31, etc.), leaving the user with the daunting chore of clicking through every single entity to identify, rename, and assign it to an area.
2. Ambiguous Devices: OpenWebNet address responses don't always distinguish between functional roles—for instance, a WHO=1 address could be a ceiling light, an extractor fan, or a switched socket (which should logically be a switch rather than a light).
3. Passive-Only Devices: Scenario pushbuttons (CEN WHO=15 and CEN+ WHO=25) never answer status polling. They only emit telegrams when physically pressed, so a static startup scan will miss them entirely.

---

Constraints & Architectural Boundaries

During our initial investigation, two major boundaries were highlighted:

1. Home Assistant Architectural Standards (ADR-0010 & Quality Scale)

• No Entity Naming in Config/Options Flows: Home Assistant guidelines strictly forbid using Config Flows or Options Flows to set or edit entity names, icons, or areas. Those belong exclusively to the native Entity Registry and Device Registry.
• Single Source of Truth: Storing custom friendly names in integration config/options entries creates competing sources of truth, which breaks when users later rename entities or reassign areas via the standard HA UI.
• Frontend Lifecycle: Integrations cannot programmatically pop open an Options Flow or configuration modal after initial setup completes.

2. OpenWebNet Protocol Realities

• No Broadcast Discovery: OpenWebNet has no single command to enumerate all devices on the bus. Discovery requires sequential polling of individual addresses across multiple subsystems (WHO=1 for lighting, WHO=2 for shutters, WHO=4 for HVAC, etc.).
• Bus Speed Limits: At 9600 bps, sequentially probing addresses without bus collisions or flooding takes 20–45+ seconds, which is far too long for a synchronous onboarding wizard.

---

Proposed Solution: The "Staged Pending Devices" Workflow

To resolve this, @xtimmy86x and @anotherjulien proposed moving from immediate auto-creation to a staged onboarding pipeline:

[Gateway Connected]
        │
        ├──► Active Background Scan (WHO 1, 2, 4...) ──┐
        │                                              ▼
        └──► Passive Telegram Sniffer (CEN, CEN+...) ──► [Pending Devices Staging Queue]
                                                               │
                                                               ▼
                                                  [Interactive Review View]
                                                  • Review WHO / WHERE / Inferred Type
                                                  • Select Platform (Light vs Switch)
                                                  • Assign Friendly Name & Area
                                                  • Actions: [Add] or [Ignore]
                                                               │
                                                               ▼
                                                  [HA Entity & Device Registries]
                                                  (Updated via native WebSocket API)

1. Dual Discovery Pipeline

• Active Background Scan: Once the gateway connects (or upon triggering a myhome.scan_bus button/service), a rate-limited background task polls known address ranges across common subsystems without blocking the user.
• Passive Bus Sniffer: The bus monitor listens for telegrams from unmapped addresses during normal daily use. When a user presses an unconfigured CEN/CEN+ scenario button or an auxiliary contact fires, it is automatically captured and staged.

2. Staging Queue ("Pending Devices")

• Discovered addresses are recorded in an integration staging state (pending_devices) rather than immediately creating HA entities.
• Each entry contains:
  • Subsystem (WHO)
  • Address (WHERE)
  • Inferred Type / Capabilities (e.g. relay, dimmer, shutter, scenario control)
  • Discovery Source (Active Scan vs Passive Bus Event)
  • First Seen / Last Seen timestamp

3. Interactive Management & Review View

• An interactive table (e.g., a dedicated tab in myhome-bus-card or a custom panel) displays all pending devices.
• For each item, the user can:
  • Disambiguate Platform: Choose whether a WHO=1 device is a Light or a Switch.
  • Name & Area: Enter the desired Friendly Name and select an HA Area directly in the table.
  • Add: Confirm the device, creating the entity.
  • Ignore: Mark the address as ignored so it no longer appears in the pending list and doesn't generate entities.
  • Bulk Operations: Bulk-add or bulk-ignore items.

4. Clean Registry Updates

• When the user clicks Add, the integration adds the technical entry and uses Home Assistant's native WebSocket API (config/entity_registry/update and config/device_registry/update) to apply the chosen Name and Area directly to the core registries.
• Home Assistant's native registries remain the sole source of truth for customization.

---

Open Questions for Community Feedback

1. UI Surface: Where should this management interface live?
   • As an additional tab/view inside the existing myhome-bus-card Lovelace card?
   • As an independent custom Lovelace card (myhome-device-manager)?
   • Or as an HA custom panel / sidebar entry?
2. Handling CEN / CEN+ Pushbuttons:
   • Since scenario buttons do not have an on/off state, should adding a pending CEN/CEN+ device create an event.* entity, HA Device Automation Triggers, or both?
3. Managing Ignored Devices:
   • Should the UI provide an "Ignored Devices" filter to easily inspect and un-ignore addresses later?
4. Coexistence with myhome.yaml:
   • How should this interact with installations that already use myhome.yaml for pre-configured wiring schedules? (e.g. YAML devices pre-populate as already approved, leaving only newly detected unmapped addresses in the pending queue).

---

We would love to hear your thoughts, use cases, and feedback on this design!
Cc @xtimmy86x @anotherjulien @TheDarkWizard

[mvalla]

So HA does not have a “inbox” for Discovery results like in openHAB ??

[anotherjulien]

Well, it does... for a new gateway it would have that behavior, but not for a new device connected via and existing gateway...

For instance if you have ZWaveUI (the application) and use it to connect a new node to your mesh, you will automatically have that device available in the ZWave integration and in HA.

[TheDarkWizard]

Regarding the identification workflow, I would leave the resources in a pending state as you already proposed. The topic of the buffer sniffer to eventually identify devices not discovered in the first instance is also interesting.

UI Surface: Where should this management interface live?
As an additional tab/view inside the existing myhome-bus-card Lovelace card?
As an independent custom Lovelace card (myhome-device-manager)?
Or as an HA custom panel / sidebar entry?

If I may contribute, I would approach the issue with a dedicated side panel, which can then be left active in case of system maintenance or to visually control all MyHOME devices from a single dashboard, without having to search for entities or customize them on the user's home screen.

Handling CEN / CEN+ Pushbuttons:
Since scenario buttons do not have an on/off state, should adding a pending CEN/CEN+ device create an event.* entity, HA Device Automation Triggers, or both?

It depends on how you want to configure it; some CEN and CEN+ scenario switches trigger automations configured directly by Home+Control. However, it is possible that the scenario you want to trigger involves another MyHOME device, so pressing an unassigned button on Home+Control triggers an action in HA.

Managing Ignored Devices:
Should the UI provide an "Ignored Devices" filter to easily inspect and un-ignore addresses later?

Yes, I find this correct.

Coexistence with myhome.yaml:
How should this interact with installations that already use myhome.yaml for pre-configured wiring schedules? (e.g. YAML devices pre-populate as already approved, leaving only newly detected unmapped addresses in the pending queue).

Personally, I would leave the file configuration as the "base" to identify the friendly names of the entities, I would leave the pending queue for new addresses as proposed, but I would provide the ability to modify them in the sidebar.

I would divide the interface by OpenWebNet "WHO" identifier, roughly mirroring how MyHomeSuite and the "Project" mobile app behave.

[GreenGrassBlueOcean]

Thanks for the thoughtful feedback and ideas, @TheDarkWizard and @anotherjulien!

To keep expectations aligned with our current release schedule: we're going to keep this RFC open for continued community input and design refinement, but we plan to queue the implementation for the v2.1 milestone.

Our primary focus right now is reaching a rock-solid v2.0.0 general release (we're currently on v2.0.0b5), hardening multi-gateway compatibility (MH200, F454, MHS1, AM4890, F461), and stabilizing core domain platforms without introducing the architectural complexity of an uncommitted device staging queue mid-beta.

In the meantime, for users setting up medium-to-large installations during the v2.0 lifecycle, two pragmatic workflows are fully functional today:

1. myhome.yaml Pre-Seeding: For installations with existing wiring schedules or exports from MyHomeSuite, defining devices in myhome.yaml allows pre-populating friendly names, areas, and platform assignments (e.g. light vs. switch) in bulk prior to first launch.
2. Native Home Assistant Bulk Management: For devices discovered dynamically via background bus polling, Home Assistant’s built-in Settings → Devices & Services → MyHOME → Entities table allows batch-selecting entities to assign areas, and the Device pages allow updating friendly names with automatic cascading updates to entity IDs.

Please feel free to continue sharing ideas, UI preferences (such as the sidebar panel concept vs. Lovelace integration), and edge cases here so we have a well-defined specification ready when we kick off v2.1!

[anotherjulien]

Having mulled over this over night, I think it might be confusing for new users to not find devices immediately.

IF there was a unified way HA handled this scenario and the UI was super clear about it, we could leverage this.
BUT if we need to build a UI from scratch to handle that, then we will inevitably end up in situations where users connect a gateway, then no device is displayed; and they do not notice/cannot find how to get into our custom built UI.

This could be appropriate for more "technical" devices, like the CEN devices that might clutter the device list while potentially unused, but the basics (lights, covers, thermo, etc...) are probably better off being discovered and auto added as they are now.

What's your opinion?

[TheDarkWizard]

we will inevitably end up in situations where users connect a gateway, then no device is displayed; and they do not notice/cannot find how to get into our custom built UI.

This could be appropriate for more "technical" devices, like the CEN devices that might clutter the device list while potentially unused, but the basics (lights, covers, thermo, etc...) are probably better off being discovered and auto added as they are now.

What's your opinion?

Absolutely correct, I hadn't thought about the user who wants to immediately test the integration's features anyway.

I would say that for the basic entity we could apply the immediate integration as suggested.

[GreenGrassBlueOcean]

Thanks for raising this point, @anotherjulien — having thought through this further, I think your intuition is completely spot-on.

Putting all newly detected devices into a custom staging queue creates two major problems:

1. User Onboarding Friction: A user connecting an F454 or MyHomeServer1 expects their lights and shutters to appear in Home Assistant immediately. If the integration discovers devices but isolates them in a custom staging view, new users will assume the integration is broken or get lost trying to find our custom UI.
2. The Custom Frontend Maintenance Trap: Home Assistant core updates every month. Custom frontend panels and Lovelace cards are notoriously brittle across releases (frontend API deprecations, WebView quirks on the iOS/Android companion apps, theme breakages). Maintaining a custom JavaScript/TypeScript interface and a separate "staging database" creates a dual source of truth that easily falls out of sync with HA's native registries.

---

How Other Large-Scale Integrations Do It (The Native HA Way)

Systems that handle dozens or hundreds of devices/zones don't build custom inboxes. Instead, they strictly follow the Home Assistant Architecture Guidelines:

• The Security Panel Pattern (e.g. Risco / ElkM1):

  • Panels often have 64 or 128+ physical and logical zones.
  • Active/named zones are enabled out-of-the-box.
  • Unassigned, spare, or secondary diagnostic entities use _attr_entity_registry_enabled_default = False and _attr_entity_category = EntityCategory.DIAGNOSTIC (see implementation in homeassistant/components/risco/binary_sensor.py).
  • Result: Zero clutter on dashboards and no database bloat, yet users can view and enable them at any time in standard HA: Settings → Devices & Services → Entities → Filter: "Show disabled entities".

• The Button / Keypad Pattern for CEN & CEN+ (e.g. Z-Wave JS & Lutron Caséta):

  • Wall controllers and scenario buttons have no permanent on/off state; creating fake toggle/sensor entities is explicitly discouraged by HA core.
  • Instead, Z-Wave JS models scene controllers using the native Event Entity Platform (homeassistant/components/zwave_js/event.py).
  • Lutron models Pico remotes as devices exposing Device Automation Triggers (homeassistant/components/lutron_caseta/device_trigger.py).
  • Buttons never clutter dashboard states, but are immediately selectable in the HA visual automation builder (e.g. "Button 1 short press", "Button 2 long release").

• Fieldbus Imports (e.g. KNX):

  • KNX auto-creates all mapped actuators natively from ETS project exports, providing a diagnostic "Group Monitor" strictly for frame inspection rather than an onboarding gate.

---

Proposed Unified Direction

Instead of building a bespoke custom UI or staging queue from scratch, we propose adhering strictly to native Home Assistant architecture:

1. Core Actuators (Zero-Friction Auto-Add):
   • Lights (WHO=1), Shutters/Covers (WHO=2), Climate (WHO=4), and Energy/Power (WHO=18) are automatically registered and enabled by default. They appear immediately on the gateway's device page.
2. Stateless Scenario Pushbuttons (CEN / CEN+):
   • Modeled as native devices exposing event.* entities and Device Automation Triggers (e.g., button_1_short_press, button_2_long_press).
   • Passively sniffed, unconfigured CEN/CEN+ addresses can be registered with entity_registry_enabled_default = False, so they stay quietly disabled until the user explicitly enables the ones they intend to automate.
3. Passive / Ambiguous Sniffed Devices:
   • If frames are observed from unclassified addresses on the bus, register them as disabled entities by default. Home Assistant’s native "Show disabled entities" list effectively acts as the staging inbox, with zero custom UI code to maintain.
4. Options Flow Setting:
   • Provide a standard checkbox in Configure via Options Flow: "Automatically discover new devices on bus activity" (enabled by default).

This approach keeps onboarding instant for new users, provides a clean opt-in path for noisy/scenario devices, leverages HA's built-in bulk editing/area assignment tools, and keeps the integration 100% pure Python without frontend maintenance overhead.

What do you all think of this native approach?

[xtimmy86x]

Hi to all

I would vote for a dedicated MyHOME configuration panel, similar to the approach used by my integration ha-s7plc. (See attached screeshot below)

In my opinion, the standard Home Assistant Config Flow / Options Flow is perfect for the initial gateway setup and for relatively simple settings, but MyHOME is becoming complex enough that managing everything through a sequence of dialogs could become limiting.

A dedicated panel could provide a much better overview of the complete installation, for example:

• gateways and their connection/status information
• discovered devices
• configured and unconfigured devices
• entities grouped by WHO/domain
• adding, editing and removing entities
• WHO-specific configuration options
• discovery management
• diagnostics and possibly the existing Bus Monitor
• easier handling of larger MyHOME installations

The important point for me is that the panel should not introduce a separate configuration system or a second source of truth.

I would keep the actual configuration in the native Home Assistant structures (Config Entries / Subentries, entity registry, etc.) and use the panel only as a richer frontend over them, ideally through backend/WebSocket APIs.

This is the approach we adopted in ha-s7plc: the normal Config Flow is used to configure the PLC connection, while a dedicated side panel is used to manage the entities and their more advanced configuration. It works particularly well when an integration has many entity types and device-specific options.

I think MyHOME is moving in a similar direction: with multiple WHO families, auto-discovery, different gateway types and increasingly advanced entity configuration, a panel would probably scale much better than continuously expanding the Options Flow.

It would also leave room in the future for a more installation-oriented view of the MyHOME bus, without changing how the integration stores or manages its configuration internally.

So my vote would be:

Config Flow for gateway/onboarding + dedicated panel for device/entity management.

[GreenGrassBlueOcean]

Thank you for bringing this up and sharing the screenshot, @xtimmy86x — this is a really compelling and elegant idea! I looked through the architecture in ha-s7plc, and I am definitely not against good ideas that significantly elevate the user experience.

Why This Concept Resonates

You hit the most critical nail on the head with this point:

"The important point for me is that the panel should not introduce a separate configuration system or a second source of truth. I would keep the actual configuration in the native Home Assistant structures (Config Entries / Subentries, entity registry, etc.) and use the panel only as a richer frontend over them, ideally through backend/WebSocket APIs."

Having inspected how panel.py in ha-s7plc handles this—talking via native HA WebSocket commands and writing straight to hass.config_entries.async_update_entry(entry, options=options)—this completely avoids the "dual source of truth" hazard that I was worried about with a disconnected staging database.

You are also completely right that as MyHOME grows across multiple WHO families (lighting, shutters, thermo, energy, CEN/CEN+), squeezing everything into standard HA Options Flow modal popups becomes painful for medium-to-large installations. A dedicated side panel organized by WHO subsystem, with diagnostics and bus monitoring integrated, would feel like a modern, web-native MyHomeSuite right inside Home Assistant.

Maintainability & Staying Native

My main concern with custom frontends has always been the long-term maintenance overhead and breakage risk across monthly Home Assistant core releases (frontend DOM changes, LitElement/webcomponent updates, and mobile companion app rendering).

Since you have real-world experience maintaining ha-s7plc, I’d love to hear your thoughts on:

1. Frontend Churn: How much maintenance does the custom webcomponent require when Home Assistant releases its monthly frontend updates? Does panel_custom.async_register_panel() remain pretty stable over time?
2. Mobile Companion App: Does the panel render and perform cleanly inside the iOS and Android Companion App WebViews, or does it require platform-specific CSS/layout handling?
3. Onboarding Harmony: If we combine this with @anotherjulien's feedback—where standard actuators (lights, covers, thermostats) are still auto-added to the HA entity registry immediately upon discovery—the panel acts as an advanced cockpit and diagnostic tool rather than a mandatory onboarding gate that new users could get stuck on.

Roadmap Perspective

This fits naturally into our roadmap: keeping v2.0 focused on rock-solid core stabilization, multi-gateway compatibility, and native entity platforms, while designing a dedicated MyHOME configuration & diagnostic panel along the lines of ha-s7plc as a headline feature for v2.1.

Really appreciate you sharing this approach — curious to hear your and Julien's thoughts!

[anotherjulien]

@xtimmy86x this is a beautiful solution!
I feel this is the best of both worlds…

It also gives me dangerous ideas 😅
A few years ago I had started reverse engineering the WHO 1001 protocol used by MyHome_suite to configure commands and actuators.
I never got really far and lost the work I had during a server migration, but I might find written notes somewhere.

It would be absolutely majestic if a custom panel could display the actual commands and actuators, with their ID, and maybe even reconfigure them!
It would be another layer of decoupling the physical world from the logical WHO*WHAT addressing!

[anotherjulien]

So, silly question.
Is there a point in having this separate panel as an application on top of the integration?
The way ZWaveJSUI is an application that handles configuration on top of the ZWave integration?

[xtimmy86x]

@anotherjulien @GreenGrassBlueOcean

Not a silly question at all — I think it is actually an important architectural distinction.

I did think about the Z-Wave JS UI model, but in my opinion there is one major difference.

Z-Wave JS UI is not just a frontend sitting on top of the Home Assistant integration. Z-Wave has a separate server/driver which actually owns the communication with the Z-Wave network, and Home Assistant connects to that server through WebSocket.

So the architecture is essentially:

Z-Wave network ↔ Z-Wave JS Server ↔ Home Assistant

and a separate UI can naturally manage the same underlying server.

With MyHOME today, the integration itself owns the gateway connection and the OpenWebNet runtime.

If we created a completely separate application now, we would either have to:

1. make that application communicate back through Home Assistant anyway, in which case it is basically an external version of the same panel, or

2. move the OpenWebNet runtime out of the integration into a standalone MyHOME server/daemon and let both Home Assistant and the UI connect to it.

The second option could be a very interesting architecture one day, but it would be a much bigger project and architectural change.

For the current integration I would therefore prefer:

MyHOME bus ↔ MyHOME integration ↔ dedicated HA panel

The panel would only be the frontend. The integration would still own discovery, gateway connections, entities and configuration.

That also keeps installation very simple: install the integration and everything is there. No additional container, add-on or application to configure.

Regarding frontend maintenance, my experience with ha-s7plc has been quite positive.

The important thing is to avoid depending too much on private Home Assistant frontend internals or manipulating HA's DOM. The panel itself can be a normal custom web component with its own responsive layout and communicate with the integration through stable Home Assistant WebSocket APIs.

panel_custom itself has been quite stable. Most problems tend to appear when custom frontend code relies on internal HA components or undocumented DOM structures rather than from the panel registration mechanism itself.

The same applies to mobile. In ha-s7plc I use responsive layouts rather than separate mobile/desktop implementations. Home Assistant gives the panel the narrow state, and normal CSS media queries can handle the rest. So there is no Android/iOS-specific implementation.

And I completely agree with the proposed onboarding model:

normal devices should still be discovered and created automatically.

The panel should not become a mandatory setup wizard.

I see it more as an advanced MyHOME cockpit:

• discovered devices
• configured/unconfigured devices
• WHO subsystem overview
• entity configuration
• gateway status
• bus monitor
• diagnostics
• advanced discovery tools

And then Julien's dangerous WHO 1001 idea 😅 could eventually take it one step further.

If we ever manage to reliably enumerate the actual physical commands and actuators and eventually configure them through WHO 1001, the panel could evolve from an integration configuration UI into something much closer to a modern MyHomeSuite.

At that point, discussing a standalone MyHOME server/application architecture like Z-Wave JS would make much more sense.

So personally I would take this incrementally:

v2.0: stabilize the integration and automatic discovery
v2.1: native dedicated MyHOME panel
future: if WHO 1001 / physical bus configuration becomes mature enough, evaluate whether separating the OpenWebNet core into an independent server actually brings benefits.

That keeps the architecture simple today without closing the door to something much more ambitious later.

[GreenGrassBlueOcean]

@xtimmy86x @anotherjulien

Timmy, this architectural breakdown is exceptional. You hit the exact balance between pragmatic simplicity today and future extensibility.

Avoiding the standalone daemon trap for now while keeping the panel strictly as a frontend layer over native HA Config Entries and WebSocket APIs completely resolves the "dual source of truth" and frontend churn concerns.

Given your hands-on expertise and success implementing this exact pattern in ha-s7plc, would you be interested in taking the lead on designing and architecting the v2.1 Dedicated MyHOME Panel?

Here is how we could structure the partnership:

• v2.0.0 (Immediate): We keep our focus on finalizing multi-gateway hardening, native platform stabilization, and automated discovery to get v2.0 out the door.
• v2.1 Panel Lead (@xtimmy86x): You take ownership of the frontend architecture (the WebComponent panel, layout, and client-side design).
• Backend & Core Support (@GreenGrassBlueOcean & @anotherjulien): We will build and expose whatever WebSocket APIs, data payloads, and bus events you need to power the panel.

If this sounds good to you, we can open a dedicated v2.1 tracking issue / draft specification once v2.0 lands and give you full technical runway to steer this!

[xtimmy86x]

@xtimmy86x @anotherjulien

Timmy, this architectural breakdown is exceptional. You hit the exact balance between pragmatic simplicity today and future extensibility.

Avoiding the standalone daemon trap for now while keeping the panel strictly as a frontend layer over native HA Config Entries and WebSocket APIs completely resolves the "dual source of truth" and frontend churn concerns.

Given your hands-on expertise and success implementing this exact pattern in ha-s7plc, would you be interested in taking the lead on designing and architecting the v2.1 Dedicated MyHOME Panel?

Here is how we could structure the partnership:

• v2.0.0 (Immediate): We keep our focus on finalizing multi-gateway hardening, native platform stabilization, and automated discovery to get v2.0 out the door.
• v2.1 Panel Lead (@xtimmy86x): You take ownership of the frontend architecture (the WebComponent panel, layout, and client-side design).
• Backend & Core Support (@GreenGrassBlueOcean & @anotherjulien): We will build and expose whatever WebSocket APIs, data payloads, and bus events you need to power the panel.

If this sounds good to you, we can open a dedicated v2.1 tracking issue / draft specification once v2.0 lands and give you full technical runway to steer this!

Absolutely — I’d be happy to take the lead on the frontend architecture and design of the v2.1 Dedicated MyHOME Panel.

I think the proposed split of responsibilities makes a lot of sense.

My preference would be to approach it the same way I did with ha-s7plc: keep the frontend as thin as possible from an architectural point of view, and expose all meaningful operations through explicit Home Assistant WebSocket APIs rather than relying on frontend internals or direct manipulation of HA components.

For v2.1 I would initially define the panel around a few clear areas:

• gateway overview and connection/status information
• discovered vs configured devices
• WHO/domain-oriented device browsing
• entity creation and advanced configuration
• diagnostics
• integrated bus monitoring
• tools for inspecting raw discovery/bus information

I would also design it responsive-first so the same panel works cleanly on desktop, tablets and Companion App WebViews without separate platform-specific implementations.

Before implementing too much UI, I think it would be useful to write a small shared technical specification defining the contract between frontend and backend:

• WebSocket commands
• payload schemas
• event subscriptions
• error responses
• configuration mutations
• discovery/device representations

That way the frontend and backend can evolve independently without coupling the panel to internal Python implementation details.

I also strongly agree with keeping v2.0 focused on stabilization. We can use that time to collect ideas and requirements, then turn them into a proper v2.1 tracking issue/spec once v2.0 lands.

And yes, I’d definitely like to leave some architectural space for Julien’s “dangerous” WHO 1001 ideas 😅. Even if physical bus configuration is not part of the first panel version, it would be smart not to design ourselves into a corner.

So yes — count me in for the v2.1 MyHOME Panel frontend/UX architecture lead. I’d be very happy to collaborate with both of you on the backend API contract and gradually turn it into something that feels like a modern MyHomeSuite inside Home Assistant.

[anotherjulien]

So @xtimmy86x, I've starting documenting the danger 😉
I've found my old notes, and spent the week-end building upon them, and I've had a fair bit of automated help to actually write the articles.

(cc: @GreenGrassBlueOcean, @fedem95 you guys might be interested as well)

[xtimmy86x]

@anotherjulien This is exactly the kind of “danger” I was hoping for 😄 Thank you for recovering your notes and documenting all of this!

After reading the wiki, I think there is already enough information to start exploring something useful in the sidepanel, beginning with read-only hardware discovery and inspection.

A first experimental version could:

• Discover physical devices through WHO1001 and identify them by hardware ID.
• Display their firmware and available identity information.
• Show their internal modules and assigned functions using DIM30.
• Read module addresses through DIM32 and, where the mapping is clear, link them to existing Home Assistant devices and entities.
• Gradually expose decoded configuration values through DIM35, starting with well-understood objects.

The physical grouping is particularly interesting. The panel currently groups entities by their HA device, but this could let us show an actual physical actuator with its different channels, addresses and associated entities underneath it. The same approach could help explain how command modules are configured and which addresses they target.

We could start by defining a small backend/WebSocket contract for discovery progress, hardware inventory and individual device inspection. I can build the panel views around that, while we validate the diagnostic sequences and decoding on real hardware. I would be happy to help test this with my F454.

I would keep the first iteration focused on WHO1001 and preserve unknown values explicitly, since some fields and other diagnostic domains still need investigation. Physical programming could follow once the read path and device-specific behaviour are sufficiently understood.

This would already make the panel much more useful for understanding and troubleshooting an installation, while keeping normal automatic entity discovery unchanged. It feels like a very concrete first step towards the MyHomeSuite-like experience we were discussing!

[anotherjulien]

I'm fairly confident in the data gathered and the inferences made (of course I would, wouldn't I?)
I've captured data for the 70 devices present in my setup (through an F454), but the variety of the devices is somewhat limited.
So YES, please, confirm all that you can with your setup, let me know of any inconsistencies ! 🙂

I'd love to have a capture of WHO1004 and 1018, that would help to confirm the "universal" aspect of the approach (if the database analysis agrees with the real world)

[Interstellar0verdrive]

Late to this one, but it's close to home: the panel you describe is what I've been running on my fork since this weekend, for one area only (cover calibration and its profiles): a built-in panel with a small Lit bundle, admin-only WebSocket commands with a written contract, in-place refresh when the store changes, drag and drop with a tap alternative on the phone, and no HA internals touched. It's unreleased but on master: docs/panel.md describes the screen, and I've just published the contract it runs on, docs/panel-websocket-api.md: every command, payload, answer and refusal, plus the undo and subscribe semantics. panel_src/ is the frontend, websocket_api.py the backend.

It was a good test of the approach. The contract is what made it manageable: the frontend was written against the document, the backend against the same document, and a parity test keeps the two honest. The costs were where @xtimmy86x said they'd be (theme tokens, the companion app, keyboard access), not in the panel registration. Take whatever is useful for the spec, so a v2.1 panel doesn't start from zero on that section.

One thing I'd hold on to from the thread above: management belongs in the panel and the bus card stays a bus monitor. It's tempting to add tools to the card because it's already there, but every tool that lands there now is one the panel has to absorb later.

[xtimmy86x]

@Interstellar0verdrive Thanks for sharing this! The documented WebSocket contract and the parity test sound particularly useful, and I’d be happy to look at how we can bring your calibration work into the shared panel.

I’m already developing the MyHOME sidepanel here:
[feat/myhome-sidepanel](https://github.com/xtimmy86x/MyHOME/tree/feat/myhome-sidepanel)

It already includes gateway selection, devices grouped by WHO, expandable device groups, address information, name/area editing through HA’s native registries, and access to the existing bus monitor. It can also be opened from the integration’s Configure menu, with an optional sidebar shortcut.

On the bus card, I would take the idea one step further: my preferred end state is a single MyHOME panel containing all advanced management and diagnostic tools, including the bus monitor, with the standalone custom card eventually retired.

For users, that provides one clear place to inspect devices, investigate traffic, calibrate covers and, eventually, explore physical hardware configuration. It also gives us one interface to maintain and document, without requiring users to install a dashboard card to access diagnostics.

The monitor currently reuses the existing card inside the panel as an intermediate step. Once the panel provides the full functionality, I would favour a planned deprecation and removal of the standalone card.

Internally, these features can remain separate modules with clear API contracts. Your calibration tools could fit naturally into that structure, alongside the monitor and future hardware inspection.

That is the direction I’ve been working towards, and I’d like us to coordinate our implementations around this shared panel. What do you think?

[Interstellar0verdrive]

Agreed on the end state: one panel, the bus monitor inside it, the standalone card retired once the panel covers it. And agreed on the structure: separate modules behind their own contracts, so the calibration screens can be one module without the panel knowing how the store works. Your "open from the Configure menu, optional sidebar shortcut" is exactly what I did for the calibration panel, so the two should feel like one thing.

Practically: my screens run on the store of my fork, which isn't v2's cover model yet, so the honest sequence is contract first, port later. I'll read feat/myhome-sidepanel and note where the two contracts differ (gateway selection, the texts endpoint, the refresh event), then we can settle a shared shape before either of us writes more UI. Not this week on my side, spare time being what it is, but soon.

[xtimmy86x]

@Interstellar0verdrive Thanks, that sounds like a good way forward. We agree on the destination: one MyHOME panel, with the bus monitor inside it and the standalone card retired once its functionality is fully covered.

Contract first, port later makes sense, especially given the differences between your calibration store and v2’s cover model.

Since my previous comment, the experimental branch has gained reusable cover profiles with separate opening and closing times, assignment/reset actions, and deletion of unused profiles. These extend the existing linear timing model; they don’t yet implement your advanced calibration mechanics.

I’ll document the current profile API and prepare a proposed shared contract covering gateway selection, translations, refresh subscriptions, errors and configuration changes. That should give us something concrete to compare with your implementation before extending the calibration UI further. The current API can evolve as we agree on that contract.

No rush on your side. I can move the documentation forward in the meantime, and we can review the differences together when you have time. I’m also happy to help validate the resulting integration on my F454.

[xtimmy86x]

@Interstellar0verdrive I reviewed your implementation at 06ebceb alongside my current panel branch, version 0.20.0. Here is a short technical summary to help coordinate the integration.

Your implementation provides several valuable additions:

• A two-phase movement model covering slats and curtain travel, with separate opening/closing times and nonlinear winding coefficients.
• Height-based adaptation of shared profiles to individual shutters.
• Guided measurements, intermediate checkpoints, fitting and verification.
• Per-cover overrides and parameter provenance.
• Profile management with assignment previews, shared edits and undo.

One important architectural distinction is that profile management already lives in your panel, while physical calibration still runs through the Options Flow. Bringing the complete workflow into the shared panel therefore requires extracting the calibration controller and exposing it through backend APIs.

My proposed integration would be to:

1. Reuse your movement mathematics, height scaling and parameter-resolution logic.
2. Extend my existing storage while preserving stable profile UUIDs, revision checks and atomic writes.
3. Integrate your profile/detail components into the existing panel.
4. Adapt your guided measurement steps to the existing WebSocket calibration sessions, preserving automatic and batch calibration.

There are a few details I would like us to align before implementation:

• Persistence: some operations perform multiple saves. Two isolated failure-injection checks also showed that a failed save can leave updated data in memory, and HA can log certain storage errors without propagating them to the caller. I suggest one atomic transaction per user operation.
• Concurrent edits: bind previews and writes to an expected revision, so an older browser tab cannot silently overwrite newer changes.
• Cancellation: leaving your calibration flow can intentionally allow movement to continue. We should agree on explicit “stop” and “leave” semantics.
• Measurement semantics: calibration checkpoints represent fractions of curtain movement time, not already-corrected HA position percentages; that distinction must survive the port.

I think the implementations complement each other well. Agreeing on the profile schema, parameter provenance and calibration session states would give us a concrete starting point for incremental integration.

[Interstellar0verdrive]

@xtimmy86x
Thanks, and yes: I'll take the covers and calibration flow inside the shared panel, with navigation, gateway context and visual conventions agreed with you. Your four integration steps are the right order, and your four alignment items are all fair. Point by point:

• Persistence: agreed, one atomic transaction per user operation, and a failed write must leave memory untouched and surface the error. My store predates the revision model and writes in more than one step in a couple of places; that's mine to fix in the port, not something to carry over.
• Concurrent edits: agreed. I protect against a stale second tab with a lock and an undo slot, not with an expected revision; yours is the better mechanism. Previews and writes should carry expected_revision, and a preview must be revalidated at apply time.
• Cancellation: worth stating explicitly because mine is deliberate, not accidental. Closing the dialog sends no stop: a run in progress ends by itself at the end stop, which is the safe outcome for a shutter. A watchdog expiry or the integration unloading does send a stop. So I'd define three verbs: stop (write a stop now), leave (detach the UI, the run finishes on its own), cancel (discard provisional measurements, no movement implied).
• Measurement semantics: yes, and this is the one that quietly breaks things if it's lost. A checkpoint is a fraction of the movement time, not a position percentage; the whole point of the tape readings is that those two are not the same, and the roll coefficients are what maps one to the other.

I'll write the storage schema and the calibration session states as the next thing: profiles with reference travel, per-direction times, slat time, per-direction roll, per-cover overrides, provenance per value, and the session as a state machine with its transitions and refusals. Give me a few days; I'd rather hand you something you can implement against than a sketch.

On your video, since you asked for feedback. The shell, the inventory and the WHO grouping are good, and the dialog is clear about what it does. Four things I'd change, all about what the user is doing at that moment rather than about looks:

1. Profiles need a home of their own. In the dialog a profile is a property of one cover, created as a by-product of measuring it ("save as a new profile and assign"). With twelve covers that produces twelve profiles and hides the thing that makes profiles worth having: one measurement, many covers. A covers view that lists profiles as groups, with their members under them, answers "who follows what" at a glance and makes assigning an act of its own.
2. Separate managing from measuring. The dialog currently holds assign, calibrate, edit, create and delete in one stack, so a destructive action sits one accordion away from a routine one. I'd put management in the page and give measurement a focused screen with nothing else on it.
3. A measuring screen has one instruction and one button. During a run the user is at the window with a tape measure, glancing at a laptop or most likely at a phone. Three competing controls (Stop, Cancel measurement, Close) and the same instruction paragraph repeated on every step make that moment harder than it is. One sentence for the current step, one large primary action, the rest behind a secondary.
4. Show the consequence before the write. Before saving, a short "these covers change, from these values to these" is what makes a shared profile safe to edit, and it's the same screen that later carries the undo.
5. The measuring screen is a phone screen first. You already design responsive and follow the HA theme, so this is agreement rather than a request: I'd just point out that measurement is the one part of the panel that is normally used on a phone, standing at the window, one hand on a tape measure. Managing profiles happens at a desk, measuring does not, and designing that screen for the phone first is what gives it the button sizes and the one-thing-at-a-time layout it needs. Dark theme included, since blinds get calibrated in the evening more often than you'd think (my neighbours must love me).

None of that is about my design surviving: it's the four decisions that changed the most over days of running the flow on real shutters.

[xtimmy86x]

@Interstellar0verdrive Thanks for confirming the direction and for taking on the schema and session states.

I would like to clarify the UI feedback, because several of the things you describe are already present in the version shown in my video:

• The view is already dedicated to travel profiles.
• Management and calibration functions are separated into collapsible sections.
• During measurement, there is already one large blue primary button; the secondary controls are smaller and have no filled background.
• At the end of calibration, the measured values are displayed for review before saving the profile.
• The interface already adapts to mobile, with a clean layout and responsive controls.

Some of your suggestions may therefore be about a different organisation rather than missing functionality. For example, putting management and measurement on separate screens instead of collapsible sections is a navigation choice we can discuss.

I also see two potentially distinct additions: grouping all associated covers visibly under each profile, and showing the before/after impact on every affected cover when editing a shared profile. That second preview is different from the calibration results we already show before saving.

Could you point to specific moments in the video where the current interaction causes a problem, and clarify which changes you mean? That would help us discuss concrete improvements without overlooking what is already implemented.

I’m happy to evolve the interface together. I would just like us to start from an accurate understanding of both implementations and preserve the parts that already work well.

[Interstellar0verdrive]

@xtimmy86x

Before anything else: thanks for taking this so seriously, and for the video! I'm genuinely glad we're doing this together rather than in two forks, and between your shell and inventory and what I've worked out on covers, I think the result is going to be something neither of us would have built alone. Everything below is in that spirit. And to be clear about what I bring and what I don't: I'm a UI/UX designer by trade, not a Home Assistant developer, so on architecture and HA internals I'll follow your lead. Where I can be genuinely useful is the interface and the flow, which is why I go into that level of detail on the screens: it's the part I can make excellent.

First, let me check we mean the same thing by "profile", because I suspect part of this is a not shared vocabulary. :)
On my side a profile is a named set of values plus a reference travel: assign it to a cover 40 cm shorter and the times are scaled to that cover, which is what lets one measurement serve a whole group. From the dropdown in your video ("Test · 9.82 / 9.07 s") a profile looks like the same object minus the reference travel, and without it the values only really fit the cover they were measured on, which may be why a per-cover dialog is a natural home for it. Is that right? If so, the scaling is the piece that turns a profile into something several covers can share, and it's in the schema I'm writing.

You're right that I described some of it as missing when it's a matter of organisation. Concretely, going by the states in your video:

Where I was wrong: the primary action is already the one big button, the secondary controls are already quiet, the sections are already collapsible, and the two measured times are already shown for review before anything is saved. The mobile layout I can't judge, it isn't in the video, of course I'll take your word that it adapts, and the thing I'd check there is the measuring screen used one-handed.

Where I still see something, by screen:

1. One button both confirms the endpoint and starts the next run. "Fully closed: start opening", then "Fully open and stopped: start closing": the same click ends one step and sets the shutter moving for the next, so the movement begins while the user is still reading what is about to happen, and a mis-click starts a run rather than just recording a value. I'd split it: confirming the endpoint closes the step, and the next run starts from its own instruction, which is also where the caveat about the stop belongs.
2. In my understanding, the dialog is dedicated to one cover's travel profile, not to profiles. Its header reads "Travel profile · Cover 72", it's opened from that cover's card in the WHO 2 inventory, and the profile appears inside it as a dropdown ("Choose a profile (opening / closing)"). What I don't see anywhere in the video is a place that lists the profiles themselves with the covers that follow each one. If that screen exists, I missed it and the point falls; if it doesn't, that's the one I'd add first, because it's where "one measurement, many covers" becomes visible.
3. Review & save offers only "Save as a new profile and assign", with a name field. From that screen I can't see how to update the profile this cover already follows, or to assign the result to an existing profile. If the only exit is a new profile, twelve measured covers leave twelve profiles behind.
4. Three secondary controls whose difference isn't stated: "Stop", "Cancel measurement" and "Close" are all on the measuring screen at once. We just agreed on three verbs, so I'd name and place them accordingly: stop writes a stop now, cancel discards the provisional values without implying movement, leave detaches the UI while the run finishes by itself.
5. The same four-line instruction paragraph is repeated on step 1, step 2 and step 3. On "Review & save" it still says to start with the cover fully closed and not to use other controls, which is no longer what the user is doing. Per-step text, and the standing warnings once at the start.
6. Two notices stack up while measuring: "Opening time recorded…" plus "Stop requested through the gateway. This is not confirmation that the motor stopped…", and the second one is still there on the review screen. The information is right, the timing is what I'd change: that caveat belongs where the user is asked to confirm the endpoint, not after.
7. Delete lives in the same dialog as assign, one accordion below ("Advanced · Delete selected profile"). That's the navigation choice you mention, and it's yours to make; my reason for splitting is that this dialog is open while a shutter is physically moving, which is when a mis-click is most expensive.

Three of those apply to my own flow, too:

• Runs that start while the user is reading: in the tape phase mine chains the positioning runs automatically after a single warning at the start of the phase, so the same objection could be turned on me. The line I ended up drawing is this: if the user has to act at the right moment, they must have read the instruction before anything moves, because a press that arrives late is a wrong measurement. If the user only has to look and measure, moving the cover into position while they read costs them nothing and saves them a step. Your two endpoint confirmations are the first kind, which is why I'd separate them from the start of the next run; my tape positioning runs are the second.
• The same three verbs are ambiguous in mine too: closing my dialog sends no stop and lets the run finish by itself, and the only place that's explained is a sentence in the text. Naming them properly is work I owe as much as you do.
• The measuring screen isn't phone-first on my side either: it's Home Assistant's own options-flow dialog, so I got the theme and the responsiveness for free and the ergonomics not at all. That's precisely why I'd rather build it in the panel than keep it where it is: it was the next thing on my list anyway, and so far it exists only in the design file, not in code.

The live "Measured elapsed time: 2.86 s" during the run is a nice touch, by the way, and something my flow doesn't show.

And I think the before/after impact preview is the distinct one: not the two times of this measurement, but "these five covers follow this profile and their values change from these to these" before a shared edit is written, with the same screen carrying the undo afterwards.

[xtimmy86x]

@Interstellar0verdrive Thanks for clarifying your feedback. I’m attaching two screenshots to show functionality that may not have been clear in the video: selecting a profile that already exists, and editing an existing profile. Both are already available, although they are separate from the calibration result screen.

I’d also like to explain my perspective. I work as a systems integrator, so I deal with different installations, different users and very different ways of using a home automation system.

From that experience, I think the calibration functionality you proposed is an excellent addition. My priority, though, is to keep the ordinary user’s task simple: open calibration, follow the necessary steps, review the result and save. In most installations, I would expect this to be an occasional setup operation—potentially done once for the lifetime of the shutter, unless something mechanical changes.

That is why I’m less convinced about making drag-and-drop profile management a central part of the experience. I understand its purpose, but in everyday use I suspect it would offer limited benefit to most users and could make the relationship between shutters, profiles and calibration less obvious. Choosing an existing profile from a clear selector may be enough for their needs.

I’m not questioning the value of shared profiles, height scaling or accurate calibration. I’m questioning how much of the management interface needs to be prominent for someone who simply wants their shutter to work correctly.

Your experience designing and using this on your shutters is valuable, and mine comes from configuring systems for different people. I’d like us to compare those perspectives, hear from the other members too, and decide together what belongs in the final version and what should remain an optional advanced function.

Selecting a profile:

Edit a profile:

[GreenGrassBlueOcean]

Brands assets — one more item for this panel work

While going through the Integration Quality Scale audit on v2-phase1-architecture: after #363 every rule is done/exempt except two — brands (Bronze, todo) and strict-typing (Platinum, in progress, needs OWNd to ship py.typed first). So the only thing between us and Gold is not code at all, it's the brands rule:

Phase 0 — Gold (independent of everything else)

1. Submit custom_integrations/myhome/ (icon + logo, 256 px + 512 px @2x, PNG) to home-assistant/brands.
2. Once merged, flip brands: done in quality_scale.yaml → the validator reports Gold.

@xtimmy86x — the MyHOME artwork you already show in the header of your experimental panel (#270 (comment)) looks like exactly what the brands repo wants. Could we reuse that? If you have the source (SVG or a large PNG) I can do the resizing and the PR to home-assistant/brands, or you're welcome to open it yourself. Only constraint: the icon must be square and the logo is the wordmark/full artwork; both need a transparent background.

The typing side (Platinum) I'll track separately — that's an OWNd release plus burning down the remaining mypy baseline in MyHOME, and doesn't block Gold.

[anotherjulien]

https://github.com/OpenWebNet-HA/brands was the branch I used to make the PR to add the logos back in the day.
I probably still have the raw files I used to work on the logos if you want to edit them.
logo+icon_psd.zip

[GreenGrassBlueOcean]

Thanks @anotherjulien! I checked home-assistant/brands upstream and confirmed that your PR #2052 was merged back in 2020 (custom_integrations/myhome/ with icon.png, icon@2x.png, logo.png, logo@2x.png). The dimensions and RGBA transparency strictly match Home Assistant's brand standards, and the images are live on brands.home-assistant.io/myhome/. So the brands rule on the Quality Scale is already fulfilled! We've also saved the logo+icon_psd.zip master files in case we want to refresh the artwork alongside the new panel design later.

[xtimmy86x]

@GreenGrassBlueOcean I can open a PR myself to add the brand used in the panel of the myhome repo, but in my opinion this is a rebranding decision that should be made together as a team.

[GreenGrassBlueOcean]

I am in favor of any solution you guys want

[anotherjulien]

No preference on my side, the design is old and was a compromise at the time, and I'm not a designer to say the least 😄
I'd say that for now the box is ticked and a new visual identity can be worked on to be deployed with an upcoming milestone (like 1st public non beta, or even incorporation in core... whatever)

[Interstellar0verdrive]

@xtimmy86x
Your integrator perspective is exactly the one I don't have, so let me take the main point: you're right that drag and drop shouldn't be the central mechanism. A selector is the primary path, it works on a phone, with a keyboard and with a screen reader; dragging is an accelerator on a desktop for someone reorganising several covers at once, and nothing should require it. Happy to design it that way.

Where I'd push back is on what management is for. Assigning is rare, I agree. The frequent question isn't "assign this cover", it's "why does this one stop badly?", six months later, and answering it means seeing which profile a cover follows, what values are in force and where they came from (measured, inherited, from the file). In a per-cover dialog that answer costs one dialog per cover. In a list grouped by profile it's one screen, and the same screen is what makes editing a shared profile safe, because it tells you who is affected before you write.

That's also why I'd change one thing on the calibration result screen: thanks for the two screenshots, choosing and editing an existing profile are clearly there, and you're right that assigning an existing profile belongs at the start, not at the end. What I mean is the exit from a measurement, which today is only "save as a new profile and assign" (right?). The two that are missing are "update the profile this cover already follows", which is where the before/after preview earns its keep because it touches the other followers, and "keep these values for this cover only", which is the answer to "one shutter drifts from its group" and the thing that stops a plant accumulating one profile per cover.

And a suggestion on how we decide the rest, rather than trading preferences: pick the tasks, then judge the screens against them. Mine would be: calibrate a cover; make every similar cover use that result; understand why one cover behaves differently; correct that one cover; change a profile and know what it affects. If you'd add or remove tasks from that list, that's the useful disagreement, and it's the kind others here can weigh in on too.

One thing still open from my previous message, because a lot depends on it: does a profile on your side carry a reference travel? If it doesn't, assigning the same profile to a shorter cover gives it the wrong times, and "pick a profile from the selector" only works for identical covers. That's the piece that makes sharing real, and it's in the schema I'm writing.

Incidentally, the strongest case for the group view isn't my twelve shutters, it's your job: commissioning a building with forty covers, where two or three profiles cover the lot and you need to see at a glance which ones aren't following any.

[xtimmy86x]

@Interstellar0verdrive Thanks, this makes the distinction much clearer. I’m happy with the selector as the primary path and drag-and-drop as an optional desktop shortcut.

To answer your technical question: our current profiles store separate opening and closing times, but no reference travel yet. They can already be shared between covers with compatible timings; your height-based scaling would extend that to compatible shutters with different travel lengths. That is part of the model we agreed to include in the shared schema.

You’re also right about the exit from calibration: currently it creates and assigns a new profile. Updating the assigned profile—with an impact preview—or keeping the measured values as an override for that cover are useful additions.

I can see the value of a profile-grouped overview for commissioning and troubleshooting. My preference is to make it available without requiring users to go through it for a straightforward calibration. Someone configuring one shutter should still have a short, direct path.

Your task list is a good basis for comparing the interfaces. I would add one acceptance criterion across those tasks: the simple case should stay simple, while the more advanced management remains accessible when needed.

Let’s use those tasks alongside your proposed schema and session states, and invite the others to weigh in. That should help us agree on the final flow based on actual use cases.

[Interstellar0verdrive]

Here it is, as promised: docs/calibration-contract-proposal.md. A proposal, not a description of my code: the names are up for discussion, and anything a backend can't support should be absent rather than present and empty.

What's in it:

• Storage. A profile carries a reference travel, per-direction times, a slat time and one roll coefficient per direction, plus two plant constants that are never scaled (the gateway's answer time and the motor's start delay) and its provenance. A cover carries its own travel, its assignment and its measured values per key, which is what makes "one shutter drifts from its group" cheap to fix without inventing a profile for it. The scaling formula is written out, including what a linear backend does with it.
• Precedence, stated once: the cover's own measured value, then the assigned profile scaled to its travel, then the YAML key, then defaults. The API returns the effective value and its origin per key; no client ever computes precedence.
• The session: one per gateway, owned by the backend, leased, and the backend is the timekeeper, measuring between bus events rather than browser clicks. States, and three verbs that each mean one thing: stop writes a stop, leave detaches the client while the run finishes by itself, cancel discards provisional values.
• Section 2.5 is the long one: the measurement plan end to end. The three paths step by step, what each step buys and what it stores, why there is no stopwatch anywhere in it, where the user decides between the basic level (a few centimetres, and the shutter is already usable) and the thorough one (one to two centimetres on my shutters, and a continuation rather than a restart), and the four things it asks of an API that a linear session doesn't need: a "drive to fraction f, then ask for a reading" step with its expected value, a fit that returns its residuals, a check that returns predicted/measured/gap, and "repeat this step" as a first-class transition.
• Three exits from a review: update the profile this cover follows (with the impact preview), save as a new profile, or keep the values for this cover only.
• Part 3 is the task list we agreed on, plus the physical acceptance case: 50 % from both end stops, within 2 cm.

On the numbers: they're what twelve shutters of two kinds in one house showed, so treat them as evidence rather than a promise. That's also why the thorough level ends on a check at a position nothing was fitted to: each installation gets its own figure instead of trusting mine.

One thing I got wrong in my own implementation and wrote down rather than hid: the check that path B offers compares the gap against a fixed threshold, but what a gap means depends on how the profile itself was measured. A profile measured only at the basic level is worth a few centimetres to start with, so a 3 cm gap on a cover following it says nothing about that cover. A profile should carry its own accuracy, and that threshold should be read against it.

@xtimmy86x, the part I'd most like you to challenge is the storage: if anything in it doesn't fit your revision and atomicity model, better to bend the schema now than to adapt around it later. @anotherjulien @fedem95 @GreenGrassBlueOcean, comments welcome, especially from hardware I don't have.

[xtimmy86x]

@Interstellar0verdrive Thanks for writing this up. I compared your proposal at 62d93a9 with the current panel branch at e472ff4, including the backend changes inherited from v2.

The storage model fits our revision and atomicity approach. We already validate writes under a per-gateway lock, reject stale revisions, and persist the complete change before publishing it to the runtime. We can extend that to cover records and individual overrides.

There are a few points I would settle before implementing the migration:

• Preserve existing effective values. The aligned branch currently has native v2 timings in Config Entry options and panel profiles in a separate store. An assigned panel profile takes precedence over native timings. Importing those native timings directly as overrides would reverse that precedence and could silently change how an existing cover runs. We need a migration that preserves both the active values and the saved fallback.
• Keep legacy profiles usable without inventing a reference travel. Existing profiles contain opening and closing times but no height. They should retain their current behavior until the user supplies the measurements needed for scaling.
• Keep provenance per key. We already track opening and closing evidence separately, including cases where only one direction was measured again. A single source/date for the whole record would lose that distinction.
• Clarify what the first measured cover follows. Path A stores the measured values in both the new profile and the cover’s overrides. With the proposed precedence, later profile edits would not reach that cover for those keys. Is that intentional? I would make “follow the profile” versus “keep individual corrections” explicit.
• Agree on session exit behavior. Our current Close/Cancel path requests Stop and invalidates queued movement. Your proposal lets the current run finish. Supporting that needs explicit rules for ownership, lease expiry and when another session may start.
• Define the timing anchors precisely. Our guided measurement starts on movement feedback and ends when the backend receives the operator’s endpoint confirmation; Stop is then queued. That is different from measuring until the Stop frame is actually written. The contract should distinguish those events.

My proposed order would be: agree on the schema and migration rules, introduce one backend resolver for effective values and their origins, then add individual overrides and shared-edit previews. Height scaling and nonlinear calibration can follow with their own physical acceptance checks.

That keeps the straightforward flow intact—calibrate, review, save—while giving the advanced interface a consistent backend to build on.

[Interstellar0verdrive]

@xtimmy86x
All six are fair, and one of them changes my mind. All six are now in the document as well, including a new section on migration, so it stops disagreeing with what we've just agreed. In order:

1. Migration must not reverse precedence. Agreed, and native v2 timings should not arrive as overrides: an override means "this cover was measured", which those numbers don't assert. They belong one tier lower, as the fallback a cover uses when nothing else applies, with their origin labelled honestly. Anything that would change how a cover runs today should fail the migration rather than be guessed at.
2. Legacy profiles without a reference travel keep working, unscaled. That's already the rule on my side: with no reference travel, or no travel on the cover, the profile is applied as it stands. Scaling happens only when both numbers exist, so a user upgrading sees nothing change until they measure a travel.
   One boundary while we're agreeing, because "optional" can quietly become "absent": I've written three invariants into the document (877b6a7). A profile produced by a measurement always records the reference travel it was measured at, since the measurement knows it; a profile without one is applied unscaled and says so wherever it can be assigned to another cover; and a backend states which model it runs, with its accuracy reported honestly rather than implied. A linear backend is a legitimate implementation and none of those three asks you to build the nonlinear part first. They only stop the schema degrading into a pair of numbers, which would make my path B pointless: the travel is measured precisely so a profile can be scaled to a different window.
3. Provenance per key, not per record. You're right and yours is the better model: my record-level source/measured_at loses the "only the closing direction was re-measured" case, which my own path C produces. Changed in the schema.
4. You caught a real one, and the fix is to stop writing the overrides. Path A stores the measured values in the profile and as the cover's own, so that the measured cover would run on its own numbers whatever the YAML said. The effect nobody wanted is the one you describe: a later edit of the profile no longer reaches the cover it was measured on. Since the profile is created from that cover, its reference travel is that cover's travel, so following the profile gives exactly the same numbers and later edits propagate. So the default after a first measurement is now assigned, no overrides, and "keep these values for this cover only" stays an explicit choice for a cover that must not move with its group. Changed, and it's a change I'll make in my own implementation too.
5. Session exit: three verbs, and a reason for the odd one. Letting a run finish isn't stylistic. A timed run is heading for an end stop, which is a known position; stopping it half way leaves the cover somewhere the estimate can't name, which on a shutter is a worse state than "still moving". So: stop writes a stop now, cancel discards provisional values without implying movement, leave detaches the client. Ownership is released when the session has no provisional values left or the lease expires; a new session may start when the target reports no movement, or immediately after an explicit stop. Lease expiry and integration unload do send a stop, because then nobody is watching. If you prefer Close to keep requesting a stop, that's a policy we can set, as long as the three verbs stay distinct in the API.
6. Timing anchors: two cases, now named in the document. A press that causes the stop (the lift-off run) is measured to the moment the stop frame is written, because that write ended the movement. A press that observes a stop that already happened (the cover reaching an end stop) is measured to the confirmation arriving at the backend: the motor stopped before the finger moved and no stop frame is involved. The user's reaction delay is inside both on purpose, and the thorough level's third point per direction is what absorbs it as a scale factor on the times.

Your order works for me: schema and migration rules, one backend resolver for effective values and origins, then overrides and shared-edit previews, then scaling and the nonlinear part with their physical checks.

[xtimmy86x]

@Interstellar0verdrive Thanks for incorporating the feedback. The migration approach, per-key provenance and assigning the first measured cover without automatically creating overrides address the main storage concerns I found.

Two details remain worth making explicit before implementation:

• Reference travel: our current guided and automatic timing-only paths measure opening and closing times but do not measure physical travel. Those results should remain valid as explicitly unscaled timing profiles. A path that measures travel should always record it; sharing with height scaling should require both the profile’s reference travel and the target cover’s travel. That preserves the short calibration path without inventing missing data.
• Session ownership after Stop/Cancel: requesting or writing a Stop frame does not by itself confirm that the motor has physically stopped. Likewise, discarding provisional values does not mean the gateway is free for another calibration while the previous cover is still moving. I would keep the gateway reserved until the backend’s completion/interruption rules have been satisfied, with explicit handling for missing feedback and timeouts.

Keeping Close as “request Stop and end the measurement” in our UI works for me, while leaving the API operations distinct. A detached run would need to retain backend ownership and supervision until it terminates.

The distinction between a press that causes a stop and one that confirms an endpoint also makes sense. We should retain those as separate measurement types and avoid presenting command delivery as proof of physical arrest.

With those points clarified, I think we have a good basis for the first implementation step: the shared schema, migration rules and one resolver returning effective values and their origins, while preserving existing behavior.

[Interstellar0verdrive]

@xtimmy86x Both clarifications are right and are in the document now (51ffaf7).

Reference travel. Your timing-only paths produce a profile that is explicitly unscaled, and that's a legitimate result rather than a missing one: it's the short calibration, and it stays valid for the cover it was measured on and for any cover the user knowingly gives it to. The invariant now reads "a measurement that measures the travel records it", so no path is asked to invent a number it never collected, and scaling requires both halves.

Ownership. You're right that I conflated two things. Client ownership ends when the session ends or the lease expires; the gateway's reservation is separate and outlives it, because writing a stop frame is not proof that a motor stopped, and discarding provisional values doesn't mean the shutter came to rest. So the gateway stays reserved until the backend's completion rules are satisfied — the actuator reports a stop, or a guard period at least as long as the movement still owed has elapsed, falling back to the full travel time when nothing better is known — and a detached run keeps its supervision: somebody has to notice that it ended, or that it didn't.

Keeping Close as "request a stop and end the measurement" in your UI is fine by me as long as the three API operations stay distinct, and yes: the two press types stay separate measurement kinds, and command delivery is never presented as physical arrest.

Agreed on the first implementation step, and it's the right half to start from: shared schema, migration rules, one resolver returning effective values and their origins, existing behaviour preserved. That's backend and it's yours — the revision and atomicity machinery is already there.

On my side, the natural next piece after the contract is the screen flow for the covers section: which states become which screens, what each one says, and the two entry points we settled (calibrate straight from a cover, the profile-grouped view when there's a fleet to look after). That way you have something to build against when the backend is ready. Build whatever quick UI you need to exercise the resolver in the meantime — I'll work from it rather than around it.

[xtimmy86x]

@Interstellar0verdrive Agreed, the latest clarifications give us a solid basis to start. I’ll open a draft PR in the main repository, based on my current panel branch, so we can share the work and review the changes as they develop. It will remain experimental while we work towards the agreed scope.

I’ll start with the shared schema, migration rules and backend resolver, preserving existing behavior and exposing effective values with their origins.

For the screen flow, the covers section should remain consistent with the other WHO sections: shared navigation, device grouping, collapsible sections and familiar interaction patterns. Calibration controls and the optional profile-grouped overview should fit into that structure without fundamentally reorganising it.

That gives us a shared place to coordinate the backend and interface work, while keeping straightforward calibration short and direct.

[Interstellar0verdrive]

@xtimmy86x Sounds right, and a draft PR in the main repo is the best place for it.

On consistency: agreed, and I'd rather work inside your structure than bend it. The only thing worth thinking about together is that covers carry one object the other sections don't have — the profile, which belongs to several devices at once — so there's a relationship to show that doesn't fit inside a single device card. I'd like to find the way to fold that in gracefully, using the same shell, the same components and the same patterns, rather than bolting a different-looking screen onto the side. And it stays a second view, never something you pass through to calibrate one shutter.

I'll design inside your patterns and raise anything that seems to need a different shape, with the task it serves, so we can judge it together. Ping me when the resolver is far enough along that the read model is real, and I'll work the screens against it.