HELIOS

HELIOS is a custom Home Assistant Lovelace card that turns your solar setup into a living 3D view of your home, the sun and the weather, all in real time and right inside your dashboard.

It reads your solar, grid and battery wiring straight from the Home Assistant Energy dashboard, pulls a multi-model weather forecast from Open-Meteo (no key), and stitches both onto a tilted, rotatable map of your home. The sun's daily arc, the live sun disc, the incidence ray, the production / battery / grid chips and the cast shadows all follow a timeline you can scrub days into the past or the future, watching every layer move with it.

The scene is drawn by a self-contained 2.5D engine with no WebGL: a tilted raster basemap with every overlay (buildings, shadows, sun arc, chips and leaders) projected on top in SVG, so the card stays light and fluid on any device, phone included. Basemap tiles come from CARTO (free, no key), themed light or dark to match Home Assistant.

Website + live demo: explore the full card, the documentation and the public roadmap at helios-ha.org.

At a glance

Helios has three view modes, switched from the round buttons in the top-left corner.

Scene mode, the live 3D view

• Sun arc, the sun's full daily trajectory projected with depth onto your home. The below-horizon portion renders as discreet dots behind the home so it reads as a calm background, while the daylight portion, the sun disc and the irradiance readout always stack on top.
• Live sun disc + irradiance halo, pinned on the arc; the inner fill scales with the live W/m², a soft sun-coloured halo fades from the centre out.
• Incidence ray, a dashed line from the sun to the home, animated to flow faster the stronger the sun.
• Sunrise / sunset markers, placed where the arc crosses the horizon, with the local time (hidden in polar day / night where there is no crossing).
• PV production chip + leader + bead (when the solar source has a live power sensor), shows the measured instantaneous production; a bead rides the leader to the home at a speed proportional to current output.
• Battery chips (when a battery is configured), state of charge and signed instantaneous power, with a bead whose direction follows charge / discharge.
• Grid chip + leader + bead (when a grid source is configured), the active import / export flow, with a bead whose direction and speed track the power.
• Custom entity chip (optional), pick a power sensor AND an energy meter in the editor and Helios surfaces them as an extra chip top-left, with a leader to the home and a bead that flows with the value's sign.
• Home pill, the hub the chip cluster orbits, showing the live home consumption balance (the energy dashboard's own definition) once every configured family has its live sensor. Click any chip (or the home) to point the timeline at that metric; the home pill even grows a per-source stacked column when several solar sources are configured.
• Cast ground shadows, projected from the surrounding building footprints, fading as the sun nears the horizon. Toggle and opacity are configurable.
• Day / night ground, the ground darkens where the sun is below the horizon, so dawn and dusk read at a glance.
• Hover glow + auto-rotation, a soft halo signals the home is interactive; an opt-in idle orbit slowly turns the scene counter to the sun's motion and pauses the moment you touch the card.
• Timeline, the active period as a re-targetable chart below the scene: production (with dashed forecast and per-string breakdown), consumption, grid, battery, battery SoC, irradiance (with the cloud layers overlaid) or your custom entity. Click or drag to scrub; the whole scene snaps to the selected instant.
• Detail panels, double-tap (or double-click) any chip to open a compact readout top-right, tinted in that chip's colour: it aggregates the metric over the selected window as icon-only figures, all in your chosen unit. Production / consumption show total, peak and per-day average; grid shows import, export and net; battery shows energy charged and discharged; battery SoC and the custom entity show min / average / max; the sun shows peak and average irradiance plus the astronomy (sunrise, solar noon, sunset, max altitude, day length). Double-tap again to close.
• No UI mode (optional), fades the timeline and the on-card controls after a few seconds of inactivity and brings them back on any tap or move. Built for kiosks and wall displays.

Clock mode, the 24-hour dial

A radial instrument that bins each metric into 24 hours of the day and stands a ring of cylinders around the flat Helios mark at the centre, one bar per hour. The right-hand rail toggles metrics as filters: each active metric adds its own concentric ring (production, consumption, battery SoC, battery, grid, irradiance, custom). Hover or tap a slice to light up that hour across every ring and read each metric's value in the tooltip; hover or tap the centre mark for the period total. A soft day / night wedge on the ground shows when the sun is up over the period, and an N / S compass keeps the dial legible as it rotates with the scene.

Trend mode, the period-over-period comparison

A radial comparison of one metric, hour by hour: the current period stands as a ring of bars while a floating marker and stem pin the same hour in the previous comparable period, so you read instantly whether each hour is up or down. Bars are coloured good or bad depending on the metric (more production is good, more grid import is not). An arrow with a drop line marks the current hour, the flat Helios mark sits at the centre (hover or tap it for the period total), and the same day / night wedge grounds the dial.

Multilingual

Helios follows your Home Assistant language, with 63 languages translated today.

Screenshots

HELIOS displaying current solar exposure, cloud coverage and live PV production for the user's home. An interactive live demo is available at helios-ha.org.

Support my work

Helios is built and maintained by one person, in the open. If it helps your daily routine, a star on GitHub or a small coffee keeps the project alive and lets me keep pushing on the next cycle. Upcoming work is tracked live on the public roadmap at helios-ha.org.

Installation via HACS

Helios is available directly in the HACS store.

1. Open HACS.
2. Search for HELIOS.
3. Install it.
4. Reload your browser.
5. Add the card to your dashboard (see Adding the card to a dashboard).

Manual installation

1. Download helios.js from the latest release.
2. Copy it to <config>/www/community/helios/.
3. Add the resource to your dashboard:

   url: /local/community/helios/helios.js
   type: module

Adding the card to a dashboard

1. Open the dashboard where you want the card and click the pencil icon (Edit dashboard) in the top right.
2. Click + Add card.
3. Search for Helios in the card picker and select it. Or scroll to the bottom, pick Manual, and paste:

   type: custom:helios-card

4. Save. Helios picks up your Energy dashboard configuration automatically, no other setup is required.

If Helios does not appear in the picker, the resource is probably not loaded. With a HACS install it is registered automatically. For a manual install, go to Settings then Dashboards, open the three-dot menu, choose Resources, and add the resource as described above, then hard-refresh your browser.

Configuration

No API key required. The basemap is served by CARTO (free, no key) and weather comes from Open-Meteo (also free, no key).

Solar, grid and battery wiring is not configured per-card: Helios resolves every entity slot from the HA Energy dashboard (Settings then Dashboards then Energy), the same global config the official Energy card reads. Set the slots there once and Helios picks them up automatically. The options below cover only the visual and install-specific bits.

Where do the numbers come from

Helios follows the energy dashboard at 100% and never estimates a value:

• Live chips (real-time values in the scene) read the live power sensors of your energy dashboard sources: the optional "power" field of each source. If a source has no live power sensor, its chip is simply not shown, and the editor's live-data panel tells you what to add. Nothing is ever derived from cumulative meters to fake a "now" value.
• Curves, scrub, energy clock and totals read your kWh meters through the recorder statistics, the exact data the energy dashboard's bars are made of. Where the dashboard has a number, Helios shows the same number.
• Home consumption is the dashboard's own balance (solar + import - export
  • battery), computed live from the live sensors, shown once every configured family has one.
