Back to Details

ha-sunsynk-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Works with Sunsynk/Deye hybrid inverters, api.sunsynk.net cloud API, and HA add-ons.
适用于Sunsynk/Deye混合逆变器、api.sunsynk.net云API以及Home Assistant（HA）插件。

Sunsynk/Deye Solar System Integration for Home Assistant

适用于Home Assistant的Sunsynk/Deye太阳能系统集成

Integrate Sunsynk and Deye solar inverters with Home Assistant using the cloud-based SolarSynkV3 add-on. This skill covers setup, configuration, entity patterns, and troubleshooting for reliable solar monitoring.
通过基于云的SolarSynkV3插件，将Sunsynk和Deye太阳能逆变器与Home Assistant集成。本指南涵盖设置、配置、实体规则和故障排查，助力实现可靠的太阳能监控。

Quick Start

快速开始

Working Integration Method:
yaml
undefined
可用的集成方法：
yaml
undefined

Add-on: SolarSynkV3 (Cloud API)

插件：SolarSynkV3 (Cloud API)

Repository: https://github.com/martinville/solarsynkv3

仓库：https://github.com/martinville/solarsynkv3

Add-on slug: d4ae3b04_solar_synkv3

插件标识：d4ae3b04_solar_synkv3

Configuration: sunsynk_user: "<your_sunsynk_account_email>" sunsynk_pass: "<your_sunsynk_account_password>" sunsynk_serial: "<INVERTER_SERIAL_FROM_PORTAL>" # CRITICAL: Use inverter serial! Home_Assistant_IP: "<ha_ip_address>" Home_Assistant_PORT: 8123 HA_LongLiveToken: "<ha_long_lived_token>" Refresh_rate: 300 API_Server: "api.sunsynk.net" # Region 2 (South Africa)

**Key Success Factor:** Use the **inverter serial number** from sunsynk.net portal (under Inverter menu), NOT the WiFi dongle serial. Using the wrong serial causes "No Permissions" API errors.
配置: sunsynk_user: "<your_sunsynk_account_email>" sunsynk_pass: "<your_sunsynk_account_password>" sunsynk_serial: "<INVERTER_SERIAL_FROM_PORTAL>" # 关键：使用逆变器序列号！ Home_Assistant_IP: "<ha_ip_address>" Home_Assistant_PORT: 8123 HA_LongLiveToken: "<ha_long_lived_token>" Refresh_rate: 300 API_Server: "api.sunsynk.net" # 区域2（南非）

**成功关键：** 使用sunsynk.net门户中「逆变器」菜单下的**逆变器序列号**，而非WiFi适配器序列号。使用错误序列号会导致API出现「无权限」错误。

Table of Contents

目录

  1. When to Use This Skill
  2. What This Skill Does
  3. Hardware Overview
  4. Integration Setup
  5. Entity Naming and Organization
  6. Monitoring and Dashboards
  7. Troubleshooting
  8. WiFi Dongle Limitations
  9. Alternative Integration Methods
  10. Supporting Files
  11. Requirements
  12. Red Flags to Avoid
  1. 适用场景
  2. 本指南涵盖内容
  3. 硬件概述
  4. 集成设置
  5. 实体命名与组织
  6. 监控与仪表板
  7. 故障排查
  8. WiFi适配器限制
  9. 替代集成方法
  10. 支持文件
  11. 要求
  12. 需避免的误区

When to Use This Skill

适用场景

Explicit Triggers:
  • "Set up sunsynk integration"
  • "Configure deye inverter home assistant"
  • "Add solar inverter to ha"
  • "Sunsynk no permissions error"
  • "SolarSynkV3 add-on setup"
  • "Monitor solar system in home assistant"
Implicit Triggers:
  • Working with Sunsynk/Deye hybrid inverters
  • Need battery SOC, PV power, grid import/export data
  • Building solar monitoring dashboards
  • Troubleshooting solar integration issues
Debugging Triggers:
  • API authentication failures
  • Missing sensor entities
  • Incorrect entity naming
  • Cloud API connection problems
