Document that FRITZ read head needs USB power; battery cadence too slow

The read head only refreshes ~every 2 min on battery, which is far too slow
for AstraMeter's ~1 s control loop, so battery balancing won't work. Make this
explicit (USB raises it to ~10 s) in docs/powermeters.md, config.ini.example,
and the web generator blurb.

Author: claude

config.ini.example

@@ -366,9 +366,10 @@ THROTTLE_INTERVAL = 0
 # HTTPS = False
 # VERIFY_SSL = True
 # TIMEOUT = 10.0
-## The read head refreshes every ~2 min on battery (≈10 s when USB-powered), so
-## throttle polling toward its update cadence — e.g. 10 (USB) up to 120
-## (battery-only) — instead of hitting the box every second.
+## IMPORTANT: power the read head over USB. On battery it only refreshes every
+## ~2 min — too slow for AstraMeter's ~1 s control loop, so battery balancing
+## won't work. USB raises the update rate to ~10 s; this throttle matches that
+## so AstraMeter doesn't hammer the box between fresh readings.
 # THROTTLE_INTERVAL = 10
 
 # [SCRIPT]

docs/powermeters.md

@@ -417,6 +417,8 @@ SERIAL_NUMBER = 0
 
 Reads grid power from an [AVM FRITZ!Smart Energy 250](https://fritz.com/en/products/fritz-smart-energy-250-20003088) smart-meter read head. The read head pairs with a FRITZ!Box over DECT and clips onto a digital electricity meter; AstraMeter polls the FRITZ!Box's [AHA-HTTP-Interface](https://fritz.com/fileadmin/user_upload/Global/Service/Schnittstellen/AHA-HTTP-Interface.pdf) (`getdevicelistinfos`) for the current reading.
 
+> **⚠️ Power the read head over USB.** On battery the read head only refreshes its reading roughly **every 2 minutes** — far too slow for AstraMeter's ~1 s control loop, so battery balancing **will not work** (the batteries would be steered from a reading that's minutes stale). Connect the read head to USB power, which raises the update rate to ~10 s and makes it usable. Even at 10 s it's on the slow side; a meter that updates every second (e.g. SML/P1, Shelly, SMA) gives noticeably tighter control.
+
 ```ini
 [FRITZ]
 HOST = fritz.box
@@ -427,15 +429,16 @@ AIN = 12345 0123456
 # HTTPS = False
 # VERIFY_SSL = True
 # TIMEOUT = 10.0
-# The read head updates every ~2 min on battery, so don't poll faster than that
-THROTTLE_INTERVAL = 2
+# Power the read head via USB: on battery it only updates ~every 2 min, too slow
+# for control. USB raises that to ~10 s, which this throttle matches.
+THROTTLE_INTERVAL = 10
 ```
 
 **Authentication.** Create a FRITZ!Box user with the **Smart Home** permission under *Home Network → FRITZ!Box Users* and put its name/password in `USER`/`PASSWORD`. AstraMeter logs in through `login_sid.lua` (supporting both the PBKDF2 and legacy MD5 challenge) and reuses the session, re-authenticating automatically if the box expires it.
 
 **AIN.** Find the AIN under *Home Network → SmartHome* (open the device's detail/edit view). The read head exposes two sub-units under that base AIN: `-1` (*Strombezug* / grid import) and `-2` (*Einspeisung* / feed-in). Both report the **signed** instantaneous power (positive = import, negative = feed-in), so AstraMeter reads the `-1` branch as net grid power and appends `-1` automatically when no suffix is given. Spaces in the AIN are optional.
 
-**Update rate.** The read head reports about every 2 minutes on battery, speeding up to ~10 s when powered over USB. Set `THROTTLE_INTERVAL` so AstraMeter doesn't poll the box faster than it gets fresh data.
+**Update rate.** USB power is effectively required (see the warning above): the ~2 min battery cadence is too slow for battery control, while USB raises it to ~10 s. `THROTTLE_INTERVAL = 10` then matches that USB cadence so AstraMeter doesn't hammer the box between fresh readings.
 
 ## Script
 

web/ts/schema.ts

@@ -623,7 +623,7 @@ export const POWERMETERS: Powermeter[] = [
     id: "fritz",
     label: "FRITZ!Smart Energy 250",
     section: "FRITZ",
-    blurb: "An AVM FRITZ!Smart Energy 250 meter read head, via the FRITZ!Box AHA-HTTP-Interface.",
+    blurb: "An AVM FRITZ!Smart Energy 250 meter read head, via the FRITZ!Box AHA-HTTP-Interface. Power it over USB — on battery it only updates every ~2 min, too slow for battery control.",
     docPython: "docs/powermeters.md#fritzsmart-energy-250",
     fields: [
       { key: "HOST", label: "FRITZ!Box host", type: "text", default: "fritz.box", placeholder: "fritz.box", required: true, help: "The FRITZ!Box hostname or IP the read head is paired with." },