• If the grid's live sensor is detected as mis-wired (for example an import-only sensor configured as a signed net sensor), Helios hides the grid chips and the editor explains what to fix, instead of showing values that cannot be trusted.

So: a visible chip is always a real-time measurement; a curve is always your official meter data. If a chip you expect is missing, open the editor: the live-data panel lists, family by family, what your dashboard provides and what is missing.

Minimal config:

type: custom:helios-card

The visual editor exposes every option below. Direct YAML editing also works.

Home location

Camera

The card also remembers the live camera pose, the active mode, the selected clock filters and the lock per home (or per cache-id), so reopening the dashboard restores exactly what you left.

Interface

Buildings + shadows

Data display

The rolling window itself is chosen live from the timeline's period selector (Standard, Today, Week, Month, Year) and remembered per card; it needs no YAML key.

Sensors + colors

Per-card cache

How it works

• Solar position, a compact declination + equation-of-time model with hour-angle normalisation so longitudes far from Greenwich stay correct, validated against the NOAA reference.
• Clear-sky GHI, Haurwitz (1945), 1098 * cos(z) * exp(-0.059 / cos(z)) W/m², attenuated by cloud via Kasten-Czeplak (1980).
• Effective cloud cover, Helios replaces Open-Meteo's raw total cloud_cover with low + 0.6*mid + 0.2*high (capped at 100 %), which matches ground perception and shortwave attenuation better.
• Multi-model weather, every fetch fuses a global model (ECMWF IFS) with the most accurate regional model for your location, taking the per-timestep median so a single-model outlier cannot skew the curve. Cached in the browser, with exponential back-off on rate limits.
• Energy from the HA Energy dashboard, the single source of truth for every solar / grid / battery number. Live chips read the configured rate sensors (or differentiate a cumulative meter to watts); the timeline's past curves read the recorder's pre-computed change metric, the exact numbers the official Energy dashboard shows, so the two surfaces agree to the watt-hour.
• PV forecast, read natively from the HA Energy dashboard's configured solar-forecast provider and drawn as the dashed prediction the live observation tracks against; scrubbing into the future flips the PV chip to the predicted figure.
• Buildings, fetched once from OpenStreetMap (via OpenFreeMap vector tiles), interpreted in the browser (height cap or fixed prism, radius / count / cluster filters) and cached locally, so the scene spins up offline on the next load.

Full algorithm + architecture details: see ARCHITECTURE.md. Per-release notes: see CHANGELOG.md.

Technical stack

Development

npm install
npm run dev        # local dev server
npm run typecheck  # strict TS
npm run build      # produces dist/helios.js

The card is TypeScript-first and fully self-contained, a single helios.js bundle with no runtime dependency beyond Lit.

Source layout:

See ARCHITECTURE.md for the subsystem-by-subsystem walkthrough.

Credits & data sources

HELIOS depends on several open data services. None require an account or API key.

• CARTO, the free raster basemap tiles (light / dark, no labels) the scene is built on.
• OpenStreetMap, the map data behind the basemap and the building footprints (served as vector tiles by OpenFreeMap). © OpenStreetMap contributors.
• Open-Meteo, weather forecasts (cloud cover, irradiance). Free, no key, multi-model fusion under the hood.
• Home Assistant Energy dashboard, the single source of truth for solar / grid / battery wiring.

A heartfelt thank you to every user who tried Helios, filed an issue, suggested an idea or simply shared a screenshot. Your feedback is what shaped the direction the card has taken.

About me

I build bridges between data and reality. To me, development is more than a profession; it is the tool I have used since childhood to try and decode the complexity of the world around me. I learn every day, fully aware that total understanding is an infinite horizon I will likely never reach, but the journey is worth it.

License

HELIOS, solar conditions visualisation card for Home Assistant. Copyright (C) 2026 Jérôme Crémoux (ReikanYsora).

This project is licensed under the GNU General Public License v3.0, see the LICENSE file for details.