明确触发场景：
  • 「搭建Sunsynk集成」
  • 「配置Home Assistant的Deye逆变器」
  • 「将太阳能逆变器添加到HA」
  • 「Sunsynk无权限错误」
  • 「SolarSynkV3插件设置」
  • 「在Home Assistant中监控太阳能系统」
隐含触发场景：
  • 使用Sunsynk/Deye混合逆变器
  • 需要电池SOC、光伏功率、电网导入/导出数据
  • 搭建太阳能监控仪表板
  • 排查太阳能集成问题
调试触发场景：
  • API认证失败
  • 传感器实体缺失
  • 实体命名错误
  • 云API连接问题

What This Skill Does

本指南涵盖内容

This skill provides:
  1. Integration Setup - Configure SolarSynkV3 add-on with correct parameters
  2. Entity Discovery - Understand entity naming patterns and sensor organization
  3. Configuration Validation - Verify critical settings (serial numbers, API servers)
  4. Troubleshooting Guidance - Resolve common integration issues
  5. Dashboard Planning - Identify key sensors for monitoring
本指南提供以下内容：
  1. 集成设置 - 配置SolarSynkV3插件的正确参数
  2. 实体发现 - 了解实体命名规则和传感器组织方式
  3. 配置验证 - 验证关键设置（序列号、API服务器）
  4. 故障排查指导 - 解决常见集成问题
  5. 仪表板规划 - 确定监控所需的关键传感器

Usage

使用方法

Follow the Quick Start section to configure the SolarSynkV3 add-on with correct parameters. Then use sections 4-7 for integration setup, entity discovery, monitoring dashboards, and troubleshooting. Always use the inverter serial number (not dongle serial) to avoid "No Permissions" errors.
按照「快速开始」部分配置SolarSynkV3插件的正确参数。然后使用第4-7节完成集成设置、实体发现、监控仪表板搭建和故障排查。请务必使用逆变器序列号（而非适配器序列号），以避免出现「无权限」错误。

Hardware Overview

硬件概述

Typical Sunsynk/Deye Setup:
ComponentPurposeDetails
InverterDC-AC conversion, battery managementDeye 8kW Hybrid (example: SN 2305178402)
WiFi DongleCloud connectivitySunsynk dongle (example: E47W23428459)
BatteryEnergy storage280Ah capacity, 48V nominal (typical)
PV ArraySolar panels2 MPPT strings (typical)
Example Plant Information:
  • Inverter Serial: 2305178402 (use THIS for integration)
  • WiFi Dongle Serial: E47W23428459 (NOT used for config)
  • Location: South Africa (Region 2)
  • Cloud Portal: https://sunsynk.net
典型Sunsynk/Deye设置：
组件用途详情
逆变器直流-交流转换、电池管理Deye 8kW混合逆变器（示例：序列号2305178402）
WiFi适配器云端连接Sunsynk适配器（示例：E47W23428459）
电池储能280Ah容量，额定48V（典型配置）
光伏阵列太阳能板2组MPPT串（典型配置）
示例电站信息：
  • 逆变器序列号：2305178402（集成时使用此序列号）
  • WiFi适配器序列号：E47W23428459（配置时不使用）
  • 位置：南非（区域2）
  • 云门户：https://sunsynk.net

Integration Setup

集成设置

4.1. Add-on Installation

4.1 插件安装

Step 1: Add Repository to HACS or Add-on Store
Via Home Assistant:
  1. Navigate to Settings > Add-ons > Add-on Store
  2. Click ⋮ (three dots) > Repositories
  3. Add repository: 
    https://github.com/martinville/solarsynkv3
  4. Install SolarSynkV3 add-on
Step 2: Identify Add-on
Add-on slug: 
d4ae3b04_solar_synkv3
Configuration URL: 
http://<ha_ip>:8123/hassio/addon/d4ae3b04_solar_synkv3/config
步骤1：将仓库添加到HACS或插件商店
通过Home Assistant操作：
  1. 导航至设置 > 插件 > 插件商店
  2. 点击**⋮**（三个点）> 仓库
  3. 添加仓库：
    https://github.com/martinville/solarsynkv3
  4. 安装SolarSynkV3插件
