[Custom Card] Helios, real-time 3D sun, clouds, PV production and LiDAR shadows on your home

Share your Projects! Dashboards & Frontend
, , , ,
1

[Custom Card] Helios, real-time 3D sun, clouds, PV production and LiDAR shadows on your home

Hi everyone,

I'm Jérôme, 44, a developer by trade (with a 3D background notably), and I've been using Home Assistant for several years to run my home, like a lot of you here. This community has given me a tremendous amount over time: the forums, the custom cards, the integrations shared without asking anything in return. After consuming for years without giving anything back, I felt it was time to contribute in return. Helios is my way of doing that, a project I'd been carrying around in the back of my head for months before I finally pulled the trigger a few weeks ago.

I wanted this project to take a different approach from the other solar cards in the ecosystem. Not yet another card with numbers stacked in columns: I wanted a lightweight, polished 3D scene, where every piece of information shown is actually relevant, where nothing is there just to look pretty without a reason. Something interactive, playful, pleasant to leave running on a wall-mounted tablet, that makes you want to look at your solar setup instead of just checking kWh when you remember to. 3D is what I do for a living, I wanted to put it to use for this rather than for another client project.

I wanted to introduce the project properly: it just shipped its 1.6.3 stable release. It already found its audience on Reddit over the past two weeks and has a few hundred active installs, but this is my first time here, so I wanted to introduce it the right way.

In two sentences

Helios renders your home on a 3D map and projects the sun, clouds, real shadows from surrounding buildings and trees (via aerial LiDAR where available), your PV production and a forecast calibrated against your actual install, plus a scrubbable 5-day timeline to replay or look ahead, all in real time. No API key to configure, no account to create, everything comes from free public sources: OpenFreeMap for the basemap, Open-Meteo for weather, national LiDAR portals for the shadows.

preview_01
preview_01500×504 74 KB

What it actually does

You have PV. You look at your dashboard. You see production as numbers but you have no context. Helios gives you that context:

  • Your home in 3D at the centre, with the sun moving along its daily arc (NOAA-validated math, mean altitude error 0.3°)
  • Shadows cast by surrounding buildings and trees, computed from real aerial LiDAR data. If a neighbour's tree is going to block your sun in 30 minutes, you see it coming before it happens.
  • Cloud cover represented as a translucent disc resting on the ground around your home
  • If you've entered your peak power per string and the layout of your panels (one or more, different orientations), a forecast curve that automatically calibrates against your actual production over the last 5 days (a Solcast sensor is great, but it costs money and it doesn't know about that neighbour's tree of yours)
  • A timeline from the day after tomorrow back to yesterday that you can grab and drag to replay or look ahead. The home, the shadows, the predicted PV, everything follows.
  • A detail dashboard on a click on the home: kWh produced today, predicted vs actual, peak hour, battery, tomorrow's forecast

Stability, where the project stands

I shipped 1.6.0 two weeks ago on r/homeassistant. Since then:

  • 1.6.3 just shipped, that's the 16th iteration (15 betas to harden it, the cadence is settling now)
  • A few hundred active installs
  • 3 external contributors have already pushed code (multi-array PV, LiDAR tooling, US sources)
  • A dozen issues, all constructive, dealt with quickly
  • A PR to add Helios to the HACS default catalog is in the review queue, install meanwhile goes through "Custom repository"
  • The project got its first spontaneous donation yesterday, which made me genuinely happy

Tested on Chromium, Firefox, Safari, iOS Safari, Android Chrome. The MapLibre 3D scene needs a decent GPU (no issue on any recent PC or smartphone, can be heavy on older tablets).

helios-lidar.org, the companion site

Helios has 13 LiDAR providers integrated natively: France IGN HD, England Defra, Spain PNOA, Netherlands AHN, Norway NHM, Germany (NRW, Brandenburg+Berlin, Baden-Württemberg), Poland GUGiK, Canada NRCan, Austria (Styria, Tyrol), USA Vermont. That's already a lot, that's not the whole world.

