Home Assistant: Fan Speed Logbook Feature Request

by SLV Team 50 views
Home Assistant: Fan Speed Logbook Feature Request

Hey guys! Let's dive into an exciting feature request for Home Assistant that could seriously level up your fan control logging. We're talking about adding optional logbook entries for fan speed changes, complete with a debounce feature to keep things clean and tidy. So, buckle up, and let's get into the nitty-gritty!

The Problem: Why Fan Speed Changes Aren't Logged

Currently, Home Assistant's Logbook is a champ at tracking state changes—think devices turning on or off. But when it comes to attribute-only updates, like fan speed adjustments, it's a no-show. For fans, the main state is usually just “on” or “off,” while the speed (expressed as a percentage) lives as an attribute. This means if you're tweaking your fan speed, you won't see these adjustments in the device's activity feed, which isn't ideal for keeping tabs on your smart home's behavior.

The Current Behavior Explained

To break it down, fan percentage updates are invisible in the Logbook unless they happen at the same time as an on/off state change. This can be pretty frustrating if you’re trying to monitor how your fan speeds are changing throughout the day. Plus, with our fast-paced interactions using sliders, optimistic updates, and automations, there can be a flurry of attribute changes happening in a short amount of time. Imagine sliding that fan speed control – you might generate a string of values like 32%, 38%, 45%, and then 50% in less than a second! That's a lot of potential log entries that we need to handle smartly.

Why Not Log Every Single Change?

You might be thinking, "Why not just log everything?" Well, here's the deal: sliders, as we just mentioned, produce tons of interim values. Optimistic updates (which make your interface feel super snappy) generate multiple updates per user action. And automations or scenes might gradually adjust fan speed over several seconds or minutes. If we logged every single change, the Logbook would become an overwhelming mess of data, losing its usefulness for high-level overviews. Remember, the Logbook is designed to give you the big picture, and too much detail would defeat the purpose.

The Solution: Optional, Debounced Fan Speed Logs

So, what's the solution? We're proposing an optional way to log “Fan speed set to X%” entries, but with some smart safeguards to prevent the Logbook from getting flooded. The key is to keep the default behavior unchanged – no speed logs unless you specifically want them – to match existing Home Assistant expectations. This way, we cater to both users who want detailed logs and those who prefer a cleaner, more concise view of their device activity.

What We Want: The Desired Behavior

Here’s the vision: we want to optionally log “Fan speed set to X%” entries, but with guardrails to prevent noise. This means keeping the default behavior untouched (no speed logs) to align with what Home Assistant users expect. The goal is to provide more insight without overwhelming the system with unnecessary data. We need to find a sweet spot that balances detail and usability, so let’s dive into the proposed approach.

The Proposed Approach: How It Works

  1. Options Toggle: Add a simple switch in the options menu labeled “Log speed changes.” By default, this will be off, ensuring no change for existing users. This gives you the power to decide whether you want these detailed logs or not.
  2. Debounce Window: Implement a debounce window (think 500–1000 milliseconds). This means we only log the last percentage value set within that quiet window. So, if you're quickly adjusting a slider, only the final value after you stop will be logged. This prevents the logbook from being spammed with intermediate values.
  3. Source Filtering: Prioritize logging changes initiated by humans through the user interface (service calls from the UI). We could even add an option to skip logging changes originating from automations or scenes. This helps differentiate between manual adjustments and automated actions.
  4. Limit Reconnect Noise: Don’t log changes during a reconnect re-sync or when changes are simply server echoes. This prevents the Logbook from getting cluttered with system-level communications.
  5. Message Format: Use a clear and concise message format like “Set speed to X%” along with the device name and a timestamp. This makes the logs easy to read and understand at a glance.

Open Questions: Let's Brainstorm!

Before we get too far ahead, there are some questions we need to chew on:

  • What debounce default feels right? Should it be 500 milliseconds, 1000 milliseconds, or something else entirely? We need to find a duration that effectively reduces noise without missing legitimate changes.
  • Should we expose “Log only manual changes” as a separate option? This would give users even more control over what gets logged, but it also adds complexity to the settings.
  • Do we need a minimum delta (e.g., log only if the change is ≥ 5%)? This could further reduce noise by ignoring minor adjustments, but it might also miss fine-tuning adjustments that users care about.

