{"id":21338262,"url":"https://github.com/smlx/goodwe-exporters","last_synced_at":"2025-08-15T19:05:49.137Z","repository":{"id":222517915,"uuid":"719584919","full_name":"smlx/goodwe-exporters","owner":"smlx","description":"Prometheus Exporters for Goodwe Energy Monitors (smart meters) and Solar Inverters","archived":false,"fork":false,"pushed_at":"2025-08-04T12:15:27.000Z","size":278,"stargazers_count":17,"open_issues_count":7,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-04T13:14:18.004Z","etag":null,"topics":["go","golang","goodwe","mitm","prometheus","prometheus-exporter","sems-portal"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smlx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2023-11-16T13:34:21.000Z","updated_at":"2025-08-04T12:15:30.000Z","dependencies_parsed_at":"2024-02-14T17:53:32.821Z","dependency_job_id":"9ff62b07-4fa2-43eb-a9d0-05e33e88bfc1","html_url":"https://github.com/smlx/goodwe-exporters","commit_stats":{"total_commits":89,"total_committers":2,"mean_commits":44.5,"dds":0.4269662921348315,"last_synced_commit":"cb8af931bf15e5de8e1e7693c7a7558ceeb9090c"},"previous_names":["smlx/goodwe-exporters"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/smlx/goodwe-exporters","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smlx%2Fgoodwe-exporters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smlx%2Fgoodwe-exporters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smlx%2Fgoodwe-exporters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smlx%2Fgoodwe-exporters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smlx","download_url":"https://codeload.github.com/smlx/goodwe-exporters/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smlx%2Fgoodwe-exporters/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270617818,"owners_count":24617121,"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","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["go","golang","goodwe","mitm","prometheus","prometheus-exporter","sems-portal"],"created_at":"2024-11-22T00:12:17.155Z","updated_at":"2025-08-15T19:05:49.100Z","avatar_url":"https://github.com/smlx.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Goodwe Prometheus Exporters\n\nThis repository contains Prometheus metrics exporters for Goodwe solar energy devices including inverters and smart meters.\n\n## SEMS MITM Exporter\n\nThis is a Prometheus exporter for Goodwe devices which integrate with the cloud-hosted Smart Energy Managment System (SEMS) portal.\nIt works by implementing a [MITM attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) on the SEMS portal protocol, hence the name.\n\n### Why does this exist?\n\n#### Short version\n\nHomekit 1000 does not support Modbus for metrics querying, so the only way to get data out of it appears to be from the SEMS Portal traffic.\n\nOther Goodwe hardware probably supports Modbus, which may be more convenient for scraping metrics.\n\n#### Long version\n\nSee the [blog post](https://smlx.dev/posts/goodwe-sems-protocol-teardown/).\n\n### Features\n\nThe SEMS MITM exporter has the following advantages over just using the SEMS Portal:\n\n* Transparently forwards data to SEMS Portal (option not to forward traffic is a WIP).\n* Allows you to store your data in a Prometheus instance that you control.\n* Visualise your data using standard tools like Grafana.\n* Drops unrecognised incoming packets to block e.g. firmware upgrades.\n* Summons Batman to the SEMS Portal (optional, set env var `BATSIGNAL=true`).\n\n### Hardware support\n\nCurrently hardware support in the SEMS MITM Exporter is limited to the equipment I own:\n\n* [Homekit 1000](https://www.goodwe.com.au/single-phase-homekit)\n* [DNS G3](https://www.goodwe.com.au/dns-g3-au)\n\nPRs welcome if you want to add support for your device.\n\n\u003e [!NOTE]\n\u003e I don't have a battery, so the exporter and metrics naming reflects that.\n\u003e Open issues to discuss how to improve this if you have a battery and don't like the metric naming.\n\n### How to get it\n\nYou have a couple of options:\n\n* Pull a docker image from the Github image registry (recommended!).\n* Download a release binary from the Releases page.\n\n### How to use it\n\nAt a high level:\n\n1. Start the exporter.\n1. Get traffic to the exporter. Either:\n    * Point the DNS of `tcp.goodwe-power.com` to the IP of the exporter; or\n    * Reconfigure your hardware to connect to the IP of the exporter.\n1. Configure Prometheus to scrape from the exporter on port 14028.\n1. Grab the [Grafana dashboard](https://grafana.com/grafana/dashboards/20479-household-power/) and visualise your metrics.\n\nDetailed instructions for supported hardware is a WIP.\nFor command-line flags and environment variables run the exporter with the `--help` flag.\n\n#### Example: docker compose\n\nHere's how I run it locally using docker compose:\n\n```yaml\n---\nversion: '3.8'\nservices:\n  sems_mitm_exporter:\n    # avoid copying host search option\n    dns_search: .\n    image: ghcr.io/smlx/goodwe-exporters/sems_mitm_exporter:latest\n    ports:\n    - \"20001:20001\"\n    restart: unless-stopped\n    environment:\n    - DEBUG=true\n```\n\n### Metrics exported\n\n\u003e [!NOTE]\n\u003e Only the useful metrics are listed here. Unlisted metrics which are also exported include:\n\u003e \n\u003e * Device metrics which aren't particularly useful (e.g. other values summed together).\n\u003e * Values which are unknown due to uncertainties when reverse engineering the packet structure (`*_unknown_*` variables). If you figure out what these are, please open an issue/PR.\n\nExcept where noted, all metrics are labelled with:\n\n* `device`\n* `model`\n* `serial`\n\n#### Homekit 1000\n\n| Metric                                         | Description                                           |\n| ---                                            | ---                                                   |\n| `meter_power_generation_watts`                 | Power generated by PV array.                          |\n| `meter_power_export_watts`                     | Power exported to the grid.                           |\n| `meter_energy_generation_decawatt_hours_total` | Cumulative energy generated.                          |\n| `meter_energy_export_decawatt_hours_total`     | Cumulative energy exported.                           |\n| `meter_energy_import_decawatt_hours_total`     | Cumulative energy imported.                           |\n| `batsignal_top`                                | Top of the batsignal. (only when `BATSIGNAL=true`)    |\n| `batsignal_bottom`                             | Bottom of the batsignal. (only when `BATSIGNAL=true`) |\n\n#### DNS G3\n\n| Metric                                              | Description                                       |\n| ---                                                 | ---                                               |\n| `inverter_input_voltage_dc_decivolts`               | Input DC voltage to inverter.                     |\n| `inverter_input_current_dc_deciamps`                | Input DC current to inverter.                     |\n| `inverter_output_voltage_ac_decivolts`              | Output AC voltage from inverter.                  |\n| `inverter_output_current_ac_deciamps`               | Output AC current from inverter.                  |\n| `inverter_output_frequency_ac_centihertz`           | Output AC frequency from inverter.                |\n| `inverter_power_output_watts`                       | Power output from inverter.                       |\n| `inverter_internal_temperature_decidegrees_celsius` | Internal temperature of inverter.                 |\n| `inverter_energy_output_hectowatt_hours_day`        | Cumulative energy output today.                   |\n| `inverter_energy_output_hectowatt_hours_total`      | Cumulative energy output total.                   |\n| `inverter_uptime_hours_total`                       | Inverter total operation time.                    |\n| `inverter_rssi_percent`                             | Inverter WLAN received signal strength indicator. |\n\n#### Exporter internals\n\n| Metric                              | Description                                          |\n| ---                                 | ---                                                  |\n| `meter_time_sync_packets_total`     | Count of outbound time sync packets.                 |\n| `meter_time_sync_ack_packets_total` | Count of outbound time sync acknowledgement packets. |\n| `meter_metrics_packets_total`       | Count of outbound metrics packets.                   |\n| `inbound_unknown_packets_total`     | Count of inbound unknown packets. (no labels)        |\n| `outbound_unknown_packets_total`    | Count of outbound unknown packets. (no labels)       |\n| `inverter_time_sync_packets_total`  | Count of outbound time sync packets.                 |\n| `inverter_metrics_packets_total`    | Count of outbound metrics packets.                   |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmlx%2Fgoodwe-exporters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmlx%2Fgoodwe-exporters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmlx%2Fgoodwe-exporters/lists"}