步骤2：确认插件
插件标识：
d4ae3b04_solar_synkv3
配置URL：
http://<ha_ip>:8123/hassio/addon/d4ae3b04_solar_synkv3/config

4.2. Configuration Parameters

4.2 配置参数

yaml
sunsynk_user: "your_email@example.com"
sunsynk_pass: "your_sunsynk_password"
sunsynk_serial: "2305178402"  # INVERTER serial from portal
Home_Assistant_IP: "192.168.68.123"
Home_Assistant_PORT: 8123
HA_LongLiveToken: "<your_ha_long_lived_token>"
Refresh_rate: 300  # 5 minutes (recommended)
API_Server: "api.sunsynk.net"  # Region 2 (South Africa)
use_internal_api: false
Enable_HTTPS: false  # Use true if HA has HTTPS
Parameter Reference:
ParameterPurposeExample
sunsynk_user
Account email for sunsynk.netyour_email@example.com
sunsynk_pass
Account passwordyour_password
sunsynk_serial
INVERTER serial (NOT dongle)2305178402
Home_Assistant_IP
HA instance IP address192.168.68.123
Home_Assistant_PORT
HA HTTP port8123
HA_LongLiveToken
Long-lived access token from HAeyJ0eXAiOiJKV1QiLCJhb...
Refresh_rate
Polling interval (seconds)300 (5 min)
API_Server
Regional API endpointapi.sunsynk.net
Regional API Servers:
RegionAPI Server
Region 1 (Global)api-internal.sunsynk.net
Region 2 (South Africa)api.sunsynk.net
Region 3 (Europe)api-eu.sunsynk.net
yaml
sunsynk_user: "your_email@example.com"
sunsynk_pass: "your_sunsynk_password"
sunsynk_serial: "2305178402"  # 门户中的逆变器序列号
Home_Assistant_IP: "192.168.68.123"
Home_Assistant_PORT: 8123
HA_LongLiveToken: "<your_ha_long_lived_token>"
Refresh_rate: 300  # 5分钟（推荐）
API_Server: "api.sunsynk.net"  # 区域2（南非）
use_internal_api: false
Enable_HTTPS: false  # 若HA启用HTTPS则设为true
参数说明：
参数用途示例
sunsynk_user
sunsynk.net账户邮箱your_email@example.com
sunsynk_pass
账户密码your_password
sunsynk_serial
逆变器序列号（非适配器）2305178402
Home_Assistant_IP
HA实例IP地址192.168.68.123
Home_Assistant_PORT
HA HTTP端口8123
HA_LongLiveToken
HA的长期访问令牌eyJ0eXAiOiJKV1QiLCJhb...
Refresh_rate
轮询间隔（秒）300（5分钟）
API_Server
区域API端点api.sunsynk.net
区域API服务器：
区域API服务器
区域1（全球）api-internal.sunsynk.net
区域2（南非）api.sunsynk.net
区域3（欧洲）api-eu.sunsynk.net

4.3. Finding Your Inverter Serial

4.3 查找逆变器序列号

CRITICAL: Use the inverter serial number, NOT the WiFi dongle serial.
How to Find Inverter Serial:
  1. Log into https://sunsynk.net (or your regional portal)
  2. Navigate to your plant/system
  3. Click Inverter menu or device details
  4. Look for serial number starting with digits (e.g., 
    2305178402
    )
  5. Do NOT use the dongle serial (alphanumeric, e.g., 
    E47W23428459
    )
Visual Identification:
Inverter Serial:  2305178402        ✓ USE THIS
Dongle Serial:    E47W23428459      ✗ NOT THIS
关键： 使用逆变器序列号，而非WiFi适配器序列号。
查找逆变器序列号的方法：
  1. 登录https://sunsynk.net（或对应区域的门户）
  2. 导航至您的电站/系统
  3. 点击逆变器菜单或设备详情
  4. 查找以数字开头的序列号（例如：
    2305178402
    ）
  5. 请勿使用适配器序列号（字母数字组合，例如：
    E47W23428459
    ）
直观区分：
逆变器序列号:  2305178402        ✓ 请使用此序列号
适配器序列号:    E47W23428459      ✗ 请勿使用

Entity Naming and Organization

