Built-in Fuzzy Logic Controller Helper

[dougransom]

Context & The Problem

Right now in Home Assistant, when automations need to control an output based on multiple continuous inputs (e.g. fan speed, target water temperature, shade position, or watering duration), users are forced to choose between several awkward approaches:

1. Threshold sensors & nested choose blocks: Brittle stair-step logic. A room at 23.9°C vs 24.1°C triggers an abrupt step change unless you write dozens of micro-conditions with hysteresis buffers.
2. Complex Jinja templates: Writing multiline mathematical polynomial approximations or weighting equations in YAML template sensors is hard to read, impossible for most users to debug, and prone to edge-case division-by-zero errors.
3. PID controllers: PID is great for steady-state setpoint tracking with direct physical feedback (e.g. sous-vide water bath), but notoriously difficult to tune for slow, non-linear multi-variable household environments (like balancing temperature + humidity + outdoor delta).

Human reasoning in home automation is inherently linguistic:

• "If the room is warm and humidity is somewhat high, run the fan at medium."
• "If solar export is high and battery SoC is decent, heat the water moderately."

Proposal

Introduce a built-in Fuzzy Logic Controller Helper (e.g. fuzzy_system or fuzzy_controller) to Core.

A fuzzy controller maps one or more existing numeric entities into continuous outputs using standard linguistic membership curves (triangular, trapezoidal, gaussian) and natural IF ... AND/OR ... THEN ... rules with linguistic hedges (very, somewhat, not).

The integration runs locally, reacts to input entity state changes, and outputs:

• A crisp defuzzified numeric sensor (e.g., 0% to 100%).
• Optional diagnostic attributes (rule_strengths, active dominant set) so users can see why an automation made a decision directly in their dashboards.

---

Real-World Use Cases

1. Dynamic Climate & Ceiling Fan Modulation

• Inputs: Indoor temperature, indoor humidity, and delta between indoor and outdoor temperature.
• Rule example: IF temp IS warm AND humidity IS humid THEN fan_speed IS high
• Why fuzzy logic: Instead of stepped fan speeds that abruptly click between speeds, the fan modulates smoothly across the entire range as temperature or humidity shifts, naturally accounting for heat index.

2. Adaptive Lighting & Solar Glare (Blinds/Shades)

• Inputs: Outdoor illuminance (lux), solar elevation angle, and room presence.
• Rule example: IF sun_elevation IS low AND outdoor_lux IS very bright THEN blind_tilt IS mostly_closed
• Why fuzzy logic: Avoids shades constantly hunting up and down when scattered clouds pass overhead, blending outdoor conditions smoothly with time of day.

3. Solar Excess & Heat Pump / EV Modulation

• Inputs: Excess grid export power (W), home battery State of Charge (%), and dynamic electricity tariff level.
• Rule example: IF solar_export IS high AND battery_soc IS good THEN water_heater_power IS high
• Why fuzzy logic: Replaces fragile nested priority matrices with a balanced continuous signal that throttles diversion smoothly as kitchen appliances turn on and off.

4. Smart Weather-Aware Irrigation

• Inputs: Soil moisture level, 24h rainfall history, and forecasted daytime high temperature.
• Rule example: IF soil IS dry AND forecast_temp IS hot AND rain_history IS low THEN watering_duration IS long
• Why fuzzy logic: Accounts for drying potential and moisture deficit holistically without requiring custom integration scripts or static cutoffs.

---

Architecture & Implementation Notes

• Entity Model: Sits alongside existing calculation helpers like derivative, threshold, min_max, and filter (iot_class: calculated, integration_type: helper).
• Reactivity: Listens to state change events of input entities. When an input updates, re-evaluates rules and updates output states.
• Performance: Pre-compiles rule structures, membership curve functions, and defuzzifier strategies on setup/init so evaluations are fast array lookups (O(1) dispatching).
• Dependencies: Can run on pure NumPy vector math or standard packaging (scikit-fuzzy).
• Proof of Concept: A fully functional, tested implementation is available here: dougransom/fuzzy_system (runs with Mamdani and Sugeno inference, 8 defuzzification algorithms, reload services, and Lovelace attribute telemetry).

Discussion Points for Core

1. Config Flow vs. YAML: Should the initial Core helper support declarative YAML configurations, a UI config flow with basic linguistic templates, or both?
2. Helper Platforms: Currently implemented as a sensor entity. Should there also be a dedicated number or climate control integration target, or is generating numeric sensor helpers that feed standard automations the cleanest approach?

[AJediIAm]

I implemented something link this with the help of AI. I use a lot of helpers so each discrete state (warm/cool) and continues scaler (delta temperature) is visible in the history. Decisions are first separated into state based scenario's and than a scaling formula is applied to regulate the output.

A nice example is my ventilation system which calculates the ventilation speed (0%-100%) based on temperature, humidity and CO2.

1. States such as warm/neutral/cool and dry/neutral/humid determine which factors contribute to the fan speed.
2. Temperature, humidity and CO2 factors are calculated. For example: min( max_co2 - 500, 100) scales the CO2 factor from 0% at 500ppm to 100% at 1500ppm.
3. Take the max of all applicable factors.
   The actual logic is more complex and also considers weather forecast, dynamic energy prices, solar power and presence. I'm very happy with the result.

Based on my experience, tuning this behaviour requires historical insight into all contributing entities. It's easy to include too many values and drown in the complexity. I let AI create dashboards specifically to understand why something is happening, showing the logic layer by layer.

I would split the proposal into 4 (mostly independent) steps:

1. multi-filter helpers: sensor_float_helper > filter outliers > moving average > threshold> time throttle > binary_sensor.state_helper.
   This would significantly reduce the number of helpers. I think this is already possible in yaml, but I only use the UI.

2. select helper based on multiple threshold filters.
   Similar to the example above, but with a multiple thresholds for multiple states.

3. binary sensor / select helper based on UI logic. Basically the automation engine for helpers so they are a bit easier to manage.

4. math in sensor helper: basic math in true UI blocks instead of Jinja templates (which are a pain).

These 4 improvements would put fuzzy logic within reach for most users. I guess a true fuzzy logic helper would be possible, but I think it's difficult to use a bit far from the current helpers.
I mean, we still need a Jinja black belt to subtract two sensors. Let's fix that before advancing to neural networking.