Data Sources

Data Sources give cards access to entity history, real-time updates, and processed values — beyond the plain current state that HA cards normally see.

---

What They Do

A data source subscribes to an entity, optionally preloads history, and runs values through a processing pipeline. Results are available in templates as {ds:name} or as chart series.

---

Basic Usage

Define data_sources on any card. Each key is a name you choose:

data_sources:
  temp:
    entity: sensor.temperature
    history:
      hours: 6

Use in a text template:

text:
  value:
    content: "{ds:temp}"         # HA-native: locale-formatted + unit → "4,7 °C"
    # content: "{ds:temp:.1f} °C"  # explicit precision + unit suffix

Use as a chart series:

type: custom:lcards-chart
data_sources:
  temp:
    entity: sensor.temperature
source: temp
chart_type: area

---

Configuration Options

data_sources:
  my_source:
    entity: sensor.power_usage      # Required — entity to track
    attribute: current              # Optional — track attribute instead of state
    windowSeconds: 120              # Rolling buffer window size in seconds (default: 60)
    minEmitMs: 500                  # Min ms between updates emitted downstream (default: 100)
    history:
      hours: 24                     # Preload history (1–168 hours)
    processing:
      # Named processors — each stores results in its own buffer
      kilowatts:
        type: scale
        input_range: [0, 1000]
        output_range: [0, 1]
      smoothed:
        type: smooth
        from: kilowatts             # Chain from previous processor
        method: exponential
        alpha: 0.3
      rounded:
        type: round
        from: smoothed
        precision: 2

Top-Level Fields

Field	Type	Description
entity	string	Entity ID to subscribe to
attribute	string	Attribute to track instead of state
windowSeconds	number	Rolling buffer window size in seconds (default: 60)
minEmitMs	number	Min ms between downstream updates (throttle, default: 100)
history.hours	number	Hours of history to preload (1–168)
processing	object	Named processing pipeline steps

---

Processors

Each processor transforms data and stores results under its name. Processors can be chained with from.

Processor	Purpose	Key params
convert_unit	Convert between unit types	from, to (e.g. c/f)
scale	Map from one range to another	input_range, output_range
smooth	Smooth noisy values	method (exponential, moving_avg), alpha, window
round	Round to decimal places	precision
expression	Custom JS expression	expression (uses value, history)
clamp	Clamp to min/max	min, max
rate	Rate of change per unit time	period
trend	Linear trend direction	—
delta	Difference from previous value	—
duration	Time spent meeting a condition	condition, reset_on
statistics	Min/max/avg/std over window	window
threshold	On/off based on threshold	above, below

processing:
  # Convert Celsius to Fahrenheit
  fahrenheit:
    type: convert_unit
    from: c
    to: f

  # Smooth the converted value
  smooth_f:
    type: smooth
    from: fahrenheit
    method: exponential
    alpha: 0.2

---

Accessing Values in Templates

# No format spec — HA-native: locale-formatted number + unit from entity metadata
"{ds:temp}"                          # → "4,73 °C"  (locale + unit)

# With format spec — you own the output: number only, no auto-unit
"{ds:temp:.1f}"                      # → "4,7"  (1 decimal, no unit)
"{ds:temp:.0f}"                      # → "5"    (integer, no unit)
"{ds:temp:.1f} °C"                   # → "4,7 °C"  (explicit unit suffix)

# From a specific processor buffer
"{datasource:temp.fahrenheit:.0f} °F"  # → "87 °F"

Rule: no format spec → HA displays it (locale + unit). With a spec → you control the output.

---

Data Sources in Charts

For chart series, use buffer to select which data series to plot:

sources:
  - datasource: temp
    buffer: main           # Raw entity history (default)
  - datasource: temp
    buffer: smoothed       # From 'smoothed' processor

See the Chart card for full sources configuration.