EyeBond Local — local Home Assistant integration for SmartESS / SmartValue solar inverters

Українською

The Open in HACS button requires HACS to be installed. HACS is optional; if you do not use it, follow the manual installation steps below.

Companion dashboard card: EyeBond Local Card adds a ready-made Home Assistant dashboard with power flow and history charts.

No factory collector? ESP EyeBond Collector is a community firmware bridge for connecting supported inverters directly to EyeBond Local without a factory cloud logger.

EyeBond Local brings local monitoring and control to Home Assistant for hybrid solar inverters that use EyeBond-compatible Wi-Fi collectors and appear in the SmartESS / SmartValue apps.

Use it when your inverter already works in the SmartESS or SmartValue app and you want local LAN access from Home Assistant instead of depending only on the vendor cloud.

It reads live inverter data over your local network. On supported models it can also expose safe controls such as charge settings, output mode, beeper settings, and model-specific switches.

Note: The integration is actively developed. Some inverters work fully, some work in read-only mode, and some need a Support Archive before support can be added.

Known issue: On some setups, vendor-cloud updates can pause while Home Assistant readings continue. This is under investigation; see Known cloud telemetry issue.

---

Is this integration for my inverter?

It may be a good fit if:

• your inverter appears in the SmartESS or SmartValue app;
• it connects through an external or built-in EyeBond-compatible Wi-Fi collector;
• you want Home Assistant to read inverter data locally over your LAN;
• you want PV, battery, load, grid and energy sensors in Home Assistant;
• you want optional local controls on supported, verified models.

People often look for this while searching for SmartESS Home Assistant, SmartValue Home Assistant, an EyeBond Wi-Fi collector integration, or brands such as Anenji, PowMr and Sandisolar — and for local solar inverter monitoring without the vendor cloud. See the full, always-current list in the inverter model catalog.

---

What it does

• Finds collectors through a normal scan, an already connected session, background discovery, or manual/remote setup.
• Adds the verified collector first, then identifies the inverter safely on the owned runtime connection.
• Reads inverter, battery, PV, load, and grid data locally.
• Creates normal Home Assistant sensors, numbers, selects, switches, and buttons.
• Keeps the collector's vendor-cloud endpoint by default for use alongside Home Assistant, or lets you point it at Home Assistant only — a reversible, explicit action that is never done silently.
• Lets you choose control access:
  • Read-only — monitoring only.
  • Auto — enable verified controls when the device match is confident.
  • Full Control — expose available controls manually for advanced use.
• Can manage supported collector Wi-Fi, restart, UART, and connection settings.
• Can collect read-only cloud evidence or verify extra controls for a partially supported device.
• Can create a Support Archive, run developer-provided diagnostic commands, and capture collector traffic when normal diagnostics are not enough.
• Works with the optional EyeBond Local Card dashboard.

---

Why local instead of the vendor cloud?

EyeBond Local talks to supported collectors over your local network, so day-to-day monitoring does not depend on the vendor cloud being reachable. Updates arrive at local speed, and your inverter data stays inside your Home Assistant installation.

On supported collectors you can keep the SmartESS or SmartValue app working at the same time, or explicitly point a collector at Home Assistant only. Home Assistant never silently redirects a collector — pointing it at Home Assistant and restoring its previous server are both explicit, reversible actions.

---

Supported hardware

EyeBond Local is intended for inverters that use EyeBond-compatible Wi-Fi collectors, including some built-in Wi-Fi modules that behave the same way.

Tested models include units sold as Anenji, PowMr, Sandisolar, LVYUAN, MUST and Yingfa, plus SMG-, PI18-, PI30- and SRNE-family protocol devices. Support level varies per model, and other brands on the same collectors may work too.

The current model list is here:

• Inverter model catalog

After the collector is added, runtime detection reports what it identified and which support level is available:

• Supported — normal monitoring and confirmed controls.
• Limited / partial — monitoring works, but some controls or sensors may be missing.
• Read-only — monitoring works, but controls are disabled.
• Unknown — the collector or inverter needs a Support Archive for review.

If your inverter is not listed, it may still work. Add it, create a Support Archive, and open a GitHub issue.

The unreleased test code also includes a limited EyeBond Short-ASCII family profile for a protocol observed on some Anern and Maxinn units. It includes basic telemetry and optional BMS/rated readings where the device answers them. This identifies the protocol, not the commercial model. See its available readings and limits.

No factory collector?

If your inverter has no factory collector, you can use the community ESP EyeBond Collector.

It is a small ESP8266/ESP32-based bridge that connects directly to the inverter and works locally with this integration. Because it does not use a vendor cloud, only local Home Assistant features are available.

---

Installation

HACS installation

