dawiddutoit/custom-claude/ha-sunsynk-integration

Works with Sunsynk/Deye hybrid inverters, api.sunsynk.net cloud API, and HA add-ons.

Sunsynk/Deye Solar System Integration for Home Assistant

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.

Quick Start

Working Integration Method:

# Add-on: SolarSynkV3 (Cloud API)
# Repository: https://github.com/martinville/solarsynkv3
# Add-on slug: 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.

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

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

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

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.

Hardware Overview

Typical Sunsynk/Deye Setup:

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

Integration Setup

4.1. Add-on Installation

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

4.2. Configuration Parameters

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:

Regional API Servers:

4.3. Finding Your Inverter Serial

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

Entity Naming and Organization

5.1. Entity ID Pattern

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

5.2. Key Sensor Categories

Most Important Sensors for Dashboards:

Power Flow Understanding:

PV → Inverter → [ Battery / Load / Grid ]
              ↑
         Grid Import (if needed)

5.3. Complete Sensor Reference

For a complete list of all 300+ available sensors across Battery, PV/Solar, Grid, Load, Inverter, and Energy categories, see 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:

# 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"

Troubleshooting

7.1. "No Permissions" Error

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:

# Check add-on logs
ha addons logs d4ae3b04_solar_synkv3
 
# Look for successful authentication
# Expected: "Connected to API" or similar success message

Alternative Causes:

• Account lacks API access (installer accounts may be restricted)
• Wrong API server for your region
• Incorrect username/password

7.2. No Sensors Appearing

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.

1. 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

1. Force Entity Discovery:

• Restart Home Assistant core
• Reload integration from Settings > Devices & Services
• Check Developer Tools > States for entities starting with sensor.solarsynkv3_

1. 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"))' ``

7.3. Connection Test Issues

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

WiFi Dongle Limitations

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:

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

1. Custom Firmware:

• Flash ESPHome to ESP-based dongle
• Requires hardware expertise
• Risk of bricking dongle

1. 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.

Alternative Integration Methods

Comparison of Methods:

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

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