TL;DR
- Surplus/excess charging decisions are driven by one device per home — the main device
- The main device is selected automatically, preferring whichever measurement source delivers the freshest values
- Control is event-driven: every main-device measurement triggers a decision pass
- Battery state is factored in across all connected batteries in the home, not only the one reported by the main device
Surplus charging control turns the home's PV surplus into real-world action — adjusting controlled loads so they consume excess solar power instead of feeding it into the grid. To do that, the control loop needs a single, authoritative view of the home's current energy balance. That view comes from the main device.
How surplus control works
One device per home acts as the measurement source for all surplus-control decisions — this device is referred to as the main device. Its readings (current grid power, solar production, and related values) are what the control loop evaluates on each cycle.
Control is event-driven: every time the main device reports a new measurement, the system runs a decision pass that:
- Compares current PV surplus against the targets of the home's controllable devices
- Turns controlled loads on or off, or adjusts their power, based on the surplus available
There is no background polling loop independent of the main device's readings — the control loop advances with each incoming main-device measurement.
Alongside the main device's power measurements, the decision pass also factors in the state of all connected batteries in the home — not only the battery reported by the main device. State of charge, charging/discharging power, and available capacity are combined across batteries (capacity-weighted state of charge, summed power) so the control loop treats the home's total battery state as a single aggregated view.
Main device selection
The main device is chosen automatically. Among the devices that produce power measurements for the home, the system prefers the one that delivers the freshest values — that is, the shortest update interval between measurements. This keeps the control loop responsive to real-world conditions.
Selection is re-evaluated whenever the set of measurement-producing devices changes — for example, when a device is added to the home, removed, or changes state. Any device that reports current power values for the home can qualify as the main device, regardless of its specific role as a grid-side meter, a production-side sensor, or an integrated meter reported by another device.
Identifying the main device from the API
The main device is also surfaced through the device list: the home's main electric meter is returned as the first entry in GET /v1/users/{userId}/devices. The entry's model.category is electricMeter, so clients can highlight the main meter in their UI directly from the list response without issuing a separate query.
If no electric meter has been picked as main yet — for example, immediately after onboarding before backend selection has run — the list still uses a deterministic fallback order: electric meters are sorted by creation time, then by ID. The first eMeter you see is therefore stable across calls.
If the home has no electric meters at all, the response simply contains no eMeter entry and this ordering rule does not apply.
See Main device selection for how the backend picks which meter is main.