1. Open HACS → Integrations.
2. Click the menu → Custom repositories.
3. Add https://github.com/groove-max/ha-eybond-local as an Integration.
4. Find EyeBond Local and click Download.
5. Restart Home Assistant.
6. Go to Settings → Devices & Services → Add Integration and search for EyeBond Local.

Manual installation

1. Download the archive from the latest EyeBond Local release.
2. Extract the archive and copy only its custom_components/eybond_local/ folder into config/custom_components/. The final path must be config/custom_components/eybond_local/manifest.json, without another repository or custom_components folder nested inside it.
3. Restart Home Assistant.
4. Add EyeBond Local from Settings → Devices & Services.

Keep backup copies outside config/custom_components/. Renaming an old copy to eybond_local_backup inside that directory does not disable it: Home Assistant can discover its unchanged manifest and load the old code. Leave only the intended eybond_local/ copy there, then fully restart Home Assistant; reloading the integration is not enough after replacing Python files.

Testing the unreleased main branch

Use this only when a maintainer asks you to test a fix that is not in a release yet. It does not update through HACS and may change before the next release.

1. Back up your Home Assistant configuration.
2. Download the current main branch archive.
3. Extract the archive. Inside ha-eybond-local-main, open custom_components. Replace the existing config/custom_components/eybond_local/ directory with the complete eybond_local folder from there. Do not copy the outer ha-eybond-local-main folder or mix files from two builds. Check that manifest.json is directly inside config/custom_components/eybond_local/. You do not need to remove the integration or its devices from Home Assistant.
4. Restart Home Assistant and check the EyeBond Local entries.
5. When reporting a result, include the Git commit shown on the repository page and attach a new Support Archive.

To return to a published build, reinstall the latest release through HACS or replace the directory with the complete directory from that release archive.

---

Setup

The setup wizard identifies and adds the collector first. After the entry is created, runtime detection identifies the inverter and creates its entities. For a complete explanation of scan results, address confirmation, background discovery, and manual setup, see Setup and Discovery.

1. Put the collector on the same network

If the collector is already on the same Wi-Fi/LAN as Home Assistant, continue.

If it is not, use the vendor app, manual Wi-Fi setup, or Bluetooth Wi-Fi setup when your collector supports it.

2. Scan for devices

Choose the Home Assistant network interface and start a scan. One bounded scan combines broadcast replies, already connected collectors, and a local /24 unicast fallback when broadcast discovery is not enough. On a larger network, use the correct subnet broadcast or enter a known collector address through advanced setup instead of expecting every address in a /16 to be probed. For a routed subnet, Add known collector IPs to scan supplements local discovery with explicitly entered addresses. Use manual setup when the collector needs a different callback address or port behind NAT.

If the scan finds nothing, run it again, choose a different Home Assistant interface, or use advanced setup to enter the collector address manually.

3. Review the result

The wizard can show collector candidates such as:

• Ready to set up — the collector was identified and can be added.
• Needs confirmation — the collector was identified through an incoming connection, but its reachable address must be confirmed.
• Check address — an address responded and can be probed directly.

4. Confirm the collector and refresh mode

Confirm the collector and choose how sensors should refresh. Home Assistant then creates the entry and detects the inverter on the owned runtime session. The inverter device may appear shortly after the collector device.

Collector mode is managed later from Collector connection and cloud, after the integration has created the device and read its collector capabilities.

Manual setup is available when automatic scanning is not practical.

Tip: Auto-discovery works best when Home Assistant and the collector are on the same network.

---

After setup

EyeBond Local usually creates two Home Assistant devices:

• Collector device — Wi-Fi signal, network actions, connection settings, restart, support archive, and troubleshooting actions.
• Inverter device — live sensors, energy totals, binary sensors, and supported controls.

The inverter device may include:

• PV, load, battery, inverter, and grid sensors.
• Energy totals for Home Assistant Energy Dashboard.
• Alarms, fault states, and operating mode sensors.
• Safe controls supported by your exact model.
• Sensor refresh mode: Automatic lets the integration choose a safe interval from device response time; Manual uses your fixed interval from 2 to 3600 seconds.

You can change the collector operating profile later from Collector connection and cloud. Inverter driver selection, control mode, and sensor refresh are under Polling and inverter detection.

In Automatic refresh mode, EyeBond Local keeps a small pause between polling cycles and applies protocol-specific limits. For example, fast Modbus devices can refresh more often than slower ASCII devices. In Manual mode, the diagnostic sensors Poll Utilization, Poll Duration, and Recommended Poll Interval show whether the chosen interval is realistic; if utilization stays high, increase the interval or switch back to Automatic. Poll Context shows whether the current cycle is reading the inverter, detecting an inverter, or only checking the collector, so long detection cycles are not confused with normal runtime polling.

