Skip to main content

Home Assistant

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

Features

  • Push data to us (grid power, solar production, battery status)
  • Optional battery control: Receive charge/discharge instructions from us
  • Supports grid power, solar production, battery SOC, and charging power
  • Configurable push interval (10-300 seconds, default: 30)
  • Various sensors for monitoring push status and battery control state

Installation

HACS (Recommended)

  1. Install HACS in Home Assistant by following the steps (https://my.home-assistant.io/redirect/supervisor_addon/?addon=cb646a50_get&repository_url=https%3A%2F%2Fgithub.com%2Fhacs%2Faddons)
  2. Once HACS is installed, restart Home Assistant (Settings -> System -> Power icon in the top right).
  3. Go to Settings -> Devices & Services
  4. Click "Add Integration" in the bottom right
  5. Search for HACS, select it, check the options, and confirm.
  6. Link your GitHub account
  7. Select HACS from the list on the left
  8. Click the three dots in the top right corner
  9. Select "Custom repositories"
  10. Add https://github.com/clever-PV/home-assistant-clever-PV with the category "Integration"
  11. Click "Add"
  12. Search for "clever-PV" and install it
  13. Restart Home Assistant
  14. Go to the "Settings" tab - "Devices & Services"
  15. Click the "+ Add Integration" button
  16. Search for "clever-PV" and add it
  17. Follow the setup process

Manual Installation

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

Configuration in Home Assistant

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

Entities

The integration creates the following diagnostic sensors:

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

If battery control is enabled, additional sensors are created:

Sensor Description
Battery Control State Current command from us: Normal, Idle, Force Charge, Force Discharge, or Limit Charge Power
Battery Force Power Target power in watts (only set during Force Charge/Discharge)

Data Format

The integration sends the following data to us:

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=Standby, 1=Charging, 2=Disabled, 3=Discharging
batteryControlEnabled If "true", control commands are requested

Battery Control

If battery control is enabled, we can send commands to optimize your battery based on electricity prices and solar forecasts. These commands are held in two sensors:

  • Battery Control State: Normal, Idle (pause), Force Charge, Force Discharge, or Limit Charge Power
  • Battery Force Power: Desired power for the battery (except in Normal or Idle mode)

Requirements

  • An account with Smart Battery Price Control enabled
  • A configured dynamic tariff

How it works

  1. The integration sends batteryControlEnabled: true with every push
  2. We respond with control commands (if available)
  3. The commands 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 power

Using the Sensors

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

Reconfiguration

To change settings after the initial setup:

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

Troubleshooting

Enable debug logging by adding the following lines to your configuration.yaml:

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