实体命名与组织

5.1. Entity ID Pattern

5.1 实体ID规则

All entities follow this pattern:
sensor.solarsynkv3_{INVERTER_SERIAL}_{SENSOR_NAME}
Example:
sensor.solarsynkv3_2305178402_battery_soc
sensor.solarsynkv3_2305178402_pv_pac
sensor.solarsynkv3_2305178402_load_total_power
所有实体遵循以下规则：
sensor.solarsynkv3_{INVERTER_SERIAL}_{SENSOR_NAME}
示例：
sensor.solarsynkv3_2305178402_battery_soc
sensor.solarsynkv3_2305178402_pv_pac
sensor.solarsynkv3_2305178402_load_total_power

5.2. Key Sensor Categories

5.2 关键传感器类别

Most Important Sensors for Dashboards:
CategoryEntity IDDescriptionUnit
Battery
battery_soc
State of Charge%
battery_power
Charge/discharge powerW
PV/Solar
pv_pac
Total solar powerW
pv_etoday
Today's solar yieldkWh
Grid
grid_pac
Grid import/exportW
grid_etoday_from
Today importedkWh
grid_etoday_to
Today exportedkWh
Load
load_total_power
Total consumptionW
load_daily_used
Today's usagekWh
Inverter
inverter_power
Inverter outputW
runstatus
Status (Normal/Fault)-
Power Flow Understanding:
PV → Inverter → [ Battery / Load / Grid ]
              ↑
         Grid Import (if needed)
仪表板常用重要传感器：
类别实体ID描述单位
电池
battery_soc
剩余电量%
battery_power
充放电功率W
光伏/太阳能
pv_pac
总太阳能功率W
pv_etoday
当日太阳能发电量kWh
电网
grid_pac
电网导入/导出功率W
grid_etoday_from
当日电网导入量kWh
grid_etoday_to
当日电网导出量kWh
负载
load_total_power
总耗电量W
load_daily_used
当日耗电量kWh
逆变器
inverter_power
逆变器输出功率W
runstatus
状态（正常/故障）-
功率流向说明：
光伏 → 逆变器 → [ 电池 / 负载 / 电网 ]
              ↑
         电网补充（若需）

5.3. Complete Sensor Reference

5.3 完整传感器参考

For a complete list of all 300+ available sensors across Battery, PV/Solar, Grid, Load, Inverter, and Energy categories, see references/sensor-reference.md.
如需查看电池、光伏/太阳能、电网、负载、逆变器和能源类别下的300+可用传感器完整列表，请参阅references/sensor-reference.md。

Monitoring and Dashboards

监控与仪表板

Essential Dashboard Components:
For complete dashboard examples including power flow charts, battery gauges, and daily energy summaries, see examples/dashboard-config.yaml.
Quick REST API Access:
bash
undefined
必备仪表板组件：
如需包含功率流向图、电池仪表和每日能源汇总的完整仪表板示例，请参阅examples/dashboard-config.yaml。
快速REST API访问：
bash
undefined

Get battery state of charge

获取电池剩余电量

curl -s "http://<ha_ip>:8123/api/states/sensor.solarsynkv3_2305178402_battery_soc"
-H "Authorization: Bearer $HA_LONG_LIVED_TOKEN"
undefined
curl -s "http://<ha_ip>:8123/api/states/sensor.solarsynkv3_2305178402_battery_soc"
-H "Authorization: Bearer $HA_LONG_LIVED_TOKEN"
undefined

Troubleshooting

故障排查

7.1. "No Permissions" Error

7.1 「无权限」错误

Symptom: Add-on logs show "No Permissions" or API authentication failures.
Root Cause: Using WiFi dongle serial instead of inverter serial.
Solution:
  1. Log into sunsynk.net portal
  2. Navigate to Inverter menu (not device/dongle settings)
  3. Copy the inverter serial (numeric, e.g., 
    2305178402
    )
  4. Update add-on configuration with correct serial
  5. Restart add-on