Setting the Bar: Acceptance Criteria

To make sure this feature is a home run, we need some clear acceptance criteria. These are the benchmarks we'll use to determine if the implementation is successful.

  • No Change in Default Behavior: With logging disabled (the default), there should be absolutely no change in the current behavior. This is crucial for maintaining a consistent experience for existing users.
  • Manual UI Changes: With logging enabled, manual speed changes made through the UI should produce a single, debounced logbook entry. This ensures that intentional adjustments are captured without creating excessive logs.
  • Slider Movements: Rapid slider movements should only log the final, settled value. This prevents the Logbook from being flooded with intermediate values during quick adjustments.
  • Reconnect/Status Reconciliation: Reconnects and status reconciliations should not produce log entries. These are system-level events that don't need to clutter the Logbook.
  • Automation Control: Optionally, changes driven by automations can be skipped if the user chooses a “manual only” setting. This gives users the flexibility to focus on manual adjustments if they prefer.

Potential Pitfalls: Risks and Trade-offs

No feature is without its potential downsides. Even with debounce, frequent automation changes could still add entries, though source filtering helps mitigate this. There’s also a slight increase in complexity when distinguishing between manual and automation sources. We need to weigh these trade-offs carefully.

Even with Debounce, Beware Automation Overload

Even with the debounce feature in place, it’s possible that frequent changes triggered by automations could still generate a fair number of log entries. Imagine an automation that gradually increases fan speed over several minutes—this could still result in multiple log entries, even with debouncing. However, the source filtering option helps mitigate this by allowing users to skip logging changes from automations altogether.

The Complexity of Distinguishing Sources

There’s a bit of added complexity in figuring out whether a change came from a manual adjustment or an automation. We need to reliably identify the source of the change to implement the “Log only manual changes” option effectively. This might involve examining the context of the service call or looking at specific flags or attributes associated with the event.

Thinking Outside the Box: Alternatives Considered

Before landing on this approach, we considered a few other options.

  • Logging every percentage change: This was quickly deemed too noisy, as it would flood the Logbook with every minor adjustment.
  • Logging only on large deltas: While clearer, this could miss fine control adjustments without a debounce. For example, if you're making small, incremental changes to find the perfect setting, you might miss these adjustments if we only log large deltas. Debouncing gives us a more nuanced way to capture these changes without overwhelming the system.

What's Next? Next Steps

So, where do we go from here? The next steps are to:

  1. Finalize Options: Nail down the exact options we want to include: the main toggle, the debounce duration, and the manual-only setting.
  2. Implement the Magic: Get this implemented in the fan.async_set_percentage path, adding a small debounce task to handle the timing.
  3. Test, Test, Test: Add thorough tests to cover manual vs. automation sources, debounce behavior, and reconnect suppression. This is crucial to ensure the feature works as expected in all scenarios.

Time to Align: Let's Settle on the Options

Before diving into the implementation, we need to make sure we’re all on the same page regarding the options. This means deciding on the specifics of the main toggle (“Log speed changes”), the default debounce duration (500ms? 1000ms?), and whether we should include a “Log only manual changes” option. Getting these details right is crucial for creating a feature that’s both useful and user-friendly.

Implementation Time: Diving into the Code

The next step is to actually implement the feature. This involves modifying the fan.async_set_percentage path in Home Assistant to include the new logging functionality. We’ll need to add a small debounce task to handle the timing, ensuring that we only log the final speed setting after a period of inactivity. This is where the rubber meets the road, and we’ll need to be careful to ensure that our changes are efficient and don’t introduce any performance bottlenecks.

The Importance of Testing: Ensuring Quality and Reliability

Last but not least, we need to add thorough tests to cover all aspects of the feature. This includes testing manual vs. automation sources to ensure that the source filtering works correctly. We also need to test the debounce behavior to make sure it’s effectively preventing log spam. And, of course, we need to test reconnect suppression to ensure that we’re not logging unnecessary events during system restarts or network interruptions. Thorough testing is essential to ensure that the feature is reliable and works as expected in all scenarios.

Conclusion: Leveling Up Fan Control Logging

This feature request is all about giving you more control and insight into your fan usage in Home Assistant. By adding optional, debounced logbook entries for fan speed changes, we can provide a richer view of your smart home activity without cluttering your logs. Let's make it happen, guys!