See Runtime Detection and Entities for the driver selector, Fast versus Full protocol detection, multiple matches, control mode, and the difference between unavailable and disabled entities.

---

Device learning

Some devices can be added in read-only or partial mode first. Expand device support can then collect extra evidence or check which additional settings and sensors your exact device supports.

Use it when:

• the integration offers it for your device;
• monitoring works, but controls are missing;
• a developer asks you to run it while adding support for your model.

What to expect:

1. Start Configure → Expand device support.
2. Choose Analyze device data (recommended) or the advanced active-control verification.
3. When more than one compatible API is available, choose the exact cloud source for this run.
4. For active verification, confirm the temporary collector endpoint change, bounded cloud test commands, and their local interception by Home Assistant.
5. Sign in to the supported cloud account for this one session, if requested.
6. Review the result. Read-only evidence does not add entities automatically; only locally proven active results can be applied.

The cloud password is not saved. Learned items apply only to this Home Assistant device until they are reviewed and added to the built-in catalog.

If anything looks unsafe or unexpected, stop and create a Support Archive instead.

For the full walkthrough, see Device Learning.

---

Getting help

If the integration does not work as expected:

1. Open the integration in Settings → Devices & Services.
2. Click Configure → Diagnostics and service tools.
3. Click Create support archive.
4. Open a GitHub issue and attach the ZIP.

The Support Archive is the preferred way to report unsupported hardware, failed setup, missing sensors, or missing controls.

For details, see Support Archive.

Use these issue templates:

• Bug Report — something regressed on already-supported hardware.
• Support Archive / Hardware Diagnostics — new hardware, failed setup, missing sensors, or missing controls.
• Device Contribution — share a learned partial/unrecognized device (with its Support Archive) to get it added to the built-in catalog.
• Feature Request — UX improvements or broader feature requests.

---

Troubleshooting

Problem	Try this
Auto-scan finds nothing	Retry the scan or choose a different Home Assistant network interface. If needed, follow Setup and Discovery and use advanced setup with a known collector address.
Bluetooth Wi-Fi setup is unavailable	Make sure Home Assistant has Bluetooth access near the collector. An ESPHome Bluetooth Proxy near the collector can help.
Manual setup cannot verify the collector	Keep the setup flow open and retry with the collector reachable. For an inbound collector, enable background discovery and continue when its identified session appears.
Only the collector device appears	Runtime detection has not identified the inverter yet. Check Poll Context and follow Runtime Detection and Entities; create a Support Archive if no driver binds.
Sensors stay unavailable	Check that the collector and Home Assistant are on the same network and that the collector has stable Wi-Fi.
Vendor app stopped showing live data	Check the connection profile: Home Assistant only intentionally disconnects the cloud. If you still use Cloud + Home Assistant, see the known cloud telemetry issue below.
Vendor app works, but Home Assistant says unavailable	The collector may have reconnected to its cloud faster than it reconnected locally. Wait a few minutes and check Wi-Fi stability.
A setting changes back immediately	The inverter rejected the value or did not confirm it. Check diagnostics, avoid changing the same setting from the vendor app at the same time, and retry after the collector is stable.
Remote setup is needed	Use Remote / NAT setup guide. Prefer VPN over public port forwarding when possible.
Controls are missing	Keep Auto mode for normal use. If monitoring works but controls are missing, run device learning if offered, or create a Support Archive. Use Full Control only if you understand the risk.
An unconfigured collector connects later	Enable the persistent EyeBond Local — Discovery entry. It publishes identified, unconfigured collector sessions without creating a placeholder device.

Known cloud telemetry issue

Some users report that, in Cloud + Home Assistant, the vendor app stops updating or shows the collector offline while local Home Assistant readings continue. Cloud updates may return on their own. This is a known issue under investigation; we have not yet confirmed its cause or a general fix.

This is different from Home Assistant only, where cloud disconnection is intentional. Neither a longer polling interval nor a restart is a confirmed general fix for the intermittent problem.

If it happens, create a Support Archive during the outage, before restarting or switching modes if possible. Add it to issue #13 or your existing support issue, together with:

• the installed version and, for a manual test build, its commit;
• when the problem started, your time zone, and the cloud's last data timestamp;
• whether Home Assistant readings still change and when cloud updates resume.

You do not need to delete the integration or reset the collector to report this.

---

Documentation

• Documentation index
• Setup and discovery
• Runtime detection and entities
• Kevolt / Deye-compatible advanced controls — experimental opt-in settings for the documented 80 kW register map
• Collector management
• Device learning
• Diagnostic commands — advanced, developer-directed scenarios
• Support Archive
• Remote / NAT setup
• Proxy capture — use this only when asked during support
• Inverter model catalog
• Interface screenshots by version — visual examples with notes about controls that moved
• Contributing

---

License

Licensed under MPL-2.0.