Hi everyone,
I’ve been working on a custom Home Assistant integration called Surplus Manager and I’d like to share it here.
The basic idea came from my own setup. I have several loads that I only want to run when enough PV surplus is available, but I didn’t want to build and maintain a large number of separate automations for every device.
So I started building one integration that manages the consumers centrally.
The integration uses the power value at the grid connection point as its main reference. In my setup, a positive value means grid import and a negative value means export.
This means it does not really care how the energy is produced. You can have one PV inverter, several PV systems, batteries or other sources. In the end, the grid meter shows whether there is actually energy left over.
When enough surplus is available, consumers are switched on one after another according to their configured priority. When the surplus disappears again, they are switched off again.
One important point for me was having separate priorities for switching on and switching off.
For example, I may want my pool pump to start first when surplus becomes available, but an electric radiator should be the first device to be switched off again when available power drops.
So each consumer has its own switch-on and switch-off priority.
Consumers can currently be configured with:
- a Home Assistant entity
- an expected power consumption
- an optional real power sensor
- minimum runtime
- minimum off time
- separate on/off priorities
- enabled or disabled state
The order can be changed directly in the dashboard card. On desktop, drag and drop is also supported.
There is also special support for climate entities. For these, Surplus Manager can set the HVAC mode and target temperature when activating the device.
I use this for split air conditioners, but the integration is not limited to climate devices. Normal switches and other controllable loads can also be used.
Another part that was important to me is battery monitoring.
You can add one or more battery guards with their own power sensors and discharge thresholds. If a battery starts discharging too heavily, Surplus Manager can begin reducing flexible loads before the system starts drawing significant power from the grid.
This is especially useful in setups with more than one battery or storage system.
There are also several timing options to avoid constant switching when PV production changes quickly:
- switch-on delay
- switch-off delay
- settling time after switching
- minimum runtime
- minimum off time
A configurable reserve can also be kept before the next device is switched on.
For example, if a consumer needs around 900 W and the reserve is set to 150 W, the integration waits until enough surplus is available for both.
A small amount of grid import can also be allowed if desired, because real power values are rarely completely stable.
The integration has an AUTO and a TEST mode.
In AUTO mode, devices are actually controlled.
In TEST mode, the logic still runs, but no devices are switched. I found this very useful when setting up the priorities and thresholds for the first time.
There is also a manual override for individual consumers. If a device is manually enabled through the card, the automatic control leaves it alone until it is returned to automatic operation.
The integration comes with its own Lovelace card.
It shows the current surplus, grid import, active load, battery status and the configured consumers. Consumers can be added, edited, removed and reordered directly from the card.
Most of the important settings are also available through the settings dialog, including the reserve, grid sensor, battery guards, operating mode and diagnostics.
The diagnostics section shows values such as current grid power, surplus, import, reserve, controller status and the next consumer that could be activated. This has been very useful while testing the control logic.
With version 2.3, I also added multilingual support.
The integration currently supports:
- German
- English
- French
- Spanish
- Dutch
By default, it follows the language configured in Home Assistant.
A fixed language can also be selected manually, either during the initial setup or later from the settings dialog in the dashboard card.
The configuration flow and the card interface are translated.
Version 2.3 also added some configuration checks for the grid sensor, consumers and battery sensors, so missing or renamed entities are easier to spot.
In version 2.3.2, I added an option to hide the explanatory help texts in the card. I wanted new users to have some guidance available, while keeping the interface cleaner for people who already know how it works.
The current version is 2.3.2.
The repository is here:
Installation is currently done through HACS as a custom repository.
Add:
as an Integration in HACS.
After installation and a Home Assistant restart, the integration can be added through Devices & Services.
The dashboard card is included with the integration itself.
The resource currently is:
/surplus_manager/surplus-manager-card.js?v=2.3.2
and the card can then be added with:
type: custom:surplus-manager-card
entity: sensor.uberschussmanager_uberschuss
The project is still fairly new, so I’d be very interested in feedback from other setups.
In particular, I’d like to know how it behaves with different smart meters, battery systems, climate devices and larger numbers of consumers.
Bug reports, feature ideas, UI suggestions and translation corrections are all welcome.
If anyone tries it, I’d also be interested to hear what kind of loads you are controlling with your PV surplus.