Verification:
bash
undefined
症状： 插件日志显示「无权限」或API认证失败。
根本原因： 使用WiFi适配器序列号而非逆变器序列号。
解决方案：
  1. 登录sunsynk.net门户
  2. 导航至逆变器菜单（而非设备/适配器设置）
  3. 复制逆变器序列号（纯数字，例如：
    2305178402
    ）
  4. 更新插件配置中的正确序列号
  5. 重启插件
验证方法：
bash
undefined

Check add-on logs

查看插件日志

ha addons logs d4ae3b04_solar_synkv3
ha addons logs d4ae3b04_solar_synkv3

Look for successful authentication

查找认证成功信息

Expected: "Connected to API" or similar success message

预期结果：「Connected to API」或类似成功提示


**Alternative Causes:**
- Account lacks API access (installer accounts may be restricted)
- Wrong API server for your region
- Incorrect username/password

**其他可能原因：**
- 账户无API访问权限（安装账户可能受限）
- API服务器与所在区域不匹配
- 用户名/密码错误

7.2. No Sensors Appearing

7.2 无传感器显示

Symptom: Add-on running but no entities created in HA.
Diagnostic Steps:
  1. Check Add-on Logs:
    bash
    ha addons logs d4ae3b04_solar_synkv3
    Look for errors during sensor creation.
  2. Verify HA Connection: Check if add-on can reach HA API:
    • Confirm 
      Home_Assistant_IP
      is correct
    • Verify 
      HA_LongLiveToken
      is valid
    • Check HA firewall rules
  3. Force Entity Discovery:
    • Restart Home Assistant core
    • Reload integration from Settings > Devices & Services
    • Check Developer Tools > States for entities starting with 
      sensor.solarsynkv3_
  4. Check Entity Registry:
    bash
    # Search for solarsynk entities
curl -s "http://<ha_ip>:8123/api/states" \
  -H "Authorization: Bearer $HA_LONG_LIVED_TOKEN" | \
  jq '.[] | select(.entity_id | contains("solarsynk"))'
症状： 插件运行正常，但HA中未创建任何实体。
诊断步骤：
  1. 查看插件日志：
    bash
    ha addons logs d4ae3b04_solar_synkv3
    查找传感器创建过程中的错误。
  2. 验证HA连接： 检查插件是否能访问HA API：
    • 确认
      Home_Assistant_IP
      正确
    • 验证
      HA_LongLiveToken
      有效
    • 检查HA防火墙规则
  3. 强制实体发现：
    • 重启Home Assistant核心
    • 从「设置」>「设备与服务」重新加载集成
    • 在「开发者工具」>「状态」中查找以
      sensor.solarsynkv3_
      开头的实体
  4. 检查实体注册表：
    bash
    # 搜索Sunsynk实体
curl -s "http://<ha_ip>:8123/api/states" \
  -H "Authorization: Bearer $HA_LONG_LIVED_TOKEN" | \
  jq '.[] | select(.entity_id | contains("solarsynk"))'

7.3. Connection Test Issues

7.3 连接测试异常

Symptom: Connection test shows unusual values (e.g., 100A current).
Interpretation:
  • Test data showing 100A is often a dummy/test value
  • Indicates HA connection is OK
  • Actual issue may be with Sunsynk API authentication
Action:
  • Don't focus on test values
  • Check API authentication in logs
  • Verify inverter serial and credentials
症状： 连接测试显示异常值（例如：100A电流）。
解读：
  • 显示100A的测试数据通常是虚拟/测试值
  • 说明HA连接正常
  • 实际问题可能出在Sunsynk API认证
操作建议：
  • 无需关注测试值
  • 查看日志中的API认证情况
  • 验证逆变器序列号和凭证

WiFi Dongle Limitations

WiFi适配器限制

Stock Sunsynk WiFi Dongle:
The stock WiFi dongle (e.g., 
E47W23428459
) is cloud-only - it does NOT expose local Modbus/TCP ports.
Port Scan Results:
bash
nmap -p 8899,502,6666 <dongle_ip>
原厂Sunsynk WiFi适配器：
原厂WiFi适配器（例如：
E47W23428459
）仅支持云端连接，不暴露本地Modbus/TCP端口。
端口扫描结果：
bash
nmap -p 8899,502,6666 <dongle_ip>

Result: All ports closed

