get_automation_settings
ChatGPTHousehold optimisation (automation) settings of the user's home: how clever-PV controls the home battery (smart price control, charge shifting, PV control with minimum state of charge, eco offset), e.g. "battery control", "minimum state of charge", "charge the battery from the grid". Read it before set_automation_settings. Includes the interventions that currently block a setting from taking effect. Interventions and the applicable flags reflect the moment of this call; they do not say whether a blocker existed at an earlier time. Intervention ids (deviceId names the affected battery when set): subscription-upgrade-required = the user's subscription does not include this setting; solar-forecast-setup-required = the solar forecast is not enabled for the home (set a home location with a PV producer connected; it is enabled once the first forecast exists); battery-capacity-required = the battery's capacity is unknown and must be entered; battery-software-update-required = the battery firmware is too old for smart control, update it via the manufacturer; wrong-operating-mode = the battery runs in an operating mode that does not allow external control, change it in the manufacturer's app or via the installer; email-verification-required = the manufacturer account needs its e-mail address verified; authentication-required = clever-PV lost access to the manufacturer account, the battery must be reconnected. The battery and solar forecast interventions only appear on smartPriceControl and chargeShifting; the other sections only carry subscription-upgrade-required. applicable = false means the stored value currently has no effect: smartPriceControl and chargeShifting without a supported battery, smartPvControl and minSocPvControl without a battery, unknownBattery when the home has a known battery.
get_current_power
ChatGPTCurrent power of the user's home right now, in W: solar production, grid flow (positive = drawn from the grid, negative = fed in), battery flow (positive = charging, negative = discharging), state of charge (only with a single battery; with several, read each one via get_devices), house consumption and the consumers that report power (same payload as GET v1/users/{userId}/home/current-power). Use this for any question about the current or live state ("now", "right now", "at the moment", "how much is my PV producing", "am I feeding in", "battery level"); use get_energy_data only for past days or periods. measuredAtUtc is the report time of the grid value; mention it when it is more than a few minutes old. Null values mean no device reports them.
get_device
ChatGPTRead-only. Get one device of the user's home with its capabilities and the current stored settings and status of each capability (same data as in get_devices). Call it after a set_ tool to check whether the stored value now matches the requested one. Changing a capability needs the matching set_ tool.
get_devices
ChatGPTRead-only. List all devices of the user's home (PV system and electric meter with the home battery, wallbox, car, heat pump, heating rod, smart plug) with their capabilities and the current stored settings and status of each capability. Call it first for any question about devices or their settings, e.g. "my devices", "state of charge of my car", "wallbox settings", "how big is my battery", and before any change to find the deviceId and the capabilities. Changing a capability needs the matching set_* tool, e.g. battery-capacity -> set_battery_capacity.
get_electricity_tariffs
ChatGPTBuy and sell electricity tariffs of the user's home, past and current, with their validity window (to = null: open-ended) and pricing: price in ct/kWh (null for dynamic tariffs), baseFee in EUR per month, gridFee and variablePriceComponents (same payload as GET v1/users/{userId}/electricity-tariffs), e.g. "my electricity tariff", "base fee", "feed-in tariff". Exchange prices per hour are in get_energy_prices.
get_energy_data
ChatGPTMeasured energy data of the user's home for one date in the home's time zone: summary, intervals and per-device breakdown. Without period: the daily view with 5-minute intervals in W (per-device consumptionWh in Wh per interval; gridConsumptionWatt is signed, negative = feed-in), interval timestamps UTC (same payload as GET v1/users/{userId}/energy-data/daily). With period weekly, monthly or yearly: aggregated intervals for the period containing the date (weeks run Monday to Sunday; same payload as GET .../energy-data/period); consolidatedIntervals[].date is dd-MM-yyyy (weekly and monthly: one entry per day; yearly: the first day of each month). Summary and intervals energy in Wh; costs in euro cents (ct): gridConsumptionCosts is the energy cost (fixed tariff: tariff price; dynamic tariff: stock price plus grid fees) plus the prorated base fee and is 0 without a buy tariff. A home without data returns a zero summary and empty or blank intervals. Use this for history (past days, weeks, months, years or the course of today), e.g. "consumption yesterday", "solar yield in May", "electricity costs this month", not for the current power: use get_current_power for that.
get_energy_forecast
ChatGPTQuarter-hourly energy forecast (price, consumption, PV production, battery state and grid flows) from now until the end of the solar forecast, usually through tomorrow (24 hours without one), e.g. "when will my battery be full", "forecast for consumption and grid import". Prices in ct/kWh (null if unknown), energy in kWh, battery state of charge (soc) in % (null without a battery), timestamps UTC. Fails with homeLocationRequired, solarProducerRequired, solarForecastDisabled or solarForecastNotAvailable when a prerequisite is missing.
get_energy_prices
ChatGPTWholesale day-ahead stock prices (EPEX spot) of the price zone of the user's home, in ct/kWh without grid fees, taxes or VAT; each slot carries its start as UTC timestamp. from and to are inclusive and must lie within yesterday, today and tomorrow (counted in Europe/Berlin); each date covers one calendar day in the home's time zone. Tomorrow's slots are missing until the day-ahead prices are published. Use it for questions such as "exchange price tomorrow" or "when is power cheapest today"; the user's own tariff and fees are in get_electricity_tariffs.
get_solar_forecast
ChatGPTSolar production forecast for the user's home: production measured so far today, hourly forecast for today and tomorrow (calendar days in the home's time zone), underlying weather and sunrise/sunset, e.g. "how much solar power will I get tomorrow". Timestamps are UTC. Fails with homeLocationRequired, solarProducerRequired, solarForecastDisabled (only when no forecast exists; otherwise the result has enabled = false) or solarForecastNotAvailable when a prerequisite is missing.
set_automation_settings
ChatGPTReplace the household optimisation (automation) settings of the user's home, i.e. how clever-PV controls the home battery, e.g. "set the minimum state of charge to 20 %", "charge the battery when power is cheap". Read get_automation_settings first and send it back with only the value the user asked for changed. The size of the home battery is not set here but with set_battery_capacity. The complete object is required; settings whose value is unchanged are not re-applied. Changed values are applied one at a time; if a later value fails to apply, part of the object may already be stored — retrying with the same object converges to the target state. minSocPvControl.minSoc must be 0-100 (%), ecoOffset and smartPvControl.minChargingPower must be greater than or equal to 0 (W); these ranges are only enforced for values that actually change. Changing a setting that requires a subscription the user does not have fails with paymentRequired. unknownBattery.hasUnknownBattery is ignored while the home has a known battery.
set_battery_capacity
ChatGPTSet the battery capacity (size of the battery) of a device with the battery-capacity capability: a car, the car charged at a wallbox, or a home battery (listed on its electric meter, model.category electricMeter). Use it whenever the user wants to enter or correct the size of a battery or storage, e.g. "change the battery size", "adjust the storage capacity", "my battery has 10 kWh", "enter my car's battery size", or when the intervention battery-capacity-required or target-charging-setup-required asks for it. Convert kWh to Wh (8 kWh = 8000). This is the size, not a charge limit (set_charge_limit) and not a minimum state of charge (set_automation_settings). The charging plan of a car or wallbox needs it to start. Call it only when the user asked for this change. Changes only this setting. get_device shows the new value once clever-PV has applied it.
set_battery_soc_plan
ChatGPTEnable or disable battery priority for a device with the soc-plan capability (only homes with a battery): clever-PV switches the device on once the home battery reaches the maximum state of charge and off again when it falls to the minimum while the battery is not charging, e.g. "only switch on once the battery is full". It does not control the battery itself; the home battery's own minimum state of charge is set_automation_settings. It takes effect only while smart mode is on (set_smart_mode). The change is applied asynchronously. Call it only when the user asked for this change. Changes only this setting. get_device shows the new value once clever-PV has applied it.
set_boost
ChatGPTStart or stop boost for a wallbox or car with the boost capability: it charges immediately at full power regardless of PV surplus and prices until boost is stopped, the car is unplugged or reaches its charge limit, e.g. "charge now", "charge the car full right away". To simply switch charging on or off use set_device_on_off. The change is applied asynchronously. Call it only when the user asked for this change. Changes only this setting. get_device shows the new value once clever-PV has applied it.
set_charge_limit
ChatGPTSet the state of charge in percent up to which clever-PV charges a car with the set-charge-limit capability, e.g. "set the charge limit to 80 %", "only charge up to 80 %". This is a limit of the car, not of the home battery, and not the battery size (set_battery_capacity); to reach a target by a departure time use set_target_charging. A charge limit the car reports itself replaces this value. Call it only when the user asked for this change. Changes only this setting. get_device shows the new value once clever-PV has applied it.
set_charging_mode
ChatGPTSet how a device with the charging-mode capability charges with PV surplus: clever stops as soon as the surplus is missing; casual follows the averaged surplus and tolerates short dips; chargeAlways never stops and keeps at least the minimum current, taking the rest from the grid. Use it for requests such as "change the charging mode" or "always charge, even without sun". The minimum solar share is set_sun_share, a one-off charge at full power is set_boost. Call it only when the user asked for this change. Changes only this setting. get_device shows the new value once clever-PV has applied it.
set_device_on_off
ChatGPTSwitch a device that has the on-off capability on or off: a smart plug, relay or heating rod is switched, a wallbox or car starts or stops charging. Use it when the user wants a device on or off right now, e.g. "turn on the heating rod", "switch off the plug", "stop charging". To charge at full power regardless of PV surplus use set_boost; to run a device with solar surplus only use set_solar_optimization. The change is applied asynchronously. Call it only when the user asked for this change. Changes only this setting. get_device shows the new value once clever-PV has applied it.
set_device_priority
ChatGPTSet the PV surplus priority of a device with the priority capability (consumers such as cars, wallboxes, heating rods, heat pumps or smart plugs), e.g. "charge the car first", "change the order of my devices". Lower numbers get surplus first: the device with priority 1 is switched on first, and when the surplus drops the device with the highest number is switched off first. get_devices shows each device's current value under priority, and the app lists the devices in the same ascending order. Two devices must never share a priority: before setting a value, read the values of all devices from get_devices. To put several devices into a desired order, call this tool once per device and give each a distinct value in that order starting at 1 (e.g. 1, 2, 3); if the new value is already taken, move the other devices as well. Call it only when the user asked for this change. Changes only this setting. get_device shows the new value once clever-PV has applied it.
set_home_location
ChatGPTSet the geographic location of the user's home (the PV system site), replacing the stored location, e.g. "change the location of my system", "enter my address". The coordinates drive the solar forecast, which requires a home location: with a PV producer connected, the forecast is generated in the background and then enabled; until it exists, get_solar_forecast fails with solarForecastNotAvailable. latitude must be -90 to 90 and longitude -180 to 180 (decimal degrees, WGS84); street, postalCode and city are optional and informational, and an omitted one is cleared.
set_max_charging_current
ChatGPTSet the maximum charging current of a wallbox with the max-amperage capability. Values outside the range the wallbox supports are rejected. Changes only this setting; the command is accepted asynchronously and get_device shows the last accepted value.
set_phase_mode
ChatGPTSet how many phases a device with the phase-mode capability (usually a wallbox) charges on: a fixed single, two or three phases, or automatic switching, e.g. "charge on one phase", "switch to three phases", "automatic phase switching". Only the modes get_device lists under availablePhaseModes are accepted. Call it only when the user asked for this change. Changes only this setting. get_device shows the new value once clever-PV has applied it.
set_price_control
ChatGPTEnable or disable price control for a device with the price-control capability: clever-PV runs the device from the grid while the end-customer price (exchange price of the home's price zone plus the grid fees of its tariff) is at or below the threshold, e.g. "charge when power costs less than 20 ct", "set a price threshold". To run a device in the cheapest hours of a dynamic tariff use set_price_optimization. It takes effect only while smart mode is on (set_smart_mode). The change is applied asynchronously. Call it only when the user asked for this change. Changes only this setting. get_device shows the new value once clever-PV has applied it.
set_price_optimization
ChatGPTEnable or disable price optimization for a device with the price-optimization capability (today heat pumps): with a dynamic electricity tariff, clever-PV runs the device in the cheapest hours, e.g. "run my heat pump when power is cheapest". This is not set_price_control, which switches a device on while the price is at or below a threshold. The device must be in smart mode (smart-mode); enabling price optimization does not turn smart mode on, and without it the device will not run: turn it on with set_smart_mode when the user asks for it. The tool only switches price optimization on or off. Enabling fails with paymentRequired when the subscription is free or expired, does not cover another smart device or does not include price optimization, and with interventionFound while another prerequisite blocks the capability. The change is applied asynchronously. Call it only when the user asked for this change. Changes only this setting. get_device shows the new value once clever-PV has applied it.
set_smart_mode
ChatGPTTurn smart mode, the automatic control by clever-PV, on or off for a device with the smart-mode capability (consumers such as a wallbox, car, heat pump, heating rod, smart plug or relay). Smart mode is the main switch of a device: only while it is on does clever-PV control the device with PV surplus (set_solar_optimization, set_sun_share, set_charging_mode), electricity prices (set_price_control, set_price_optimization), battery priority (set_battery_soc_plan) and charging plans (set_target_charging). While it is off, these settings have no effect and clever-PV does not control the device. Use it when the user wants clever-PV to control a device automatically, e.g. "turn on smart mode", "let clever-PV control my heat pump", or no longer, e.g. "stop controlling the wallbox automatically". Turning it off also stops an active charging plan, and a heat pump or heating rod is switched off. A manual or scheduled switch-on can turn smart mode off by itself. For a car that charges at a wallbox, use the wallbox. get_device shows the state under smart-mode: enabled, and reason for what currently controls the device. Turning it on fails with paymentRequired when the subscription is free or expired or, with a Starter subscription, another device already uses smart mode, and with interventionFound while another prerequisite blocks the device.
set_solar_optimization
ChatGPTEnable or disable PV surplus control (solar optimization) for a device with the solar-optimization capability, for example a heating rod, smart plug, heat pump, wallbox or car: clever-PV then runs or charges the device with surplus solar power (for a wallbox or car, set_sun_share decides how much grid power may be added), e.g. "charge with surplus solar", "run it on solar power only". It takes effect only while smart mode is on (set_smart_mode). Enabling fails with paymentRequired without the needed subscription, or with interventionFound while a prerequisite blocks it. Call it only when the user asked for this change. Changes only this setting. get_device shows the new value once clever-PV has applied it.
set_sun_share
ChatGPTSet the minimum solar share in percent for a wallbox or car with the sun-share capability: clever-PV charges once the PV surplus covers this share of the charging power and takes the rest from the grid. 100 charges with solar surplus only; lower values also charge when there is little sun, e.g. "charge with at least 50 % solar", "also charge when there is little sun". Switching PV surplus control on or off is set_solar_optimization; charging always, even without sun, is set_charging_mode (chargeAlways). Allowed values are 10 to 100 in steps of 10; other values are rejected with validationError. Call it only when the user asked for this change. Changes only this setting. get_device shows the new value once clever-PV has applied it.
set_target_charging
ChatGPTSet the charging plan (target charging) of a car or wallbox with the target-charging capability: charge up to a target by a departure time (local time of the home). Use it when the user wants the car charged by a certain time, e.g. "charge to 80 % by 7 am", "I need 200 km of range tomorrow morning". For a general upper limit without a time use set_charge_limit. The plan runs only while smart mode is on (set_smart_mode); turning smart mode off stops it. Only the sent fields change; omitted fields keep the stored plan, and get_device shows the current plan under target-charging. Without a stored plan, omitted fields default to unitType kwh, executionTime 00:00, type once and useSmartChargePlan true; send targetWh, or unitType percent with targetSoC. enabled true starts and false stops the plan. Starting is checked before the other fields are stored: it fails with paymentRequired without the needed subscription, with carLinkedToWallbox for a car that charges at a wallbox (set the plan on the wallbox), or with interventionFound (e.g. target-charging-setup-required while the vehicle's battery capacity or consumption is not set; set them with set_battery_capacity and set_vehicle_consumption), and then nothing of the call is stored. In get_device, target-charging shows consumption in Wh per 100 km and batteryCapacity in Wh. For a driving range in km, use unitType kwh with targetWh = km * consumption / 100, e.g. 200 km at 18000 Wh/100 km = 36000. The command is accepted asynchronously.
set_vehicle_consumption
ChatGPTSet the average energy consumption of a car, or of the car charged at a wallbox, with the consumption capability, e.g. "my car uses 18 kWh per 100 km". The charging plan needs it, together with the battery capacity, to start. Call it only when the user asked for this change. Changes only this setting. get_device shows the new value once clever-PV has applied it.
