Repository navigation
Services Reference
Use Developer Tools > Actions to run PowerSync actions or add them to a Home Assistant automation. Generic battery actions use the selected connection’s control route. Confirm its capabilities before enabling an automation. Some calls return response data with ownership, readback or recovery status.
Configuration · Battery connections · Controls and automations
| Service | Description | Parameters |
|---|---|---|
power_sync.sync_tou_schedule |
Manually refresh Time-of-Use tariff prices. Tesla systems upload the schedule; Modbus systems store it for PowerSync display and optimization | None |
power_sync.sync_now |
Refresh provider and battery data immediately | None |
power_sync.recover_ev_headroom can request fresh Tesla vehicle
and local Powerwall meter readings when a retained EV reservation blocks battery
grid charging. Choose
Developer Tools → Actions → PowerSync: Recover EV charging headroom.
Supply the affected vehicle's exact VIN and enable Allow provider refresh.
Specify entry_id when multiple PowerSync entries are installed.
action: power_sync.recover_ev_headroom
data:
vin: YOUR_17_CHARACTER_VIN
allow_provider_refresh: trueThe action makes up to two independent vehicle reads and local meter updates, with a five-second interval and an eight-second timeout per round. This gives normal two-second meter polling time to satisfy the unchanged three-second acquisition-progress check. Teslemetry refreshes can consume credits; there are no automatic paid retries. The car is not woken or commanded, settings are not changed, and battery charging is not started. There is a one-minute cooldown between recovery attempts.
success: true with reservation_cleared: true confirms durable retirement of
the targeted reservation after consistent fresh stopped/zero-current/zero-power
readings. Retry the intended battery charge or wait for the next optimizer cycle.
Other guards still apply; this response does not prove physical battery charging.
Stale or conflicting data, active EV ownership, unresolved recovery holds,
unavailable sources, or changed identities leave the reservation held and return
success: false with an error. Send that response and attempt time to support
first. Another log is not required to try recovery. Do not delete the reservation
store or repeatedly run the action when the car cannot supply fresh data.
| Service | Description | Parameters |
|---|---|---|
power_sync.force_charge |
Force battery charge from grid for a timed window |
duration optional, whole minutes 1–1440, or until as HH:mm in HA timezone; omit both for 30 minutes; power_w optional, 0/omitted uses inverter default |
power_sync.force_discharge |
Force battery discharge/export for a timed window |
duration optional, whole minutes 1–1440, or until as HH:mm in HA timezone; omit both for 30 minutes; power_w optional, 0/omitted uses inverter default |
power_sync.hold_battery_soc |
Hold the battery around its current SOC and block normal charge/discharge where the hardware supports it |
duration optional, minutes, default 30 |
power_sync.set_self_consumption |
Put the battery into self-consumption mode | None |
power_sync.restore_normal |
Cancel force/hold/self-consumption overrides and return to normal operation | None |
In Battery controls, enable Custom charge/discharge time to enter hours and minutes under Run for, or a finish time under Until. Both Charge and Discharge use this timing; +/− changes duration by one minute. Quick presets return to preset timing. Hold charge and Power the home continue to use the Run for preset. Tap twice to confirm; changing time or power requires confirmation again.
Both services accept whole-minute duration values from 1 to 1440, or until: "18:30" in Home Assistant’s configured timezone. Supply one timing field only; omitting both retains 30 minutes. Until selects the next valid occurrence, shows tomorrow when appropriate, and rounds up by less than one minute. DST skips/repeated hours use the next real occurrence; windows beyond 24 elapsed hours are rejected. Provider limits still apply, including Amber’s 240-minute maximum, FoxESS’s 1092-minute maximum and native SolaX/Neovolt duration support. Existing discharge Custom entity IDs and saved values remain compatible.
Coverage notes:
-
Force Discharge retains presets through six hours and its existing Custom entity IDs. The dashboard’s custom time now applies to Charge and Discharge; Hold / Self Consumption retains its separate preset duration picker. SolaX discharge durations must match the native export option or remote-control range; SolaX charge schedules must be shorter than 24 hours. Neovolt durations must fit every battery’s native range and step. Unsupported manual requests are rejected before ownership or timer changes.
-
The countdown is the requested window. Native modes, SOC/reserve limits, connectivity, HA availability and restore success can affect actual discharge; a running timer does not prove battery export. Cancellation, expiry and restart use the existing restore and recovery safeguards.
-
Force charge/discharge routes through Tesla, Sigenergy, Sungrow, FoxESS, GoodWe, AlphaESS, Solax Hybrid, ESY Sunhome, SAJ H2/HS2, Fronius Reserva, SolarEdge, and Anker Solix where the configured hardware exposes the required controls.
-
On Tesla, a manual battery command waits for an in-flight optimizer command to finish before taking control. A successful request or active countdown confirms command handling; use fresh Battery Power and Grid Power readings to verify discharge/export.
-
When requesting a Tesla
restore_normalservice response,pending: truemeans restoration is still awaiting physical settling, whilenoop: truemeans there was no override to restore. Neither response is independent proof of battery power; use fresh site readings and restoration status. -
Tesla native Max charge and discharge can run alongside managed EV charging when the active site has fresh, verified import/export limits and control ownership. The native site adjusts battery power around household and EV demand. EV charging is not a blanket export veto; reserve, export permission, unresolved settings and other site limits can still prevent a command. Battery discharge does not add extra EV import capacity. Other brands require their own verified equivalent control capability.
-
Sigenergy manual Force Discharge and optimizer export use PV-first discharge whenever live DC or third-party AC solar is present, even when solar is below the grid-export ceiling. ESS-first is selected only when live solar is known to be zero. The configured grid-export ceiling and ESS discharge limits still apply; PV-first prioritizes solar but does not guarantee a particular battery discharge rate.
-
Neovolt / Bytewatt is also supported when the upstream Neovolt integration exposes dispatch mode, power, duration, charge target, and discharge cutoff entities.
-
Anker Solix direct X1 Modbus and the official local HA bridge support dispatch when third-party control/write entities are available. The unofficial Anker cloud bridge can be telemetry-only when owner-account or writable preset entities are missing.
-
Custom / external controller systems are planner-only. These services do not dispatch hardware for that battery system; use the optimizer sensors as inputs to your own controller or automations.
-
power_wis best-effort. ESY Sunhome is mode-only, and SAJ H2/HS2 uses a percentage of rated power through the upstream SAJ integration. -
hold_battery_socis strongest on Modbus systems with a standby/backup mode. Tesla and AlphaESS are best-effort; solar surplus can still move SOC. -
Turning off an already inactive Tesla Force Charge/Discharge switch leaves the tariff unchanged when there is no outstanding override or recovery. A historical tariff cache alone no longer starts a restore. Genuine force, Hold SoC and restart recovery still run; for Other / Custom TOU, recovery without a captured tariff uses the configured custom schedule before the historical cache. Saving Custom rates still does not automatically upload them to Tesla.
-
Force charge/discharge state is persisted across Home Assistant restarts. If a timed force mode is still valid after restart, PowerSync restores the mode and its expiry timer; if it expired during downtime, PowerSync restores normal operation. Paired Powerwall local dispatch is an exception: startup releases it without replaying power. SolarEdge is another exception: startup does not replay persisted force commands or timers. Retained or uncertain controls require supervised reconciliation.
-
After Tesla force discharge, including cleanup of a failed start, PowerSync checks the Tesla battery SOC before restoring the saved backup reserve. If the saved reserve exceeds the measured SOC, it skips that reserve write to avoid triggering grid charging and notifies you to set the reserve manually. This does not confirm that physical discharge stopped; check battery and grid power as well.
Fixed battery control includes solar standby consumption in site import and export calculations on every renewal.
If a slow read leaves local telemetry too old to renew dispatch, PowerSync reads the gateway once more within the original control window. Dispatch stops if fresh telemetry is still unavailable.
Explicit positive numeric force_charge and force_discharge requests use timed LAN control on paired Powerwalls with a gateway address. Max and optimiser requests follow the Preferred battery control selector described below. Charge power is battery input; discharge power is a grid-export target that accounts for live home load and solar. Configured rate, reserve, charge ceiling, site import/export and network-envelope limits apply. The usual monitoring/external-control and demand-protection gates remain in force.
Gateway-configured site import/export limits are read automatically with fresh local telemetry. Charging respects import headroom; discharge respects the export limit before adding home load and subtracting solar. The export range respects both the configured site export limit and available battery output after home load and solar, including a learned gateway battery ceiling. For example, a 10 kW battery ceiling with 8 kW home load and no solar leaves about 2 kW available for grid export. The battery ceiling still caps every actual command. Raised or lowered site limits are picked up as local telemetry and controls refresh; failed config reads stop dispatch rather than erase a limit.
Selected Local V1R never falls back to a tariff. An explicit numeric request also fails rather than becoming unrestricted tariff control. Any Automatic fallback needs fresh safety checks and an optimiser plan for the tariff route; it cannot reuse a precise local request's duration. Once a local command may have reached the battery, a competing control waits for an acknowledged resume. Uncertain cleanup remains pending. Restart releases the old local request instead of replaying it.
If Automatic chooses tariff control on an eligible paired Powerwall, a manual or automation force_charge with power_w: 0 or no power parameter requests native Tesla Max charging. Selecting Tariff uses the cloud settings and tariff path without requiring a live LAN gateway. An explicit positive numeric target remains on the local wattage path. The saved preference determines the optimiser route. Native Max temporarily uses a charging tariff, Time-Based Control and reserve, then restores the captured settings; it does not change grid-charging permission or gateway site limits.
The timed-command ceiling can be lower than native charging capability. Max can exceed the saved optimiser charge planning rate. A finite software import limit requires a fresh gateway limit no higher. Managed EV control can coexist when fresh site evidence confirms Tesla can enforce the applicable limits; missing proof keeps admission blocked. For export, PowerSync can first tighten a higher gateway limit to the software limit under a recorded restore obligation. It confirms that limit before forcing export or admitting new EV demand, then restores the original limit during cleanup.
Startup restores a retained Max session without replaying charging. Settings restoration can precede physical settling by about a minute. PowerSync retains ownership until two fresh, balanced readings show charging has returned to its original level; uncertain signed writes and tariff uploads retain cleanup as well. This path needs HA for timed restoration and has no short hardware lease. Check actual Battery Power and Grid Power to verify the result.
The Tesla-only Preferred battery control selector is saved per Home Assistant entry and shared with the mobile app. It is available independently of an optimiser subscription; actual controls retain their existing admission checks.
- Tariff (default): use Tesla cloud control for Max and optimiser charge/export. An unreachable paired gateway does not block cloud tariff uploads. Cloud settings/readback, restore ownership, demand/network protections and shared EV headroom checks remain in force; no local startup kick is required. Tariff control does not hold an exact software watt target.
- Local V1R: use timed gateway commands capped at 10 kW or a lower learned charge/discharge ceiling. This requires pairing and fails explicitly if local control is unavailable; it does not silently upload a tariff.
- Automatic: choose charge and discharge independently using fresh home load, solar, connection limits and available battery power. A multi-Powerwall site can therefore use Local V1R for a modest export and Tariff for charging. Missing or unsafe telemetry selects Tariff, whose own safety checks must still pass. A running native tariff action retains its route until restored.
Explicit positive kW requests retain local wattage control regardless of this preference. They cannot become unrestricted tariff actions. Local inverter output includes home consumption as well as export, so the same grid-export target may fit the local ceiling at one load and exceed it at another.
Changing the preference stops the current force action and confirms restoration before saving. Pending or failed cleanup keeps the previous preference. PowerSync attempts unfinished cloud settings restoration even after local control has stopped. Grid-charging confirmation is still required before Tariff export starts. The optimiser requests a fresh plan; a stopped manual action is not replayed. Mobile reads the saved backend preference and hides the selector when an older backend does not advertise support.
When Automatic selects native tariff control on a paired Powerwall site, Max charge/discharge and optimiser actions use tariff control for the sustained action. When safe, PowerSync sends one local startup command capped at 10 kW, explicitly releases it, then applies the tariff. It skips the startup command when existing battery output, solar or home demand makes it restrictive. A brief transition in power is possible.
For native Max discharge, PowerSync can verify a temporary gateway export limit when the software cap is tighter than the gateway’s reported limit or the gateway explicitly reports no limit. A stricter native limit remains in place. Missing, null or malformed capture blocks takeover. After the battery settles, PowerSync restores the exact owned limit while preserving external changes. A failed readback keeps the action or restoration pending. Import limits, reserve, SOC and EV ownership apply independently.
The optimiser's configured charge/discharge rate is a planning value. A rounded rating below reported site capacity does not block targetless tariff control. Reserve and charge-cap safety calculations use the higher reported/configured rating. A reserve-limited window can therefore be shorter than the planned row; allowed minutes do not prove an accepted command or physical export. Shortened native deadlines are saved without repeating the startup command or extending the original action.
For optimizer export at or below 20% usable SOC, PowerSync uses tariff forcing, including with Local V1R selected. The configured reserve floor still applies. Crossing 20% during a local export releases local control and requests a new plan. The low-SOC tariff path skips the startup pulse. Battery Mode reports powerwall_native_tariff with low_usable_soc_export. Manual numeric targets retain local control.
The Battery Mode attributes distinguish a pending request, acknowledged tariff control and pending restoration. startup_kick_w describes the startup request, not current battery power. Use Battery Power and Grid Power to check physical results. Interrupted actions retain their original restoration owner across restart.
If a signed local settings reply is lost, Settings → System → Repairs → Powerwall local settings recovery retains the affected site and incident. PowerSync: Resume Powerwall settings through cloud (power_sync.resume_powerwall_settings) requires the notice's entry_id, site_id, incident_id and explicit acknowledge: true. It resumes cloud access under supervision; it does not change device settings or prove that the earlier request finished. Verify the intended Tesla settings and measured Battery/Grid Power after a subsequent supported change. Keep the Repair until the incident is resolved.
Recover Powerwall local settings under supervision provides a separate administrator recovery path for an old generic settings incident. In Developer tools → Actions, run power_sync.recover_powerwall_local_settings with the affected entry_id and operation: inspect. It returns the current limits, site_id, incident_id, and recovery_revision. To accept the inspected configuration, use operation: resume, those same IDs, expected_recovery_revision set to that returned revision, and both acknowledgement fields enabled. A changed configuration or incident requires a fresh inspection.
This action sends no device command. It retains the original incident and restore evidence while reopening local settings and persistent limits. The original full configuration may still apply later, including unrelated permissions and limits; explicit acceptance of that uncertainty is required. Active controls, submissions and unfinished restores block recovery. New uncertain writes block access again. The exception survives restart only for the same site and pairing, and the retained outcome remains available in inspection and diagnostics even if Repairs was ignored. A native site-limit transaction keeps its own reconciliation path.
Local settings writes remain suspended for that site. Timed Local V1R charging also respects this restriction when it would enable or restore grid-charging permission. Unfinished permission restoration stays pending. Short timed power commands that require no settings change remain subject to their normal fresh-telemetry, ownership, SOC, power-limit and permission checks; charging requires grid charging already permitted. These commands do not clear the Repair or reopen local settings. Native Max has separate recovery admission checks.
EV planner settings and cached battery levels save without overwriting a concurrent Powerwall recovery record.
| Service | Description | Parameters |
|---|---|---|
power_sync.reconcile_solaredge_control |
Read fresh storage settings and clear the persistent control block only when a safe baseline is verified; writes only to restore the baseline of a dispatch PowerSync itself completed |
entry_id required; acknowledge: true required |
Inspect the inverter under supervision before calling this service. A restart or a successful service request alone does not establish safe device settings. See SolarEdge Control Recovery for the procedure and the limitation for uncertain active-power curtailment writes.
| Service | Description | Parameters |
|---|---|---|
power_sync.set_backup_reserve |
Set the hardware backup reserve / minimum SOC |
percent required, 0-100 |
Supported reserve writes: Tesla Powerwall, Sigenergy, Sungrow, FoxESS, GoodWe, Solax Hybrid, Fronius Reserva, SolarEdge, and Neovolt / Bytewatt when the upstream reserve/cutoff entity exists. GoodWe shared control verifies on-grid reserve through the selected GoodWe Experimental connection and leaves off-grid DOD unchanged. Charge, discharge, Hold SoC and restore use the same connection and fresh device register readback; the EMS controls and telemetry must belong to the same loaded GoodWe device. ESY Sunhome, SAJ H2/HS2, and direct Anker X1 Modbus do not expose a validated PowerSync backup reserve write path, so the call is logged as unsupported or no-op for those systems.
Tesla currently rejects reserve values from 81-99%; PowerSync clamps those requests to 100%.
Tesla backup reserve changes, including optimizer and restore requests, use the Tesla cloud API and require a separate matching reserve readback. Local pairing does not provide offline reserve control. If cloud access or confirmation fails, PowerSync reports the reserve change as unconfirmed and retains its existing restore/retry safeguards. Other local telemetry and controls remain available.
When another force or restore command takes over, an older force-charge reserve request stops retrying its previous value. A standalone reserve request also stops if a newer settings request takes its place. A temporary reserve pulse still completes its exact restore before releasing the reserve write lock. Cleanup from a failed charge kick carries its original ownership checks, so a queued cleanup cannot restore settings over a newer command.
The Grid Export Rule selector waits for its settings operation to finish before the next automation action can run, and reports a failure to that automation if the change fails. When combining ordinary settings with Force Charge or Force Discharge, apply the ordinary settings first and start the force action last: a later manual settings change can restore an active force session before applying the new setting.
The Backup Reserve number also waits for its settings service to finish before the next automation action runs. This keeps a following Grid Charging or force action from overtaking the reserve request. Completion of the service does not by itself prove that Tesla applied the reserve or that the battery is charging; check the reported reserve and fresh Battery/Grid Power.
The Backup Reserve entity uses the confirmed cloud value, with its existing saved-value fallback when cloud data is unavailable; local raw reserve remains diagnostic data. Previously saved user preferences are not automatically rewritten. Confirm your intended reserve after updating if you previously saw unexpected settings.
On paired Powerwalls using tariff control, optimiser charge refreshes retain tariff control for the active plan. A Restore message saying physical settling is pending means the saved settings have been restored, but fresh local power readings have not yet confirmed that forced charging has settled. PowerSync keeps cleanup ownership until two fresh, balanced readings confirm this; normal charging from surplus solar can continue without blocking completion. Restoring settings does not guarantee an immediate change in measured battery power.
| Service | Description | Parameters |
|---|---|---|
power_sync.set_operation_mode |
Set Powerwall operation mode |
mode: autonomous, self_consumption, or backup
|
power_sync.set_grid_export |
Set Powerwall grid export rule |
rule: never, pv_only, or battery_ok
|
power_sync.set_grid_export_auto |
Restore Tesla's grid export rule from PowerSync's preferred automatic behavior | None |
power_sync.set_grid_charging |
Enable or disable grid charging |
enabled boolean |
power_sync.set_storm_watch |
Enable or disable Storm Watch when the site supports it |
enabled boolean |
power_sync.set_off_grid_ev_reserve |
Set the battery percentage reserved for EV charging during an outage |
percent required, 0-100 |
power_sync.set_vpp_enrollment |
Enroll or unenroll from a Tesla grid-services program |
program_id, enrolled boolean |
power_sync.schedule_max_backup |
Raise backup reserve to 100% for a fixed window, then restore the previous reserve |
duration_minutes required, 1-1440 |
power_sync.refresh_calibration |
Clear PowerSync's local Powerwall calibration guard after a calibration cycle | None |
power_sync.resume_powerwall_settings |
Resume cloud settings after an unresolved local settings write; retains the incident and original restore evidence |
entry_id, site_id, incident_id from Repairs; explicit acknowledge: true
|
power_sync.recover_powerwall_local_settings |
Administrator adoption of current local settings after an unresolved generic write; preserves the original unknown incident | Inspect first; then exact entry/site/incident IDs, expected_recovery_revision, acknowledge: true, accept_unknown_full_configuration_write: true
|
Operation mode, Grid Charging and grid-export preferences can use a paired same-site gateway for local writes and independent readback, including with Tariff control selected. Unpaired or unavailable local access falls back to confirmed cloud settings. These settings do not require native watt control. Tariff uploads and backup reserve changes continue through cloud.
If a signed local reply is lost, Settings > System > Repairs provides supervised recovery instructions. Run Resume Powerwall settings through cloud using the IDs in the notice, then use Restore Normal or make the intended setting change and verify Tesla settings and measured Battery/Grid Power. Resumption itself issues no device command. It persists across restart and failed cloud attempts; local settings writes remain suspended. The old full configuration write may still apply later, so this action accepts uncertainty rather than proving completion. Original restore evidence remains with the incident after active forcing ends. Ignoring the notice does not resume control.
Restore Normal finishes a current forcing owner. After that owner ends, the retained incident basis is a reference for explicit manual recovery and is never automatically replayed over newer settings. A failed active restore remains retryable through cloud and retains its existing ownership protections.
Before starting Tesla force charge or force discharge, PowerSync records the current Grid Charging setting so normal operation can restore it exactly. If neither paired local control nor Tesla's cloud response exposes that setting and PowerSync has no remembered preference, the force command is rejected before any Powerwall setting changes. Set the Grid Charging control in PowerSync once, then retry; the confirmed preference is remembered for later force sessions.
The Grid Charging control can take up to a minute while PowerSync checks Tesla's response. If Tesla accepts the request and repeatedly returns valid site information without the grid-charging field, PowerSync reports acceptance without claiming confirmed readback. A slow final check no longer discards that result at the timeout boundary. Invalid or contrary replies still fail verification; check fresh Battery/Grid Power to establish actual charging.
Paired native control correctly reads an omitted charge-from-grid disallow flag as false within a returned native site_info object, across firmware versions. Manual Local V1R, native Max, scheduled charging and owned setting restoration use the same native default. No firmware allowlist or additional firmware query is required. An unavailable native configuration or explicit invalid value is still unknown.
Tariff force discharge checks the live Grid Export setting on each gateway. When a fresh local or cloud reading reports battery_ok, PowerSync skips the write. Otherwise it requests battery export and checks Tesla's acceptance. An accepted energy-setting receipt may omit the field. It records submission only. New Tariff discharge sessions leave export enabled afterward. Older retained sessions, native Max and explicit Grid Export setting changes can have stricter readback and restoration requirements.
Tariff discharge preparation requires Grid Charging Off across every configured site. Setting confirmation can take up to 60 seconds across the sites. After 45 seconds, a fresh, explicitly opposite response can permit one retry. Missing fields alone do not trigger that retry. The optimizer rechecks the active plan, recent measurements, reserve and permissions before applying tariff discharge.
When Local V1R or Automatic lacks usable gateway Grid Charging evidence, the plan can still charge from solar but excludes grid refills. On eligible scheduled charges, PowerSync can temporarily enable a known disabled setting, verify it, and restore the original value afterward. A change by another controller or missing restoration evidence can end or hold the operation. Tariff mode uses the cloud route and its own confirmation checks.
Powerwall charging blocked and Powerwall discharge blocked report refusals caused by the corresponding permission or site evidence. Each warning clears after a later eligible action passes the corresponding checks. Check the exact refusal and fresh battery/grid power before relying on dispatch.
Configure temporary tariff prices in Tesla force-discharge prices. For measured results, compare Battery Power, Grid Power and current gateway settings.
| Service | Description | Parameters |
|---|---|---|
power_sync.powerwall_go_off_grid |
Physically disconnect from grid using local Powerwall control |
bypass_soc_check optional boolean; mode optional advanced TEDAPI mode override |
power_sync.powerwall_reconnect_grid |
Reconnect to grid | None |
power_sync.powerwall_verify_pairing |
Verify the stored local pairing key | None |
power_sync.powerwall_set_on_grid_solar_curtailment |
Save the paired gateway's permission to reduce supported solar while grid-connected; confirm native setting readback |
enabled boolean; entry_id required when multiple PowerSync entries exist |
power_sync.powerwall_get_battery_calibration_delay_status |
Read calibration deferral allowance and remaining delay; response required |
entry_id required for multiple entries |
power_sync.powerwall_delay_battery_calibration |
Request one calibration deferral in whole hours after a fresh allowance check |
delay_hours positive integer; optional request_id; entry_id required for multiple entries |
Local off-grid control requires completed gateway pairing. Powerwall 3 uses signed TEDAPI commands; Powerwall 2 uses the local gateway path.
Allow on-grid solar curtailment is also exposed as a switch in the paired Tesla Powerwall Local Control dashboard card. Its state reflects gateway setting readback, not measured solar reduction.
On-grid solar curtailment is a persistent native permission, separate from off-grid control and battery dispatch. Use it with an export restriction such as power_sync.set_grid_export with rule: never. Solar can continue supplying the house and charging the battery; this is not a command to switch off all PV or directly control a separate AC-coupled inverter. The action requires a paired LAN gateway and has no Fleet/tariff fallback. Monitoring Mode blocks automated changes; a monitoring-only battery connection always blocks them. To undo a change, explicitly set the previous enabled value. Stopping battery dispatch does not change this permission. A confirmed permission is not proof that solar production fell. Powerwall 2 compatibility and any firmware-specific SOC requirement remain unverified. There is no confirmed universal requirement for 100% SOC: under zero export, solar can still supply household loads and battery charging. A physical test must observe grid connection, PV production, home load, battery power and grid power, with any independent inverter controller isolated so its actions are not attributed to Tesla.
Calibration delay: choose 1, 2, 3, 6, 12 or 24 hours in the delay action, or supply another positive whole-hour value. Firmware must report an available allowance before PowerSync sends a request. Some firmware acknowledges the native delay command but returns UNIMPLEMENTED for status; the selector stays disabled because the allowance cannot be checked. An acknowledgement alone does not prove deferral. This does not cancel calibration or clear calibration_active / PowerSync's optimiser guard. No Fleet fallback, automatic retry or automatic scheduling is performed. Supply a stable request_id for each intended request; an uncertain ID is never resent. Status reads are allowed in Monitoring Mode; automated writes are blocked.
action: power_sync.powerwall_set_on_grid_solar_curtailment
data:
enabled: trueSee Battery System Setup for the full pairing process, including the 2-minute DC-isolator toggle window and re-pair confirmation behavior.
When a Tesla site is configured, PowerSync also exposes helper entities for local control:
| Entity | Purpose |
|---|---|
| Pair Powerwall Gateway button | Starts local Powerwall gateway pairing. Re-pairing requires a second press within 30 seconds. |
| Unpair Powerwall Gateway button | Clears the stored local key after a two-press confirmation. |
switch.power_sync_off_grid |
Calls local off-grid / reconnect services and reflects the actual island state when local data is available. |
| Powerwall Local Paired binary sensor | Shows whether local pairing is complete |
| Powerwall Gateway IP Missing binary sensor | Flags Tesla sites that need a local gateway IP before local controls can work |
| Powerwall Off-Grid binary sensor | Mirrors the local island/on-grid state when available |
| Service | Description | Parameters |
|---|---|---|
power_sync.curtail_inverter |
Manually curtail the configured AC-coupled inverter |
mode optional: load_following default or shutdown
|
power_sync.restore_inverter |
Restore the configured AC-coupled inverter to normal operation | None |
Automatic curtailment uses the configured AC inverter settings and current price/load data. Manual load_following mode passes home load to controllers that support it; unsupported paths fall back to zero export or native curtailment behavior.
For Enphase (Envoy Installer integration), PowerSync waits up to 15 seconds after each DPEL service call for Home Assistant to confirm the changed setting. Delayed HA refreshes no longer cause an immediate failure. Missing confirmation or a conflicting control change stops further writes and preserves the saved settings for a later restore. This does not change Envoy or Enlighten communication timeouts, and confirmation of settings does not prove a change in solar output.
| Service | Description | Parameters |
|---|---|---|
power_sync.get_calendar_history |
Return battery energy history for the mobile app |
period optional: day, week, month, or year
|
power_sync.sync_battery_health |
Update Tesla battery-health data from a mobile TEDAPI scan or capacity blueprint |
original_capacity_wh, current_capacity_wh, degradation_percent; optional battery_count, scanned_at
|
get_calendar_history supports service responses in Home Assistant versions that expose response data from service calls.
These are Home Assistant entities, not Developer Tools services, but they are part of PowerSync's control surface:
| Entity | Description |
|---|---|
switch.power_sync_auto_sync |
Automatically refreshes tariff prices. Tesla sites show this as Auto-Sync TOU Schedule because the schedule is uploaded to the Powerwall; non-Tesla systems show Auto-Sync Tariff Prices because PowerSync stores the prices for display and optimization |
select.power_sync_force_charge_duration |
Default duration used by force-charge controls |
select.power_sync_force_discharge_duration |
Default duration used by force-discharge controls |
number.power_sync_force_discharge_custom_duration |
Saved custom duration in whole minutes; retains its entity ID and existing discharge Custom behavior, and initializes dashboard custom charge/discharge timing |
select.power_sync_hold_self_duration |
Separate Hold / Self Consumption duration, retaining the existing choices through 240 minutes |
number.power_sync_force_power_kw |
Preferred manual force charge/discharge power target in kW; 0 uses inverter/BMS maximum |
switch.power_sync_optimization_enabled |
Turns Smart Optimization on or off without deleting saved optimizer settings |
switch.power_sync_monitoring_mode |
Blocks ordinary battery dispatch while telemetry and planning continue; independently permitted curtailment and owned-state recovery have separate rules |
switch.power_sync_auto_update |
Enables PowerSync's HACS update automation; configure the update time in Configure > Advanced settings > PowerSync auto-update |
switch.power_sync_away_mode |
Makes the load forecaster recover from holiday/low-load periods |
switch.power_sync_profit_max_mode |
Uses the more aggressive LP terminal value profile for strong export windows |
switch.power_sync_optimization_spread_export |
Smooths planned battery export across eligible export windows when supported |
switch.power_sync_optimization_spread_import |
Smooths planned grid charging across same-price import windows when supported |
Tesla sites also expose number/select/switch/binary entities for backup reserve, off-grid EV reserve, operation mode, grid export rule, grid charging, Storm Watch, VPP program enrollment, manual export override, grid-services status, permission-to-operate, active Powerwall alerts, and calibration state when the site supports them.
The mobile app's Automations engine also exposes actions such as Enable Optimizer, Disable Optimizer, AEMO spike export, EV charging actions, and grid-status workflows. These are PowerSync automation actions, not separate Home Assistant Developer Tools services.
The Import kWh and Export kWh triggers measure cumulative site grid energy in the selected direction inside a required daily time window. Each fires once when its configured kWh threshold is crossed, persists its window state across restarts, and resets for the next local window. Import uses only point-of-common-coupling import and Export uses only point-of-common-coupling export; unavailable counters fall back to bounded live grid-power integration instead of treating missing telemetry as zero. Use the existing IF conditions and actions to apply the measured threshold safely. Export kWh is exposed only when the Home Assistant backend advertises support; Cloud automations do not accept this trigger.
| HA service | Parameters and effect |
|---|---|
power_sync.set_connected_ev |
Required loadpoint_id; optional vehicle_id and entry_id. Selects the vehicle profile for a shared physical non-Tesla charger. Omitting/clearing vehicle_id selects no vehicle and disables automated control until a profile is selected. It is not proof that a cable or vehicle changed physically. |
power_sync.preview_history_relink |
Optional entry_id. Previews matching Sungrow entity relinks without changing entities. |
power_sync.apply_history_relink |
Optional entry_id, required confirm: true. Applies ready relinks; it does not rewrite recorder statistics. Create a backup and inspect the preview first. |
See Sungrow history relink for identity checks and verification. These are HA services, not the normal connection-source selector or mobile charging-mode buttons.
power_sync.get_ev_recovery_status inspects retained attempts for
one exact uppercase VIN. Supply vin and, when multiple PowerSync entries are
loaded, entry_id. It returns original IDs, operations, deadlines, producer
identities, generation/revision and available request metadata. It performs no
provider refresh, wake, control, history migration or hold removal, and does not
end a manual-control session. Unloaded history is reported as unavailable.
Status also includes automatic_native_recovery: the last passive attempt,
its result and the next retry time. Background recovery checks continue after
restart without an active charging session. They use existing native telemetry
and make no provider refresh, wake or charging request. Stale, incomplete or
non-advancing reports keep the hold; sufficiently fresh stopped/zero reports
allow the existing recovery checks to release it.
native_route_diagnostics reports producer-binding and ownership-session matches
separately. A new PowerSync-owned plan can carry the same verified native
connection out of a completed session's old lease automatically. Actual
provider/entity changes, unresolved commands and finite cleanup remain blocked.
Native Fleet/Teslemetry/Tessie current and limit requests retain their actual HA service value and unit before dispatch. Historical missing values stay missing.
PowerSync adds operational recovery for native Start, Stop, current and limit uncertainty. It uses two advancing stopped/zero reports with stable settings, exact producer identity, no active writer and a finite settling period. It preserves old outcomes as unknown and re-enters normal electrical/ownership admission. Status separates historical unknowns from current blockers and shows recovery results/retry times. It no longer requires an unavailable historical terminal proof to resume ordinary control. See native recovery details.
power_sync.get_ble_recovery_status returns each configured bridge's native receipt capability, power freshness and retained command requirements. Enable response data and supply the exact entry_id when multiple PowerSync entries are installed. It reads existing HA data without refreshing telemetry, restarting a bridge, ending a manual-control session or issuing vehicle commands.
The action reports the applicable Stop-only or general command-history action, firmware recovery capability and any unfinished bridge commit. Historical unknown outcomes can remain while no operational blockers remain. Inspection never clears a hold. See Tesla BLE reliability.
power_sync.recover_ble_command_history reconciles Start, Stop, current and
charge-limit history using the full inventory, confirm_complete_history: true
and optional exact entry_id. Both Pedro and yoziru have compatible companion
adapters; they require different component/library pins.
Every bridge freezes executable old work, reboots into a persistent read-only session, and supplies fresh source-native stopped/zero reports. HA saves the recovery decision before firmware commit, and retains a durable pending-commit fence across restart until the exact generation unlocks. Original outcomes stay unknown. New commands traverse ordinary ownership, settings and electrical admission. A new unknown command receives a new hold. See the complete procedure.
power_sync.recover_ble_stop_history provides an explicit
recovery route for held Stop-only history on bridges running the PowerSync
companion firmware. It needs the complete inventory of {prefix, vin} pairs,
confirm_complete_history: true, and optionally entry_id. Do not confirm if
any historical vehicle is missing, a bridge moved between vehicles, or its
history is uncertain. Legacy bridge aliases remain historical aliases.
Every declared bridge restarts into a persistent read-only session and must provide fresh native stopped, zero-current and zero-power proof. PowerSync saves the entire release before unlocking bridges. Mixed positive/unknown commands, changed bindings/owners, another held incident and missing proof remain held. Retained outcomes are not rewritten as confirmed, and recovery does not replay a saved Start. An interrupted unlock retries the same complete inventory against the exact durable release.
A retry can reconcile an older attempt when the original bridge and quarantined command still match. Missing bindings or incomplete reports keep the hold. Pause EV automations and other writers. Follow the companion firmware and recovery procedure to preserve the original bridge inventory, keys and pairings.
If the PedroKTFC companion fails to build with ESPHome 2026.11 because
format_hex is undeclared, update both PowerSync references in the existing
bridge YAML to v2.12.1776 or newer, then rebuild and install the firmware
with the existing pairing. Follow the ESPHome package example.
power_sync.recover_ev_transport takes the exact vin, an optional incident_id
and optional entry_id. It performs the supported stock-node restart and
independent vehicle reconciliation, preserving charge limits, existing plans
and original stop times. Request its structured response in Developer Tools →
Actions to distinguish completed recovery from a held incident.
Recovery tries BLE Wake first when a sleeping car prevents fresh readback. If cloud fallback is configured and BLE still fails, it can request one native Fleet or Teslemetry cloud Wake and wait up to 60 seconds before reading again. This can use provider credits. BLE-only mode keeps cloud Wake disabled, and a Wake acknowledgement alone cannot release the charging hold.
Native Teslemetry recovery may also request an explicit data refresh when cloud fallback is permitted, because its ordinary vehicle-data response can be cached. Each read permits at most one refresh and can use provider credits; the returned vehicle timestamp and requested settings still require validation. Command confirmation can use the same bounded refresh after an ordinary read returns cached data, without changing the selected provider or extending the charging deadline. Periodic status reads do not force refreshes. BLE-only mode does not enable these paid refreshes.
Supported stock bridges may omit unchanged charge fields. PowerSync can use an advancing authenticated vehicle-data update to establish local transport health within the same established connection. Cached updates replayed on reconnect do not qualify. This does not make cached power fresh or confirm that a command changed the car. Completed or proven-unsent commands retain exact completion proofs so reload cannot incorrectly turn them back into pending commands.
If recovery fails, it requests the bridge's BLE Connection switch off to contain the unresolved transport and logs the reason. This is a recovery action; a connected BLE status alone does not prove fresh vehicle charge data.
This service does not clear historical uncertainty, confirm missing producer inventory or grant a new charging session. Its initial supported profiles and held-state guidance are in Tesla BLE EV Charging. Automatic controllers use the same recovery and retain pending plans for retry.
After a cleanup Stop completes, its saved completion proof releases the old stop-only route in the running controller as well as storage. A new command selects its own route without requiring a reload. Unresolved commands and other vehicles' holds remain separate.
The existing force-charge, force-discharge, hold-SOC, self-consumption and restore services route through Amber when that battery backend is selected. power_sync.preserve_battery accepts entry_id and a duration from 1 to 240 minutes. Explicit nonzero watt targets are rejected. See Amber modes, ownership and expiry.
PowerSync can explicitly manage Tesla's own Charge on Solar through PowerSync Fleet or a Teslemetry vehicle connection. This is separate from PowerSync Solar Surplus and Smart Schedule: Tesla controls the vehicle's charging rate in native mode.
The matching mobile controls appear under EVs & Chargers > Vehicles > Tesla Charge on Solar. Opening the card reads cached provider/ownership status only. Tap Read Tesla settings to contact the vehicle, then edit enabled status and the two limits and use Apply Tesla settings. Enabling requires a confirmation of native setup and controller eligibility. Readback is shown separately from an unconfirmed control hold; it does not establish actual solar charging.
When No solar installed is selected, enabling native Charge on Solar is blocked. Reading and disabling remain available subject to monitoring and active-session restrictions. The setting never releases an existing or uncertain native ownership hold.
| Action | Fields | Result |
|---|---|---|
power_sync.get_teslemetry_charge_on_solar |
entry_id, vin
|
Returns current native settings and whether PowerSync EV control is held. Request a response in Developer Tools → Actions. |
power_sync.set_teslemetry_charge_on_solar |
entry_id, vin, enabled, lower_charge_limit, upper_charge_limit; confirm_eligible: true when enabling |
Sends the settings and reads them back. Limits are whole percentages from 0–100, with the lower limit no higher than the upper. |
With PowerSync as the energy provider, native solar can use the PowerSync Fleet account and its virtual key. Register the vehicle in PowerSync Cloud, grant vehicle-data and charging permissions, and complete key pairing first. The matching extended gateway and Cloud update are required. If Teslemetry is selected as the vehicle API provider, its dedicated vehicle token takes precedence. The separate Home Assistant Tesla Fleet integration does not support these custom commands. Service IDs retain teslemetry for compatibility.
Before enabling, complete Charge on Solar setup and location pairing in the Tesla app, and install the selected provider’s vehicle virtual key. Tesla requires a compatible vehicle and Powerwall with solar, internet connectivity, supported firmware and a site without export or site limits. Legacy Model S/X support also depends on Teslemetry command-signing compatibility. Check the current Tesla requirements and Teslemetry custom command documentation. Do not remove required site/export limits to qualify.
Turn off PowerSync EV charging sessions before reading or changing native settings, and disable other charging controllers, including another PowerSync product controlling the same charger. Confirm eligibility only when those requirements are met. Below the lower limit, Tesla may charge from solar and grid energy; between the limits, Tesla uses excess solar. Native mode does not enforce PowerSync price rules, battery-first preferences, phase allocation or grid-import limits. Keep required electrical protections in the charger itself.
PowerSync Fleet sends one signed read; applying sends a write followed by settings readback. Provider costs and the daily vehicle-command budget apply. The Fleet extension does not send wake commands; a sleeping or unsupported car may return an error. With Teslemetry, reading costs one credit. Applying settings uses a write and a read, normally two credits; each request can add 20 credits if the vehicle is asleep and may wake it. There is no periodic native-state polling or automatic retry. Requests are separated by at least 15 seconds.
PowerSync persists an EV control hold before contacting either provider. The PowerSync Fleet path additionally holds Cloud EV control, and HA writes require an authenticated actuating-mode HA connection. A failed read without a prior hold leaves PowerSync charging available. Failed writes and existing holds survive a restart. A complete read showing native mode disabled releases the hold; PowerSync does not automatically restart EV charging. Start the desired PowerSync mode explicitly afterward. Commands without a resolved vehicle are blocked while a native vehicle hold exists; independently identified vehicles remain separate. Controls outside PowerSync are not fenced by this local hold.
An accepted write is not proof of applied settings. The response reports readback_confirmed only after comparing the returned settings; it is not proof of actual charging or solar energy flow. If a request cannot be confirmed, correct the connection or credits and call the read action again. Never bypass the hold to force an uncertain handover.
Paired LAN systems expose Force Power in kW on the generated dashboard and battery device. Zero selects the configured maximum. Charge kW is battery input; discharge kW is an export target, subject to the gateway battery ceiling and live home load/solar. Entity renames are supported.
A gateway can enforce lower timed-dispatch charge and discharge limits than its nameplate rating. PowerSync learns charge and discharge ceilings independently, preserving the configured battery rating. When an out-of-range response reports a lower ceiling, PowerSync requires the gateway’s resume acknowledgement before retrying once with fresh safety checks inside the original time window. If an explicit kW request still fails, PowerSync reports the failure rather than substituting a tariff that cannot enforce the selected power. Other local-access failures can use the existing fallback after confirmed release only when it cannot bypass a known site or learned dispatch limit.
Native Max charging and export require readback of the exact temporary tariff before reporting the command accepted. Restore normal also rechecks the actual tariff before releasing control, including when resuming cleanup after a restart. A temporary PowerSync tariff keeps cleanup pending; an unavailable readback does not establish restoration. Confirm battery and grid power separately to establish the physical result.
A manual or automation force_discharge request with omitted or zero power_w selects Max. When native safety checks allow it, PowerSync releases timed local control and uses the previous tariff method, allowing larger systems to use their native output beyond a timed-command ceiling. Positive kW targets retain local control. Site export limits and the current reserve remain effective; Restore normal returns the captured tariff and settings. For larger sites, a tighter software export limit is temporarily enforced at the gateway and verified before tariff upload; failed takeover is explicit. The temporary limit remains through physical settling and is restored only while PowerSync still owns it.
| Action | Purpose | Required fields |
|---|---|---|
power_sync.set_solar_surplus_charging |
Enable/disable Solar Surplus |
entry_id, boolean enabled
|
power_sync.set_scheduled_charging |
Enable/disable Scheduled Charging |
entry_id, boolean enabled
|
power_sync.set_price_level_charging |
Enable/disable Price Level |
entry_id, boolean enabled
|
power_sync.set_smart_schedule_charging |
Enable/disable one existing Smart Schedule |
entry_id, boolean enabled, exact configured vehicle_id
|
These actions save mode eligibility. Use the EV charging guide to configure an automation and verify a stop.
Paired V1R gateways expose Fixed power, Idle and charge or discharge to a target percentage under Controls. Use its additional controls for site limits and backup preparation. The sections load independently; use Refresh control state to retry a failed read. Manual V1R controls remain available in Monitoring Mode; automatic actions do not execute.
| Service | Purpose | Inputs |
|---|---|---|
power_sync.dispatch_battery_power |
Timed fixed output, Idle, or charge/discharge to a percentage |
power_w, duration_seconds, request_id, expected_control_revision; optional target_soc and takeover
|
power_sync.stop_battery_dispatch |
Stop the returned owned operation |
operation_id, request_id
|
power_sync.set_native_site_limits |
Persistent import/export limits and recovery | Nonnegative import_limit_w and/or export_limit_w, request_id, expected_config_revision
|
Battery watts are signed: positive discharges, negative charges, and exactly zero holds idle. Optional target_soc is a whole percentage from 1 to 100 with nonzero power. PowerSync checks fresh SOC before initial and renewed commands and stops on reaching the target or maximum duration. The application input range is ±10,000 W; the actual gateway/inverter maximum may be lower. The service accepts 1–86,400 seconds, with enough remaining time required for signing and takeover; the app uses 1–1440 whole minutes. Battery watts are the total for the controlled battery system, not per battery or phase. Reserve, charging permission and site limits still apply. Legacy Force zero/omitted power retains its existing Max meaning.
Site limits apply to whole-site net grid flow, independently in each direction, not per battery or phase. Each accepts 0–1,000,000 whole watts (5000 W = 5 kW); that application input ceiling is not an inverter rating or a permitted connection limit. Native configuration stores kilowatts. Omitted directions stay unchanged; zero is a hard limit. Limits persist after Stop and restart. PowerSync preserves other gateway settings and requires independent readback. operation: restore takes the latest owned snapshot_id and current configuration revision; restoration is refused if ownership changed. operation: reconcile checks uncertain writes. After re-pairing, an administrator can confirm a fresh baseline with operation: rebaseline and confirm_pairing_change: true. A supplied legacy expected_approval_revision must still match, but ordinary edits do not require it.
The Backup preparation section uses the existing guarded native Max Backup lifecycle. It keeps the house connected to the grid, respects charging permission and native caps, and offers End this backup window and Check backup status. Checking a healthy owned window leaves it running; a replacement created elsewhere is left untouched.
Authenticated status endpoints are /api/power_sync/powerwall/battery_dispatch, /api/power_sync/powerwall/native_site_limits and /api/power_sync/powerwall/backup_preparation. Supply entry_id for multiple entries. Backup preparation accepts authenticated POST requests with request_id and duration_minutes, or operation: cancel plus the owned operation_id, or operation: reconcile. New automation modes require contract version 2; older clients retain legacy actions without overwriting new fields.
When native site-limit writes are disabled, the HA dashboard shows the specific blocking control, connection restriction, or pending recovery. The status endpoint includes capabilities.block_reason; an unavailable configuration or changed pairing is distinguished from a runtime hold. An allowed guard does not prove gateway freshness or hardware enforcement. Ordinary Monitoring Mode alone does not block a manual site-limit change; a monitoring-only battery connection does.
See Advanced Powerwall Controls and Smart Optimization. Command acknowledgement, readback and measured physical effect remain separate evidence.
Connect your system
- Battery directory
- Connection methods and sensors
- Electricity providers
- Tariffs and time periods
- Amber Smart Shift
Manage energy
- Smart Optimization
- Optimization settings
- HA optimiser access
- EV charging
- EV load management
- Advanced settings
- Controls and automations
Readings and controls
Help