结果：所有端口均关闭


**Why Local Integration Won't Work:**

- Kellerza/sunsynk integration requires Modbus access (port 502 or 8899)
- Stock dongle firmware blocks all local network access
- Only cloud API path is available

**Alternatives for Local Integration:**

1. **Replace Dongle:**
   - Use Solarman LSW-3 dongle (supports local Modbus)
   - Cost: ~$50-100 USD

2. **Custom Firmware:**
   - Flash ESPHome to ESP-based dongle
   - Requires hardware expertise
   - Risk of bricking dongle

3. **Direct RS485 Connection:**
   - Connect Raspberry Pi or ESP32 directly to inverter RS485 ports
   - Use Modbus RTU protocol
   - Most complex but most reliable

**Recommendation:** Use cloud API (SolarSynkV3) unless you have strong requirement for local-only control.

**本地集成不可用原因：**

- Kellerza/sunsynk集成需要Modbus访问权限（端口502或8899）
- 原厂适配器固件阻止所有本地网络访问
- 仅支持云API路径

**本地集成替代方案：**

1. **更换适配器：**
   - 使用Solarman LSW-3适配器（支持本地Modbus）
   - 成本：约50-100美元

2. **自定义固件：**
   - 为基于ESP的适配器刷入ESPHome固件
   - 需要硬件专业知识
   - 存在适配器变砖风险

3. **直接RS485连接：**
   - 将树莓派或ESP32直接连接到逆变器RS485端口
   - 使用Modbus RTU协议
   - 复杂度最高但可靠性最强

**建议：** 除非对本地控制有强烈需求，否则推荐使用云API（SolarSynkV3）。

Alternative Integration Methods

替代集成方法

Comparison of Methods:
MethodTypeProsCons
SolarSynkV3Cloud APIEasy setup, no hardware changesDepends on cloud service
Kellerza/SunsynkLocal ModbusFast updates, local controlRequires dongle replacement
HASS-Sunsynk-MultiLocal ModbusMultiple inverter supportStock dongle incompatible
ESPHome CustomDirect RS485Full control, no cloudComplex setup, DIY hardware
When to Use Each:
  • Cloud API (SolarSynkV3) - Default choice for most users
  • Local Modbus - When cloud is unreliable or privacy-sensitive
  • ESPHome/Direct - Advanced users, custom automation requirements
方法对比：
方法类型优点缺点
SolarSynkV3云API设置简单，无需更改硬件依赖云端服务
Kellerza/Sunsynk本地Modbus更新速度快，支持本地控制需要更换适配器
HASS-Sunsynk-Multi本地Modbus支持多逆变器与原厂适配器不兼容
ESPHome自定义直接RS485连接完全控制，无需云端设置复杂，需DIY硬件
各方法适用场景：
  • 云API（SolarSynkV3） - 大多数用户的默认选择
  • 本地Modbus - 云端服务不可靠或对隐私有要求时
  • ESPHome/直接连接 - 高级用户，有自定义自动化需求时

Supporting Files

支持文件

References:
  • references/sensor-reference.md
    - Complete list of 300+ entities with descriptions
  • references/api-specification.md
    - Sunsynk API endpoints and authentication
  • references/modbus-registers.md
    - Modbus register map for direct integration
Examples:
  • examples/dashboard-config.yaml
    - Complete solar dashboard example
  • examples/automations.yaml
    - Battery management automations
  • examples/api-queries.sh
    - REST API query examples
Scripts:
  • scripts/verify-integration.py
    - Test integration and list available entities
  • scripts/entity-discovery.py
    - Discover all Sunsynk entities in HA
  • scripts/generate-sensor-list.sh
    - Export sensor list from add-on logs
参考文档：
  • references/sensor-reference.md
    - 300+实体的完整列表及描述
  • references/api-specification.md
    - Sunsynk API端点与认证说明
  • references/modbus-registers.md
    - 直接集成用Modbus寄存器映射表
示例文件：
  • examples/dashboard-config.yaml
    - 完整太阳能仪表板示例
  • examples/automations.yaml
    - 电池管理自动化示例
  • examples/api-queries.sh
    - REST API查询示例
