Repository navigation
Battery FoxESS
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 > FoxESS connection.
| Connection method | What this route provides |
|---|---|
| PowerSync Modbus TCP | Direct device connection. Operations depend on the supported model, firmware and enabled write permissions. |
| PowerSync RS485 serial | Direct device connection. Operations depend on the supported model, firmware and enabled write permissions. |
| FoxESS Cloud API | Cloud telemetry/control where the provider supports it; polling and API availability affect response. |
| FoxESS Modbus Home Assistant integration | Uses the selected companion integration. Required control entities must be present and writable; telemetry alone is insufficient. |
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.
Supports H1, H3, H3-Pro, H3 Smart, and KH model families. All control is done locally — no cloud API required for battery control.
OEM rebrands using identical hardware are also supported — the model family is detected automatically during setup.
| Model Family | Type | OEM Rebrands |
|---|---|---|
| H1 | Single Phase | AIO-H1, a-TroniX AX |
| H3 | Three Phase | AIO-H3, Kuara H3, Sonnenkraft SK-HWR, 1KOMMA5 |
| H3-Pro | Three Phase (Higher Power) | — |
| H3 Smart | Three Phase (Native WiFi) | — |
| KH | Single Phase Hybrid | — |
Rebrands: If your inverter is an OEM rebrand (e.g., Kuara, Sonnenkraft, 1KOMMA5), just connect it like any other FoxESS unit. PowerSync identifies the model family automatically — no special configuration needed.
Modbus TCP (Recommended for H3 Smart)
- Port: 502 (default)
- Slave ID: 247 (default)
- For H3 Smart: Connect directly to the inverter's IP address — no external adapter needed
RS485 Serial
- Baud rate: 9600 (default)
- Slave ID: 247 (default)
- Requires an RS485 adapter (USB or network gateway like Elfin EW11)
The H3 Smart has a built-in WiFi connection. No external adapter is needed.
- Find the inverter's IP address — it appears as "espressif" on your network
- Ensure firmware is up to date — required for a stable connection
- Use default settings — Port 502, Slave ID 247
- PowerSync will auto-detect the model as H3 Smart during setup
Troubleshooting: If the connection test fails:
- Check your router for a device named "espressif" to find the correct IP
- Update inverter firmware to the latest version
- Verify port 502 is not blocked by your network
A FoxESS Cloud API key allows PowerSync to sync electricity prices as time-based schedules on your inverter (up to 8 periods per day). This is not required for battery control.
Getting your API key:
- Log in to foxesscloud.com
- Go to User Profile > API Management
- Generate a new API key
- Enter the API key and your device serial number during PowerSync setup
Note: When Smart Optimization is enabled, cloud schedule sync is automatically skipped — the optimizer controls the inverter directly, and uploading schedules to the cloud would conflict.
| Mode | Description |
|---|---|
| Self Use | Normal self-consumption — battery powers home, charges from solar |
| Feed-in First | Prioritises exporting to grid |
| Backup | Reserves battery for backup power |
| Peak Shaving | Reduces grid import during peak periods (H3-Pro/Smart only) |
Precise power control for charging or discharging the battery on demand. The power level is read from the inverter's own configured maximum — not a fixed cap.
| Feature | Description |
|---|---|
| Force Charge | Charges battery from grid at a configurable power level |
| Force Discharge | Discharges battery to grid |
| Max power | Read automatically from the inverter |
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 |
|---|---|---|
| Connection type | Modbus TCP connects over LAN/WiFi. RS485 Serial provides direct register access. FoxESS Cloud API uses Open API control with cloud-rate-limit latency. Entity bridge reuses an existing foxess_modbus integration instead of opening another Modbus connection. | Saved/detected value or the form’s shown fallback |
| Field | Meaning / input | Fallback / limits |
|---|---|---|
| foxess_modbus integration | Select the foxess_modbus integration entry PowerSync should read and control. If there is only one entry, PowerSync selects it automatically. | Saved/detected value or the form’s shown fallback |
| Entity prefix | Optional fallback for renamed entities. Example: foxess for sensor.foxess_battery_soc and select.foxess_work_mode. | Fallback blank (see retention/clear rules) |
| Field | Meaning / input | Fallback / limits |
|---|---|---|
| Inverter IP address | Local IP of your FoxESS inverter. H3 Smart may appear as 'espressif' on your network. | Saved/detected value or the form’s shown fallback |
| Modbus port | Default Modbus TCP port is 502. | Fallback 502; 1–65535; step 1 |
| Modbus slave ID | Default is 247 for FoxESS. | Fallback 247; 1–247; step 1 |
| Field | Meaning / input | Fallback / limits |
|---|---|---|
| Serial port path | e.g. /dev/ttyUSB0 for a USB-to-RS485 adapter. | Fallback /dev/ttyUSB0 |
| Baud rate | Default 9600. Only change if the inverter is configured differently. | Fallback 9600; 1200–115200; step 1 |
| Modbus slave ID | Default is 247 for FoxESS. | Fallback 247; 1–247; step 1 |
| Field | Meaning / input | Fallback / limits |
|---|---|---|
| Inverter model | H3-Pro and H3 Smart use the same register set. The H3 Smart has built-in WiFi Modbus. | Saved/detected value or the form’s shown fallback |
| Field | Meaning / input | Fallback / limits |
|---|---|---|
| Entity prefix | Optional fallback for renamed entities. Example: foxess for sensor.foxess_battery_soc and select.foxess_work_mode. | Saved/detected value or the form’s shown fallback |
| Connection type | Choose Modbus TCP, RS485 serial, FoxESS Cloud API, or the entity bridge for Nathan Marlor's foxess_modbus integration. | Saved/detected value or the form’s shown fallback |
| Inverter IP address | Local IP of your FoxESS inverter. H3 Smart may appear as 'espressif' on your network. | Saved/detected value or the form’s shown fallback |
| Modbus port | Default Modbus TCP port is 502. | 1–65535; step 1 |
| Modbus slave ID | Default is 247 for FoxESS. | 1–247; step 1 |
| Serial port path | e.g. /dev/ttyUSB0 for a USB-to-RS485 adapter. | Saved/detected value or the form’s shown fallback |
| Baud rate | Default 9600. Only change if the inverter is configured differently. | 300–115200; step 1 |
| FoxESS Cloud API key | Get your API key from foxesscloud.com > User Centre > API Management. | Saved/detected value or the form’s shown fallback |
| Device serial number | Inverter serial number from FoxESS Cloud. | Saved/detected value or the form’s shown fallback |
| foxess_modbus integration | Select the foxess_modbus integration entry PowerSync should read and control. If there is only one entry, PowerSync selects it automatically. | Saved/detected value or the form’s shown fallback |