Skip to content

About

Monitor your energy generation, storage, and usage data using the official API from Alpha ESS.

Topics

Resources

Stars

148 stars

Watchers

26 watching

Forks

Repository files navigation

homeassistant-alphaESS

Project Stage hacs_badge

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.

AlphaESS OpenAPI

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.

  1. Navigate to https://open.alphaess.com/ and choose the option to register an account.
  2. Once registered and logged in, follow the instructions in your inverter's manual to find its SN and check code. See an example here.
  3. Add your inverter to the developer portal using its SN and check code.
  4. 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.

Installation

Marketplace

The integration is in the default catalog of the Marketplace, which is built into Home Assistant from 2026.11 and replaces HACS.

Open your Home Assistant instance and open a repository in the Marketplace.

  1. Open Settings > Marketplace and search for AlphaESS, or use the button above.

  2. Open the repository and install it.

  3. Go to Settings > Devices & services > Add integration and search for Alpha ESS, or use this button:

    Open your Home Assistant instance and start setting up a new integration.

  4. 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.

Manual installation

  1. Make a custom_components/alphaess folder in your Home Assistant configuration directory.
  2. Copy the contents of this repository's custom_components/alphaess folder into it, including the brand folder.
  3. Restart Home Assistant.
  4. Go to Settings > Devices & services > Add integration and search for Alpha ESS.
  5. Enter the AppID and AppSecret for your account on the Alpha ESS OpenAPI developer portal.

Configuration

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.

Integration options

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.

Inverter settings

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.

Adding an inverter

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.

Re-authentication

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.

Charge and discharge schedules

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.

Editing schedules with Home Assistant entities

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.

  1. Edit all of the related time, SOC, switch, and power entities.
  2. Select Apply Charge/Discharge Schedule to send the complete draft.
  3. 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.

Driving schedules from an automation (Predbat and similar)

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 as 00:00–00:00 is 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

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 rate

With 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_start and inverter_clock_skew_end at 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.

Safe writes and external-change conflicts

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).

The enable flags are write-only

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 error 6017. 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; or
  • unknown - 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.

Reporting a schedule problem

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_store and periodic_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_snapshot and legacy_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.

Exporting the raw API responses

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: snapshot

For anything the download cannot show — what happened, in what order — turn on debug logging:

logger:
  default: warning
  logs:
    custom_components.alphaess: debug
    alphaess: debug

Every 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.

AlphaESS API limitations

  • The periodic API requires at least one complete charge period and one complete discharge period: an empty list answers 6001 and a missing one 10001. The integration never inserts a fake 00:00-00:00 period. 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 poinv rating 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 6008 only as generic Set 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 200 from setTimeChargeBySn means 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.

EV charger controls

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.

Currency and daily history sensors

  • Monetary sensors report an ISO 4217 currency code, which is what Home Assistant's monetary device class accepts. AlphaESS answers moneyType with 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. The Currency Code diagnostic 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 Generation
    • Daily Grid Consumption
    • Daily Feed-in
    • Daily Grid Charge
    • Daily Battery Charge
    • Daily Battery Discharge
    • Daily EV Charging Energy
    • Daily Energy Date

AlphaESS request limits

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.

Local Inverter Support

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.

Issues with registering systems to the AlphaESS OpenAPI

There have been a few issues registering systems to the AlphaESS OpenAPI. These are the ones reported so far, and how to resolve them.

Issue: Unable to register system to AlphaESS OpenAPI (not receiving verification code)

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:

  1. Access the current postman collection library for the AlphaESS OpenAPI here (you will need to fork the collection)
  2. 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.
  3. 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.

Issue: Entities becoming unavailable/not working and/or defaulting to 0

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:

  1. The diagnostics download: Settings > Devices & services > Alpha ESS > ⋮ > Download diagnostics.
  2. The response of the alphaess.export_raw_snapshot action, 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.

Services

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:00 is 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.

Alpha ESS: Set Battery Charge

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: 100

Alpha ESS: Set Battery Discharge

alphaess.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: 10

Alpha ESS: Export Raw Snapshot

alphaess.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

About

Monitor your energy generation, storage, and usage data using the official API from Alpha ESS.

Topics

Resources

Stars

148 stars

Watchers

26 watching

Forks

Releases

Used by

Contributors

Languages