Skip to content

feat(sonnen): set battery power via the local API (2.1.0) - #237

Draft
yogiohlsson-ai wants to merge 8 commits into
srcfl:mainfrom
yogiohlsson-ai:feat/sonnen-control
Draft

yogiohlsson-ai wants to merge 8 commits into
srcfl:mainfrom
yogiohlsson-ai:feat/sonnen-control

Conversation

@yogiohlsson-ai

Copy link
Copy Markdown

Summary

Adds battery control to the sonnen driver (drivers/lua/sonnen.lua, 2.1.0) through the local API v2. This is a separately reviewed control change on top of the read-only driver.

Draft, stacked on two open PRs. The first commit of this branch is the same change as #232 (Pac_total_W sign convention). It also needs srcfl/ftw#2028 (host.http_put, used to switch the operating mode). I will rebase once those are merged, so that only the commits of this PR remain.

How control works:

  • A setpoint is applied as manual mode (EM_OperatingMode = 1) plus POST /api/v2/setpoint/charge/{W} or /discharge/{W}. A setpoint of 0 clears it.
  • Every session starts with a confirmed PUT of mode 1. host.http_post is not gated by allow_write, so this PUT is what keeps a read-only driver from posting a setpoint.
  • The limit comes from the unit (IC_InverterMaxPower_w, 9900 W on the test unit). An optional max_power_w can lower it. If the unit reports no limit, setpoints are refused.
  • Lease: with no command for 60 s the driver hands the unit back to the automatic mode (default 2, self-consumption; 10 via default_operating_mode). Default mode and deinit do the same. Only refusals count against the hand-back attempts.
  • At start, a non-zero setpoint left in manual mode by a previous controller is cleared. A manual idle (setpoint 0) set by the owner is left alone.
  • setpoint_w is reported only after this session's own setpoint POST was confirmed and a fresh read shows manual mode. In the automatic modes the unit's SetPoint_W follows the house load and is never reported. Before this fix the first poll after start could report a setpoint this driver had not written (-1622 W and -942 W were seen).

Driver evidence

  • Driver id: sonnen
  • Device make/model: sonnenBatterie, three-phase, about 18.7 kWh
  • Firmware tested: 1.40.5
  • Protocol/register source: sonnen local REST API v2 (/api/v2/latestdata, /api/v2/configurations, /api/v2/setpoint/charge|discharge/{W}), measured on one unit
  • Hardware test performed: see Control evidence
  • Known limits:
    • The unit has no device-side timeout. A setpoint left by a killed or frozen controller stays on the unit (observed for more than 10 minutes). The lease works only while the driver runs. A leftover is cleared at the next start, and we recommend an external watchdog that sets the mode back to 2 if FTW is not running.
    • The first poll after a command can show the previous value (0) for about one second.
    • Only charging setpoints were exercised on hardware. Discharge is covered by fake-unit tests, including an unclamped discharge (-1500 W).
    • If the unit leaves manual mode while a session is active (for example changed from the app), the driver drops its setpoint on the next read. Covered by a fake-unit test, not tested on hardware.

Safety

  • The driver starts read-only, or this is a separately reviewed control change.
  • Vendor signs are converted at the driver boundary.
  • Cached telemetry becomes stale instead of being re-emitted as fresh.
  • No credentials, serial numbers, private addresses or site data are included.

Control evidence

  • HIL evidence: each write step was run by hand, one at a time, with a read-only logger and a rescue script ready that returns the unit to mode 2.
Test Result
Poll only, no writes Telemetry correct, setpoint_w null
500 W charge, release Charges 500 W, returns to mode 2
max_power_w 1000, request 3000 W Battery held at 995 to 1002 W
Lease 60 s Handed back to mode 2 exactly 60 s after the last command
kill -9 while charging Setpoint stays on the unit (see known limits)
Next start after kill -9 Orphan setpoint cleared, unit back in mode 2
SIGSTOP, SIGCONT, SIGTERM Charge continues while frozen, driver hands back on wake, default mode on exit
500 W charge with the setpoint_w fix No setpoint on the first poll, 500 W after the confirmed POST, null again after hand-back
  • Control changes include default-mode, lease-expiry and HIL evidence.

