docs: clarify watts-only rule for literal power-limit values#3996
Merged
springfall2008 merged 1 commit intoJun 2, 2026
Merged
Conversation
Literal numeric values for inverter_limit / export_limit / battery_rate_max etc. bypass Predbat's required_unit auto-conversion (which only fires when the value is a sensor reference, reading unit_of_measurement from the HA entity). A literal `inverter_limit: 7.3` is therefore taken as 7.3 watts, not 7.3 kW — clamps battery_draw to ~0.0006 kWh per 5-min step and produces a plan that looks like Predbat refuses to discharge. Adds an NB callout at the top of "Inverter control configurations" naming every affected key, plus a concrete YAML example under inverter_limit (for consistency with pv_ac_limit which already has one). Cross-referenced from the "unsupported inverter" guide where custom- inverter users — most likely to use literals because no sensor exists for their inverter limit — actually land. Related: springfall2008#3979
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Spawned from discussion #3979 where gcoan asked for a docs note making the literal-vs-entity behaviour explicit. Two surgical edits:
docs/apps-yaml.md— NB callout at the top of Inverter control configurations naming every key affected by the literal-vs-entity unit rule, plus a concrete YAML example block under### **inverter_limit**(for consistency with### **pv_ac_limit**which already has one).docs/inverter-setup.md— one bullet added to I want to add an unsupported inverter to Predbat, cross-linking to the new callout. Custom-inverter users are the most likely to hit this trap (they hand-write the dict rather than copy a tested template, so don't get a sensor-reference example to follow).Why
Without the callout, a user reasoning "I have a 7.3 kW inverter, the docs say 'in watts' so 7.3 is wrong, but I'll use what feels natural" could easily land on
inverter_limit: 7.3and silently lose discharge planning. The existing docs say5000for a 5 kW inverter but don't explain why the unit handling is asymmetric between literals and sensor references — so the rule is invisible if you don't already understand the auto-conversion machinery.The callout names the specific failure mode (
battery_drawclamp, plan with no discharge) so future searchers hitting the symptom find the docs by Google rather than via a github discussion.Out of scope (could be a follow-up if useful)
templates/*.yaml. Most use sensor entities for the relevant keys (so auto-conversion works) and commented-out literal examples are already correct; trap doesn't bite copy-pasters in practice. Happy to PR that separately if you'd like coverage there too.Test plan
docs/apps-yaml.mdanddocs/inverter-setup.mdvia mkdocs locally or on the docs site after merge — confirm the new callout + YAML block render cleanly and the cross-link from inverter-setup.md resolves.