# Home Assistant Integration: __evcc☀️🚘- Solar Charging__ (unofficial) ![ha-logo](https://github.com/marq24/ha-evcc/raw/main/logo-ha.png)  ![evcc-logo](https://github.com/marq24/ha-evcc/raw/main/logo.png) I was surprised that it looks like that there does not exist a simple Home Assistant integration for the very popular evcc. So before my first EV spawned at my driveway, I wanted to contribute a very simple and basic integration that allows you to control evcc objects simply via the default HA gui and use sensors and switches in your automations. __Please note__, _that this Home Assistant integration is not official and not supported by the evcc developers. I am not affiliated with evcc in any way. This integration is based on the evcc API and the evcc API documentation._ [![hacs_badge][hacsbadge]][hacs] [![hainstall][hainstallbadge]][hainstall] [![Wero][werobadge]][wero] [![wise][wisebadge]][wise] [![Revolut][revolutbadge]][revolut] [![PayPal][paypalbadge]][paypal] [![github][ghsbadge]][ghs] [![BuyMeCoffee][buymecoffeebadge]][buymecoffee] ## Disclaimer Please be aware that we are developing this integration to the best of our knowledge and belief, but can't give a guarantee. Therefore, use this integration **at your own risk**. ## Requirements - A __running__ & configured evcc instance in your network - A Home Assistant instance that can reach your evcc instance ## Main features - Supporting all evcc API-POST & DELETE requests (except `POST /api/settings/telemetry/`) to adjust the evcc settings, loadpoints and the corresponding vehicles - Loadpoint mode [Off, Solar, Min+Solar, Fast] - Phases to use [Auto, 1p, 3p] - Assign vehicles to loadpoints - Configure min & max charging currents - Configure cost limits (€ or CO₂) - Adjust home-battery settings - Adjust/create vehicle & loadpoint charging plan via HA-Services [http://[YOUR-HA-INSTANCE]:8123/developer-tools/service](http://[YOUR-HA-INSTANCE]:8123/developer-tools/service) - Enable/eisable repeating charging plan #2-#10 per vehicle (details about the plan can be found in the attributes of the switch entity) - Supporting most of the other loadpoint and vehicle data that is available via the API – please let me know if you miss some data – probably it just slipped through my attention during testing. ### ~~evcc-Configuration objects are **not supported**~~ ~~With the release of _0.3.x_, evcc is now fully configurable via the graphical user interface (GUI). Since to be able to access the evcc-configuration GUI section requires a user authorization (for good reasons) is required, __THIS INTEGRATION DOES NOT OFFER ANY ENTITIES OF THE CONFIGURATION SECTION of EVCC!__ Please don't ask me to add them to _this_ integration. There is __no plan to support__ the evcc-configuration GUI entities in __the future__. This would require storing the evcc user credentials in the integration configuration, and the variety of possible objects is just too big.~~ ~~If you want/need to adjust the evcc configuration via home assistant, __make use of the HA-REST integration__ and create the required API calls yourself. Here in this readme you will find an example of what needs to be done.~~ ### Example Dashboard Take a look at this sample Dashboard (showing Sensors from one load point): ![sampledashboard](https://github.com/marq24/ha-evcc/raw/main/sample-dashboard.png) ### Using evcc Custom Card (external repository) [@mkshb](https://github.com/mkshb) have created multiple custom cards that can be installed via HACS (or manually) that will be a great enhancement for this integration. You can find all the details @ [https://github.com/mkshb/hass-evcc-card](https://github.com/mkshb/hass-evcc-card). ![sampledashboard2](https://github.com/marq24/ha-evcc/raw/main/sample-dashboard_cards.png) Make sure, that you leave a GitHub star also at mkshb's repostitory! --- ## Installation ### Before you start — there are two 'tiny' requirements! 1. **You must have installed & configured an evcc instance in your network.** This can be either a stand-alone installation (e.g via Docker) or as a HASS-IO-AddOn[^1]. This __AddOn__ is available via the [official evcc hassio-addon repository](https://github.com/evcc-io/hassio-addon). 2. You **must know the URL** from which your HA-Instance can reach your evcc instance. - This is usually the IP address of your evcc server and the port on which the evcc server is running (default is `7070`). - If you are using a reverse proxy, you need to know the URL that your HA instance can use to reach your evcc instance. - When you are using docker (or docker-compose), you must ensure that the containers can communicate with each other. This means that the network and the port must be configured and exposed correctly. It's not enough that you can reach your evcc instance via a browser — your HA container must be also able to reach it! [^1]: There is a known issue when using HASS-IO - For whatever reason it has been reported that the startup sequence of the containers (the different installed AddOns) _might not match the requirements_ of this Integration: Your evcc-server __must be up and running before the Integration can be initialized__ in HA. This is because during the initial start of the Integration your evcc configuration (active loadpoints and configured vehicles) will be evaluated in order to create the corresponding HA entities.

