{"id":23503147,"url":"https://github.com/kpfleming/esphome-sunpower","last_synced_at":"2025-04-15T21:34:43.537Z","repository":{"id":190170288,"uuid":"681869389","full_name":"kpfleming/esphome-sunpower","owner":"kpfleming","description":"A set of experimental ESPHome components for gathering data from SunPower PV Supervisor devices.","archived":false,"fork":false,"pushed_at":"2024-09-08T17:19:07.000Z","size":150,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"v2","last_synced_at":"2025-03-29T01:34:35.930Z","etag":null,"topics":["esphome","esphome-component","homeassistant","solar-energy","sunpower"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kpfleming.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"kpfleming","liberapay":"kpfleming"}},"created_at":"2023-08-23T00:07:06.000Z","updated_at":"2025-03-02T16:10:13.000Z","dependencies_parsed_at":"2023-09-24T12:53:04.384Z","dependency_job_id":"28f09a50-36c7-4179-88c9-1b8f51906726","html_url":"https://github.com/kpfleming/esphome-sunpower","commit_stats":{"total_commits":57,"total_committers":3,"mean_commits":19.0,"dds":0.07017543859649122,"last_synced_commit":"09ce3d572c974032c11c8887c2f59ae29532369a"},"previous_names":["kpfleming/esphome-sunpower"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpfleming%2Fesphome-sunpower","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpfleming%2Fesphome-sunpower/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpfleming%2Fesphome-sunpower/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpfleming%2Fesphome-sunpower/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kpfleming","download_url":"https://codeload.github.com/kpfleming/esphome-sunpower/tar.gz/refs/heads/v2","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249157959,"owners_count":21222031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esphome","esphome-component","homeassistant","solar-energy","sunpower"],"created_at":"2024-12-25T08:15:33.630Z","updated_at":"2025-04-15T21:34:43.507Z","avatar_url":"https://github.com/kpfleming.png","language":"C++","funding_links":["https://github.com/sponsors/kpfleming","https://liberapay.com/kpfleming"],"categories":[],"sub_categories":[],"readme":"\u003e [!CAUTION]\n\u003e With the announcement of SunPower's bankruptcy, the PVS5/6 devices\n\u003e will have no future software support from the manufacturer. As a\n\u003e result, many SunPower customers will switch to other 'supervisor'\n\u003e solitions, including the author of this component. As a result, this\n\u003e component will receive only very limited bugfixes in the future: if\n\u003e the ESPHome infrastructure changes in a way that makes this\n\u003e component incompatible, then this repository will be archived and\n\u003e its use discouraged.\n\n# esphome-sunpower\n\n\u003ca href=\"https://opensource.org\"\u003e\u003cimg height=\"150\" align=\"left\" src=\"https://opensource.org/files/OSIApprovedCropped.png\" alt=\"Open Source Initiative Approved License logo\"\u003e\u003c/a\u003e\n[![License - GNU GPL v3.0+](https://img.shields.io/badge/License-GNU%20GPL%203.0%2b-9400d3.svg)](https://spdx.org/licenses/GPL-3.0-or-later.html)\n\nThis repo contains a series of experimental ESPHome components which\ngather data from SunPower PV Supervisor (PVS) devices. It requires\nESPHome 2024.6.0 or later.\n\nOpen Source software: [GNU General Public License v3.0 or later](https://spdx.org/licenses/GPL-3.0-or-later.html)\n\n## \u0026nbsp;\n\n## Comparison with other integrations\n\nThe most commonly used other integration is\n[hass-sunpower](https://github.com/krbaker/hass-sunpower), so this\ncomparison focuses on the differences between it and esphome-sunpower.\n\n### Advantages\n\n#### Synthesized 'from grid' and 'to grid' sensors\n\nhass-sunpower reports the 'kWh from Grid' and 'kWh to Grid' sensors\nfrom the PVS, when they are available. Unfortunately they are not\nalways available, and so to improve consistency esphome-sunpower\nsynthesizes its own sensors. Users can choose to use them or not, as\ntheir needs dictate. In addition, the PVS only provides *energy*\nsensors of this type, but esphome-sunpower also provides *power*\nsensors.\n\n#### Explicit control over sensor visibility and names\n\nESPHome configurations require explicit enablement of every sensor to\nbe reported to HA (opt-in), which is a different design from Home\nAssistant integrations which typically don't offer such controls. Home\nAssistant itself provides the ability to 'hide' and even 'disable'\nsensors being reported by an integration, but this does not remove\nthem from the overall system configuration.\n\nHome Assistant also allows users to override sensor names, but these\noverrides are lost if the integration is ever deleted from the Home\nAssistant configuration and re-added. ESPHome's usage of a separate\nconfiguration system means that the user's defined sensor names will\nalways be used, even if the ESPHome device is deleted from the Home\nAssistant configuration and re-added (or added to another Home\nAssistant instance).\n\n#### Support for aggregating panels into arrays\n\nSome SunPower customers have panels in arrays (strings), on separate\nroof surfaces and oriented in different directions. esphome-sunpower\nprovides the ability to aggregate current, power, and energy sensors\nfrom the panels in each array and present these to HA as 'array'\nsensors.\n\n#### Ability to manipulate sensor data before it is delivered to Home Assistant\n\nWhile it is unlikely to be needed frequently, some users may wish to\nmanipulate PVS sensor data before displaying it in Home Assistant\ndashboards. Using hass-sunpower, those modifications must be done by\ncreating `template sensors` in Home Assistant, and then hiding the\noriginal sensor. With esphome-sunpower, various types of data\nfiltering and manipulation can be performed directly in the ESPHome\nconfiguration, with only the resulting data delivered to Home\nAssistant (and no 'extra' sensors).\n\n#### Reduction of startup time and workload in Home Assistant\n\nBecause the PVS responds to API queries so slowly (see the [PVS Data\nCollection](#pvs-data-collection) section below), users of\nhass-sunpower are warned during Home Assistant startup that the\n'integration is taking too long to startup', even though there is\nnothing wrong. This also results in delays for data being delivered to\ndashboards. Using esphome-sunpower, the data collection is happening\noutside of Home Assistant, and is immediately available the moment\nthat Home Assistant connects to the ESPHome device. Even with more\nthan 100 sensors in the esphome-sunpower configuration, delivery of\nthe most current data for those sensors to Home Assistant happens\nalmost instantly during startup.\n\n#### Reduction of Home Assistant 'Recorder' database growth\n\nBecause the esphome-sunpower user controls the number and type of\nsensors to be reported to Home Assistant, they have complete control\nover the growth of the Recorder database. Hiding sensors in Home\nAssistant doesn't stop them from being stored in the database, so\nhass-sunpowers users are often storing much more data than they\nactually need.\n\n#### Direct publication of data to InfluxDB\n\nSome PVS users store their long-term solar data in InfluxDB; using\nhass-sunpower means that this data must go into Home Assistant before\nbeing pushed to InfluxDB. esphome-sunpower users can make use of\nInfluxDB components for ESPHome itself, ensuring that the data always\nflows to InfluxDB without needing Home Assistant's help.\n\n### Disadvantages\n\n#### Lack of 'device' support\n\nESPHome does not currently support the Home Assistant Device Registry\nin a way which allows components to associate entities (sensors, etc.)\nwith multiple devices. As a result all of the sensors enabled in an\nesphome-sunpower configuration will appear under a single device in\nHome Assistant. There is a proposal to enhance ESPHome to provide\nsupport for this, though, see the [Roadmap](#roadmap) section below.\n\n#### Requires additional hardware\n\nUntil ESPHome supports multiple network connections in a single device\n(allowing the ESP32 device to be installed in the PVS cabinet, see the\n[Roadmap](#roadmap) section below), esphome-sunpower users need *both*\na device in the PVS cabinet to provide connectivity to the PVS `LAN`\nport *and* an ESP32 device to collect and process the data.\n\n## Requirements\n\n* One or more SunPower PVS 6 (may also work with PVS 5).\n* An ESP32-based device; note that this has only been tested with the\n  original ESP32 (dual-core Tensilica 240MHz CPU, 520KB SRAM) with at\n  least 4MB of flash memory attached. The other ESP32 variants are\n  likely to be usable, depending on the complexity of the PVS networks\n  being monitored and the number of individual sensors enabled in the\n  configuration. The device should be dedicated to PVS\n  monitoring. Since there are no GPIOs used, any ESP32 board will\n  work.\n* Network connectivity between the ESP32, the PVS, and Home Assistant,\n  on a *single* network connection; if dual network connectivity\n  becomes available in a future ESPHome release, this requirement\n  would be eliminated and the ESP32 device could be installed in the\n  PVS cabinet in place of any other device used for the _LAN_ network\n  connection. If you don't already have connectivity to the PVS, you\n  should review the [long\n  topic](https://community.home-assistant.io/t/options-for-sunpower-solar-integration/289621)\n  on the Home Assistant Discourse forum to learn about your options.\n\n## PVS Data Collection\n\nThroughout the examples in this documentation, you will see a `\u003cPVS\u003e`\nplaceholder; in your actual configuration you will need to replace\nthis with the IP address you've made available to reach the PVS (or\nthe DNS name, if you've setup DNS for it and your ESP32 is able to use\nDNS.)\n\nThe PVS responds to the data collection API request quite slowly; in a\nconfiguration with 37 panels, the response takes between 9 and 10\nseconds in most cases. As a result, the example configurations include\nan override for the ESP-IDF 'watchdog timer' to ensure that the ESP32\nwon't be restarted while waiting for the response. This is a rather\ninelegant workaround, but it is necessary until such time as ESPHome\ncan issue HTTP requests and wait for responses in an asynchronous\nmanner. If your PVS takes longer than 10 seconds to respond, you may\nneed to increase the watchdog timeout correspondingly (be sure to\nleave a few seconds buffer in case there are any network traffic\nproblems which might increase the response time).\n\nYou will need to determine two buffer sizes to be used in the ESPHome\nconfiguration:\n\n* `http_request.get-\u003emax_response_buffer_size`: this needs to be large\n  enough to hold the entire response from the PVS (see below).\n\n* `sunpower_solar_pvs-\u003ebuffer_size-\u003edata`: this needs to be large\n  enough to hold the portion of the JSON data from the PVS that is\n  used to populate the sensors. In a configuration with _all_ sensors\n  enabled it needs to be about 25% of the `max_response_buffer_size`,\n  but if fewer sensors are enabled it can be reduced.\n\nTo determine the buffer sizes required for your configuration and\nconfirm that you have PVS connectivity, you can use `curl`:\n\n```shell\n$ curl -o pvs-data.json http://\u003cPVS\u003e/cgi-bin/dl_cgi?Command=DeviceList\n  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n                                 Dload  Upload   Total   Spent    Left  Speed\n100 31195  100 31195    0     0   3385      0  0:00:09  0:00:09 --:--:--  7789\n```\n\nThe resulting `pvs-data.json` file should look similar to the one in\nthe [examples directory](examples). You will need this file in order\nto build your configuration, since it contains the serial numbers of\nall of the SunPower devices.\n\nIn the output above you can see that the transfer took 9 seconds, and\nthe resulting JSON document was 31,195 bytes long. For that system,\n`max_response_buffer_size` should be set to 34000, and\n`buffer_size-\u003edata` should be set to 10000 if all sensors are enabled.\n\nOnce the system is running you can monitor the logs (with\n`logger-\u003elevel` set to `debug`) to see how much of the JSON data buffer\nis being used; if a large portion is unused, reconfigure for a lower\nsize, but be prepared to increase it again if you enable more\nsensors. If the JSON data buffer is not large enough, an error will\nbe emitted in the logs and no sensor data will be published.\n\n## Configuration\n\nThe ESPHome 'logger' defaults to `debug` level; while this can be\nuseful for troubleshooting ESPHome configurations, it also means that\nsensor data publication can be slowed down substantially. If you have\nthe level set to `debug`, and you enable more than 7 or 8 sensors in\ntotal in the esphome-sunpower component, then you will see a warning\nin the ESPHome log every time esphome-sunpower publishes data. The\nwarning will indicate that component `sunpower_solar_pvs` took *too\nmuch time* to do its work, but if as suggested previously you've\ndedicated an ESP32 board for this task, then you can safely ignore the\nwarning as no other important ESPHome activities will be missed.\n\nYou will see the same type of warning for the `http_request`\ncomponent, since it will block ESPHome activities for many seconds\nwhile it waits for a response from the PVS.\n\n### Minimal\n\nThis section is a walkthrough of [minimal.yml](examples/minimal.yml)\nfrom the `examples` directory. It is the most basic configuration\nneeded to support the Home Assistant 'Energy Dashboard' (which\nrequires three sensors).\n\n```yaml\nesphome:\n  name: pvs-minimal\n  friendly_name: Minimal PVS Monitor\n\nesp32:\n  board: esp32dev\n  framework:\n    type: esp-idf\n\nwifi:\n  networks:\n    - ssid: example-network\n      password: network-password\n\napi:\n```\n\nThis section fulfills basic ESPHome requirements: node information,\nboard selection, and WiFi/API connectivity.\n\n```yaml\nexternal_components:\n  - source: github://kpfleming/esphome-sunpower@v2\n```\n\nThis configuration requires only one external component: esphome-sunpower.\n\n```yaml\nsunpower_solar:\n  serial: PVS1\n  consumption_meter:\n    serial: CM1\n  production_meter:\n    serial: PM1\n```\n\nThis section configures esphome-sunpower to accept data from the\nPVS, including its consumption meter and production meter. The serial\nnumbers of all three components must be specified, and they can be\nobtained from the JSON data file gathered while following the steps in\n[PVS Data Collection](pvs-data-collection).\n\nSince this configuration only publishes data for three sensors, the\ndefault values for the esphome-sunpower buffer sizes are sufficient,\nand they are not included in the example configuration.\n\n```yaml\nsensor:\n  - platform: sunpower_solar\n\n    energy_from_grid: Energy From Grid\n    energy_to_grid: Energy To Grid\n\n    consumption_meter:\n      lifetime_energy:\n        name: Energy Consumed\n        internal: true\n\n    production_meter:\n      lifetime_energy: Energy Produced\n```\n\nThis section configures the three sensors required by the Energy Dashboard:\n\n* Energy From Grid\n\n* Energy To Grid\n\n* Energy Produced\n\nIn addition an `Energy Consumed` sensor is configured but marked as\n`internal` so it will not be published to Home Assistant. It is\nrequired for the `Energy From Grid` and `Energy To Grid` sensor\ncalculations.\n\n```yaml\nhttp_request:\n  useragent: esphome/pvs\n  timeout: 15s\n  watchdog_timeout: 15s\n```\n\nThis section configures the `http_request` component; the only\nrelevant item here is `watchdog_timeout`, which is necessary due to\nthe issues described in the [PVS Data\nCollection](README.md#pvs-data-collection) section.\n\n```yaml\ninterval:\n  interval: 1min\n  then:\n    - delay: 15s\n    - http_request.get:\n        url: http://\u003cPVS\u003e/cgi-bin/dl_cgi?Command=DeviceList\n        capture_response: true\n            - delay: 3s\n        max_response_buffer_size: 35000\n        on_response:\n          then:\n            - sunpower_solar.process: body\n```\n\nThis final section configures an `interval` component so that ESPHome\ncan periodically pull data from the PVS and push it to\nesphome-sunpower.\n\nThe trigger is used to poll the PVS every minute, capture the response, and then\nsupply the response to esphome-sunpower for parsing and sensor\npublication. The initial 15 second delay in the trigger is necessary\nbecause the `interval` component will immediately trigger during\nESPHome boot, and the blocking HTTP request will cause initialization\nof other parts of the ESPHome system to fail.\n\nSee the [PVS Data Collection](#pvs-data-collection) section\nfor details about `max_response_buffer_size`.\n\n### Full Featured\n\nSee [FULL_CONFIGURATION](FULL_CONFIGURATION.md).\n\n## Roadmap\n\n### Device Support\n\nThe author of these components also plans to work on 'connected\ndevice' support for ESPHome, which would resolve one of the major\ndifferences between this integration and hass-sunpower. If you are\ninterested, you can follow the [feature-requests\nissue](https://github.com/esphome/feature-requests/issues/1335).\n\n### Dual Network Support\n\nThere is an open [feature-requests\nissue](https://github.com/esphome/feature-requests/issues/2102) on\nthis topic; the author of these components may try to tackle that one\ntoo at some point in the near future!\n\n## Issues, Feature Requests, Discussions\n\nIf you need to report an issue, or suggest a new feature, please do so\nin the\n['Issues'](https://github.com/kpfleming/esphome-sunpower/issues) area\nof this repository.\n\nIf you'd like to discuss usage of these components, or ask for help\nwith them (but not with ESPHome itself or PVS connectivity), please do\nso in the\n['Discussions'](https://github.com/kpfleming/esphome-sunpower/discussions)\narea of this repository.\n\n## Chat\n\nIf you'd like to chat with the esphome-sunpower community, join us on\n[Matrix](https://matrix.to/#/#esphome-sunpower:km6g.us)!\n\n## Credits\n\nThis project was inspired by the excellent\n[hass-sunpower](https://github.com/krbaker/hass-sunpower) project by\n[@krbaker](https://github.com/krbaker).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpfleming%2Fesphome-sunpower","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkpfleming%2Fesphome-sunpower","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpfleming%2Fesphome-sunpower/lists"}