Local polling of solar inverters, batteries and energy meters through their Solarman Wi-Fi / Ethernet stick logger, or through any Modbus TCP gateway.
No cloud, no Solarman account. Home Assistant talks directly to the logger on the local network, on TCP port 8899.
This repository is a maintained fork of davidrapan/ha-solarman, itself inspired by StephanJoubert/home_assistant_solarman. All the protocol work, the profiles and the documentation come from there.
Upstream has had no commit since May 2026, with fixes waiting in issues and
pull requests. This fork carries them, adds a test suite, and keeps the
integration domain unchanged (solarman), so switching from upstream keeps
your devices, entities and history.
| Change | Why |
|---|---|
asyncio.Event instead of multiprocessing.Event |
multiprocessing needs /dev/shm, absent from some containers (OCI on Proxmox VE): setup failed with [Errno 2] No such file or directory |
| Profile listing fully in the executor (#1071) | Detected blocking call to scandir warning when opening the configuration flow |
| Reconnection loop instead of recursion | _open_connection called itself on every failure, growing the stack by 3 frames per attempt: the reconnect task died with RecursionError after about 100 s offline — every night, for a microinverter whose logger is powered by the panels. Now an iterative loop with exponential backoff, capped at 15 s |
async_get_devices instead of async_get_device (#1154) |
The old call is deprecated, logs a warning today and is removed in HA 2027.8 |
| Test suite and CI | 304 tests: V5 protocol against a simulated logger, every bundled profile, packaging |
- 🏠 Local only — Solarman V5 protocol, Modbus TCP or Modbus RTU over TCP
- 🔍 Auto-discovery — UDP broadcast on port 48899 and DHCP (
E8:FD:F8loggers) - 🧭 Profile auto-detection — Deye inverters are identified from their device-type register
- 📚 30 bundled profiles — Deye, Sofar, Solis, Afore, Kstar, Pylontech and more
- ✏️ Custom profiles — kept across updates in
inverter_definitions/custom/ - 🎛️ Read and write — sensors, plus numbers, selects, switches, buttons, date and time entities where the profile exposes settings
- 🔧 Raw Modbus actions — read and write any register from an automation
- 🩺 Diagnostics — downloadable from the device page
Entities come from the selected profile, not from the integration itself. A hybrid inverter profile typically exposes:
| Platform | Examples |
|---|---|
| sensor | PV power and voltage per MPPT, grid power, battery SOC and SOH, daily and total energy |
| binary_sensor | Power state, battery alarms and faults |
| number | Battery absorption, float and equalization voltages, capacity |
| select | Work Mode, Energy Pattern, Battery Operation Mode |
| switch | Inverter on/off, Time of Use, grid and generator charging |
| button | Restart, Clear records (Afore, Kstar, Sofar G3 hybrid) |
| datetime / time | Inverter clock, time-of-use program slots |
Writable entities only appear in profiles that declare them. They change your inverter's configuration — check the value before sending it.
| Manufacturer | Profiles |
|---|---|
| Deye (and rebrands: Sunsynk, Sol-Ark…) | deye_hybrid, deye_micro, deye_p3, deye_string |
| Sofar / ZCS Azzurro | sofar_g3, sofar_g3hyd, sofar_hybrid, sofar_string |
| Solis | solis_1p-5g, solis_3p-4g, solis_3p-5g, solis_hybrid, solis_s6-gr1p |
| Afore | afore_2mppt, afore_BNTxxxKTL-2mppt, afore_hybrid |
| Others | anenji_hybrid, astro-energy_micro, chint_cps-scetl, hinen_hybrid, invt_xd-tl, kstar_hybrid, maxge_string, megarevo_r-3h, pylontech_force, renon_ifl, solarman_dtsd422-d3, srne_asf, swatten_sih-th, tsun_tsol-ms |
The upstream wiki keeps the detailed list of tested models.
- Home Assistant 2026.8.0 or later — the device registry helpers this fork uses landed in that release
- The logger reachable from Home Assistant on TCP 8899 (or the port of your Modbus TCP gateway)
- No other local poller on the same logger: most sticks accept a single TCP client at a time, and a second one causes timeouts on both
The Solarman cloud keeps working in parallel: the logger pushes to the cloud on its own connection.
Or manually:
- Open HACS → Integrations
- Click ⋮ → Custom repositories
- Add
https://github.com/Micka41/ha-solarman— Category: Integration - Install Solarman
- Restart Home Assistant
cp -r custom_components/solarman \
/config/custom_components/solarmanRestart Home Assistant.
The domain is the same, so the existing configuration entries are picked up as they are.
- Back up
custom_components/solarman/inverter_definitions/custom/if you use custom profiles - In HACS, remove the
davidrapan/ha-solarmanrepository — do not delete the integration under Devices and services - Add this repository as above and install it
- Restore your custom profiles, then restart Home Assistant
Settings → Devices and services → Add integration → Solarman. Loggers found on the network are offered directly.
| Field | Default | Purpose |
|---|---|---|
| Device name | Inverter |
Prefix of every entity |
| Host | — | IP address or hostname of the logger |
| Port | 8899 |
Logger port, or the Modbus TCP gateway port |
| Transport | tcp |
tcp for a Solarman stick, modbus_tcp or modbus_rtu for a gateway |
| Profile | Auto |
Auto-detection works for Deye; choose the file for other brands |
The logger's serial number is not asked for: it is read from the first response.
| Option | Default | Purpose |
|---|---|---|
| Modifier | 0 |
Selects a variant inside a profile (firmware generation, model range) |
| Number of MPPTs | 4 |
Hides PV inputs you do not have |
| Number of phases | 3 |
Hides L2/L3 sensors on single-phase models |
| Number of battery packs | -1 |
-1 lets the integration read it from Deye three-phase hybrids |
| Battery nominal voltage | 48 |
Used for the Battery SOH and life-cycle sensors |
| Battery life cycle rating | 6000 |
Used for the Battery SOH and life-cycle sensors |
| Modbus slave ID | 1 |
Change only if the inverter uses another address |
All of these can be changed later through Configure, without losing entities.
Drop your own .yaml in:
/config/custom_components/solarman/inverter_definitions/custom/
It appears as custom/<file>.yaml in the profile list. HACS preserves this
folder across updates (persistent_directory in hacs.json). The profile
format is documented in the
upstream wiki.
| Action | Modbus | Fields |
|---|---|---|
solarman.read_holding_registers |
FC 03 | device, address, count (1–125) |
solarman.read_input_registers |
FC 04 | device, address, count (1–125) |
solarman.write_single_register |
FC 06 | device, address, value |
solarman.write_multiple_registers |
FC 16 | device, address, values |
The read actions return the values, keyed by address:
action: solarman.read_holding_registers
data:
device: 1a2b3c4d5e6f7a8b9c0d
address: 86
count: 3
response_variable: registerswrite_multiple_registers with a single value instead.
write_holding_register and write_multiple_holding_registers are kept as
deprecated aliases for older automations.
Every 5 seconds, the coordinator asks the profile which registers are due — power values are read often, serial numbers and settings rarely — groups them into as few Modbus requests as possible (125 registers maximum each), and sends them wrapped in a Solarman V5 frame to the logger.
The connection stays open between polls. The logger also sends spontaneous frames (heartbeat, data reports); each one is acknowledged, as the logger expects.
Tested on:
- Deye micro-inverter through its Wi-Fi stick logger, TCP 8899
- Home Assistant 2026.x in an OCI container on Proxmox VE
python3 -m venv venv
./venv/bin/pip install -r requirements-test.txt
./venv/bin/python -m pytest -qThe suite runs without installing Home Assistant, in about ten seconds. tests/README.md describes what it covers and what it does not.
| Workflow | Runs on | Does |
|---|---|---|
validate.yml |
push, PR, weekly | HACS and hassfest validation |
tests.yml |
push, PR | pytest on Python 3.13 and 3.14 |
release.yml |
published release | Sets the manifest version from the tag, builds and checks solarman.zip |
Issues and pull requests are welcome. Please include:
- Home Assistant and integration versions
- Inverter model, profile and transport
- Integration logs, with
debugenabled
logger:
logs:
custom_components.solarman: debugDebug logs contain the logger's serial number and IP address. Anonymise before posting.
- David Rapan and the ha-solarman contributors
- Stephan Joubert, author of the original integration
- Jonathan McCrohan for
pysolarmanv5, and uModbus,
both bundled in
pysolarman/
MIT License — see LICENSE