So when you restart your HASS-IO server, it _can happen_ that HA already starting to initialize this Integration before the HASS-OS has started the evcc-instance. __This will lead to the situation that the Integration is not started correctly__.

I am sorry that my HA developer skills are not sufficient to find a solution that works in this scenario – nor did I found other integrations with similar challenges (to find inspiration). If you know one (that's actively maintained), please let me know. Of course, I am also open to any PR solving this issue for AddOn users that work in the different scenarios (deactivating/activating the integration, with WebSocket support and without).

As a personal note on this: IMHO restarts of HA Servers should only happen under observation, and should not be automated in any kind – but I might be alone with my opinion. ### Step I: Install the integration #### Option 1: via HACS [![Open your Home Assistant instance and adding repository to HACS.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=marq24&repository=ha-evcc&category=integration) 1. Use the search bar and type `evcc☀️🚘- Solar Charging` 2. Use the 3-dots at the right of the list entry (not at the top bar!) to download/install the custom integration — the latest release version is automatically selected. Only select a different version if you have specific reasons. 3. After you press download and the process has completed, you must __Restart Home Assistant__ to install all dependencies 4. Setup the evcc custom integration as described below (see _Step II: Adding or enabling the integration_) #### Option 2: manual steps 1. Using the tool of choice, open the directory (folder) for your HA configuration (where you find `configuration.yaml`). 2. If you do not have a `custom_components` directory (folder) there, you need to create it. 3. In the `custom_components` directory (folder) create a new folder called `evcc_intg`. 4. Download _all_ the files from the `custom_components/evcc_intg/` directory (folder) in this repository. 5. Place the files you downloaded in the new directory (folder) you created. 6. Restart Home Assistant 7. Setup the evcc custom integration as described below (see _Step II: Adding or enabling the integration_) ### Step II: Adding or enabling the integration __You must have installed the integration (manually or via HACS before)!__ #### Option 1: My Home Assistant (2021.3+) Just click the following Button to start the configuration automatically (for the rest see _Option 2: Manually steps by step_): [![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=evcc_intg) #### Option 2: Manually — step by step Use the following steps for a manual configuration by adding the custom integration using the web interface and follow instruction on screen: - Go to `Configuration -> Integrations` and add "evcc☀️🚘- Solar Charging" integration #### Common further steps - Provide a unique name for the integration installation (will be used in each sensor entity_id) created by the integration - Provide the URL of your __evcc web server__ (including the port) — e.g. `http://your-evcc-server-ip:7070` - [optional] Provide the area where the evcc installation is located After the integration was added, you can use the 'config' button to adjust your settings, you can additionally modify the update interval Please note that some of the available sensors are __not__ enabled by default. --- ## Understanding the different parts of evcc, Home Assistant and other additional components It's quite easy to mix up the things when it comes to issues with evcc and Home Assistant. It can be kind of tricky to understand which different components exist and what is the purpose of each of them. And **where you should open an issue** or start a discussion in case of a problem or which **developer you want to support**. ### The _evcc (Server)_ component The evcc main component, a server (implemented in go), serving an own GUI that have implemented interfaces to wallboxes, batteries, meters, vehicles and probably many other devices that exist in your home. Evcc is completely independent of anything that is happening in Home Assistant. Have that said, evcc can also read data from your Home Assistance instance, in this case HA is the source for some data used by evcc. So in this case HA can be considered just like any other interface implemented in evcc as data source. The simplest way to run _evcc_ is via docker (IMHO) - but you can of course also install and run it alternatively. #### Maintainer: evcc-community - https://github.com/evcc-io/evcc ### The _evcc HA (hassio) AddOn/App_ component When you are using the Home Assistant hassio (OS), then you have the possibility to install/run additional conatiners as Apps (named _Addons_ in the past). The _evcc AddOn/App__ allow you to install & run an instance of the evcc server directly as addon/app in your HA hassio. So there is no need, that you install a separate instance of evcc (e.g. in a docker container). Running the App/Addon will typically add an entry to the left navigation of your running HA and will show the default user interface of evcc (GUI) in a frame of your Home Assistant. #### Maintainer: evcc-community - https://github.com/evcc-io/hassio-addon > [!IMPORTANT] > So _evcc Server_ or _evcc HA (hassio) AddOn/App_ are the components that you must install in order to have an evcc instance up and running. A running evcc server can access HA entities and read values from different HA entities (as data source for evcc). How all this can be done is part of the [evcc.io documentation](https://docs.evcc.io/en/). ### The _HA integration_ (this repository) When you run your evcc Server (or Addon/App) there **is no possibility to systematically interact** e.g. via automations **from HA with your evcc server**. This gap will be filled by this _evcc HA integration_. Most (if not all) of the controls that exists in the evcc GUI will be provided as HA entities (selects, switches, buttons or sensors). This allows you to control any evcc option/setting via HA automations or other types of scripting. The HA integration can be considered as some sort of _remote control_ of your evcc server inside the ecosystem of Home Assistant. I hope it's obviously to be able to use this HA integration you must have previously installed an _evcc Server_ or the _Addon/App_. #### Maintainer: marq24 - https://github.com/marq24/ha-evcc ### The _evcc custom HA card_ component A custom Lovelace card for Home Assistant that provides a comprehensive Home Assistant dashboard for evcc - using the _evcc HA integration_. Since the default HA controls have certain limitations, the custom card brings you the (look &) feel from the evcc GUI into your HA. #### Maintainer: mkshb - https://github.com/mkshb/hass-evcc-card --- ## Using evcc with Home Assistant ### Use Home Assistant sensor data as input for evcc (beyond the existing evcc HA-features) Please see the separate document where you can find examples [how to provide your evcc instance with HA sensor data](https://github.com/marq24/ha-evcc/blob/main/HA_AS_EVCC_SOURCE.md). ### Use evcc to control any of your Home Assistant devices This is IMHO a very powerful feature of evcc, that is not known to many users (yet). You can use evcc to control your Home Assistant devices or Automation, e.g., to switch on/off anything you like when you are actually feeding power into the grid. Using the maximum out of your solar panels to charge your EV is great, but what if you have more power available — or if your EV is already fully charged? I am facing this challenge for quite a long time now and used several helpers & Blueprints to control my home devices with larger energy consumption. You can use evcc to control any Home Assistant entity that has implemented the `turn_on` and `turn_off` services. This means you can control devices like smart plugs, or even Home Assistant automations (which is IMHO the door to PV surplus handling heaven). Since the setup and configuration of this evcc feature might not be straight forward, I have created a separate document where you can find examples [Master PV surplus handling with evcc & Home Assistent](https://github.com/marq24/ha-evcc/blob/main/HA_CONTROLLED_BY_EVCC.md). I use this feature to control the hot-water temperature of my waterkotte heat pump. --- ## Are you are go-eCharger V3 (or higher) User? Do you know, that as owners of a go-eCharger (V3+) there is no need to use evcc for solar surplus charging? Even without any additional hardware! Home Assistant and the __go-eCharger APIv2 Connect__ Integration is all you need. Get all details from [https://github.com/marq24/ha-goecharger-api2](https://github.com/marq24/ha-goecharger-api2). --- ## Want to report an issue? Please use the [GitHub Issues](https://github.com/marq24/ha-evcc/issues) for reporting any issues you encounter with this integration. Please be so kind before creating a new issues, check the closed ones if your problem has been already reported (& solved). To speed up the support process, you might like to already prepare and provide DEBUG log output. In the case of a technical issue, I would need this DEBUG log output to be able to help/fix the issue. There is a short [tutorial/guide 'How to provide DEBUG log' here](https://github.com/marq24/ha-senec-v3/blob/main/docs/HA_DEBUG.md) — please take the time to quickly go through it. For this integration, you need to add: ``` logger: default: warning logs: custom_components.evcc_intg: debug ``` --- ###### Advertisement / Werbung - alternative way to support me ### Switch to Tibber! Be smart switch to Tibber - that's what I did in october 2023. If you want to join Tibber (become a customer), you might want to use my personal invitation link. When you use this link, Tibber will grant you and me a bonus of 50,-€ for each of us. This bonus then can be used in the Tibber store (not for your power bill) — e.g. to buy a Tibber Bridge. If you are already a Tibber customer and have not used an invitation link yet, you can also enter one afterward in the Tibber App (up to 14 days). [[see official Tibber support article](https://support.tibber.com/en/articles/4601431-tibber-referral-bonus#h_ae8df266c0)] Please consider [using my personal Tibber invitation link to join Tibber today](https://invite.tibber.com/6o0kqvzf) or Enter the following code: 6o0kqvzf (six, oscar, zero, kilo, quebec, victor, zulu, foxtrot) afterward in the Tibber App - TIA! --- ### References - https://github.com/evcc-io/evcc - https://docs.evcc.io/docs/reference/api [hacs]: https://hacs.xyz [hacsbadge]: https://img.shields.io/badge/HACS-Default-blue?style=for-the-badge&logo=homeassistantcommunitystore&logoColor=ccc [hainstall]: https://my.home-assistant.io/redirect/config_flow_start/?domain=evcc_intg [hainstallbadge]: https://img.shields.io/badge/dynamic/json?style=for-the-badge&logo=home-assistant&logoColor=ccc&label=usage&suffix=%20installs&cacheSeconds=15600&url=https://analytics.home-assistant.io/custom_integrations.json&query=$.evcc_intg.total [ghs]: https://github.com/sponsors/marq24 [ghsbadge]: https://img.shields.io/github/sponsors/marq24?style=for-the-badge&logo=github&logoColor=ccc&link=https%3A%2F%2Fgithub.com%2Fsponsors%2Fmarq24&label=Sponsors [buymecoffee]: https://www.buymeacoffee.com/marquardt24 [buymecoffeebadge]: https://img.shields.io/badge/buy%20me%20a-coffee-blue.svg?style=for-the-badge&logo=buymeacoffee&logoColor=ccc&link=https%3A%2F%2Fwww.buymeacoffee.com%2Fmarquardt24 [buymecoffee2]: https://buymeacoffee.com/marquardt24/membership [buymecoffeebadge2]: https://img.shields.io/badge/coffee-subs-blue.svg?style=for-the-badge&logo=buymeacoffee&logoColor=ccc&link=https%3A%2F%2Fbuymeacoffee.com%2Fmarquardt24%2Fmembership [paypal]: https://paypal.me/marq24 [paypalbadge]: https://img.shields.io/badge/paypal-me-blue.svg?style=for-the-badge&logo=paypal&logoColor=ccc&link=https%3A%2F%2Fpaypal.me%2Fmarq24 [wero]: https://share.weropay.eu/p/1/c/6O371wjUW5 [werobadge]: https://img.shields.io/badge/_wero-me_-blue.svg?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZwogICByb2xlPSJpbWciCiAgIHZpZXdCb3g9IjAgMCA0Mi4wNDY1MDEgNDAuODg2NyIKICAgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIgo+CiAgPGcKICAgICBjbGlwLXBhdGg9InVybCgjY2xpcDApIgogICAgIHRyYW5zZm9ybT0idHJhbnNsYXRlKC01Ny4zODE4KSI+CiAgICA8cGF0aAogICAgICAgZD0ibSA3OC40MDUxLDMwLjM1NzQgYyAwLDAgLTAuMDE4NSwwIC0wLjAyNzgsMCAtNC4zMTg0LDAgLTcuMzQ2MiwtMi41NzY5IC04LjY0NjEsLTUuOTg4NyBIIDk5LjA2OTggQyA5OS4zMDU3LDIzLjA4NDkgOTkuNDI4MywyMS43NzExIDk5LjQyODMsMjAuNDQxIDk5LjQyODMsOS43NTY3MyA5MS43Mzc1LDAuMDEzODc4NyA3OC40MDUxLDAgdiAxMC41MjcgYyA0LjM0MzksMC4wMTE2IDcuMzQxNiwyLjU4MzcgOC42Mjc2LDUuOTg4NyBoIC0yOS4yOTcgYyAtMC4yMzM2LDEuMjgzNyAtMC4zNTM5LDIuNTk3NiAtMC4zNTM5LDMuOTI3NiAwLDEwLjY5MTMgNy43MDAyLDIwLjQ0MzQgMjAuOTk1NSwyMC40NDM0IDAuMDA5MywwIDAuMDE4NSwwIDAuMDI3OCwwIHYgLTEwLjUyNyB6IgogICAgICAgZmlsbD0iI0NDQ0NDQyIvPgogICAgPHBhdGgKICAgICAgIGQ9Im0gNzguMzc3NCw0MC44ODQ0IGMgMC40NTEsMCAwLjg5NTEsLTAuMDEzOSAxLjMzNDYsLTAuMDM0NyAyLjcwMTcsLTAuMTM2NSA1LjE1MzUsLTAuNjgwMSA3LjMzOTMsLTEuNTU2NyAyLjE4NTgsLTAuODc2NyA0LjEwNTcsLTIuMDgxOCA1LjczODcsLTMuNTM5MSAxLjYzMywtMS40NTczIDIuOTgxNSwtMy4xNjQzIDQuMDI3LC01LjA0NDkgMC45NTA2LC0xLjcwOTQgMS42NDQ1LC0zLjU1OTkgMi4wNzk0LC01LjQ5MTMgSCA4Ni42NzIgYyAtMC4yNDk4LDAuNTE1OCAtMC41NDEzLDEuMDA4NSAtMC44NzQ0LDEuNDY4OCAtMC40NTU2LDAuNjI5MSAtMC45ODk5LDEuMjAwNSAtMS41OTYsMS42OTMyIC0wLjYwNiwwLjQ5MjcgLTEuMjg2LDAuOTA5IC0yLjAzNTQsMS4yMzA2IC0wLjc0OTUsMC4zMjE1IC0xLjU2NiwwLjU0ODIgLTIuNDQ5NSwwLjY2MTUgLTAuNDMwMywwLjA1NTUgLTAuODc0NCwwLjA4NzkgLTEuMzM0NywwLjA4NzkgLTIuNzUwMiwwIC00Ljk3NzYsLTEuMDQ3OCAtNi41NjY3LC0yLjY4NzggbCAtNy45NDc2LDcuOTQ3OCBjIDMuNTM2NiwzLjIyOTIgOC40NDI2LDUuMjY0NyAxNC41MTY2LDUuMjY0NyB6IgogICAgICAgZmlsbD0idXJsKCNwYWludDApIgogICAgICAgc3R5bGU9ImZpbGw6dXJsKCNwYWludDApIiAvPgogICAgPHBhdGgKICAgICAgIGQ9Ik0gNzguMzc3NywwIEMgNjcuMTAxNiwwIDU5Ljg1MDIsNy4wMTMzNyA1Ny45MDcyLDE1LjY2OTEgSCA3MC4wOTcgYyAxLjQ1NzIsLTIuOTgxNyA0LjMyNzcsLTUuMTQyMSA4LjI4MDcsLTUuMTQyMSAzLjE1MDMsMCA1LjU5NTIsMS4zNDYyIDcuMTkzNSwzLjM4MTggTCA5My41OTA1LDUuODg5MiBDIDkwLjAwNzYsMi4zMDE1NSA4NC44NTY1LDAuMDAyMzEzMTIgNzguMzc1MywwLjAwMjMxMzEyIFoiCiAgICAgICBmaWxsPSJ1cmwoI3BhaW50MSkiCiAgICAgICBzdHlsZT0iZmlsbDp1cmwoI3BhaW50MSkiIC8+CiAgPC9nPgogIDxkZWZzPgogICAgPGxpbmVhckdyYWRpZW50CiAgICAgICBpZD0icGFpbnQwIgogICAgICAgeDE9IjkyLjc0MzY5OCIKICAgICAgIHkxPSIxOC4wMjYxOTkiCiAgICAgICB4Mj0iNzQuNzU0NTAxIgogICAgICAgeTI9IjQwLjMxMDIiCiAgICAgICBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+CiAgICAgIDxzdG9wCiAgICAgICAgIG9mZnNldD0iMC4wMiIKICAgICAgICAgc3RvcC1jb2xvcj0iI0NDQ0NDQyIKICAgICAgICAgc3RvcC1vcGFjaXR5PSIwIi8+CiAgICAgIDxzdG9wCiAgICAgICAgIG9mZnNldD0iMC4zOSIKICAgICAgICAgc3RvcC1jb2xvcj0iI0NDQ0NDQyIKICAgICAgICAgc3RvcC1vcGFjaXR5PSIwLjY2Ii8+CiAgICAgIDxzdG9wCiAgICAgICAgIG9mZnNldD0iMC42OCIKICAgICAgICAgc3RvcC1jb2xvcj0iI0NDQ0NDQyIvPgogICAgPC9saW5lYXJHcmFkaWVudD4KICAgIDxsaW5lYXJHcmFkaWVudAogICAgICAgaWQ9InBhaW50MSIKICAgICAgIHgxPSI2MS4yNzA0MDEiCiAgICAgICB5MT0iMjMuMDE3Nzk5IgogICAgICAgeDI9Ijc5Ljc1NDUwMSIKICAgICAgIHkyPSI0LjUzNDI5OTkiCiAgICAgICBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+CiAgICAgIDxzdG9wCiAgICAgICAgIG9mZnNldD0iMC4wMiIKICAgICAgICAgc3RvcC1jb2xvcj0iI0NDQ0NDQyIKICAgICAgICAgc3RvcC1vcGFjaXR5PSIwIi8+CiAgICAgIDxzdG9wCiAgICAgICAgIG9mZnNldD0iMC4zOSIKICAgICAgICAgc3RvcC1jb2xvcj0iI0NDQ0NDQyIKICAgICAgICAgc3RvcC1vcGFjaXR5PSIwLjY2Ii8+CiAgICAgIDxzdG9wCiAgICAgICAgIG9mZnNldD0iMC42OCIKICAgICAgICAgc3RvcC1jb2xvcj0iI0NDQ0NDQyIvPgogICAgPC9saW5lYXJHcmFkaWVudD4KICAgIDxjbGlwUGF0aAogICAgICAgaWQ9ImNsaXAwIj4KICAgICAgPHJlY3QKICAgICAgICAgd2lkdGg9IjE3Ny45MSIKICAgICAgICAgaGVpZ2h0PSI0MSIKICAgICAgICAgZmlsbD0iI2ZmZmZmZiIKICAgICAgICAgeD0iMCIKICAgICAgICAgeT0iMCIgLz4KICAgIDwvY2xpcFBhdGg+CiAgPC9kZWZzPgo8L3N2Zz4= [revolut]: https://revolut.me/marq24 [revolutbadge]: https://img.shields.io/badge/_revolut-me_-blue.svg?style=for-the-badge&logo=revolut&logoColor=ccc&link=https%3A%2F%2Frevolut.me%2Fmarq24 [wise]: https://wise.com/pay/me/matthiasm1046 [wisebadge]: https://img.shields.io/badge/_wise-me_-blue.svg?style=for-the-badge&logo=wise&logoColor=ccc&link=https%3A%2F%2Fwise.com%2Fpay%2Fme%2Fmatthiasm1046