[JS+Editor Module] Energy Consumption

[Skycrox]

Energy Consumption

Version: 2026.3.1
Creator: Skycrox

Important

Supported cards:

• Button
• custom-button

Bubble Card module for compact energy and sensor statistics in the card state line.

Features

• Shows energy and sensor values for the selected time range
• Uses the Energy dashboard date range automatically when available
• Falls back to the last X hours when no range is active (optional: start at beginning of day)
• Lets you choose the calculation: increase, average, median, minimum, or maximum
• Works with both long-term statistics and short-term history data
• Detects entity and unit automatically, with optional manual override
• Optionally scales units automatically for better readability
• Can show period hints when data starts later or ends earlier than expected
• Supports custom period labels (for example your own words for from/to)
• Includes built-in translations with automatic fallback to English
• Stays responsive even when data updates frequently

Great for energy monitoring, consumption tracking, and quick at-a-glance statistics in Bubble Card.

Example configuration

energy_consumption:
  entity: sensor.home_energy_consumption
  data_settings:
    mode: increase
    data_source: statistics
    collection_key: energy
    ignore_date_selector: false
    fallback_hours: 24
    min_update_interval_seconds: 15
    extend_fallback_start_to_day_boundary: false
  display_settings:
    precision: 2
    unit: ""
    show_unit_scaling: true
    show_period_info: true
    label_settings:
      custom_period_from: ""
      custom_period_to: ""

🧩 Get this Module

To use this module, simply copy and paste the following configuration into your /www/bubble/bubble-modules.yaml file.

