Adds new plugin [ReikanYsora/Helios]

[ReikanYsora]

Checklist

• I've read the publishing documentation.
• I've added the HACS action to my repository.
• (For integrations only) I've added the hassfest action to my repository.
• The actions are passing without any disabled checks in my repository.
• I've added a link to the action run on my repository below in the links section.
• I've created a new release of the repository after the validation actions were run successfully.

Links

Link to current release: https://github.com/ReikanYsora/Helios/releases/tag/v1.5.0
Link to successful HACS action (without the ignore key): https://github.com/ReikanYsora/Helios/actions/runs/25945285803
Link to successful hassfest action (if integration): N/A, this is a plugin (Lovelace card), not an integration

---

Hey HACS team,

I'd love to add HELIOS to the default catalog.

It's a Lovelace card I built to scratch a personal itch: I wanted to see, at a glance and in real time, how much sun was hitting my house, how the clouds were going to mess with that over the next few hours, and what my panels were doing about it. HELIOS is exactly that, on a 3D map of your home.

Since v1.5.0, the card ships with zero credentials to configure: basemap, sprites, glyphs and building tiles all come from OpenFreeMap (free, no key, no signup, no rate limit), weather from Open-Meteo (also free, no key), and LiDAR shadow data from national open-data programmes. A user can drop the card on a dashboard and have it render their home in 3D without filling in a single API key.

What the card does

Sun arc. The sun's full daily trajectory projected with depth onto the 3D map centred on the home. Split into two passes: below-horizon dots render behind the home chip cluster so the home reads cleanly through the night portion of the orbit; above-horizon arc + sun disc + W/m² readout render in front of every chip so the live sun always dominates the stack.

Live sun disc with irradiance-driven halo. Pinned on the arc at the current solar position. Four concentric layers: a soft halo (SVG radialGradient, 100 % alpha at the centre dropping cleanly to 0 % at the rim, peak alpha = sqrt(irradiance/1000) × 0.55), a faint background tint, an inner fill whose radius scales with irradiance, and an outer rim. Clear-sky noon radiates a visible aura while a cloudy / low-altitude sun stays compact.

Incidence ray. Dashed line from sun to PV chip, animated to flow at a speed proportional to live irradiance. Stronger sun, faster pulse. Snaps to the side of the PV chip that faces the sun.

Cloud-cover disc. Translucent disc on the ground centred on the home, scaled by the live cloud-cover percentage and outlined in the configured cloud colour. A fixed reference ring marks 100 %. Hovering opens a low/mid/high breakdown tooltip.

Effective cloud cover. Open-Meteo's raw cloud_cover is the satellite-view total; HELIOS replaces it with a ground-perception weighted blend (low + 0.6·mid + 0.2·high, clamped at 100 %) matching shortwave attenuation.

LiDAR-driven shadows (5 providers integrated; more on the roadmap). Where coverage exists, cast shadows reflect real buildings AND vegetation captured by aerial LiDAR. Five national providers integrated today: IGN HD (metropolitan France + Corsica), Defra (England), IGN España PNOA-LiDAR (peninsular Spain + Balearics), PDOK AHN4 (Netherlands), Kartverket NHM (Norway + Svalbard). Outside coverage, the card falls back to OpenFreeMap building footprints (buildings only). All shadows are rasterised onto a single offscreen canvas at the configured opacity, so overlapping clumps cannot saturate to black through alpha-compositing. The provider plug-in shape is a single-file drop documented in ARCHITECTURE.md; additional national programmes are picked up as their APIs become available with a CORS-friendly raw raster endpoint.

Multi-model weather fusion. Every fetch queries one global model (ECMWF IFS 0.25°) plus the most accurate national/regional model for the home location: AROME-France, UKMO UK, DWD ICON-D2, ItaliaMeteo, MET Nordic, NOAA HRRR, KMA LDPS, JMA MSM, BOM ACCESS-G, or ECMWF + GFS elsewhere. Per-timestep median fusion absorbs single-model outliers.

PV production chip (optional, pv-power-entity). A chip above the home shows the instantaneous production in W or kW. Cumulative-energy sensors (kWh) are differentiated automatically over a rolling 60 s window so the chip shows real instantaneous power, not a misleading lifetime total. A dedicated mirror chart appears above the irradiance / cloud timeline.

