Repository navigation
Connection Methods
Select your battery during initial setup, then choose the connection route. Existing installations use Configure > Battery connection method & sensors. The battery references list the choices for each supported system.
| Route | What PowerSync uses | What to check first |
|---|---|---|
| Direct device connection | Device IP/serial connection owned by PowerSync | Supported model/firmware, enabled protocol and write permission; avoid competing clients |
| Configured provider | Selected Tesla energy API provider | Correct site, access and permissions; energy and vehicle API choices are separate |
| Companion integration | Telemetry/control entities from a selected HA integration | Install and configure that integration first; required telemetry and control entities must exist |
| Monitoring-only integration/cloud route | Readings used for sensors, accounting and planning | Fresh telemetry for the correct site; this route does not enable battery dispatch |
| Custom external controller | Explicitly selected household/battery telemetry | The custom battery route publishes a plan in monitoring mode and does not enable battery dispatch; separately configured curtailment has its own permission and route |
Connection method lists only the selected battery's registered routes. Home Assistant integration selects a source when companion entries are available. A single suitable entry can be selected automatically; with multiple sites/inverters, choose the intended entry explicitly. A selected integration takes precedence over an alternative discovery anchor where the route supports both.
Sungrow YAML-based installations can use Sungrow anchor sensor to constrain discovery to the existing Modbus namespace when there is no config entry to select. Leave an optional anchor unset rather than choosing an unrelated sensor. Missing required telemetry, a wrong integration domain or ambiguous sources must be resolved before continuing. An enabled but currently unavailable entity can be discovered; discovery alone does not establish a healthy live reading.
Additional sensors chooses the amount of extra sensor exposure. It is separate from the source needed for canonical SOC, battery/grid/solar power and home load. GoodWe's Whole-site solar power sensor (all PV) can include all PV at the site, rather than only the battery inverter's PV; see GoodWe.
PowerSync's normalized grid power is positive for import and negative for export. Battery power is positive for discharge and negative for charge. The supported integration profiles normalize known upstream conventions; do not invert a source again merely because its original sensor uses another sign. Custom telemetry must follow the requested conventions. Power sensors use W or kW; cumulative energy uses Wh/kWh and is not interchangeable with live power.
Compare fresh readings at the same time and for the same site. A believable SOC plus an unavailable grid sensor is not enough for reliable import/export planning.
Change battery / control method selects a different battery brand. Selecting the current brand returns to the menu; use its separate connection page to edit credentials or endpoints. Selecting a new brand persists that choice and removes other-brand connection keys before its connection page is completed. Have the new details ready; cancelling is not an atomic preview or guaranteed undo.
Changing a connection profile can first restore control state owned by the old route. If that cleanup fails, PowerSync aborts the profile change rather than persisting the new route. Successful connection/profile saves reload the integration. Review telemetry again after reload before relying on dispatch.
Existing installations without a valid explicit profile resolve through their saved legacy connection type. An invalid or cross-brand profile does not grant another system's controls. Monitoring-only route selection, the optimizer's Monitoring mode and independent curtailment permission are related but distinct; see Curtailment and Controls.
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 |
|---|---|---|
| Connection method | Only connection bundles validated for the selected battery are offered. | Saved/detected value or the form’s shown fallback |
| Additional sensors | Recommended shows useful battery, solar, grid, energy and status values without duplicating recorder entities. | Fallback recommended |
| Home Assistant integration | Select the exact upstream integration entry for this physical installation. | Saved/detected value or the form’s shown fallback |
| Sungrow anchor sensor | For YAML-based Sungrow setups, select a sensor belonging to the intended inverter. | 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 |
| Field | Meaning / input | Fallback / limits |
|---|---|---|
| Connection method | Only validated bundles are offered. Existing installations keep their current method until changed here. | Saved/detected value or the form’s shown fallback |
| Additional sensors | Recommended shows high-value battery, solar, grid, energy and status entities. All supported includes every sensor in the selected source scope. | Saved/detected value or the form’s shown fallback |
| Home Assistant integration | Select the exact upstream integration entry for this physical installation. | Saved/detected value or the form’s shown fallback |
| Sungrow anchor sensor | For YAML-based Sungrow setups without a config entry, select a sensor belonging to the intended inverter. PowerSync will restrict discovery to its stable namespace. | 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 |
A monitoring-only connection profile is distinct from switching ordinary Monitoring mode on for a control-capable route. The custom route does not dispatch the battery, but a separately configured automatic curtailment route may still operate when its explicit monitoring-mode permission is enabled. User/manual-source calls can also be permitted on control-capable routes; a monitoring-only profile remains restricted. Owned-control cleanup is a source-level result, not independent confirmation of physical restoration.