脚本文件：
  • scripts/verify-integration.py
    - 测试集成并列出可用实体
  • scripts/entity-discovery.py
    - 发现HA中所有Sunsynk实体
  • scripts/generate-sensor-list.sh
    - 从插件日志导出传感器列表

Requirements

要求

Hardware:
  • Sunsynk or Deye hybrid inverter
  • WiFi dongle (cloud-connected)
  • Home Assistant instance
Software:
  • Home Assistant 2023.1+ (for add-on support)
  • Add-on Store or HACS access
  • Long-lived access token
Access:
  • Sunsynk.net account credentials
  • Inverter serial number (from portal)
  • Network access to Home Assistant
Knowledge:
  • Basic Home Assistant configuration
  • YAML syntax (for dashboards)
  • REST API usage (optional, for scripting)
硬件：
  • Sunsynk或Deye混合逆变器
  • WiFi适配器（已连接云端）
  • Home Assistant实例
软件：
  • Home Assistant 2023.1+（支持插件）
  • 可访问插件商店或HACS
  • 长期访问令牌
访问权限：
  • Sunsynk.net账户凭证
  • 逆变器序列号（来自门户）
  • 可访问Home Assistant的网络环境
知识储备：
  • 基础Home Assistant配置知识
  • YAML语法（用于仪表板）
  • REST API使用知识（可选，用于脚本）

Red Flags to Avoid

需避免的误区

Configuration Mistakes:
  • Using WiFi dongle serial instead of inverter serial
  • Wrong API server for your region
  • Forgetting to restart add-on after config changes
  • Using expired or invalid HA token
Integration Issues:
  • Expecting local Modbus from stock WiFi dongle
  • Installing multiple conflicting Sunsynk add-ons
  • Not checking add-on logs during troubleshooting
  • Assuming test values are real sensor data
Dashboard/Automation Problems:
  • Hardcoding entity IDs without checking they exist
  • Not accounting for negative values (battery_power)
  • Using instantaneous power for energy calculations
  • Polling too frequently (< 60 second refresh rate)
Security:
  • Storing credentials in YAML files
  • Using admin account instead of restricted API user
  • Exposing HA token in public repositories
  • Not using HTTPS when HA is internet-accessible
配置错误：
  • 使用WiFi适配器序列号而非逆变器序列号
  • API服务器与所在区域不匹配
  • 更改配置后未重启插件
  • 使用过期或无效的HA令牌
集成问题：
  • 期望原厂WiFi适配器支持本地Modbus
  • 安装多个冲突的Sunsynk插件
  • 故障排查时未查看插件日志
  • 将测试值视为真实传感器数据
仪表板/自动化问题：
  • 硬编码实体ID而未确认其存在
  • 未考虑负值（如battery_power）
  • 使用瞬时功率计算能源数据
  • 轮询频率过高（刷新间隔<60秒）
安全问题：
  • 在YAML文件中存储凭证
  • 使用管理员账户而非受限API用户
  • 在公共仓库中暴露HA令牌
  • 当HA可访问互联网时未启用HTTPS

Notes

注意事项

Refresh Rate Considerations:
  • 300 seconds (5 minutes) is recommended default
  • Faster polling may hit API rate limits
  • Slower polling reduces cloud service load
Entity Count:
  • Expect 300-400 entities depending on inverter model
  • Disable unused entities to reduce database size
  • Group related entities for dashboard organization
Cloud Dependency:
  • Integration requires internet access to api.sunsynk.net
  • Local network outage won't affect monitoring if HA has internet
  • Consider UPS for router and HA server
Support Resources:
刷新间隔注意事项：
  • 推荐默认值为300秒（5分钟）
  • 轮询频率过快可能触发API速率限制
  • 轮询频率过慢可降低云端服务负载
实体数量：
  • 根据逆变器型号，预计会有300-400个实体
  • 禁用未使用的实体以减少数据库占用
  • 对相关实体进行分组，便于仪表板管理
云端依赖：
  • 集成需要互联网访问api.sunsynk.net
  • 若HA可访问互联网，本地网络中断不会影响监控
  • 建议为路由器和HA服务器配备UPS
支持资源：