clever-PV Home Assistant Integration

Push your PV system data (grid power, solar production, battery status) to the clever-PV Push API and receive battery control instructions if needed.

Features

• Push data to clever-PV (grid power, solar production, battery status)
• Optional battery control: receive charging/discharging instructions from clever-PV
• Supports grid power, solar production, battery SOC, and charging power
• Configurable push interval (10-300 seconds, default 30)
• Various sensors to monitor push status and battery control state

Installation

HACS (Recommended)

1. Open HACS in Home Assistant
2. Click the three dots in the top right corner
3. Select "Custom repositories"
4. Add https://github.com/clever-PV/home-assistant-clever-PV with category "Integration"
5. Click "Add"
6. Search for "clever-PV" and install it
7. Restart Home Assistant
8. Go to "Settings"->"Integrations"-Tab
9. Click "+ Add Integration button"
10. Search for clever-PV and add it.
11. Follow the setup flow

Manual Installation

1. Copy the custom_components/cleverpv folder to your Home Assistant's config/custom_components/ directory
2. Restart Home Assistant

Configuration in clever-PV

1. Add a Push API device according to this tutorial: https://support.clever-pv.com/hc/de/articles/22801081762066-Push-API
2. Optional: Enable AI Battery Control

Configuration in Home Assistant

1. Go to Settings > Devices & Services
2. Click Add Integration
3. Search for "clever-PV"
4. Enter your clever-PV Push URL (from your clever-PV account)
5. Select the entities to push:
   • Grid Power (required): Sensor showing grid power in watts (positive = import, negative = export)
   • Solar Production (optional): Sensor showing current solar production in watts
   • Battery SOC (optional): Sensor showing battery state of charge in percent
   • Battery Power (optional): Sensor showing battery charging/discharging power in watts
6. Configure optional features:
   • Enable Battery Control (optional): When enabled, clever-PV can send battery control instructions back to Home Assistant

Entities

The integration creates the following diagnostic sensors:

Sensor	Description
Push Status	Success or error status of the last push
Last Push	Timestamp of the last successful push
Last Response	Response message from the clever-PV API
Last Payload	JSON payload of the last push
Push Count	Total number of successful pushes

When Battery Control is enabled, additional sensors are created:

Sensor	Description
Battery Control State	Current instruction from clever-PV: Normal, Idle, Force Charge, Force Discharge, or Limit Charge Power
Battery Force Power	Target power in watts (only set for Force Charge/Discharge)

Data Format

The integration sends the following data to clever-PV:

Field	Description
watt	Grid power (positive = import, negative = export)
producingWatt	Solar production in watts
soc	Battery state of charge (0-100%)
chargingPower	Battery power in watts
powerStorageState	0=idle, 1=charging, 2=disabled, 3=discharging
batteryControlEnabled	When true, requests battery control instructions

Battery Control

When battery control is enabled, clever-PV can send instructions to optimize your battery based on electricity prices and solar forecast. These instructions will be held in two sensors:

• Battery Control State: Normal, Idle, Force Charge, Force Discharge, or Limit Charge Power
• Battery Force Power: Desired Power for your battery not in Idle or Normal mode

Prerequisites

Battery control requires:

• A clever-PV account with Smart Battery Price Control enabled
• A dynamic electricity tariff configured in clever-PV

How It Works

1. The integration sends batteryControlEnabled: true with each push
2. clever-PV responds with battery control instructions (if available)
3. The instructions appear as sensor values in Home Assistant

Control States

State	Description
Normal	Self-consumption mode (default behavior)
Idle	Pause charging and discharging
Force Charge	Charge battery at specified power
Force Discharge	Discharge battery at specified power
Limit Charge Power	Self-consumption with limited charging

Using the Sensors

You can use the battery control sensors in Home Assistant automations to control your battery inverter. For example, create an automation that reads the Battery Control State sensor and sends the appropriate command to your inverter.

Reconfiguration

To change settings after initial setup:

1. Go to Settings > Devices & Services
2. Find the clever-PV integration
3. Click Configure
4. Update the Push URL or entity selections

Troubleshooting

Enable debug logging by adding to configuration.yaml:

logger:
  default: info
  logs:
    custom_components.cleverpv: debug

License

This project is licensed under the MIT License - see the LICENSE file for details.