SMA WebConnect Inverter

Local telemetry driver for SMA solar inverters with a WebConnect (Speedwire) Ethernet interface — Sunny Boy, Sunny Tripower, and Sunny Highpower families. Polls AC power, DC input power, per-phase voltage and current, grid frequency, and daily / lifetime energy over the inverter's on-device HTTPS JSON-RPC surface. No cloud round-trip; the inverter serves everything on the LAN.

caution

The WebConnect JSON-RPC surface is read-only. There is no write / control endpoint over this API; if you need to curtail export, restart the inverter, or reconfigure feed-in behaviour, use the vendor web UI or a Modbus/TCP profile against the inverter's Modbus map instead. This driver is for monitoring.

Prerequisites

• An SMA inverter with a WebConnect / Speedwire interface. This covers:
  • Sunny Boy 1.5-AV / 2.0-AV / 2.5-AV / 3.0-AV / 3.6-AV / 4.0-AV / 5.0-AV / 6.0-AV
  • Sunny Tripower 3.0 through 25000TL / STP 15-25kW-3AV-40 range
  • Sunny Highpower PEAK1 / PEAK3
  • Older Sunny Boy TL with a SMA-Speedwire stick installed
• Older Bluetooth-only models (e.g. Sunny Boy 1.5-VL-40 / 2.5-VL-40) do not answer this API.
• The user or installer password set on the inverter web UI.
• Network access from the GEM host to the inverter on TCP 443 (HTTPS).

Setup steps

1. In a browser, open https://<inverter-ip>/ and confirm the SMA login page loads. Log in once with the same password you plan to use for GEM to verify it works.
2. In GEM open Devices → Add Device and select the sma_webconnect driver.
3. Fill in the device row:
   • Inverter IP Address — the LAN IP of the Speedwire interface (e.g. 192.168.1.60).
   • Web UI Password — the password matching the login group you'll use.
   • Login Group — pick usr for a homeowner-owned site, istl for an installer-owned site (Grid Guard).
   • Protocol — leave as https unless you have an old model that only speaks plain HTTP on Speedwire.
   • Port — 443 (default).
4. Save the device. On successful login you should see sma webconnect connected in the GEM log.
5. Create a zone on the device:
   • Subsystem — power (or a solar-specific subsystem if you have one).
   • Address — any label; plant, roof, or the inverter serial number are all fine.
6. Wait one poll interval (default 15 s). The driver populates telemetry attributes on the zone; verify from the attribute editor.

Attribute reference

Device attributes

Attribute	Required	Description
ip	✅	LAN IP of the inverter Speedwire interface.
password	✅	Web UI password. Secret.
user_group		usr (homeowner) or istl (installer). Default usr.
port		HTTPS port, default 443.
protocol		https or http. Default https.
status_interval		Poll interval in milliseconds. Default 15000, minimum enforced 5000.
request_timeout		Per-request HTTP timeout in milliseconds. Default 15000.

Zone attributes (written by driver)

The driver populates these on each poll — do not enter them by hand.

Attribute	Type	Description
ac_power	float (W)	Momentary total AC output. Sum of L1 + L2 + L3 on three-phase inverters.
dc_power	float (W)	DC input power on the primary string (A).
energy_today	float (kWh)	Yield since local midnight.
energy_total	float (kWh)	Lifetime yield.
grid_frequency	float (Hz)	Grid frequency at the inverter output.
inverter_status	string	ok, off, warning, error, stopped, mpp, or the raw numeric enum.
state	string	on when producing (> 5 W AC), off when standby / at night.

Zone address format

Any string label. This driver treats every zone as a facet of the same inverter — put multiple zones on the device only if you want to slice the same telemetry differently in your UI (e.g. one zone tagged roof, another historical). There is no per-string zone routing yet.

Commands

Command	Description
poll_status	Force an immediate telemetry read outside the poll cadence.
get_values	Return the raw JSON-RPC getValues payload — full object dump for debugging.
get_ac	Return AC power (total + per-phase), voltage, current, and grid frequency.
get_dc	Return DC power / voltage / current for the primary string.
get_energy	Return energy_today_kwh, energy_total_kwh, and operating / feed-in seconds.
get_status	Return the current inverter operating enum decoded to a string.
login	Force re-authentication and return a new SID.
logout	Invalidate the current session on the inverter.

Known limitations

• Read-only. No control endpoints — curtailment, restart, and firmware upgrade are not accessible over WebConnect JSON-RPC. Use Modbus/TCP against the inverter if you need write access.
• Single DC string. Only string A telemetry is polled (dc_power_a, dc_voltage_a, dc_current_a). Multi-MPPT inverters expose B / C / D under different object ids — future addition.
• Historical data not fetched. The inverter buffers 5-minute samples for up to 30 days; this driver only reads live values. Historical extraction is a future addition.
• Fixed object list. The polled object ids are hard-coded for the current-generation Sunny Boy AV / Sunny Tripower / Sunny Highpower firmware. Very old Sunny Boy TL firmware may return NaN for some ids — the driver skips those values rather than writing zero.
• Self-signed cert. Certificate verification is disabled (rejectUnauthorized=false). A future release will add an opt-in strict-verify mode for sites that have replaced the inverter certificate.

Troubleshooting

• sma err 501 on every getValues call — the login group does not have visibility on the requested objects. If the site was installer-commissioned, try user_group=istl. If you get 501 as istl too, the installer and user passwords differ — set the one matching the group you selected.
• Login returns SID but all values are null — the inverter is not a supported model. Verify it responds to the SMA Sunny Explorer / SMA Web Interface tools. Some older Sunny Boy TL firmware answers WebConnect but returns a completely different object catalogue.
• ECONNREFUSED / EHOSTUNREACH — Speedwire web server is disabled, or a local firewall on the GEM host is blocking outbound to 443. Log in to the inverter from a browser first to prove the interface is reachable.
• Password rejected but is correct in the web UI — SMA enforces per-group passwords. A site set up with only an installer password will reject user_group=usr. Switch to istl.
• Sudden burst of sma err 401 after weeks of running — the session expired or was invalidated by someone opening the inverter web UI in a browser. The driver re-authenticates automatically on the next poll.
• Telemetry disappears overnight — expected. The inverter drops to standby when there is no sun, reports 0 W, and puts inverter_status into off. Grid frequency and lifetime energy remain readable through the night.