Manual PV peak power (optional, pv-peak-kwp). When set, the card overlays a dotted clear-sky forecast line on the PV chart (Haurwitz / Kasten-Czeplak scaled by the configured peak), and the PV chip flips to a predicted value (italicised, prefixed ≈) when the timeline is scrubbed into the future. Leave empty to hide the forecast; observed production and the daily peak still render.

PV → home animated leader. A vertical dashed line in the configured PV colour from the production chip down to a small anchor bead on the home; when pv-peak-kwp is set, dashes flow toward the home at a speed proportional to current production over the configured peak. Static and arrow-less when production is 0.

Home-battery overlay (optional, battery-soc-entity and/or battery-power-entity). State-of-Charge and signed instantaneous Power chips flank the PV chip, each connected to PV by an L-shaped leader whose foot lands at 25 % / 75 % of the PV chip's width. The Power leader's dashes flow with the sign of the live power (charging vs discharging). Either entity is independently optional; the corresponding chip only renders when its entity is set.

Click-the-home detail dashboard. Clicking the focal building triggers a camera dive (zoom + pitch ease) and fades a chip-styled overlay over the HUD with up to three sections that appear in sequence: Today (produced kWh, projected end-of-day total, peak-of-day time), Tomorrow (estimated kWh + expected peak hour from the multi-model forecast scaled by pv-peak-kwp), and Battery (live SoC + the day's charge / discharge totals integrated client-side from the battery power entity). Click anywhere outside to exit; the camera eases back to its pre-dive bearing and the HUD fades back in.

Hover home glow. Hovering the home triggers a soft sun-coloured halo underneath the silhouette so the focal building reads as interactive before the user clicks. Halo colour tracks the configured sun colour.

Timeline. 5 days wide (2 past + today + 2 forecast). Dual-area chart with irradiance on top and cloud cover below, sharing a midline that doubles as a date axis. A second chart for PV production appears above when a PV entity is configured. Daily kWh totals are surfaced under each date label. Click or drag anywhere to scrub; the entire map snaps to the selected instant, past or future.

Top corner overlays. Date/time chip top-LEFT mirrors the back-to-live button top-RIGHT, both with the same 8 px frame margin as the timeline. The clock chip flips to a blue scrub theme during a scrub and the back-to-live button is fused next to it; the LiDAR busy chip rides in the same column when both are active.

3D MapLibre basemap. Two styles served by OpenFreeMap (OpenMapTiles schema): streets (Liberty, full-colour vector basemap) and minimal (Positron, muted grey, very sober for low-end devices). Both flip to OpenFreeMap's Fiord style when card-theme: 'dark', so the card sits cleanly inside light or dark Home Assistant dashboards.

Self-sourced building rendering. The card fetches OpenFreeMap planet vector tiles around the home directly (snapshot URL resolved once via the public /planet TileJSON, cached for the page lifetime), decodes them with @mapbox/vector-tile, splits MultiPolygons that group unrelated buildings, and renders only buildings within a configurable radius. Two layers: the home (full opacity) and the surroundings (configurable opacity). Stroke outlines keep footprints legible at low opacity. A building-cluster-radius setting lets attached verandas, garages and sheds join the home group at full opacity, so the home reads as one structure. Building colour is configurable and modulated by sun altitude through the day.

Pixel ratio. A pixel-ratio toggle replaces the older performance-mode switch. auto (default) uses the device's native devicePixelRatio capped at 2 on desktop / 1.25 on mobile for crisp rendering; 1x forces 1.0 for the cheapest per-frame fragment workload, useful on low-end devices or for long sessions where battery / heat matters more than crispness.

Auto-rotation (opt-in). When enabled, the camera slowly orbits the home in the opposite direction to the sun's apparent motion (~1°/s) after a few seconds of inactivity. Any pinch / drag / wheel pauses it for a few seconds; it resumes from the user's bearing. Custom single-pointer rotation handler so single-finger touch rotates cleanly on mobile (touch-action: none on the canvas, direction inverted so the map follows the gesture). Off by default; opt in for kiosk dashboards.

Animation perf and accessibility. An IntersectionObserver pauses every CSS animation and SVG SMIL animation when the card scrolls out of the viewport. The browser's prefers-reduced-motion setting disables every Helios animation and transition.

Memory and stability hardening. Engine init is debounced by 500 ms so ephemeral Home Assistant dashboard-editor preview cards never spawn a MapLibre engine or claim a WebGL context. A module-level cap on live engine instances force-cleans the oldest when needed. Canvas listeners are detached on cleanup; the WebGL context is force-released via WEBGL_lose_context.loseContext() after map.remove(); the map container is drained of leftover canvas nodes before each engine re-init. Solves the FPS drift that compounded across editor re-inits on long-lived dashboards and the Safari mobile WebGL context cap.

Solar math. Solar position is NOAA-validated (mean altitude error 0.30°, mean azimuth error 0.36° across 376 sample points). Clear-sky GHI from Haurwitz (1945): 1098 · cos(z) · exp(-0.059 / cos(z)) W/m² (MAE ~62 W/m² versus PVGIS / NREL benchmarks). Cloud attenuation from Kasten-Czeplak (1980) cubic: 1 - 0.75 · (cloud/100)^3.4.

Diagnostics. window.heliosStats() returns + prints a snapshot of every live <helios-card> on the page: full config (no API keys are ever stored, so the snapshot is safe to paste publicly), engine state (resolved LiDAR provider, shadow source, building / weather / cache counters), PV history, and lifecycle counters. Companion helpers window.setHeliosLocation(lat, lon) and window.clearHeliosLocation() override Home Assistant's home coordinates at runtime (non-persistent, refresh restores the user's home) for reproducing user-reported visual issues without touching HA's config.