energy_consumption:
  name: "Energy Consumption"
  version: "2026.3.1"
  creator: "skycrox"
  supported:
    - button
    - custom-button
  description: |
    Compact statistics module for Home Assistant sensors.
    Supports increase, average, median, minimum, and maximum.
    Works with Statistics or History data source.
    Includes optional auto unit scaling, period info, and multi-language labels.
    Entity and unit can be auto-detected from Bubble Card config.
    Supports Energy Date Selector or a fixed fallback hour range.
  code: |
    ${(async () => {
      const moduleName = "Bubble Energy Consumption";
      const DEFAULTS = Object.freeze({
        dataSource: "statistics",
        mode: "increase",
        precision: 2,
        unit: "",
        collectionKey: "_energy",
        requestDebounceMs: 150,
        minUpdateIntervalSeconds: 15,
        minUpdateIntervalSecondsMin: 0,
        fallbackHours: 24,
        fallbackHoursMin: 0,
        fallbackHoursMax: 168,
        ignoreDateSelector: false,
        extendFallbackStartToDayBoundary: false,
        showPeriodInfo: true,
        showUnitScaling: false,
        customPeriodFrom: "",
        customPeriodTo: "",
      });

      const mCfg = this.config.energy_consumption || {};
      const dataSettings = mCfg.data_settings || {};
      const displaySettings = mCfg.display_settings || {};
      const labelSettings = displaySettings.label_settings || {};
      const entityId = mCfg.entity || this.config.entity;

      if (!entityId) return;

      const stateObj = hass.states[entityId];
      const autoUnit = stateObj?.attributes?.unit_of_measurement || "kWh";
      const configuredUnit = displaySettings.unit ?? DEFAULTS.unit;
      const unit = configuredUnit || autoUnit;
      const precision = clampNumber(
        resolveInteger(
          displaySettings.precision,
          DEFAULTS.precision,
        ),
        0,
        4,
      );
      const mode = dataSettings.mode || DEFAULTS.mode;
      const dataSource = dataSettings.data_source || DEFAULTS.dataSource;
      const showPeriodInfo = resolveBoolean(
        displaySettings.show_period_info,
        DEFAULTS.showPeriodInfo,
      );
      const showUnitScaling = resolveBoolean(
        displaySettings.show_unit_scaling,
        DEFAULTS.showUnitScaling,
      );
      const customPeriodFrom =
        labelSettings.custom_period_from ||
        DEFAULTS.customPeriodFrom;
      const customPeriodTo =
        labelSettings.custom_period_to ||
        DEFAULTS.customPeriodTo;
      const actualCollectionKey = normalizeCollectionKey(dataSettings.collection_key);
      const minUpdateIntervalSeconds = Math.max(
        DEFAULTS.minUpdateIntervalSecondsMin,
        Number(dataSettings.min_update_interval_seconds ?? DEFAULTS.minUpdateIntervalSeconds),
      );
      const requestCacheTtlMs = Math.round(minUpdateIntervalSeconds * 1000);
      const fallbackHours = Math.max(
        DEFAULTS.fallbackHoursMin,
        Math.min(
          DEFAULTS.fallbackHoursMax,
          Number(dataSettings.fallback_hours ?? DEFAULTS.fallbackHours),
        ),
      );
      const ignoreDateSelector = resolveBoolean(
        dataSettings.ignore_date_selector,
        DEFAULTS.ignoreDateSelector,
      );
      const extendFallbackStartToDayBoundary = resolveBoolean(
        dataSettings.extend_fallback_start_to_day_boundary,
        DEFAULTS.extendFallbackStartToDayBoundary,
      );
      const locale = hass.locale?.language || hass.language || "en-US";

      const runtime = ensureRuntimeState();
      let moduleState = runtime.moduleState;

      if (hasContextChanged()) {
        cleanupModuleState(moduleState);
        moduleState = createModuleState();
        moduleState.entityId = entityId;
        moduleState.collectionKey = actualCollectionKey;
        moduleState.ignoreDateSelector = ignoreDateSelector;
        moduleState.extendFallbackStartToDayBoundary = extendFallbackStartToDayBoundary;
        moduleState.dataSource = dataSource;
        moduleState.mode = mode;
        moduleState.fallbackHours = fallbackHours;
        moduleState.minUpdateIntervalSeconds = minUpdateIntervalSeconds;
        runtime.moduleState = moduleState;
      }

      const translations = {
        en: { from: "from", to: "to" },
        de: { from: "ab", to: "bis" },
        es: { from: "desde", to: "hasta" },
        fr: { from: "depuis", to: "jusqu'à" },
        it: { from: "da", to: "a" },
        nl: { from: "vanaf", to: "tot" },
        pl: { from: "od", to: "do" },
        pt: { from: "desde", to: "até" },
        ru: { from: "с", to: "до" },
        zh: { from: "从", to: "到" },
      };

      const langCode = locale.split("-")[0].toLowerCase();
      const trans = translations[langCode] || translations["en"];
      const periodFrom = customPeriodFrom || trans.from;
      const periodTo = customPeriodTo || trans.to;

      requestConfiguredRange();
      updateDisplay();

      // ---- State management ----

      function createModuleState() {
        return {
          entityId: null,
          collectionKey: null,
          ignoreDateSelector: null,
          extendFallbackStartToDayBoundary: null,
          dataSource: null,
          mode: null,
          fallbackHours: null,
          minUpdateIntervalSeconds: null,
          energyUnsubscribe: null,
          pendingTimer: null,
          pendingRange: null,
          lastFetchAtMs: 0,
          isFetching: false,
          fetchRangeKey: null,
          rangeKey: null,
          data: { value: null, isLoading: false, periodInfo: null },
        };
      }

      function ensureRuntimeState() {
        if (!card._energyConsumptionRuntime) {
          card._energyConsumptionRuntime = {
            entityRequestCache: new Map(),
            moduleState: createModuleState(),
          };
        }

        return card._energyConsumptionRuntime;
      }

      function hasContextChanged() {
        return moduleState.entityId !== entityId ||
          moduleState.collectionKey !== actualCollectionKey ||
          moduleState.ignoreDateSelector !== ignoreDateSelector ||
          moduleState.extendFallbackStartToDayBoundary !== extendFallbackStartToDayBoundary ||
          moduleState.dataSource !== dataSource ||
          moduleState.mode !== mode ||
            moduleState.fallbackHours !== fallbackHours ||
            moduleState.minUpdateIntervalSeconds !== minUpdateIntervalSeconds;
      }

      // ---- Utilities ----

      function normalizeCollectionKey(collectionKey) {
        if (!collectionKey) return DEFAULTS.collectionKey;
        return collectionKey.startsWith("_") ? collectionKey : `_${collectionKey}`;
      }

      function resolveBoolean(primaryValue, fallbackValue) {
        if (typeof primaryValue === "boolean") return primaryValue;
        return fallbackValue;
      }

      function resolveInteger(primaryValue, fallbackValue) {
        const candidate = primaryValue;
        const parsed = Number.parseInt(candidate, 10);
        return Number.isFinite(parsed) ? parsed : fallbackValue;
      }

      function clampNumber(value, minValue, maxValue) {
        const numeric = Number(value);
        if (!Number.isFinite(numeric)) return minValue;
        return Math.min(maxValue, Math.max(minValue, numeric));
      }

      function logWarning(message, error) {
        if (error) {
          console.warn(`[${moduleName}] ${message}`, error);
          return;
        }

        console.warn(`[${moduleName}] ${message}`);
      }

      function cleanupModuleState(state) {
        if (!state) return;

        if (state.pendingTimer) {
          clearTimeout(state.pendingTimer);
          state.pendingTimer = null;
        }

        if (typeof state.energyUnsubscribe === "function") {
          try {
            state.energyUnsubscribe();
          } catch (error) {
            logWarning("Failed to unsubscribe from the energy collection.", error);
          }

          state.energyUnsubscribe = null;
        }

        state.pendingRange = null;
      }

      function getEntityCache(entityKey) {
        let entityCache = runtime.entityRequestCache.get(entityKey);
        if (!entityCache) {
          entityCache = new Map();
          runtime.entityRequestCache.set(entityKey, entityCache);
        }

        return entityCache;
      }

      function pruneEntityRequestCache(entityKey) {
        const entityCache = runtime.entityRequestCache.get(entityKey);
        if (!entityCache) return;

        const nowMs = Date.now();
        for (const [cacheKey, entry] of entityCache.entries()) {
          const resolvedAt = Number(entry?.resolvedAt || 0);
          const isExpired = !entry?.promise && resolvedAt && nowMs - resolvedAt > requestCacheTtlMs;
          if (isExpired) {
            entityCache.delete(cacheKey);
          }
        }

        if (!entityCache.size) {
          runtime.entityRequestCache.delete(entityKey);
        }
      }

      // ---- Formatting ----

      function scaleUnit(value, originalUnit) {
        if (!showUnitScaling || !originalUnit || value === null || value === 0) {
          return { value, unit: originalUnit };
        }

        const unitChains = {
          "Wh": ["mWh", "Wh", "kWh", "MWh", "GWh"],
          "mWh": ["mWh", "Wh", "kWh", "MWh", "GWh"],
          "kWh": ["mWh", "Wh", "kWh", "MWh", "GWh"],
          "MWh": ["mWh", "Wh", "kWh", "MWh", "GWh"],
          "GWh": ["mWh", "Wh", "kWh", "MWh", "GWh"],
          "W": ["mW", "W", "kW", "MW", "GW"],
          "mW": ["mW", "W", "kW", "MW", "GW"],
          "kW": ["mW", "W", "kW", "MW", "GW"],
          "MW": ["mW", "W", "kW", "MW", "GW"],
          "GW": ["mW", "W", "kW", "MW", "GW"],
          "mm": ["mm", "cm", "m", "km"],
          "cm": ["mm", "cm", "m", "km"],
          "m": ["mm", "cm", "m", "km"],
          "km": ["mm", "cm", "m", "km"],
          "ml": ["ml", "cl", "dl", "l", "hl", "m³", "km³"],
          "cl": ["ml", "cl", "dl", "l", "hl", "m³", "km³"],
          "dl": ["ml", "cl", "dl", "l", "hl", "m³", "km³"],
          "l": ["ml", "cl", "dl", "l", "hl", "m³", "km³"],
          "hl": ["ml", "cl", "dl", "l", "hl", "m³", "km³"],
          "m³": ["ml", "cl", "dl", "l", "hl", "m³", "km³"],
          "km³": ["ml", "cl", "dl", "l", "hl", "m³", "km³"],
          "ct": ["ct", "€"],
          "€": ["ct", "€"],
          "¢": ["¢", "$"],
          "$": ["¢", "$"],
          "p": ["p", "£"],
          "£": ["p", "£"],
          "¥": ["¥"],
          "mg": ["mg", "g", "kg", "t"],
          "g": ["mg", "g", "kg", "t"],
          "kg": ["mg", "g", "kg", "t"],
          "t": ["mg", "g", "kg", "t"],
        };

        const conversionFactors = {
          "mWh": 0.001, "Wh": 1, "kWh": 1000, "MWh": 1000000, "GWh": 1000000000,
          "mW": 0.001, "W": 1, "kW": 1000, "MW": 1000000, "GW": 1000000000,
          "mm": 0.001, "cm": 0.01, "m": 1, "km": 1000,
          "ml": 0.001, "cl": 0.01, "dl": 0.1, "l": 1, "hl": 100, "m³": 1000, "km³": 1000000000000,
          "ct": 0.01, "€": 1, "¢": 0.01, "$": 1, "p": 0.01, "£": 1, "¥": 1,
          "mg": 0.001, "g": 1, "kg": 1000, "t": 1000000,
        };

        const chain = unitChains[originalUnit];
        if (!chain || !conversionFactors[originalUnit]) return { value, unit: originalUnit };

        const baseValue = value * conversionFactors[originalUnit];
        let bestUnit = originalUnit;
        let bestValue = value;
        let bestScore = -Infinity;

        for (const targetUnit of chain) {
          const targetValue = baseValue / conversionFactors[targetUnit];
          if (targetValue <= 0) continue;

          let score;
          if (targetValue >= 1 && targetValue < 1000) {
            score = 100 - Math.abs(Math.log10(targetValue) - 1.5) * 10;
          } else if (targetValue < 1) {
            score = -100;
          } else {
            score = -50;
          }

          if (score > bestScore) {
            bestUnit = targetUnit;
            bestValue = targetValue;
            bestScore = score;
          }
        }

        return { value: bestValue, unit: bestUnit };
      }

      function formatNumber(value) {
        if (value === null || value === undefined || isNaN(value)) return "0";
        return value.toLocaleString(locale, {
          minimumFractionDigits: precision,
          maximumFractionDigits: precision,
        });
      }

      function formatDate(date) {
        return date.toLocaleDateString(locale, {
          day: "2-digit",
          month: "2-digit",
          year: "numeric",
        });
      }

      // ---- Display ----

      function updateDisplay() {
        const stateEl = card.querySelector(".bubble-state");
        if (!stateEl) return;

        const data = moduleState.data;

        if (data.isLoading) {
          stateEl.innerText = "Loading...";
          return;
        }

        if (data.value !== null) {
          const scaled = scaleUnit(data.value, unit);
          const periodText = showPeriodInfo && data.periodInfo ? ` ${data.periodInfo}` : "";
          stateEl.innerText = `${formatNumber(scaled.value)} ${scaled.unit}${periodText}`;
          return;
        }

        const currentValue = parseFloat(hass.states[entityId]?.state) || 0;
        const scaled = scaleUnit(currentValue, unit);
        stateEl.innerText = `${formatNumber(scaled.value)} ${scaled.unit}`;
      }

      // ---- Data loading ----

      function resolveStatisticValue(entry) {
        if (entry.sum !== undefined && entry.sum !== null) return entry.sum;
        if (entry.state !== undefined && entry.state !== null) return entry.state;
        if (entry.mean !== undefined && entry.mean !== null) return entry.mean;
        return null;
      }

      async function loadHistorySeries(startTime, endTime) {
        const startIso = startTime.toISOString();
        const endIso = endTime.toISOString();
        const historyPath =
          `history/period/${encodeURIComponent(startIso)}` +
          `?filter_entity_id=${encodeURIComponent(entityId)}` +
          `&end_time=${encodeURIComponent(endIso)}` +
          `&minimal_response&no_attributes`;
        const historyResponse = await hass.callApi("GET", historyPath);

        if (!Array.isArray(historyResponse) || !Array.isArray(historyResponse[0])) return [];

        return historyResponse[0].map((entry) => ({
          value: parseFloat(entry.state),
          start: entry.last_changed || entry.last_updated,
          end: entry.last_changed || entry.last_updated,
        }));
      }

      async function loadStatisticsSeries(startTime, endTime) {
        const statisticsData = await hass.callWS({
          type: "recorder/statistics_during_period",
          start_time: startTime.toISOString(),
          end_time: endTime.toISOString(),
          statistic_ids: [entityId],
          period: "hour",
        });
        const entityStatistics = statisticsData?.[entityId];

        if (!Array.isArray(entityStatistics)) return [];

        return entityStatistics.map((entry) => ({
          value: resolveStatisticValue(entry),
          start: entry.start,
          end: entry.end,
        }));
      }

      async function loadSeries(startTime, endTime) {
        if (dataSource === "history") return loadHistorySeries(startTime, endTime);
        return loadStatisticsSeries(startTime, endTime);
      }

      async function loadCachedSeries(startTime, endTime, forceRefresh = false) {
        const startIso = startTime.toISOString();
        const endIso = endTime.toISOString();
        const entityCache = getEntityCache(entityId);
        const requestCacheKey = `${dataSource}|${startIso}|${endIso}`;
        const cachedEntry = entityCache.get(requestCacheKey);
        const nowMs = Date.now();

        if (forceRefresh) {
          entityCache.delete(requestCacheKey);
        }

        if (!forceRefresh && cachedEntry?.promise) {
          return cachedEntry.promise;
        }

        if (!forceRefresh && cachedEntry?.series && nowMs - Number(cachedEntry.resolvedAt || 0) <= requestCacheTtlMs) {
          return cachedEntry.series;
        }

        const requestPromise = loadSeries(startTime, endTime);
        entityCache.set(requestCacheKey, {
          promise: requestPromise,
          resolvedAt: 0,
          series: null,
        });

        try {
          const series = await requestPromise;
          entityCache.set(requestCacheKey, {
            promise: null,
            resolvedAt: Date.now(),
            series,
          });
          pruneEntityRequestCache(entityId);
          return series;
        } catch (error) {
          entityCache.delete(requestCacheKey);
          throw error;
        }
      }

      // ---- Calculation ----

      function computeResult(values, calculationMode) {
        if (!values.length) return 0;

        if (calculationMode === "increase") {
          return Math.max(0, values[values.length - 1] - values[0]);
        }

        if (calculationMode === "avg") {
          return values.reduce((acc, val) => acc + val, 0) / values.length;
        }

        if (calculationMode === "median") {
          const sorted = [...values].sort((a, b) => a - b);
          const mid = Math.floor(sorted.length / 2);
          return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
        }

        if (calculationMode === "min") return Math.min(...values);
        if (calculationMode === "max") return Math.max(...values);

        return 0;
      }

      function computePeriodInfo(stats, startTime, endTime) {
        if (!stats.length) return null;

        const actualStart = new Date(stats[0].start || stats[0].end);
        const actualEnd = new Date(stats[stats.length - 1].end || stats[stats.length - 1].start);
        const now = new Date();
        const oneDayMs = 24 * 60 * 60 * 1000;

        const startDiff = Math.abs(actualStart - startTime);
        const endDiff = Math.abs(actualEnd - endTime);
        const isEndNow = Math.abs(now - actualEnd) < oneDayMs;

        if (startDiff > oneDayMs && endDiff > oneDayMs && !isEndNow) {
          return `(${formatDate(actualStart)} - ${formatDate(actualEnd)})`;
        }

        if (startDiff > oneDayMs) {
          return `(${periodFrom} ${formatDate(actualStart)})`;
        }

        if (endDiff > oneDayMs && !isEndNow) {
          return `(${periodTo} ${formatDate(actualEnd)})`;
        }

        return null;
      }

      // ---- Fetching ----

      async function fetchConsumption(startTime, endTime, rangeKey, forceRefresh = false) {
        if (moduleState.isFetching && moduleState.fetchRangeKey === rangeKey) return;

        const hasCachedDisplayValue = moduleState.data.value !== null;
        moduleState.isFetching = true;
        moduleState.lastFetchAtMs = Date.now();
        moduleState.fetchRangeKey = rangeKey;
        moduleState.data.isLoading = forceRefresh || !hasCachedDisplayValue;
        updateDisplay();

        try {
          const stats = await loadCachedSeries(startTime, endTime, forceRefresh);
          const values = stats
            .map((entry) => entry.value)
            .filter((val) => val !== null && val !== undefined && !Number.isNaN(val));

          moduleState.data.value = values.length ? computeResult(values, mode) : 0;
          moduleState.data.periodInfo = showPeriodInfo ? computePeriodInfo(stats, startTime, endTime) : null;
        } catch (error) {
          logWarning(`Failed to fetch consumption data for ${entityId}.`, error);
          moduleState.data.value = null;
        } finally {
          moduleState.data.isLoading = false;
          moduleState.isFetching = false;
          if (moduleState.fetchRangeKey === rangeKey) {
            moduleState.fetchRangeKey = null;
          }
          updateDisplay();
        }
      }

      function requestFetchForRange(startTime, endTime, options = {}) {
        const forceRefresh = options.forceRefresh === true;
        const rangeKey = `${startTime.toISOString()}|${endTime.toISOString()}`;
        if (moduleState.rangeKey === rangeKey && !forceRefresh) return;

        moduleState.rangeKey = rangeKey;
        moduleState.pendingRange = { startTime, endTime, rangeKey, forceRefresh };

        const nowMs = Date.now();
        const elapsedSinceLastFetchMs = nowMs - Number(moduleState.lastFetchAtMs || 0);
        const remainingThrottleMs = !forceRefresh && requestCacheTtlMs > 0
          ? Math.max(0, requestCacheTtlMs - elapsedSinceLastFetchMs)
          : 0;
        const baseDebounceMs = !forceRefresh && requestCacheTtlMs > 0 ? DEFAULTS.requestDebounceMs : 0;
        const delayMs = Math.max(baseDebounceMs, remainingThrottleMs);

        if (moduleState.pendingTimer) {
          clearTimeout(moduleState.pendingTimer);
        }

        moduleState.pendingTimer = setTimeout(() => {
          const pendingRange = moduleState.pendingRange;
          moduleState.pendingTimer = null;
          if (!pendingRange) return;

          moduleState.pendingRange = null;
          fetchConsumption(
            pendingRange.startTime,
            pendingRange.endTime,
            pendingRange.rangeKey,
            pendingRange.forceRefresh === true,
          );
        }, delayMs);
      }

      // ---- Subscription & range resolution ----

      function getFallbackRange() {
        const nowMs = Date.now();
        const intervalMs = Math.max(1000, requestCacheTtlMs || 0);
        const alignedEndMs = Math.floor(nowMs / intervalMs) * intervalMs;
        const endTime = new Date(alignedEndMs);
        const startTime = new Date(alignedEndMs - fallbackHours * 60 * 60 * 1000);
        if (extendFallbackStartToDayBoundary) {
          startTime.setHours(0, 0, 0, 0);
        }

        return { startTime, endTime };
      }

      function subscribeToEnergyCollection(energyCollection) {
        if (moduleState.energyUnsubscribe) return;

        moduleState.energyUnsubscribe = energyCollection.subscribe((collection) => {
          if (!collection?.start || !collection?.end) return;
          requestFetchForRange(new Date(collection.start), new Date(collection.end), { forceRefresh: true });
        });
      }

      function requestConfiguredRange() {
        const energyCollection = hass.connection?.[actualCollectionKey];
        if (ignoreDateSelector || !energyCollection) {
          const { startTime, endTime } = getFallbackRange();
          requestFetchForRange(startTime, endTime);
          return;
        }

        subscribeToEnergyCollection(energyCollection);

        const currentCollection = energyCollection.state;
        if (currentCollection?.start && currentCollection?.end) {
          requestFetchForRange(new Date(currentCollection.start), new Date(currentCollection.end));
          return;
        }

        const { startTime, endTime } = getFallbackRange();
        requestFetchForRange(startTime, endTime);
      }
    })()}
  editor:
    - label: "Entity ID (optional, auto-detected)"
      name: entity
      selector:
        entity:
          filter:
            domain: sensor
    - name: "data_settings"
      type: "expandable"
      title: "Data & Calculation"
      icon: "mdi:database"
      expanded: true
      schema:
        - label: "Mode"
          name: mode
          selector:
            select:
              mode: "dropdown"
              options:
                - label: "Increase"
                  value: "increase"
                - label: "Average"
                  value: "avg"
                - label: "Median"
                  value: "median"
                - label: "Minimum"
                  value: "min"
                - label: "Maximum"
                  value: "max"
          default: "increase"
        - label: "Data Source"
          name: data_source
          selector:
            select:
              mode: "dropdown"
              options:
                - label: "Statistics (Recorder, long-term)"
                  value: "statistics"
                - label: "History (All sensors, short-term)"
                  value: "history"
          default: "statistics"
        - label: "Collection Key (e.g., energy_test, energy_custom_yearly)"
          name: collection_key
          selector:
            text: {}
          default: "_energy"
        - label: "Ignore Energy Date Selector"
          name: ignore_date_selector
          selector:
            boolean: {}
          default: false
        - label: "Fallback Hours (used when no energy period is active)"
          name: fallback_hours
          selector:
            number:
              min: 0
              max: 168
              step: 1
              unit_of_measurement: "h"
          default: 24
        - label: "Minimum Update Interval"
          name: min_update_interval_seconds
          selector:
            number:
              min: 0
              step: 0.5
              unit_of_measurement: "s"
          default: 15
        - label: "Extend Fallback Range to Start of Day"
          name: extend_fallback_start_to_day_boundary
          selector:
            boolean: {}
          default: false
    - name: "display_settings"
      type: "expandable"
      title: "Display"
      icon: "mdi:eye"
      expanded: false
      schema:
        - label: "Decimal Precision"
          name: precision
          selector:
            number:
              min: 0
              max: 4
              step: 1
          default: 2
        - label: "Unit (optional, auto-detected)"
          name: unit
          selector:
            text: {}
          default: ""
        - label: "Enable Unit Scaling"
          name: show_unit_scaling
          selector:
            boolean: {}
          default: false
        - label: "Show Period Info"
          name: show_period_info
          selector:
            boolean: {}
          default: true
        - name: "label_settings"
          type: "expandable"
          title: "Custom Period Labels"
          icon: "mdi:translate"
          expanded: false
          schema:
            - label: "Custom 'From' Label (e.g., 'since', 'ab')"
              name: custom_period_from
              selector:
                text: {}
              default: ""
            - label: "Custom 'To' Label (e.g., 'until', 'bis')"
              name: custom_period_to
              selector:
                text: {}
              default: ""

Changelog

• 2026.3.1
  • Breaking change: due to the settings restructure, old settings are no longer applied automatically
  • Please review and reconfigure your module settings after updating
  • Added configurable request caching via Minimum Update Interval
  • Added support for custom Collection Key values
  • Added option to ignore the Energy Date Selector and use fallback range
  • Added option to align fallback range start to beginning of day
  • Improved fallback range behavior when no active energy period is available

---

Screenshot:

Before posting your module

• I've replaced all lines starting with ->
• I've updated the unsupported cards above the description and under the unsupported property
• I've added a screenshot
• I've chosen a unique your_module_key
• I really enjoyed working on this module ❤️