Surplus Charging Control

TL;DR

• One device per home sets the cadence for PV surplus control — the main device
• clever-PV selects the main device automatically; is-main-device exposes this as read-only information
• Control is event-driven: updates from the main device trigger evaluation when control is active
• The main device does not have to supply the home's grid-power reading; relevant measurements from other devices are also considered
• 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. The main device sets the timing of this control loop, while the home's energy balance can include measurements from several connected devices.

How surplus control works

One device per home acts as the main device. Its measurement updates set the cadence of surplus control. This role is separate from supplying a particular measurement such as grid power, solar production, or battery state.

Control is event-driven: when control is active, a new measurement from the main device triggers evaluation 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

An electricMeter can therefore have is-main-device: true without exposing display-grid-power, while another device with is-main-device: false supplies grid-power measurements. This is not a contradiction, and false does not mean that a device's measurements are ignored.

The decision pass also factors in the state of all connected batteries in the home — not only the battery reported by the main device.

Main device selection

clever-PV selects the main device automatically based on the connected devices and the home's setup. The selected device can change as the setup changes. Clients do not need to reproduce the selection logic.

The is-main-device capability is read-only and informational. It cannot be changed through a capability PUT, and the Connect API does not offer manual main-device selection.

Identifying the main device from the API

Read the is-main-device capability in GET /v1/users/{userId}/devices or GET /v1/users/{userId}/devices/{deviceId}:

Code
{
  "name": "is-main-device",
  "data": {
    "isMainDevice": true
  }
}

• true: this device is currently the home's main device.
• false: this device is not currently the home's main device; its measurements may still contribute to control.
• Missing capability: no main-device status is exposed for this device. Do not infer the status from its other capabilities or its position in the list.

The role belongs to at most one electric meter per home. A home may have no main device yet, for example before selection has completed.

Clients can use the status for display or diagnostics. Do not use it to filter out measurements from other devices, to choose which device supplies grid power, or to infer that control is currently running.