Checks

  • Commits include Signed-off-by.
  • make test-driver ID=sonnen: 44 passed, 10 skipped, 0 failed
  • make check: 5093 passed, 951 skipped, 0 failed (origin/main: 5091 passed).

🤖 Generated with Claude Code

https://claude.ai/code/session_017rc5E7dBomboUb3BCbVuNF

yogiohlsson-ai and others added 8 commits November 19, 2026 20:39
sonnen's JSON API v2 reports Pac_total_W positive while discharging. The
driver passed it through, so FTW showed charge as discharge. Negate it so
battery.w is positive while charging. Measured on a sonnenBatterie with
software 1.40.5 on 2026-11-13: in manual mode, a 500 W charge setpoint
read back over six reads as Pac_total_W -495 to -504 W, SetPoint_W -500
and BatteryCharging true.

The driver stays read-only. battery_pac_w keeps the vendor sign.

Signed-off-by: Jörgen Ohlsson <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
sonnen applies setpoints only in manual mode, which it enters through
PUT /api/v2/configurations; PATCH and POST there return 404. With FTW's
host.http_put and capabilities.http.allow_write, a battery command enters
manual mode and posts /setpoint/charge|discharge/<W>, limited to
IC_InverterMaxPower_w and an optional owner max_power_w.

A manual setpoint holds until replaced, so the driver owns the way back:
a 60 s lease in poll, default mode and deinit clear the setpoint and
restore the automatic mode the unit ran before (2 or 10), with readback;
init clears a manual mode a stopped FTW left behind; three failed
handovers stop the unprompted writes. {"error": ...} replies are failed
reads instead of w = 0. Without http_put the driver refuses commands and
keeps reporting telemetry.

Adds http_put to the host API profile and the harness mock.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Jörgen Ohlsson <[email protected]>
host.http_post is not gated by capabilities.http.allow_write. When the
unit already reported manual mode, a battery command skipped the PUT and
posted the setpoint directly, so a driver without write permission could
still move the battery. Every control session now starts with a
confirmed PUT; a refused PUT ends the command before any POST.

Also report 0 instead of -0 W when the battery is idle.

Found in a dry run of the hardware test protocol against a local fake
unit. The new harness case fails on the previous code.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Jörgen Ohlsson <[email protected]>
Default mode counted every failed hand-back toward the three-attempt
limit, including calls made while the unit was unreachable, such as FTW's
watchdog during a network loss. After three of those it reported the
default as held and the lease stopped trying, so the unit kept its manual
setpoint after the network returned. Only refusals, where the unit
answered the read, now count.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Jörgen Ohlsson <[email protected]>
…left

Init and default mode returned the unit to its automatic mode whenever it
reported manual mode. That overrode an owner who keeps the unit in manual
mode with setpoint 0 (idle), and without allow_write it still posted
setpoint 0, because http_post is not gated by allow_write.

Now the driver undoes its own session as before (setpoint 0, then the
automatic mode). A manual setpoint other than 0 that it did not set is
cleared with a PUT only. A manual mode with setpoint 0 that it did not set
is left alone. Without write access nothing is written.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Jörgen Ohlsson <[email protected]>
In the automatic modes a sonnenBatterie reports its own load-following
target in SetPoint_W (1255 W was seen in self-consumption). The driver
reported it as setpoint_w in every mode, so FTW would read it as a
command it never gave. setpoint_w is now emitted only after a fresh
/configurations read confirms manual mode.

A /configurations reply without EM_OperatingMode kept the mode from an
earlier read, and default mode could then report the unit as automatic
while another controller held a manual setpoint. Such a reply is now a
failed read.

The harness fake now follows the house load in mode 2, as the unit does.
Both new cases fail on the previous driver.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Jörgen Ohlsson <[email protected]>
When the unit was already in manual mode at start, the first poll
reported its SetPoint_W as FTW's setpoint, although this driver had not
posted one (-1622 and -942 W were seen in the harness log). setpoint_w is
now emitted only after this session's own setpoint POST was answered
"true" and a fresh read confirms manual mode. A refused POST, a hand-back
to automatic mode, or the unit leaving manual mode withdraws it. Mode 2
still never reports SetPoint_W.

The max_power_w config example now reads 5000.

The new harness case fails on the previous driver with -1622.

Signed-off-by: Jörgen Ohlsson <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Jörgen Ohlsson <[email protected]>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant