ha-sunsynk-integration

What this skill does

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:**
```yaml
# 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:**

| Component | Purpose | Details |
|-----------|---------|---------|
| **Inverter** | DC-AC conversion, battery management | Deye 8kW Hybrid (example: SN 2305178402) |
| **WiFi Dongle** | Cloud connectivity | Sunsynk dongle (example: E47W23428459) |
| **Battery** | Energy storage | 280Ah capacity, 48V nominal (typical) |
| **PV Array** | Solar panels | 2 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

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

```yaml
sunsynk_user: "[email protected]"
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:**

| Parameter | Purpose | Example |
|-----------|---------|---------|
| `sunsynk_user` | Account email for sunsynk.net | [email protected] |
| `sunsynk_pass` | Account password | your_password |
| `sunsynk_serial` | **INVERTER** serial (NOT dongle) | 2305178402 |
| `Home_Assistant_IP` | HA instance IP address | 192.168.68.123 |
| `Home_Assistant_PORT` | HA HTTP port | 8123 |
| `HA_LongLiveToken` | Long-lived access token from HA | eyJ0eXAiOiJKV1QiLCJhb... |
| `Refresh_rate` | Polling interval (seconds) | 300 (5 min) |
| `API_Server` | Regional API endpoint | api.sunsynk.net |

**Regional API Servers:**

| Region | API Server |
|--------|------------|
| Region 1 (Global) | api-internal.sunsynk.net |
| Region 2 (South Africa) | api.sunsynk.net |
| Region 3 (Europe) | api-eu.sunsynk.net |

### 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:**

| Category | Entity ID | Description | Unit |
|----------|-----------|-------------|------|
| **Battery** | `battery_soc` | State of Charge | % |
| | `battery_power` | Charge/discharge power | W |
| **PV/Solar** | `pv_pac` | Total solar power | W |
| | `pv_etoday` | Today's solar yield | kWh |
| **Grid** | `grid_pac` | Grid import/export | W |
| | `grid_etoday_from` | Today imported | kWh |
| | `grid_etoday_to` | Today exported | kWh |
| **Load** | `load_total_power` | Total consumption | W |
| | `load_daily_used` | Today's usage | kWh |
| **Inverter** | `inverter_power` | Inverter output | W |
| | `runstatus` | Status (Normal/Fault) | - |

**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](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](examples/dashboard-config.yaml).

**Quick REST API Access:**
```bash
# 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