Equinox

Equinox is a custom Lovelace card for Home Assistant. It is designed for Versatile Thermostat while keeping compatibility with standard climate entities.

The project uses Lit, strict TypeScript, and Vite library mode. The Lovelace card is registered as:

type: custom:equinox-card

If Equinox is useful in your Home Assistant setup, you can support development on Buy Me a Coffee.

History Viewer

Equinox embeds @kipk/ha-better-history, a standalone Home Assistant history web component also available on GitHub. It powers the history dialog with multi-series charts, no-refetch view zoom, display modes, entity and attribute series support, and portable JSON export/import.

Installation

Equinox requires Home Assistant 2026.5 or newer.

Via HACS

1. Add this repository as a custom repository in HACS (type: Dashboard).
2. Install equinox from HACS.
3. Clear browser cache and reload Home Assistant.

Manual

1. Download equinox-card.js from the latest release.
2. Copy it to www/community/equinox/.
3. Add it as a Lovelace resource:

url: /local/community/equinox/equinox-card.js
type: module

Build

Install dependencies:

npm install

@kipk/ha-better-history is installed from npm and bundled into equinox-card.js. Equinox registers its embedded history component as <equinox-better-history> so local development can run alongside other cards that bundle different ha-better-history builds.

Build the distributable card:

npm run build

The generated Lovelace resource is a single file with everything bundled in:

dist/equinox-card.js
dist/equinox-card.js.gz

Translations, attribute units, and built-in Regulation dashboards are compiled directly into the JavaScript bundle — no external JSON files are needed at runtime. The .gz file is a precompressed copy for Home Assistant deployments that serve it when the browser advertises gzip support.

Vite 8 requires Node ^20.19.0 || >=22.12.0.

Home Assistant Resource

After building, expose dist/equinox-card.js to Home Assistant, then add it as a Lovelace resource:

url: /local/equinox-card.js
type: module

The exact /local/ path depends on where the built file is copied in the Home Assistant www/ directory.

In Home Assistant 2026.6 and newer, Equinox appears in the card picker suggestions when a climate entity is selected.

Example

type: custom:equinox-card
entity: climate.salon
name: Salon
power_entity: sensor.salon_puissance
humidity_entity: sensor.salon_humidity
theme: liquid_glow
display_mode: classic
primary_display: setpoint
card_background_color: "#20242a"
card_background_opacity: 92
disable_name: false
enable_lock: true
additional_dashboards: auto

Configuration

Climate mode customization

Use mode_customizations to override the label, Material Design icon, tone, or visibility of any mode exposed by the climate entity. Mode keys are case-sensitive and must exactly match the Home Assistant attribute value.

type: custom:equinox-card
entity: climate.living_room
mode_customizations:
  fan:
    "4":
      label: Strong
      icon: mdi:fan-speed-3
      tone: fan-high
  swing:
    custom_sweep:
      label: Sweep
      icon: mdi:arrow-oscillating
      tone: swing-on

The supported families are hvac, preset, fan, swing, and swing_horizontal. Each mode accepts label, icon (mdi:*), tone, and hidden. The visual editor provides Home Assistant's icon picker and exposes the valid tones for each family. The legacy hidden_hvac_modes and hidden_preset_modes options remain supported.

Option	Required	Default	Description
entity	yes	-	Climate entity to display. Must use the climate domain.
name	no	Entity friendly name	Display name; hidden in the editor when display_mode: thin.
power_entity	no	-	Sensor or input number for instant power, shown in the detailed power dialog.
humidity_entity	no	-	External humidity sensor when climate humidity is unavailable.
auto_start_stop_enable_entity	no	-	VTherm auto-start/stop enable switch. Shown in the visual editor only when the selected VTherm reports that the feature is configured.
auto_start_stop_stop_mode_entity	no	-	VTherm auto-start/stop stop-mode select. Its HA options determine whether off, fan_only, and dry are offered.
auto_fan_enable_entity	no	-	Enable switch for the VTherm auto-fan plugin. Shown in the visual editor only when the selected climate exposes auto_fan.
theme	no	liquid_glow	Visual theme: flat or liquid_glow.
display_mode	no	classic	Display format: classic, compact, or thin.
primary_display	no	setpoint	Main emphasis: setpoint or sensors; ignored in thin.
setpoint_selector	no	slider	Setpoint selector for classic/compact: slider opens the popup slider, buttons keeps the inline +/- selector. thin always uses the slider popup.
card_background_color	no	HA card background	CSS color for the card background, editable with the visual editor color picker. HVAC and preset selectors follow this surface.
card_background_opacity	no	100	Card background opacity from 0 to 100; lower values make the card more transparent.
disable_name	no	false	Hide the header name; hidden in the editor when display_mode: thin.
show_fan_mode	no	true	Show the fan mode selector when the climate entity supports fan modes.
show_swing_mode	no	true	Show the swing mode selector when the climate entity supports swing modes.
mode_customizations	no	-	Per-mode label, icon, tone, and visibility overrides for HVAC, preset, fan, and vertical/horizontal swing modes.
enable_lock	no	true	Enable lock UI when supported by VT.
additional_dashboards	no	auto	Regulation dashboard mode: auto, custom, or disabled.
state_icons_layout	no	horizontal	State icon layout for classic/compact: horizontal or vertical; thin is always horizontal.
show_power_value	no	true	Show the numeric percentage beside the valve/power gauge; set to false for the gauge alone.

