bohdans/sungather

SunGather

镜像概述和主要用途

SunGather 是一款用于从网络连接的阳光(Sungrow)逆变器收集数据的工具，通过 ModbusTcpClient、SungrowModbusTcpClient 或 SungrowModbusWebClient 实现数据采集，并支持导出到多种目标位置。首次连接时，工具会自动查询逆变器型号并返回对应寄存器，无需手动查找或创建型号文件。

核心功能和特性

• 自动设备识别：首次连接自动查询逆变器型号，返回正确寄存器
• 多导出方式：支持控制台输出、MQTT、PVOutput.org、InfluxDB、Prometheus、Web服务器等
• Home Assistant 集成：作为 HassIO 插件提供完整支持，包含自动发现功能
• 灵活配置：通过配置文件设置数据采集级别、智能电表支持等
• 跨平台支持：兼容 Raspberry Pi 等设备，提供 Docker 部署选项

使用场景和适用范围

适用于拥有阳光(Sungrow)逆变器的用户，需要监控逆变器运行数据（如发电量、温度、功率等）并集成到智能家居系统、数据监控平台或可视化工具中。特别适合希望将太阳能数据整合到 Home Assistant、Grafana 等系统的用户。

详细使用方法和配置说明

系统要求

• Python 3
• 依赖库：paho-mqtt、pymodbus、SungrowModbusTcpClient、SungrowModbusWebClient、PyYAML、requests、influxdb-client

本地安装

bash
git clone https://github.com/bohdan-s/SunGather.git
cd SunGather
pip3 install --upgrade -r requirements.txt

复制配置文件并修改：

bash
cd SunGather
cp config-example.yaml config.yaml

运行：

bash
python3 sungather.py

Docker 部署

Docker Run 命令

bash
docker pull bohdans/sungather
docker run -d --name sungather \
  --restart always \
  -v {本地配置文件路径}:/config/config.yaml \
  -v {日志路径}:/logs \
  -e TZ=Asia/Shanghai \
  -p 8080:8080 \
  bohdans/sungather

Docker 参数说明

• -v {本地配置文件路径}:/config/config.yaml：挂载配置文件
• -v {日志路径}:/logs：挂载日志目录（需在配置文件中设置 log_file）
• -e TZ=Asia/Shanghai：设置时区
• -p 8080:8080：映射 Web 服务器端口（如使用 webserver 导出）

配置文件说明

配置文件（config.yaml）包含以下关键部分：

逆变器设置

yaml
inverters:
  - name: Inverter1
    type: tcp  # 或 web
    host: 192.168.1.100  # 逆变器IP
    port: 502  # Modbus端口
    level: 1  # 数据采集级别：1（日常使用）、2（全部支持数据）、3（所有寄存器，包含不支持项）
    smart_meter: True  # SG*型号需启用智能电表（SH*混合逆变器默认支持）

导出配置

支持多种导出方式，示例：

yaml
exports:
  - name: console
    enabled: True  # 控制台输出，用于调试
  
  - name: mqtt
    enabled: True
    host: 192.168.1.200  # MQTT服务器IP
    port: 1883
    homeassistant: True  # 启用Home Assistant自动发现
  
  - name: influxdb
    enabled: True
    url: http://192.168.1.201:8086
    token: your-token
    org: your-org
    bucket: sungather

命令行参数

命令行参数可覆盖配置文件设置：

• -c config.yaml：指定配置文件路径
• -r registersfile.yaml：指定寄存器文件
• -v 30：日志级别（10=调试，20=信息，30=警告（默认），40=错误）
• --runonce：运行一次后退出
• -h/--help：显示帮助信息

示例：

bash
python3 sungather.py -c /full/path/config.yaml -v 20 --runonce

常用寄存器说明

Home Assistant 集成

1. 在配置文件中启用 MQTT 并开启 Home Assistant 自动发现：

yaml
exports:
  - name: mqtt
    enabled: True
    host: 192.168.1.200  # Home Assistant MQTT服务器IP
    homeassistant: True

2. 对于 SG*型号逆变器，需启用智能电表：

yaml
inverters:
  - name: Inverter1
    # ... 其他配置
    smart_meter: True

3. 在 Home Assistant 中，可通过 Energy 面板添加以下数据：
   • 电网消耗：每日从电网输入
   • 电网反馈：每日向电网输出
   • 太阳能发电：每日发电量

支持的设备

光伏并网 string 逆变器

SG30KTL、SG10KTL、SG12KTL、SG15KTL、SG20KTL、SG30KU、SG36KTL、SG36KU、SG40KTL、SG40KTL-M、SG50KTL-M、SG60KTL-M、SG60KU、SG30KTL-M、SG30KTL-M-V31、SG33KTL-M、SG36KTL-M、SG33K3J、SG49K5J、SG34KJ、LP_P34KSG、SG50KTL-M-20、SG60KTL、SG80KTL、SG80KTL-20、SG60KU-M、SG5KTL-MT、SG6KTL-MT、SG8KTL-M、SG10KTL-M、SG10KTL-MT、SG12KTL-M、SG15KTL-M、SG17KTL-M、SG20KTL-M、SG80KTL-M、SG111HV、SG125HV、SG125HV-20、SG30CX、SG33CX、SG36CX-US、SG40CX、SG50CX、SG60CX-US、SG110CX、SG250HX、SG250HX-US、SG100CX、SG100CX-JP、SG250HX-IN、SG25CX-SA、SG75CX、SG3.0RT、SG4.0RT、SG5.0RT、SG6.0RT、SG7.0RT、SG8.0RT、SG10RT、SG12RT、SG15RT、SG17RT、SG20RT

第二代光伏并网 string 逆变器

SG5K-D、SG8K-D

户用混合逆变器

SH5K-20、SH3K6、SH4K6、SH5K-V13、SH5K-30、SH3K6-30、SH4K6-30、SH5.0RS、SH3.6RS、SH4.6RS、SH6.0RS、SH10RT(-V112)、SH8.0RT、SH6.0RT、SH5.0RT

测试过的设备

• SG7.0RT 带 WiNet-S dongle
• SG10RT 带 WiNet-S dongle 和以太网（@rark-ha 贡献）
• SH6.0RT 带 WiNet-S dongle
• SH10RT(-V112) 带 WiNet-S dongle 和以太网

许可证

采用 GPL3 许可证。详见 https://github.com/bohdan-s/SunGather/blob/main/LICENSE.txt%E3%80%82

项目链接

https://github.com/bohdan-s/SunGather