Visual editor. Every option is editable visually via a custom card editor; numeric options are sliders so out-of-range values can't be entered. Slider input is debounced (250 ms) before the engine sees the value, so dragging doesn't cascade per-pixel re-renders.

Multilingual. 8 locales: English, French, German, Spanish, Italian, Dutch, Portuguese, Norwegian. Adapts to the Home Assistant locale. French follows local typographic conventions (non-breaking spaces before :, ;, ?, !).

Engineering side

Three GitHub Actions are wired up so the project stays compliant with HACS expectations on every push, every PR, and on a nightly cron:

• HACS validation, runs the official hacs/action@main with category: plugin, exactly as documented.
• Tests, typecheck + tests + production build, with an explicit guard that fails the run if dist/helios.js isn't produced (so a release can never end up missing its artifact).
• Attach helios.js to release, on every published release, rebuilds dist/helios.js and uploads it as a release asset.

The current release has the built helios.js attached, the hacs.json manifest is in place (render_readme: true, minimum HA 2024.4.0, HACS 1.32.0), the LICENSE is MIT, and the README has screenshots and a full configuration table.

• Repo: https://github.com/ReikanYsora/Helios
• Release: https://github.com/ReikanYsora/Helios/releases/tag/v1.5.0
• Latest validation run (green): https://github.com/ReikanYsora/Helios/actions/workflows/validate.yml

Thank you for everything you do for this catalog, it's genuinely an honour to be asking to join it. Happy to address anything you'd like changed.

Jérôme

[hacs-bot]

Thank you for submitting your repository to HACS (Home Assistant Community Store).

Your submission is in the review queue:
Your repository is waiting to be reviewed and included in HACS.

You can view the current queue here. Pull requests are processed in the order they were created, oldest first.

What to avoid during review:
To help reviewers work efficiently, don't do the following:

• Comment on the pull request - The reviewer will contact you when they have feedback or questions.
• Open a new pull request - This won't speed up the process and creates duplicate work.
• Ask followers to comment on the pull request - This won't speed up the process and may delay your review.
• Merge in the default branch - Only do this if a maintainer asks you to resolve a merge conflict.

If you need to make changes:
You can continue updating your repository while waiting for review. Changes to your repository will be reflected when the reviewer examines it. Only comment on the pull request if you need to withdraw your submission or have critical information for reviewers.

About draft pull requests:
Draft pull requests aren't included in the review queue. Your pull request may be marked as draft by a reviewer if issues need to be addressed. Once you've resolved all issues, mark it as ready for review to re-enter the queue.

What happens next:
Once a reviewer examines your submission, they'll either:

• Approve and merge your pull request if everything meets the requirements
• Request changes or ask questions if adjustments are needed