Monitor your energy generation, storage, usage data and electric vehicle using the official Open API from Alpha ESS
Requires Home Assistant 2026.11.0 or newer.
The integration uses the AlphaESS Open API at https://open.alphaess.com/, so you first need a developer account there with your inverter registered to it.
- Navigate to https://open.alphaess.com/ and choose the option to register an account.
- Once registered and logged in, follow the instructions in your inverter's manual to find its SN and check code. See an example here.
- Add your inverter to the developer portal using its SN and check code.
- Home Assistant asks for the AppID and AppSecret the developer portal shows for your account.
If registering a system does not work, see Issues with registering systems to the AlphaESS OpenAPI.
The integration is in the default catalog of the Marketplace, which is built into Home Assistant from 2026.11 and replaces HACS.
-
Open Settings > Marketplace and search for AlphaESS, or use the button above.
-
Open the repository and install it.
-
Go to Settings > Devices & services > Add integration and search for Alpha ESS, or use this button:
-
Enter the AppID and AppSecret from the AlphaESS OpenAPI developer portal.
A first install can be set up straight away. Updates appear under Settings > Updates; after installing one, a repair offers to restart Home Assistant. An installation made through HACS before Home Assistant 2026.11 is taken over by the Marketplace on its first start, so there is nothing to reinstall.
- Make a
custom_components/alphaessfolder in your Home Assistant configuration directory. - Copy the contents of this repository's
custom_components/alphaessfolder into it, including thebrandfolder. - Restart Home Assistant.
- Go to Settings > Devices & services > Add integration and search for Alpha ESS.
- Enter the AppID and AppSecret for your account on the Alpha ESS OpenAPI developer portal.
Each system bound to your developer account when you set up the integration gets its own inverter entry, listed under the AlphaESS entry in Settings > Devices & services > Alpha ESS.
Select Configure (the cog) on the AlphaESS entry. Saving reloads the integration.
| Option | Default | What it does |
|---|---|---|
| Verify SSL Certificate | on | Verify the AlphaESS API's TLS certificate. |
| Full poll interval (seconds) | 60 | How often everything is fetched: summary, energy, schedule and power. 10–3600. In alt polling mode this is the slow interval. |
| Alt polling mode (split fast/slow) | off | Poll live power (SOC, PV, grid, battery, load) at the fast interval and everything else at the full interval. |
| Fast poll interval (seconds) | 15 | The live power interval in alt polling mode. 10–300. |
| Assume scheduled charging and discharging are enabled when unknown | off | See The enable flags are write-only. |
Select the pencil (Reconfigure) on an inverter's row under the AlphaESS entry:
- IP Address (optional): the local IP address of the inverter's dongle. See Local Inverter Support.
- Disable notifications on charge/discharge confirmation: on by default. Turn it off to get a persistent notification for each duration button, schedule Apply or Discard, Reset and EV charger command, including the ones that fail. Failures are raised in Home Assistant either way.
- Unbind inverter from account: unbinds the system from your AlphaESS developer account and removes it from Home Assistant.
Bind Inverter on the AlphaESS entry adds a system to your developer account from Home Assistant. Enter its serial number (SN) and check code; AlphaESS sends a verification code to the email or phone registered for the system, and entering that code binds the system and reloads the integration.
If AlphaESS rejects the AppID and AppSecret, for example after the secret was regenerated in the developer portal, Home Assistant asks you to reauthenticate the AlphaESS entry with the new AppSecret.
The periodic schedule API (getTimeChargeBySn/setTimeChargeBySn) — the
list-based schedule used by recent versions of the AlphaESS app — is the
primary schedule store. Whenever AlphaESS lets your developer account read
it, it is the only store the integration touches.
The older fixed-slot endpoints (getChargeConfigInfo/updateChargeConfigInfo,
getDisChargeConfigInfo/updateDisChargeConfigInfo) remain solely as a
backup: a definitive 6017 No operation permissions on the periodic read
switches that system to the legacy two-slot surface, because until AlphaESS
grants the permission it is the only control path the OpenAPI offers. Ask
AlphaESS to enable the timed charge/discharge permission for your developer
account to move to the primary store.
A system is always in exactly one mode — the two stores are never read together, merged, or mirrored. Issue #269 showed what mixing them does: hidden values, phantom conflicts, and writes the server accepts without acting on. Two backup-mode caveats, from live probing of the new server: the inverter there may not act on the legacy discharge store even though it accepts the write, and per-period power setpoints exist only in the periodic store, so the Power entities stay unavailable in backup mode. A system whose periodic read works but whose write is refused stays fail-closed rather than falling back: the app-facing periodic store governs that inverter, and editing a store it ignores would only mislead.
Changes to charge/discharge times, cutoff SOC values, enable switches, and per-slot power values are staged locally. They are not sent while you are still editing related fields. Times are rounded to the nearest 15 minutes, as required by AlphaESS.
AlphaESS has no "empty" time value — an unused slot is stored as start equal
to end (usually 00:00–00:00). The time entities show such slots as
unknown and the period sensors as Not set, rather than pretending a
zero-length midnight window is configured. Setting both halves of a slot to
different times brings it to life; the write path already treats equal times
as "slot off". A half you have just staged keeps showing the staged time even
while it still matches the other half, so a half-finished edit does not read as
a lost one.
- Edit all of the related time, SOC, switch, and power entities.
- Select Apply Charge/Discharge Schedule to send the complete draft.
- Select Discard Schedule Changes instead to abandon the draft and return to the latest remote values.
The Apply and Discard buttons are available only while a draft exists. Normal
polling keeps the draft visible instead of resetting an end time while the other
fields are being edited. A failed or conflicted Apply also keeps the draft so it
can be reviewed, retried, or discarded. Drafts are held only for the current
integration session, so apply or discard them before reloading Home Assistant or
the config entry. An entity's Home Assistant Last changed timestamp records a
local draft edit; it is not proof that AlphaESS accepted or activated a schedule.
Apply and Discard are temporarily unavailable while an Apply transaction is in
flight. If another entity edit arrives before that transaction finishes, the
accepted snapshot is reported and the newer edit remains pending for another
Apply.
The entity UI exposes the first two charge periods and first two discharge periods. When a readable periodic schedule already exists, editing those periods preserves its cycle type, weekday selections, per-period power, and any additional periods that the UI does not expose. Changing a side's cutoff SOC applies that limit only to the first two slots represented by Home Assistant; extra app-only periods keep all of their writable fields unchanged.
Duration charge/discharge buttons and service calls are immediate actions; they do not create a draft and do not require the Apply button. They still fail safely when the existing periodic resource cannot form a complete valid replacement. The charge/discharge services accept optional per-slot power fields, which are required when the call creates a new periodic slot.
Reset Charge/Discharge exists only for backup mode, where it zeroes both legacy two-slot stores. The periodic schedule cannot be cleared through the API (empty period lists are rejected), so on periodic-governed systems the button reports unavailable — clear the schedule in the AlphaESS app instead.
The duration buttons retarget only period/slot 1 of their side, carrying its existing power and cutoff over, and leave every other period untouched — in backup mode, slot 2 is likewise preserved from a fresh read. On a weekly periodic schedule a duration button refuses to retarget a first period that does not run today: AlphaESS would accept the write, nothing would happen now, and the period's other weekdays would be silently rescheduled. A press rejected by the 30-second cooldown fails with a visible error instead of quietly doing nothing.
The one-sided duration buttons and setbatterycharge/setbatterydischarge
services cannot initialise a completely empty periodic resource: AlphaESS requires
both a charge list and a discharge list in the same replacement. They require the
opposite list and a valid power for the target slot to exist already. To initialise
both sides, stage the charge and discharge entities (including explicit power and
SOC values) and use Apply. Pending entity drafts are deliberately not consumed by
the immediate buttons or services.
An automation has two surfaces here, and an inverter should use only one of them:
- Immediate —
alphaess.setbatterycharge/alphaess.setbatterydischarge. One call is one complete transaction. Every time field is required, so each call rewrites both slots of its side: a slot passed as00:00–00:00is removed from a periodic schedule, including one the AlphaESS app created. - Staged — write the time, cutoff SOC, power and switch entities, then press
Apply Charge/Discharge Schedule with
button.press. This is the surface an optimiser should use: a whole plan change becomes a single API write, slots that are not named keep their values, and nothing has to be restated.
Do not mix them on one inverter. A service write replaces the remote schedule, so a draft staged before it fails its next Apply as a conflict.
New entities get the entity ID <domain>.<serial in lower case>_<name>; the EV
charger's entities use the inverter's serial. An entity keeps the ID it was
first registered with, so an existing install can differ: depending on when an
entity was first added, its ID may also carry the device name and the device's
area (sensor.home_alpha_ess_energy_statistics_<serial>_...,
sensor.alpha_ess_energy_statistics_<serial>_<serial>_...). Check the entity
list rather than assuming the short form. Recreate entity IDs on a device's
page moves its entities to the short form; then update any automation, script
or dashboard that used the old IDs.
| Purpose | Entity |
|---|---|
| Charge window 1 | time.<sn>_charge_start_time_1, time.<sn>_charge_end_time_1 |
| Discharge window 1 | time.<sn>_discharge_start_time_1, time.<sn>_discharge_end_time_1 |
| Enable flags | switch.<sn>_scheduled_charging, switch.<sn>_scheduled_discharging |
| Cutoff SOC | number.<sn>_charge_cut_off_soc, number.<sn>_discharge_to_soc |
| Per-period power (periodic systems only) | number.<sn>_charge_power_1, number.<sn>_discharge_power_1 |
| Commit or abandon a draft | button.<sn>_apply_charge_discharge_schedule, button.<sn>_discard_schedule_changes |
| Which store governs the system | sensor.<sn>_periodic_schedule_read |
| Last confirmed enable flags (not the working mode) | binary_sensor.<sn>_recorded_schedule_flags_enabled |
Predbat already drives inverters that stage settings and then press an apply
button (time_button_press), so it needs no custom service templates — only a
custom inverter definition in apps.yaml. Everything not listed is inherited
from Predbat's GivEnergy defaults, and slot 2 is left to the AlphaESS app.
inverter_type: ALPHA
inverter:
name: AlphaESS
has_rest_api: False
output_charge_control: "none" # per-period power is not an inverter charge rate
has_charge_enable_time: True
has_discharge_enable_time: True
has_target_soc: True
has_reserve_soc: False # Discharge To SOC is a cutoff, not a Predbat reserve
has_timed_pause: False
has_ge_inverter_mode: False
charge_time_entity_is_option: False
soc_units: "%"
time_button_press: True # press Apply once the draft is staged
write_and_poll_sleep: 2
support_charge_freeze: False
support_discharge_freeze: False
can_span_midnight: False
# Control
charge_start_time: time.<sn>_charge_start_time_1
charge_end_time: time.<sn>_charge_end_time_1
scheduled_charge_enable: switch.<sn>_scheduled_charging
charge_limit: number.<sn>_charge_cut_off_soc
discharge_start_time: time.<sn>_discharge_start_time_1
discharge_end_time: time.<sn>_discharge_end_time_1
scheduled_discharge_enable: switch.<sn>_scheduled_discharging
charge_discharge_update_button: button.<sn>_apply_charge_discharge_schedule
# Read
soc_percent: sensor.<sn>_instantaneous_battery_soc
soc_max: sensor.<sn>_installed_capacity
inverter_limit: sensor.<sn>_inverter_nominal_power
battery_rate_max: 5000 # W, from the battery spec; the inverter
# nominal rating is not a battery rateWith more than one inverter, Predbat expects the inverter: block and each
argument as a list, one entry per inverter. The keys inside inverter: belong
to Predbat, not to this integration; check them against your Predbat version.
What this setup depends on:
- Charge period 1 and discharge period 1 must already exist, created in the
AlphaESS app. An unused slot is stored as start equal to end and reads as
unknown, which Predbat cannot parse as a window, and no one-sided write can create both sides at once. - Leave Scheduled Discharging on if you do not want Predbat's temporary charge-disable step to leave both schedules disabled while it moves a window.
- Times are rounded to the nearest 15 minutes. Predbat reads an entity back
after writing it and warns when the value differs, so keep
inverter_clock_skew_startandinverter_clock_skew_endat 0 and expect that warning for any window that does not land on a quarter hour. The schedule still applies, rounded. - Predbat cannot see whether an Apply succeeded. Home Assistant timestamps a button press before the write is attempted, so every press looks successful to it. The real outcome — accepted, refused with the API's return code, or explicitly unknown after a timeout - is raised in Home Assistant and, where relevant, as a persistent notification. Look there when the plan and the inverter disagree.
- Each Apply is one full transaction (fresh read, then one write), and moving a window costs two because Predbat disables the charge flag first. Weigh that against the request limits described below.
- Set both enable switches once before letting Predbat write. The periodic API cannot report whether scheduled charging and discharging are on, so until Scheduled Charging and Scheduled Discharging have an answer every write is refused — see The enable flags are write-only below.
If you drive the services from Predbat instead, note two things about its
service templates: falsy values are dropped before the call, so enabled: false
is never sent and the service is rejected for a missing required field; and
{charge_start_time} resolves to the entity named by the charge_start_time
argument rather than to the plan, defaulting to 00:00:00 when that argument is
absent — which asks this integration to delete the period rather than to move
it.
Before an Apply or immediate action, the integration reads a fresh copy of the store the system runs on — the app-facing periodic resource, or in backup mode the legacy two-slot resources — patches only the requested fields, and serialises writes per inverter.
When a draft is opened, the integration records the remote schedule on which it was based. If the remote schedule changes before Apply, the write is rejected as a conflict instead of overwriting the newer schedule. Discard the draft, allow fresh values to load if necessary, review them, and stage the change again. Immediate actions and services have no long-lived draft, but still start from a fresh read. If one succeeds while a draft is open, untouched draft fields are rebased onto the new remote schedule while explicitly staged fields remain pending. An immediate action uses only its own arguments plus the last confirmed enable pair; it never consumes staged switch values before Apply.
The diagnostic binary sensor Recorded Schedule Flags Enabled reports whether
either flag in Home Assistant's last confirmed pair is on. Its unique ID remains
compatible with the former Time Based Control Active entity so an existing
registry entry is renamed in place and keeps its entity ID
(binary_sensor.<sn>_time_based_control_active on such installs). It is
deliberately not a working-mode sensor: AlphaESS OpenAPI exposes no
authoritative way to tell Time Based Control from Self Consumption
(Plus).
gridChargeCycle and ctrDisCycle are the scheduled charge/discharge intent
sent with a periodic replacement. They are effectively write-only: probing
on issue #267 showed getTimeChargeBySn can answer 0 for both regardless of
the inverter's app-selected working mode, while setTimeChargeBySn accepts the
explicit pair it is sent.
| sent | recorded schedule intent |
|---|---|
1 / 0 |
scheduled charging on, scheduled discharging off |
1 / 1 |
both schedules on |
0 / 1 |
scheduled charging off, scheduled discharging on |
0 / 0 |
both schedules off |
That pair does not reveal or reliably change the app's overall working mode. In Self Consumption modes the cloud may still accept and retain schedule edits, but the inverter may not physically act on them until its mode is changed in the AlphaESS app.
Two consequences follow, and the integration is built around them.
The read is never echoed back. A replacement built from the read could post
an invented 0/0 pair on every write. Snapshots therefore drop both flags, and
every write sends only values that came from the user or the last confirmed pair.
The switches are the record. Scheduled Charging and Scheduled Discharging are the only place that answer can live, so a separate last-confirmed attribute is restored across restarts and handed back to the coordinator. The displayed switch can show a newer local draft without that draft becoming confirmed after a restart. Until both confirmed values are known, unrelated immediate writes are refused rather than borrowing a pending draft or guessing. Stage both switch choices and press Apply once to establish the pair.
Or tell the integration to assume. Systems in the UK and Europe read the
pair back as 0/0 whatever the app shows, so a fresh install there has no
record at all, and every one-sided write — a service call from an automation,
a duration button — is refused until the switches have been set once. The
option Assume scheduled charging and discharging are enabled when unknown
(Settings → Devices & Services → AlphaESS → Configure) changes only that
case: a flag Home Assistant has no record of is sent as 1 instead of the
write being refused. A switch you have set always wins, and the pair sent is
recorded as soon as AlphaESS accepts the write, so the assumption is used at
most once per system per session; the log says when it was. Leave it off if
either scheduled charging or scheduled discharging is meant to stay off in
the app, and set the switches instead. It is off by default.
Schedule controls are gated only by whether a complete governing store can be
read and safely replaced. A recorded 0/0 pair does not lock them, because the
same flags and schedule contents cannot tell Home Assistant which working mode
the AlphaESS app selected. In legacy backup mode the flags are read-write fields,
but they still are not treated as an overall working-mode endpoint.
The diagnostic sensor Periodic Schedule Read reports:
readable- the periodic resource can be read; the primary store governs;unreadable- AlphaESS definitively rejected the GET with error6017. The system runs on the legacy backup: schedule controls work through the two-slot endpoints, except the per-period Power entities, which exist only in the periodic store; orunknown- the integration has not yet obtained a definitive usable response.
An empty or malformed response, a transient error, or an unknown read state
fails closed: schedule entities remain unavailable and writes are refused
until a full periodic read succeeds. The integration never builds a
replacement schedule from anything but a fresh read, because doing so could
erase weekly settings, extra periods, or power values that it cannot see.
Settings → Devices & Services → AlphaESS → ⋮ → Download diagnostics answers
most of what a report needs, without anyone having to sign API requests by hand.
Alongside the usual entry and entity data, the schedule section carries one
atomic completed-poll snapshot per inverter:
governing_storeandperiodic_read— which surface the system is on;capabilities— schedule read/write capability plus the explicit fact that working mode is unavailable through OpenAPI;enable_intent/enable_last_sent— the write-only pair, which nothing else can report;periodic_snapshotandlegacy_snapshot— what each store actually held, including an empty period list or a stale window the app no longer shows;draft— what was staged when that poll completed;- cooldowns and consecutive poll errors.
schedule_live separately reports the current draft, dirty fields, and
in-flight Apply state. Keeping it separate prevents a diagnostics download
during a sequential multi-inverter poll from pretending that live transaction
state and completed-poll data came from the same tick.
The coordinator.api section reports the current call spacing and whether the
fast lane is still active, which is what to check when something else is sharing
the same API account. Serials are replaced with inverter_1, inverter_2 and so
on, and credentials, keys and addresses are redacted.
The download carries the parsed entity view. When the question is what the
API actually returned, call the alphaess.export_raw_snapshot action
(Developer tools → Actions, or from a script with response_variable). It
returns the last response the integration received from every OpenAPI
endpoint it uses — getEssList, the summary/energy/power reads,
getTimeChargeBySn, the legacy config reads in backup mode, the EV charger
reads, the local dongle read when an IP is configured — plus the request
each answered, the parsed data, the schedule state and the coordinator's
pacing. Nothing is requested from AlphaESS; it is what Home Assistant already
holds, so it is safe to call as often as you like. A rejected call is
recorded as its return code and a transport failure as the exception.
Serial numbers are replaced by inverter_1, ev_charger_1 and so on
everywhere they appear, including inside response bodies and entity IDs, with
the same numbering as the diagnostics download; credentials, register keys,
wifi details and the local dongle serial are redacted by key. Bind and unbind
calls never have their arguments retained. With one AlphaESS entry configured
no field is needed; with more, pass serial, config_entry_id or
device_id.
action: alphaess.export_raw_snapshot
data: {}
response_variable: snapshotFor anything the download cannot show — what happened, in what order — turn on debug logging:
logger:
default: warning
logs:
custom_components.alphaess: debug
alphaess: debugEvery OpenAPI request and its full response is then written out, along with each staged field, each write and the enable pair sent with it, and a line whenever schedule capability changes and what decided it. That is the same information a hand-signed API request would give you, without signing one. Very large responses are capped rather than dropped. Requests carry no credentials — those live in the headers, which are not logged — but the log does contain your serial number, so trim it before posting if you would rather not share it.
- The periodic API requires at least one complete charge period and one
complete discharge period: an empty list answers
6001and a missing one10001. The integration never inserts a fake00:00-00:00period. If either list would be empty, Apply fails rather than replacing an app-managed schedule with incomplete data. AlphaESS itself will happily store an empty list, so a system with no discharge periods cannot be written to from Home Assistant at all until one exists — add a period to that side in the app, or give it one and turn its switch off, which is how the API is told to run a single side. - Both a start and end time must be set before adding a new period. Existing weekly periods keep their weekdays when edited. The entity UI has no weekday selector, so a period added to a weekly schedule runs on the same days as the period it is added alongside — the newer AlphaESS app writes "every day" as a weekly schedule covering all seven, so that is usually what you want. Change the days in the app if it is not. A weekly schedule with no existing period on that side has nothing to copy, and adding one there is refused.
- Existing per-period power values are preserved. Adding a brand-new period
requires an explicit positive power value for that slot; the inverter's nominal
poinvrating is not a verified battery charge/discharge rate and is never used as a fallback. - Periodic SOC limits must be from 10% through 100%, and every period must contain a valid positive power value. Invalid remote data is reported instead of being silently clamped or replaced.
- The periodic schedule cannot be cleared through the API (empty period lists are rejected), which is why the Reset button works only in backup mode. Clear a periodic schedule in the AlphaESS app.
- AlphaESS reports
6008only as genericSet failed. Overlapping charge and discharge windows are one documented cause, but the code is not conclusive. The log records the periods sent and retains the original API explanation. - A discharge period does not force export to the grid. On the systems probed on #267 it governs whether the battery may discharge to support the house load during the window; feed-in and export control are not exposed through these endpoints.
- A
200fromsetTimeChargeBySnmeans the cloud stored the schedule, and the next poll re-reads it. The integration does not poll back to confirm that the inverter has activated a period; the AlphaESS app's active-period indicator and the battery power readings are the check for that.
A network timeout after a POST is not proof of rejection: the server might have stored the request before the response was lost. Home Assistant reports that outcome as unknown, retains the duration-button cooldown, and asks you to check the AlphaESS app before retrying. In periodic mode the schedule lives in a single store, so there is no partial-write case: a change either landed, was refused with the API's own return code, or has that explicitly-unknown outcome. Backup mode writes two separate stores, so a two-sided change there can partially land; that is reported as a partial-write error naming what already applied.
A detected EV charger appears as a child device beneath its inverter/battery
system in the integration page, named EV Charger (SMILE-EVCT11) when its model
is known. Its controls, charging status, and current setting stay on the charger.
Charger model and serial number remain available through its sensors. Home
Assistant inherits the model subtitle and hardware information from the parent.
Existing device and entity IDs, user names, areas, and disabled settings are
preserved when upgrading. The charger follows its parent when it is disabled or
removed.
The charger's entity IDs use the inverter's serial: button.<sn>_start_charging,
button.<sn>_stop_charging, number.<sn>_ev_charger_current_setting,
sensor.<sn>_ev_charger_status and so on, where <sn> is the inverter's
serial in lower case.
The integration exposes EV charger controls (start/stop and current setting) when
an EV charger is detected. Can Start Charging and Can Stop Charging are
advisory binary sensors based on the latest successful EV poll. Start and stop
buttons remain available, and every requested command is sent to AlphaESS even if
the cached status is old or already appears to match it. This lets the server make
the authoritative decision; an API rejection is surfaced to Home Assistant
instead of the command being skipped locally. Read-only charger status values
continue to refresh even when charger control is unavailable for the account.
The upstream charger-config endpoint can return multiple chargers, while the
current Home Assistant entity model exposes the first one only. EV Charger Count and a one-time warning make that limitation explicit instead of silently
discarding the list shape.
- Monetary sensors report an ISO 4217 currency code, which is what Home
Assistant's monetary device class accepts. AlphaESS answers
moneyTypewith either a code or the symbol and has changed which, so a symbol is resolved to a code. Where a symbol names more than one currency ($,¥,kr) the currency Home Assistant is configured for wins if it is one of them, otherwise the most common is used. An unrecognised value falls back to the configured currency rather than being guessed at. TheCurrency Codediagnostic sensor reports the resolved code, not the raw value. - Diagnostic currency sensors are available for troubleshooting:
Currency Code
- Daily history energy breakdown sensors are exposed:
Daily PV GenerationDaily Grid ConsumptionDaily Feed-inDaily Grid ChargeDaily Battery ChargeDaily Battery DischargeDaily EV Charging EnergyDaily Energy Date
The upstream API asks clients to leave at least 10 seconds between requests and
can return 6053 when calls are too frequent. The integration serialises and
spaces cloud reads and writes accordingly, including bind/unbind operations, and
clamps fast polling to 10 seconds or slower.
In practice the integration runs calls at 1-second spacing: live probing of
the current server showed reads accepted at sub-second spacing without
6053, and at the documented 10 seconds a two-inverter full poll took
minutes — blocking Home Assistant startup and delaying app-side changes
by up to five minutes. The documented pace remains the fallback: if the server ever
answers 6053, that call is retried once and the session drops back to
10-second spacing permanently.
Staged Apply avoids the old burst of one full replacement per entity edit, but the server remains authoritative and may reject an Apply, duration button, or service call made too soon. The 30-second guard on the duration buttons prevents accidental double presses.
Each inverter can be given the local IP address of its AlphaESS dongle, which Home Assistant must be able to reach (preferably on the same subnet). With an address set, the integration also reads the dongle directly:
- diagnostic sensors for that inverter: local IP, WiFi, ethernet, 4G and cloud connection status, connected SSID, software and hardware version, device serial number and register key;
- the software and hardware version on the inverter's device, with a link to the dongle's web page;
- when the cloud API cannot be reached, the local sensors keep updating while the cloud sensors become unavailable.
To set or change the address, for example after a DHCP change, select the
pencil (Reconfigure) on the inverter's row under the AlphaESS entry and fill
in IP Address (optional). Clear the field, or enter 0, to stop using it;
the local sensors are then left unavailable and can be deleted from the entity
list.
There have been a few issues registering systems to the AlphaESS OpenAPI. These are the ones reported so far, and how to resolve them.
If you are unable to register your system to the AlphaESS OpenAPI because you are not receiving the verification code, you can try the following steps to resolve the issue:
- Access the current postman collection library for the AlphaESS OpenAPI here (you will need to fork the collection)
- Click on the root of the list of API calls (it should be called AlphaESS Open API), then click on the variables tab and fill in your AppID, AppSecret, systemSN and CheckCode into the initial and current value fields.
- Click on the getVerificationCode GET API call followed by the send button to send the request. You should receive a verification code either in the response body or by email.
Newer AlphaESS inverter firmware can return data the integration does not handle yet, or nothing at all from some endpoints. To help add support for your inverter, open an issue and attach:
- The diagnostics download: Settings > Devices & services > Alpha ESS > ⋮ > Download diagnostics.
- The response of the
alphaess.export_raw_snapshotaction, which is what the API last returned from every endpoint (see Exporting the raw API responses).
Both replace serial numbers with inverter_1, ev_charger_1 and so on, and
redact credentials, keys and addresses. To query the API outside Home Assistant
instead, use the
Postman collection
with your AppID, AppSecret and system serial, and remove the serial before
posting the results.
alphaess.setbatterycharge and alphaess.setbatterydischarge are immediate:
each call reads the store that governs the system, replaces the two slots of
its side and writes it back in one transaction, without using or consuming a
staged draft. Everything in
Charge and discharge schedules applies to
them, in particular:
- Times are rounded to the nearest quarter hour and zero-padded, since the API
rejects anything else. A slot given as
00:00–00:00is turned off; on a periodic schedule that removes the period. - On a periodic schedule both enable flags must be known, from the Scheduled Charging and Scheduled Discharging switches or the assume option (see The enable flags are write-only), and a one-sided call cannot create an empty schedule.
- Power fields exist only on the periodic schedule; in backup mode a call that passes one is refused and nothing is changed.
- A call AlphaESS rejects fails with its return code instead of passing silently.
alphaess.setbatterycharge
| Field | Required | Description |
|---|---|---|
serial |
yes | The system's serial number. |
enabled |
yes | Scheduled charging on (true) or off (false). |
cp1start, cp1end |
yes | Charge period 1, HH:MM. |
cp2start, cp2end |
yes | Charge period 2, HH:MM. |
chargestopsoc |
yes | Stop charging at this state of charge, 10–100 %. |
cp1power, cp2power |
no | Charge power for each period in W. Required when the call creates a new period. |
action: alphaess.setbatterycharge
data:
serial: AA123456789
enabled: true
cp1start: "01:00"
cp1end: "04:00"
cp2start: "13:00"
cp2end: "16:00"
chargestopsoc: 100alphaess.setbatterydischarge
| Field | Required | Description |
|---|---|---|
serial |
yes | The system's serial number. |
enabled |
yes | Scheduled discharging on (true) or off (false). |
dp1start, dp1end |
yes | Discharge period 1, HH:MM. |
dp2start, dp2end |
yes | Discharge period 2, HH:MM. |
dischargecutoffsoc |
yes | Stop discharging at this state of charge, 10–100 %. |
dp1power, dp2power |
no | Discharge power for each period in W. Required when the call creates a new period. |
action: alphaess.setbatterydischarge
data:
serial: AA123456789
enabled: true
dp1start: "17:00"
dp1end: "21:00"
dp2start: "00:00"
dp2end: "00:00"
dischargecutoffsoc: 10alphaess.export_raw_snapshot returns the last response received from every
AlphaESS endpoint the integration uses, redacted so it can be attached to an
issue. It makes no API request; see
Exporting the raw API responses. With one
AlphaESS entry no field is needed; with more, pass one of:
| Field | Description |
|---|---|
serial |
A system serial managed by the entry to export. |
config_entry_id |
The entry to export. |
device_id |
An inverter or EV charger device of the entry to export. |
action: alphaess.export_raw_snapshot
data: {}
response_variable: snapshot