bushrangers/ha-voltronic-mqtt

基于Docker的MPP/Voltronic太阳能逆变器Home Assistant接口

镜像概述和主要用途

本项目源自'skymax' C语言监控应用，旨在从Voltronic、Axpert、Mppsolar PIP、Voltacon、Effekta及其他OEM品牌逆变器获取监控数据，并发送到https://www.home-assistant.io/ MQTT服务器进行数据 ingestion。程序还可通过MQTT接收来自Home Assistant的命令，实现逆变器状态的远程控制。

核心功能和特性

• 数据采集与传输：实时读取逆变器数据并通过MQTT发送至Home Assistant
• 远程控制：支持通过MQTT接收命令，远程修改逆变器状态
• 复杂自动化：可实现多种自动化场景，如：
  • 白天切换至"太阳能优先"模式，傍晚切换至"电网充电"模式；雨天自动切换至"太阳能与市电混合充电"模式
  • 基于温度传感器动态调整充放电电压，避免电池因温度过高/过低受损
  • 动态调整逆变器"太阳能功率平衡"及其他配置，优化系统性能

使用场景和适用范围

适用于需要监控和远程管理Voltronic/Axpert系列太阳能逆变器的用户，特别适合：

• 家庭太阳能系统用户
• Home Assistant智能家居用户
• 需要实现太阳能系统自动化控制的场景
• 可部署在轻量级单板计算机（如Orange Pi Zero）上，通过逆变器的RS232或USB端口读取数据

!示例Lovelace仪表板 示例1：使用逆变器数据构建的Lovelace仪表板，支持通过MQTT更改模式/配置

!示例Grafana仪表板 示例2：Grafana数据汇总，支持详细数据分析和历史数据深度挖掘

详细使用方法和配置说明

Docker Hub地址

https://hub.docker.com/r/bushrangers/ha-voltronic-mqtt/

!https://img.shields.io/github/license/ned-kelly/docker-voltronic-homeassistant.svg !https://img.shields.io/docker/pulls/bushrangers/ha-voltronic-mqtt.png

前提条件

• Docker
• Docker-compose
• Voltronic/Axpert/MPPSolar系列逆变器
• 运行MQTT服务器的Home Assistant环境(https://www.home-assistant.io/components/mqtt/)

配置与部署

1. 获取源码并配置

bash
# 在监控主机上克隆源码
git clone https://github.com/ned-kelly/docker-voltronic-homeassistant.git /opt/ha-inverter-mqtt-agent
cd /opt/ha-inverter-mqtt-agent

# 配置设备连接（RS232或USB）
vi config/inverter.conf

# 配置MQTT服务器信息（IP/主机名、端口、凭据、HA主题及逆变器名称）
# 若MQTT服务器无需用户名/密码，留空即可
vi config/mqtt.json

2. 启动容器

将串口或USB电缆连接至逆变器后，启动容器：

bash
docker-compose up -d

注意：Docker Hub上的镜像当前为x64架构。若在Linux发行版（如树莓派/ARM设备）上部署遇到问题，需手动构建镜像，可通过取消docker-compose.yml中的build标志实现。

Home Assistant集成

若已在Home Assistant中配置MQTT，容器首次启动时设备将自动注册，无需手动定义传感器。

数据可视化与控制

• 可通过https://www.home-assistant.io/lovelace/history-graph/%E5%B1%95%E7%A4%BA%E4%BC%A0%E6%84%9F%E5%99%A8%E6%95%B0%E6%8D%AE
• 通过https://www.home-assistant.io/docs/mqtt/service/%E5%8F%AF%E6%9B%B4%E6%94%B9%E9%80%86%E5%8F%98%E5%99%A8%E7%8A%B6%E6%80%81

!更改充电优先级示例 示例：更改逆变器的充电优先级

常用逆变器命令

（完整命令列表参见协议手册）

注意：首次设置充放电电压时，建议参考电池大学指南优化充电条件，延长电池寿命。

直接使用inverter_poller二进制文件

本项目基于https://github.com/manio/skymax-demo%E4%BF%AE%E6%94%B9%EF%BC%8C%E5%8F%AF%E7%BC%96%E8%AF%91%E4%B8%BA%E7%8B%AC%E7%AB%8B%E7%A8%8B%E5%BA%8F%E5%9C%A8Linux%E3%80%81Mac%E5%92%8CWindows%EF%BC%88%E9%80%9A%E8%BF%87Cygwin%EF%BC%89%E4%B8%8A%E8%BF%90%E8%A1%8C%E3%80%82

编译方法

bash
cd sources/inverter-cli
cmake . && make

支持的参数

用法:  ./inverter_poller <参数> [-r <命令>], [-h | --help], [-1 | --run-once]

支持的参数:
          -r <原始命令>      向逆变器发送原始命令
          -h | --help        显示帮助信息
          -1 | --run-once    执行一次逆变器数据采集后退出
          -d                 启用额外调试信息

附加：Lovelace仪表板文件

请参考上述截图查看仪表板示例

homeassistant/目录中提供了Lovelace仪表板文件，需根据Home Assistant配置及mqtt.json中定义的逆变器名称进行调整。使用示例模板需安装以下自定义Lovelace卡片：

• https://github.com/custom-cards/vertical-stack-in-card
• https://github.com/custom-cards/circle-sensor-card