Skip to content

v0.0.3 #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
0xAHA merged 1 commit into from
Oct 11, 2025
Merged

v0.0.3 #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 126 additions & 72 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Growatt Modbus Integration for Home Assistant ☀️

![HACS Badge](https://img.shields.io/badge/HACS-Custom-orange.svg)
![Version](https://img.shields.io/badge/Version-0.0.2b-blue.svg)
![Version](https://img.shields.io/badge/Version-0.0.3-blue.svg)
[![GitHub Issues](https://img.shields.io/github/issues/0xAHA/Growatt_ModbusTCP.svg)](https://github.com/0xAHA/Growatt_ModbusTCP/issues)
[![GitHub Stars](https://img.shields.io/github/stars/0xAHA/Growatt_ModbusTCP.svg?style=social)](https://github.com/0xAHA/Growatt_ModbusTCP)

Expand All @@ -22,26 +22,51 @@ Based on the official **[Growatt Modbus RTU Protocol V1.39](https://shop.franken
- 🌡️ **Complete diagnostics** - Temperatures, fault codes, derating status
- 💾 **No cloud dependency** - Local polling, your data stays yours
- 🔄 **Grid power inversion** - Fix backwards CT clamp installations with one click
- 🎛️ **Multi-model support** - Profiles for MIN, MID, MAX, SPH, and MOD series
- 🎛️ **Multi-model support** - 14 profiles covering MIN, MID, MAX, SPH, MOD, TL-XH, MAC, MIX, SPA, and WIT series

---

## 🔌 Supported Inverter Models

The integration supports multiple Growatt inverter series with dedicated register maps:
The integration supports **14 different Growatt inverter profiles** with dedicated register maps:

| Inverter Series | Model Range | Type | Phase | Tested | Notes |
|----------------|-------------|------|-------|--------|-------|
| **MIN 3000-6000TL-X** | 3000-6000TL-X | Grid-tied | Single | ⚠️ Untested | 2 PV strings, 3-6kW |
| **MIN 7000-10000TL-X** | 7000-10000TL-X | Grid-tied | Single | ✅ **Tested** | 3 PV strings, 7-10kW |
| **MID 15000-25000TL3-X** | 15000-25000TL3-X | Grid-tied | Three | ⚠️ Untested | Commercial, 15-25kW |
| **MAX 50000-125000TL3-X** | 50000-125000TL3-X | Grid-tied | Three | ⚠️ Untested | Industrial, 50-125kW |
| **SPH 3000-10000** | SPH 3000-10000 | Hybrid | Single | ⚠️ Untested | Battery storage, 3-10kW |
| **MOD 6000-15000TL3-XH** | MOD 6000-15000TL3-XH | Hybrid | Three | ⚠️ Untested | 3-phase hybrid, 6-15kW |
### Single-Phase Grid-Tied Inverters

| Inverter Series | Model Range | PV Strings | Tested | Notes |
|----------------|-------------|------------|--------|-------|
| **MIN 3000-6000TL-X** | 3000-6000TL-X | 2 | ⚠️ Untested | Grid-tied, 3-6kW |
| **MIN 7000-10000TL-X** | 7000-10000TL-X | 3 | ✅ **Tested** | Grid-tied, 7-10kW |

### Single-Phase Hybrid Inverters (with Battery)

| Inverter Series | Model Range | PV Strings | Tested | Notes |
|----------------|-------------|------------|--------|-------|
| **TL-XH 3000-10000** | TL-XH 3000-10000 | 3 | ⚠️ Untested | Hybrid with battery, 3-10kW |
| **TL-XH US 3000-10000** | TL-XH US 3000-10000 | 3 | ⚠️ Untested | US version hybrid, 3-10kW |
| **SPH 3000-10000** | SPH 3000-10000 | 2 | ⚠️ Untested | Storage hybrid, 3-10kW |
| **MIX Series** | Various | 2 | ⚠️ Untested | Legacy storage (merged into SPH) |
| **SPA Series** | Various | - | ⚠️ Untested | AC-coupled storage |

### Three-Phase Grid-Tied Inverters

| Inverter Series | Model Range | PV Strings | Tested | Notes |
|----------------|-------------|------------|--------|-------|
| **MID 15000-25000TL3-X** | 15000-25000TL3-X | 2 | ⚠️ Untested | Commercial, 15-25kW |
| **MAC 20000-40000TL3-X** | MAC 20000-40000TL3-X | 2 | ⚠️ Untested | Compact commercial, 20-40kW |
| **MAX 50000-125000TL3-X** | MAX 50000-125000TL3-X | 3 | ⚠️ Untested | Industrial, 50-125kW |
| **MAX 1500V Series** | MAX 1500V | 3+ | ⚠️ Untested | High-voltage, up to 150kW |
| **MAX-X LV Series** | MAX-X LV | 3+ | ⚠️ Untested | Low-voltage, up to 125kW |

### Three-Phase Hybrid Inverters (with Battery)

| Inverter Series | Model Range | PV Strings | Tested | Notes |
|----------------|-------------|------------|--------|-------|
| **MOD 6000-15000TL3-XH** | MOD 6000-15000TL3-XH | 3 | ⚠️ Untested | Modular hybrid, 6-15kW |
| **WIT TL3 Series** | WIT TL3 | 3+ | ⚠️ Untested | Business storage, up to 50kW |

**Legend:**
- ✅ **Tested** - Confirmed working with real hardware
- ⚠️ **Untested** - Profile created from documentation, needs validation
- ⚠️ **Untested** - Profile created from official documentation, needs validation

> 💡 **Help us test!** If you have a model marked as untested and can confirm it works, please open an issue or PR to update the documentation!

Expand All @@ -51,49 +76,49 @@ The integration supports multiple Growatt inverter series with dedicated registe

Different inverter models create different sensors based on their capabilities:

| Sensor | MIN 3-6k | MIN 7-10k | MID | MAX | SPH | MOD |
|--------|:--------:|:---------:|:---:|:---:|:---:|:---:|
| Sensor | MIN 3-6k | MIN 7-10k | TL-XH | MID/MAC | MAX | SPH | MOD/WIT |
|--------|:--------:|:---------:|:-----:|:-------:|:---:|:---:|:-------:|
| **Solar Input** |
| PV1 Voltage/Current/Power | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| PV2 Voltage/Current/Power | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| PV3 Voltage/Current/Power | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ |
| Solar Total Power | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| PV1 Voltage/Current/Power | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| PV2 Voltage/Current/Power | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| PV3 Voltage/Current/Power | ❌ | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ |
| Solar Total Power | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **AC Output (Single-Phase)** |
| AC Voltage/Current/Power | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ |
| AC Frequency | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ |
| AC Voltage/Current/Power | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ |
| AC Frequency | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ |
| **AC Output (Three-Phase)** |
| AC Phase A/B/C Voltage | ❌ | ❌ | ✅ | ✅ | ❌ | ✅ |
| AC Phase A/B/C Current | ❌ | ❌ | ✅ | ✅ | ❌ | ✅ |
| AC Phase A/B/C Power | ❌ | ❌ | ✅ | ✅ | ❌ | ✅ |
| AC Total Power | ❌ | ❌ | ✅ | ✅ | ❌ | ✅ |
| AC Phase R/S/T Voltage | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ✅ |
| AC Phase R/S/T Current | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ✅ |
| AC Phase R/S/T Power | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ✅ |
| AC Total Power | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ✅ |
| **Grid Power (Calculated)** |
| Grid Export Power | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| Grid Import Power | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| Self Consumption | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| House Consumption | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| Grid Export Power | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Grid Import Power | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Self Consumption | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| House Consumption | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **Grid Power (From Registers)** |
| Power to Grid | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| Power to Load | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| Power to User | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| Power to Grid | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ |
| Power to Load | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ |
| Power to User | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ |
| **Battery (Hybrid Only)** |
| Battery Voltage/Current/Power | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| Battery SOC | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| Battery Temperature | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| Battery Voltage/Current/Power | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ |
| Battery SOC | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ |
| Battery Temperature | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ |
| **Energy Totals** |
| Energy Today/Total | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Energy to Grid Today/Total | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Load Energy Today/Total | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Energy Today/Total | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Energy to Grid Today/Total | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Load Energy Today/Total | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **System & Diagnostics** |
| Inverter Temperature | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| IPM Temperature | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Boost Temperature | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Status/Derating/Faults | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Inverter Temperature | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| IPM Temperature | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Boost Temperature | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Status/Derating/Faults | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

**Legend:**
- ✅ Available for this model
- ❌ Not available (hardware limitation)

> 📝 **Note:** Hybrid models (SPH/MOD) have power flow measured directly from registers. Grid-tied models (MIN/MID/MAX) calculate power flow from solar production vs AC output.
> 📝 **Note:** Hybrid models (TL-XH, SPH, MOD, WIT) have power flow measured directly from registers. Grid-tied models (MIN, MID, MAC, MAX) calculate power flow from solar production vs AC output.

---

Expand Down Expand Up @@ -169,14 +194,37 @@ Growatt COM Pin 4 (B) ──────► Adapter RS485-B (or D-)

### Inverter Series Selection

Choose the profile that matches your inverter model:

#### Single-Phase Grid-Tied
| Selection | When to Use |
|-----------|-------------|
| **MIN 3000-6000TL-X** | 2 PV string models (3-6kW single-phase) |
| **MIN 7000-10000TL-X** | 3 PV string models (7-10kW single-phase) |
| **MID 15000-25000TL3-X** | Commercial 3-phase grid-tied (15-25kW) |
| **MAX 50000-125000TL3-X** | Industrial 3-phase grid-tied (50-125kW) |
| **SPH 3000-10000** | Single-phase hybrid with battery (3-10kW) |
| **MOD 6000-15000TL3-XH** | 3-phase hybrid with battery (6-15kW) |

#### Single-Phase Hybrid (with Battery)
| Selection | When to Use |
|-----------|-------------|
| **TL-XH 3000-10000** | 3 PV string hybrid with battery (3-10kW) |
| **TL-XH US 3000-10000** | US version 3 PV string hybrid (3-10kW) |
| **SPH 3000-10000** | 2 PV string storage hybrid (3-10kW) |
| **MIX Series** | Legacy storage system |
| **SPA Series** | AC-coupled storage system |

#### Three-Phase Grid-Tied
| Selection | When to Use |
|-----------|-------------|
| **MID 15000-25000TL3-X** | Commercial 3-phase (15-25kW) |
| **MAC 20000-40000TL3-X** | Compact commercial 3-phase (20-40kW) |
| **MAX 50000-125000TL3-X** | Industrial 3-phase (50-125kW) |
| **MAX 1500V Series** | High-voltage commercial (up to 150kW) |
| **MAX-X LV Series** | Low-voltage commercial (up to 125kW) |

#### Three-Phase Hybrid (with Battery)
| Selection | When to Use |
|-----------|-------------|
| **MOD 6000-15000TL3-XH** | Modular 3-phase hybrid (6-15kW) |
| **WIT TL3 Series** | Business storage 3-phase (up to 50kW) |

### TCP Connection Settings

Expand All @@ -195,9 +243,9 @@ Access via **Settings** → **Devices & Services** → **Growatt Modbus** → **
| **Device Name** | "Growatt" | - | Friendly name (appears before all sensor names) |
| **Scan Interval** | 30 seconds | 5-300s | How often to poll inverter |
| **Connection Timeout** | 10 seconds | 1-60s | How long to wait for responses |
| **Invert Grid Power** 🆕 | OFF | ON/OFF | **Reverse import/export if CT clamp backwards** |
| **Invert Grid Power** | OFF | ON/OFF | **Reverse import/export if CT clamp backwards** |

### 🔄 Invert Grid Power (New in v0.0.2!)
### 🔄 Invert Grid Power

Got your CT clamp installed backwards? No problem! Just enable this option:

Expand Down Expand Up @@ -233,9 +281,9 @@ Got your CT clamp installed backwards? No problem! Just enable this option:
| `sensor.{name}_pv2_voltage` | PV2 Voltage | V | String 2 DC voltage |
| `sensor.{name}_pv2_current` | PV2 Current | A | String 2 DC current |
| `sensor.{name}_pv2_power` | PV2 Power | W | String 2 power output |
| `sensor.{name}_pv3_voltage` | PV3 Voltage | V | String 3 DC voltage (MIN 7-10k, MID, MAX, MOD only) |
| `sensor.{name}_pv3_current` | PV3 Current | A | String 3 DC current (MIN 7-10k, MID, MAX, MOD only) |
| `sensor.{name}_pv3_power` | PV3 Power | W | String 3 power output (MIN 7-10k, MID, MAX, MOD only) |
| `sensor.{name}_pv3_voltage` | PV3 Voltage | V | String 3 DC voltage (selected models) |
| `sensor.{name}_pv3_current` | PV3 Current | A | String 3 DC current (selected models) |
| `sensor.{name}_pv3_power` | PV3 Power | W | String 3 power output (selected models) |
| `sensor.{name}_solar_total_power` | Solar Total Power | W | Combined PV power |

**Attributes:**
Expand All @@ -256,15 +304,15 @@ Got your CT clamp installed backwards? No problem! Just enable this option:

| Entity ID | Name | Unit | Description |
|-----------|------|------|-------------|
| `sensor.{name}_ac_voltage_a` | AC Voltage Phase A | V | Phase A voltage |
| `sensor.{name}_ac_voltage_b` | AC Voltage Phase B | V | Phase B voltage |
| `sensor.{name}_ac_voltage_c` | AC Voltage Phase C | V | Phase C voltage |
| `sensor.{name}_ac_current_a` | AC Current Phase A | A | Phase A current |
| `sensor.{name}_ac_current_b` | AC Current Phase B | A | Phase B current |
| `sensor.{name}_ac_current_c` | AC Current Phase C | A | Phase C current |
| `sensor.{name}_ac_power_a` | AC Power Phase A | W | Phase A power |
| `sensor.{name}_ac_power_b` | AC Power Phase B | W | Phase B power |
| `sensor.{name}_ac_power_c` | AC Power Phase C | W | Phase C power |
| `sensor.{name}_ac_voltage_r` | AC Voltage Phase R | V | Phase R voltage |
| `sensor.{name}_ac_voltage_s` | AC Voltage Phase S | V | Phase S voltage |
| `sensor.{name}_ac_voltage_t` | AC Voltage Phase T | V | Phase T voltage |
| `sensor.{name}_ac_current_r` | AC Current Phase R | A | Phase R current |
| `sensor.{name}_ac_current_s` | AC Current Phase S | A | Phase S current |
| `sensor.{name}_ac_current_t` | AC Current Phase T | A | Phase T current |
| `sensor.{name}_ac_power_r` | AC Power Phase R | W | Phase R power |
| `sensor.{name}_ac_power_s` | AC Power Phase S | W | Phase S power |
| `sensor.{name}_ac_power_t` | AC Power Phase T | W | Phase T power |
| `sensor.{name}_ac_power_total` | AC Total Power | W | Total 3-phase power |
| `sensor.{name}_ac_frequency` | AC Frequency | Hz | Grid frequency |

Expand Down Expand Up @@ -469,8 +517,9 @@ custom_components/growatt_modbus/
├── __init__.py # Integration setup
├── binary_sensor.py # Binary sensors (inverter connectivity)
├── config_flow.py # Configuration UI with inverter series selection
├── const.py # Register definitions for all models (V1.39)
├── const.py # Register definitions for all 14 models (V1.39)
├── coordinator.py # Data coordinator with night-time handling
├── device_profiles.py # Inverter profile definitions
├── growatt_modbus.py # Modbus communication (pymodbus 2.x & 3.x)
├── manifest.json # Integration metadata
├── sensor.py # Sensor platform with model-specific sensors
Expand All @@ -491,15 +540,21 @@ To view device information:

---

## 🆕 What's New in v0.0.2
## 🆕 What's New in v0.0.3

- 🎛️ **Expanded Model Support** - Now supports 14 inverter profiles (up from 6)
- 🔋 **Fixed SPH Register Map** - SPH models now include complete PV, AC, and battery sensors
- ⚡ **New Hybrid Series** - Added TL-XH, TL-XH US profiles for single-phase hybrid inverters
- 🏭 **More Commercial Models** - Added MAC, MAX 1500V, MAX-X LV, WIT TL3 series
- 💾 **Legacy Storage** - Added MIX and SPA series profiles
- 📊 **Profile-Based Sensors** - Optimized sensor creation based on inverter capabilities
- 🐛 **Bug Fixes** - Resolved config flow loading issues and type hint errors

- 🎛️ **Multi-Model Support** - Added profiles for MIN (3-6k & 7-10k), MID, MAX, SPH, and MOD series
### v0.0.2 Features (Previously Released)
- 🔄 **Invert Grid Power Option** - Fix backwards CT clamp installations via UI toggle
- 📊 **Model-Specific Sensors** - Only relevant sensors created based on inverter capabilities
- ⚡ **Three-Phase Support** - Full support for MID, MAX, and MOD models
- 🔋 **Battery Sensors** - Complete battery monitoring for SPH and MOD hybrid models
- 🎨 **Enhanced Configuration UI** - Better inverter series selection with descriptions
- 📝 **Improved Options Flow** - Device name, timeout, and grid power inversion settings

---

Expand All @@ -526,13 +581,12 @@ Contributions welcome! Here's how:

### Help Us Test More Models! 🧪

We need community members with different inverter models to validate the untested profiles:
We need community members with different inverter models to validate the untested profiles. Currently only **MIN 7000-10000TL-X** is tested with real hardware!

- MIN 3000-6000TL-X series
- MID 15000-25000TL3-X series
- MAX 50000-125000TL3-X series
- SPH 3000-10000 series
- MOD 6000-15000TL3-XH series
**Profiles needing validation:**
- All single-phase grid-tied (MIN 3-6k)
- All hybrid models (TL-XH, SPH, MIX, SPA)
- All three-phase models (MID, MAC, MAX variants, MOD, WIT)

If you successfully test any of these, please report back via GitHub Issues!

Expand All @@ -548,7 +602,7 @@ MIT License - see [LICENSE](LICENSE) file for details.

- Based on [Growatt Modbus RTU Protocol V1.39](https://shop.frankensolar.ca/content/documentation/Growatt/AppNote_Growatt_WIT-Modbus-RTU-Protocol-II-V1.39-English-20240416_%28frankensolar%29.pdf) (2024.04.16)
- Built for the Home Assistant community
- Tested by solar enthusiasts worldwide 🌍
- Tested by solar enthusiasts worldwide (soon, hopefully) 🌍
- Special thanks to all hardware testers and contributors
- MIN-10000TL-X validation by [@0xAHA](https://github.com/0xAHA)

Expand Down
Loading