For Versatile Thermostat entities, the main-card power indicator is a live percentage gauge: valve-controlled thermostats show valve_open_percent, while switch-controlled thermostats show power_percent. Clicking the gauge opens the detailed dialog and history. A configured power_entity is shown in that dialog but does not replace the regulation percentage on the main card. Set show_power_value: false to keep only the radial gauge on the card.

VTherm auto-start/stop and auto-fan

When a VTherm reports is_auto_start_stop_configured: true, Equinox displays an auto-start/stop control. Configure both related entities to make it writable:

type: custom:equinox-card
entity: climate.salon
auto_start_stop_enable_entity: switch.salon_enable_auto_start_stop
auto_start_stop_stop_mode_entity: select.salon_auto_start_stop_stop_mode

The popup adds a synthetic Disabled choice that turns off the switch. The other choices come directly from the select entity, so Equinox never offers fan_only or dry unless the VTherm equipment supports them. Without both entities, the current state remains visible but read-only.

Equinox also supports both auto-fan implementations:

• Legacy auto-fan keeps using versatile_thermostat.set_auto_fan_mode and the existing AUTO_FAN_MODES selector.
• The plugin is detected from the climate auto_fan attribute. It displays selected_fan_mode and reads enabled; configure its switch to make the control writable:

type: custom:equinox-card
entity: climate.salon
auto_fan_enable_entity: switch.salon_enable_auto_fan

These fields only appear in the visual editor when the selected VTherm exposes the corresponding capability. Hidden fields are preserved rather than removed silently. Equinox uses specific_states.hvac_mode_reason for the active-mode cause and falls back to the deprecated hvac_off_reason for older VTherm installations.

Regulation diagnostics are discovered automatically from the climate entity attribute specific_states.regulation_diagnostics when the thermostat algorithm publishes it.

Regulation Dashboard

Equinox can show a Regulation entry in the card menu. It opens a dedicated dashboard for the thermostat regulation algorithm with compact sections, values, statuses, progress bars, history graphs, and optional confirmed actions.

The additional_dashboards option controls this feature:

Value	Behavior
auto	Detects the regulation algorithm from the climate entity and loads the matching built-in dashboard. If no dashboard exists for the detected algorithm, the Regulation menu entry is hidden.
custom	Always shows the Regulation menu entry and loads /local/equinox/dash/custom.js. If the file is missing or invalid, the dialog shows a short error.
disabled	Hides Regulation completely.

Built-in dashboards currently include Smart PI and Hysteresis. Desktop uses a side section menu inside the dialog; mobile opens a single section directly or shows multi-section dashboards from the Equinox menu first.

For custom dashboards, JSON schema details, available block types, sources, conditions, history graph options, and actions, see Regulation Dashboard.

Dashboard sizing

Equinox declares Home Assistant dashboard sizing hints for both masonry and sections views. In sections view, the default grid height is automatic so the card follows its rendered content instead of forcing a fixed row count.

Development Notes

• User-visible text must go through src/localize/languages/{lang}.json (19 languages). The English file (en.json) is the reference; other languages fall back to it for missing keys.
• The card must remain compatible with a standard Home Assistant climate entity.
• VT-specific features are displayed only when the required data or capability is available.

Adding a language

1. Add src/localize/languages/{code}.json using en.json as a template.
2. Add the import and export entry in src/localize/languages/index.ts.
3. Add the language code to SUPPORTED_LANGUAGES in src/localize/loader.ts.
4. Add the card.description string to the CARD_DESCRIPTIONS map in src/equinox-card.ts.
5. Run npm run build — the new language file compiles into the single JS bundle automatically.