Repository navigation
Battery GoodWe
Battery connections · Connection methods and sensors · Configuration index
Choose the battery during initial setup. Later, use Settings > Devices & Services > PowerSync > Configure > Battery connection method & sensors to choose its telemetry/control route. Edit connection details under Configure > GoodWe connection.
| Connection method | What this route provides |
|---|---|
| PowerSync direct IP control | Direct device connection. Operations depend on the supported model, firmware and enabled write permissions. |
| Home Assistant GoodWe telemetry and EMS control | Uses the selected companion integration. Required control entities must be present and writable; telemetry alone is insufficient. |
| Home Assistant GoodWe integration — monitoring only | Monitoring and planning only; this route does not enable battery dispatch. |
Select one route for PowerSync. A second integration using the same device connection can cause conflicts; the companion-integration route is appropriate when that integration should own communications. See source discovery and switching.
Full support for GoodWe hybrid inverters. Local connection only — no cloud API required.
- Auto-Detection — Model family is automatically identified during setup
- Force Charge/Discharge — Charges or discharges the battery on demand
- Backup Reserve — Set minimum state of charge
- Grid Export Limit — Configurable export power limit
- Battery Health — State of health read from inverter
| Series | Type | Battery Control |
|---|---|---|
| ET | Three Phase Hybrid | Full support |
| EH | Three Phase Hybrid | Full support |
| BT | Three Phase Hybrid | Full support |
| BH | Three Phase Hybrid | Full support |
| ES | Single Phase Hybrid | Full support |
| EM | Single Phase Hybrid | Full support |
| BP | Single Phase Hybrid | Full support |
| DT/MS/XS | Grid-only (no battery) | Not supported |
UDP via WiFi Dongle (Default)
- Port: 8899
- Works with most GoodWe inverters out of the box
TCP via LAN Dongle
- Port: 502
- Requires a GoodWe LAN dongle (WLA0000-01-00P V2.0)
- More reliable for installations with poor WiFi
TCP via Modbus Gateway (EMS Mode)
- Some installations connect GoodWe through a third-party Modbus TCP gateway
- In this setup the inverter's UDP port 8899 is unreachable, so operation mode registers cannot be written directly
- PowerSync works around this by relaying force charge/discharge commands through the GoodWe Home Assistant integration's EMS entities, which use registers that accept TCP writes
- See Modbus TCP Gateway Setup below
- Find the inverter's IP address — check your router's device list for the WiFi or LAN dongle
- Select GoodWe as your battery system during PowerSync setup
- Enter the inverter's IP address
- Select the protocol (UDP or TCP) matching your dongle type
- The port defaults automatically (8899 for UDP, 502 for TCP)
- PowerSync tests the connection and auto-detects your inverter model
Note: If setup reports "no battery support", your inverter is a grid-only model (DT/MS/XS series) which does not have battery control capabilities.
If the property has solar on both the GoodWe hybrid and a separate AC-coupled array, select Whole-site solar power sensor (all PV) on Battery connection method & sensors during setup. Choose a sensor reporting the total instantaneous production of all arrays, including the GoodWe PV strings. The sensor can use W, kW or MW. Leave the field empty when all solar is connected to the GoodWe.
Existing installations can select, replace or clear the sensor through the Battery connection method & sensors options form or the direct GoodWe connection options. Saving reloads the integration and applies the selection to both direct and Home Assistant entity telemetry.
PowerSync uses the whole-site reading, with the inverter's own PV as a lower bound, and calculates household load from solar, grid and battery power. This also handles negative inverter house-consumption readings that can occur with AC-coupled generation. Corrected readings feed solar nowcasting, forecast learning and daily energy accumulation.
If the selected sensor is missing, unavailable, non-numeric, non-finite or negative, the displayed readings remain inverter-only. PowerSync marks the solar sample invalid, skips solar nowcasting and forecast learning for that sample, and skips its daily energy accumulation. Clearing the optional field restores the normal inverter-only telemetry.
If your GoodWe inverter is connected via a Modbus TCP gateway (rather than a direct WiFi/LAN dongle), force charge and force discharge require an extra configuration step. GoodWe's operation mode registers only accept writes over the proprietary UDP protocol on port 8899 — TCP writes are silently ignored.
Prerequisites:
- The GoodWe Home Assistant integration must be installed and working
- This integration must be providing
select.<prefix>_ems_modeandnumber.<prefix>_ems_power_limitentities (where<prefix>is typicallygoodwe)
Steps:
- Go to Settings → Devices & Services → PowerSync → Configure
- Open GoodWe Connection Settings
- Set EMS Entity Prefix to the entity prefix used by the GoodWe integration — typically
goodwe - Save
PowerSync will now route force charge, force discharge, and normal operation commands through the EMS mode entities instead of writing directly to operation mode registers. EMS mode options used: charge_pv (force charge, falling back to charge_battery where needed), sell_power (force discharge, falling back to discharge_battery where needed), auto (normal/idle).
| Mode | Description |
|---|---|
| General / Auto | Normal self-consumption operation |
| ECO Charge / Buy Power | Force charge from grid |
| ECO Discharge / Sell Power | Force discharge to grid |
GoodWe controls backup reserve using depth of discharge (how deeply the battery is allowed to deplete). PowerSync converts automatically:
- Setting backup reserve to 20% → battery allowed to deplete to 20%
- Setting backup reserve to 100% → battery kept fully charged (full backup)
- Internally this is written as DOD = 100 - reserve percentage
When leaving force-charge or force-discharge modes, PowerSync restores General / Auto operation before applying the reserve floor so the inverter is no longer stuck in ECO Charge or ECO Discharge while the DOD setting is updated.
After saving connection changes, allow the integration reload to complete. Check fresh battery SOC, grid/solar/battery power and home-load readings for the selected site. Compare signs and totals with the vendor/upstream readings. Planning sensors can update on a monitoring route; that does not establish dispatch capability. Verify any permitted control separately using readback and measured power.
The tables use the current form labels and help text. They list the conditional field union: a field can be hidden for a different battery, provider, route or available integration. The instructions above explain those conditions. Existing saved/discovered values take precedence over fresh fallbacks. Rate units follow the provider; check the displayed currency/energy unit.
| Field | Meaning / input | Fallback / limits |
|---|---|---|
| Inverter IP address | Local IP address of your GoodWe inverter. | Saved/detected value or the form’s shown fallback |
| Protocol | UDP uses direct GoodWe control on port 8899. TCP uses Modbus on port 502 for LAN/Kit-20 setups. | Saved/detected value or the form’s shown fallback |
| Port | Default: 8899 for UDP, 502 for TCP. | 1–65535; step 1 |
| EMS control method | Choose how PowerSync sends GoodWe EMS commands. Direct IP requires UDP 8899 control. For TCP / LAN Kit-20 setups, PowerSync auto-uses detected GoodWe Experimental EMS entities because direct operation-mode writes do not reliably control the inverter. TCP / LAN Kit-20 telemetry can also use detected GoodWe HA sensors to avoid a second direct TCP/502 polling client. | Saved/detected value or the form’s shown fallback |
| GoodWe entity mode prefix | Required only when EMS control method is Home Assistant entity control. PowerSync will auto-detect a matching EMS entity pair when possible. You can also enter only the prefix for the GoodWe Experimental EMS controls. Example: goodwe uses select.goodwe_ems_mode and number.goodwe_ems_power_limit. | Saved/detected value or the form’s shown fallback |
| Field | Meaning / input | Fallback / limits |
|---|---|---|
| Inverter IP address | Local IP address of your GoodWe inverter. | Saved/detected value or the form’s shown fallback |
| Protocol | UDP uses direct GoodWe control on port 8899. TCP uses Modbus on port 502 for LAN/Kit-20 setups. | Saved/detected value or the form’s shown fallback |
| Port | Default: 8899 for UDP, 502 for TCP. | 1–65535; step 1 |
| EMS control method | Choose how PowerSync sends GoodWe EMS commands. Direct IP requires UDP 8899 control. For TCP / LAN Kit-20 setups, PowerSync auto-uses detected GoodWe Experimental EMS entities because direct operation-mode writes do not reliably control the inverter. TCP / LAN Kit-20 telemetry can also use detected GoodWe HA sensors to avoid a second direct TCP/502 polling client. | Saved/detected value or the form’s shown fallback |
| GoodWe entity mode prefix | Required only when EMS control method is Home Assistant entity control. PowerSync will auto-detect a matching EMS entity pair when possible. You can also enter only the prefix for the GoodWe Experimental EMS controls. Example: goodwe uses select.goodwe_ems_mode and number.goodwe_ems_power_limit. | Saved/detected value or the form’s shown fallback |
| Whole-site solar power sensor (all PV) | Optional. A sensor reporting TOTAL solar production for the whole property: the GoodWe inverter's own PV plus any AC-coupled array such as Enphase microinverters. Leave empty if the GoodWe PV strings are all your solar. If this sensor becomes unavailable, PowerSync ignores solar samples instead of using a partial reading. | Saved/detected value or the form’s shown fallback |