For the other regions, I built a companion site: helios-lidar.org. You drop your raw LAZ file (downloaded from your country's open-data portal), the site does the full GIS conversion server-side (reprojection to metric UTM, nDSM computation, 2-band COG output with nDSM + DTM for proper terrain handling), and gives you back a file ready to drop into config/www/helios/ along with the YAML snippet to paste into your card. Free, no account, no signup. Hosted on a VPS I pay for out of my own pocket.

Install

For now via HACS as a custom repository (https://github.com/ReikanYsora/Helios), until the default-catalog PR is processed. Once merged, "HELIOS" will show up in the standard HACS list, one-click install.

Minimum config: literally nothing. The card runs fine without any PV entity at all if you just want the 3D scene with the sun, the clouds and the LiDAR shadows on your home.

​yaml type: custom:helios-card ​

And if YAML is not your thing, all of the above is also exposed through a full visual editor in HA's card picker: dropdown for the PV entity, sliders for tilt and azimuth, add/remove panel strings, battery setup, theme, LiDAR precision, opacities, colours, the whole lot. You tick/pick what you need in the form, the editor generates the matching YAML in the background. Live preview on the right as you change values.

Why I'm writing here

I wanted the card to be stable before knocking on this community's door. Now that it is, I'd really appreciate your feedback, especially on:

  • The bugs on configurations I couldn't test myself
  • The LiDAR providers you'd like to see integrated (your country/region, if you know where the open-data lives)
  • The PV / battery sensors whose unit or format diverges from what the card expects
  • The perf on your setups (tablets, older phones, dashboards stacked with 6 cards)

Thanks in advance for any feedback, and have a great day.

Jérôme :slight_smile:

10 Likes
2

preview_02
preview_02500×504 95.1 KB

And the LiDAR view ! ;D

1 Like
3

I've installed this, and put it in a dedicated Dashboard.

I must say, there is A LOT to tweak, so it will be A WHILE before I can discover all nooks and crannies. But that's not a bad thing, quite the contrary.

My location isn't supported, but I did find where to get the required data, so a quick download, upload, and download, and I have the data available on my HA instance. NEAT!

The data for Portugal can be found here Interactive Map | Geospatial Data Viewer by DGT. However, you must apparently register an account to be able to download data, not sure if it's something you'd be willing to do to add support for your card.

A couple of things I'd like to see done differently, if I may:

  • Place the battery charge/discharge information just below the battery charge indicator. Right now it feels like they are referring to two different entities, when they're not;
  • Allow the card to occupy more vertical space. Right now it fills about 50% of the available page, I'd like to have it fill more of it.

No bugs found so far, will open an issue on GitHub if that changes.

Thank you very much for your work on this!

2 Likes
4

Hello,

First of all, thank you for installing and testing my card, it really means a lot to me.

Regarding your feedback:

  • Yes, unfortunately I haven't found a free LiDAR API without an account for Helios's built-in provider for Portugal, but I'm glad that the alternative solution I set up allowed you to get there. I'm indeed quite uncomfortable with the idea that my card requires API keys to work. That said, it doesn't bother me at all when it comes to generating your LiDAR map from Helios-lidar.org. I'm going to add your solution to the file that lists all the countries so that future Portuguese users can easily find the information.
  • I was actually planning to rework the design of the battery/production section in 1.7, since I also intend to add grid export/import. This will be the perfect opportunity to slightly redesign these elements.
  • Noted regarding the vertical limit, I'll see what I can do, I'm adding it to my backlog.

In any case, thank you for everything and see you soon :slight_smile:

Jérôme

2 Likes
5

I kind of understand why the Portuguese authority decided not to have an API (both local and central governments are grossly understaffed in the IT area, and woefully over capacity in anything server-related, so supporting API requests would be... interesting at best).

At the same time, putting the data behind a required registry seems unnecessary.

A quick look seems to indicate that you might possibly be able to map all sections of the LAZ to their corresponding download files, but that would be hacky AF, and it would break as soon as a section were to be updated on the server side, so not ideal.

As someone who never heard about LAZ LiDAR maps before today, finding the data was fairly straightforward, and getting hold of the relevant file was easy enough that I don't feel that not having direct access through the card is cumbersome.

The only downside is that for Portugal the smallest file you can download is ~130MB, but unless you're at the edge of 4 chunks, downloading and uploading those files shouldn't be too taxing.

1 Like
6

Hi Jérôme and thanks for your amazing card!
I'm from Italy and for my country the LiDAR data can be downloaded at this portal:https://sim.mase.gov.it/portalediaccesso/mappe/#/viewer/new
Not all of the country is mapped but I hope they will complete the work in the future.
If you have time, take a look at it and include it in the instructions for the various countries.
I have a question for you:
When I download the DSM data, I get two versions: first and last gridded.

Immagine 2026-05-26 135100
Immagine 2026-05-26 135100862×479 67.2 KB

I think the first gridded one is for first laser points detections (high buildings etc), the last gridded is for point where laser reach the surface. I hope I understood the difference.
Which of the two values ​​(first or last) should I enter as DSM data in your companion site?

Anyway sorry for the specific question and thanks again for the great work

1 Like
7

HI !

Thank you so much for your kind words, honestly messages like yours are exactly what keeps me motivated to maintain this project. And thank you even more for the Italian LiDAR portal, that's incredibly helpful. I'm going to add Italy and this source to the country list on the site so other Italian users can benefit from it too. Really, thank you.

Now, about your question, you actually understood the difference perfectly. The "first" version captures the top of everything (roofs, treetops, the highest thing the laser hits), while the "last" version captures the lowest points the laser reaches, closer to the ground.

For Helios, you want the "first" one as your DSM. That's the file that describes how tall the buildings and trees actually are, which is exactly what the card needs to draw the shadows correctly.

One thing worth checking: ideally Helios works best when you also have a proper ground-level model (a DTM, the bare-earth version). If the Italian portal offers a separate terrain model somewhere, grab that too and use the "DSM + DTM" mode, you'll get the cleanest result. If only those two DSM files are available, you can use "first" as the DSM and "last" as the DTM as a workaround, it won't be perfect but it usually works fine on flat, open areas.

I'm just getting home from a (too) long day at work, I really wanted to reply to you but I haven't been able to test it yet. I'll do it tomorrow without fail and get back to you quickly to confirm :slight_smile:

And please don't apologize for the question, it was a great one.

Thanks again for the portal and for the support, it genuinely means a lot.

2 Likes
8

Well, I did give it a try... but I can't manage to get a usable map.

Could you email me (you'll find the link at the bottom of the page on my website) a LiDAR map of somewhere other than where you live? There's something I can't figure out about the format of the file I'm getting, as if the download isn't working properly from France.

Thanks in advance :slight_smile:

9

Thank you Jérôme for the detailed reply.
Fortunately, I noticed that from the Italian site, in addition to the data in DSM format, I can also download the data in DTM format for the same area, so I don't need to use "last gridded DSM data" as a DTM workaround. I will test "DSM + DTM" mode as soon as possible and I'll keep you updated.
You're really helpful, take your time. I understand that it's hard to pay attention to the forum after a day at work. Don't worry, you're already doing a lot. :slightly_smiling_face:

1 Like
10

Hello !

Thanks for this really interesting card !

I'm facing an issue within my dashboard. The card is quite black :

Capture d’écran 2026-05-27 à 13.55.13
Capture d’écran 2026-05-27 à 13.55.13800×980 98.1 KB

I can see the house when my mouse is over the card.

Capture d’écran 2026-05-27 à 13.55.23
Capture d’écran 2026-05-27 à 13.55.23800×976 24.3 KB

I'm in France so LIDAR should be avaiblable, right ?

Thanks a lot

1 Like
11

Hi !

First off, thank you for trying Helios.

What you're seeing is a bug I've already identified and fixed two days ago.
The basemap stays black when the card is placed inside a Masonry dashboard layout (the default layout type in newer HA installs).

The reason is technical : Masonry mounts the card container with zero dimensions and resizes it on a later frame. MapLibre initialises against that 0-by-0 container, creates its WebGL context fine, but its tile manager decides there's nothing visible and never fetches any basemap tile.
The custom layers (sun arc, LiDAR shadows, building extrusions) keep rendering on top.

Two ways forward :

Option A , wait for 1.7.0 stable. The fix is in v1.7.0-alpha.15 (available in HACS if you select a specific version to download). I'm working hard on 1.7.0 right now and it should land as stable in one to two weeks. If you don't mind running the alpha, install it and the black map will be gone.

Option B , use a different dashboard layout in the meantime. If you'd rather stay on the 1.6.4 stable, the workaround is to put Helios in a dashboard view that uses the Sections layout, or the legacy Sidebar layout, or set the whole view to Panel mode. Any of these will mount the card with proper dimensions from the first frame and the basemap will load normally. You can do that by going to the view's settings (the pencil icon at the top of the dashboard, then "View configuration") and changing the "View type" dropdown.

And to answer your other question : yes, France is fully covered out of the box. The card pulls IGN LiDAR-HD data automatically based on your home location set in HA. Once the black-map issue is gone, you should see real shadows from the buildings and trees around your house. I'm French too :wink:

Let me know if either workaround works for you, and thanks again for the patience.

Jérôme

Edit: My bad... My fix doesn't work in the alpha version. I'm working on it :s

2 Likes
12

Fix in 1.7.0-alpha.21 :smiley:

13

Great job ! I figured it out that you're French :wink:

Thanks for the reply, I'll stay in 1.6 and I'll switch to Sections :wink:

Have a nice (hot) day !

1 Like
14

1.7.0 is out !

You can update it now if you want :wink:

2 Likes
15

Crazy work, amazing! As you said somewhere on the website, the context is/was missing for PV production, now thanks to your card that is not the case anymore!

1 Like
16

Thanks :wink:

Version 1.8.0 has been released.

I had to speed things up because of a major performance issue I was having with version 1.7.0.

I sincerely apologize for the problem. So I worked tirelessly to release the content I had planned for version 1.8.0, along with all the fixes, so that users of my card wouldn’t have to deal with this issue for too long.
I had to reorder some topics on my internal roadmap to make this happen.
I sincerely apologize for the performance issues that I should have detected before the release; I’ve implemented plenty of safeguards to prevent this from happening again.

At least you get to enjoy the new 1.8.0 design sooner than expected :slight_smile:

See you soon, and thanks again

Jérôme

1 Like
17

You did here an amazing job. Thanks a lot for this nice card. This is a luxurary problem, but is it planned that other weather provider service apart from Meteo can be used?

18

Not for now, because I wanted to use all the free and open-source services available to me to create this card. That's why I went with OpenMeteo.

May I ask why you'd like that? Do you find OpenMeteo isn't reliable enough?

Thanks in any case for your feedback :slight_smile: