{"id":49160146,"url":"https://github.com/senalse/ha-alphaess-modbus","last_synced_at":"2026-05-23T11:07:05.204Z","repository":{"id":353070706,"uuid":"1217837868","full_name":"senalse/ha-alphaess-modbus","owner":"senalse","description":"Local Home Assistant integration for AlphaESS solar inverters via Modbus TCP. No cloud required.","archived":false,"fork":false,"pushed_at":"2026-05-20T22:11:58.000Z","size":270,"stargazers_count":12,"open_issues_count":2,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-05-21T03:45:13.778Z","etag":null,"topics":["alphaess","battery-storage","custom-component","hacs","home-assistant","homeassistant","modbus","solar"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/senalse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-22T09:11:51.000Z","updated_at":"2026-05-20T22:12:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/senalse/ha-alphaess-modbus","commit_stats":null,"previous_names":["senalse/ha-alphaess-modbus"],"tags_count":56,"template":false,"template_full_name":null,"purl":"pkg:github/senalse/ha-alphaess-modbus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senalse%2Fha-alphaess-modbus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senalse%2Fha-alphaess-modbus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senalse%2Fha-alphaess-modbus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senalse%2Fha-alphaess-modbus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/senalse","download_url":"https://codeload.github.com/senalse/ha-alphaess-modbus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senalse%2Fha-alphaess-modbus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33392832,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alphaess","battery-storage","custom-component","hacs","home-assistant","homeassistant","modbus","solar"],"created_at":"2026-04-22T12:04:15.299Z","updated_at":"2026-05-23T11:07:05.196Z","avatar_url":"https://github.com/senalse.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AlphaESS Modbus TCP — Home Assistant Integration\n\n[![HACS Custom](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://github.com/hacs/integration)\n[![GitHub Release](https://img.shields.io/github/release/senalse/ha-alphaess-modbus.svg)](https://github.com/senalse/ha-alphaess-modbus/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nLocal Home Assistant integration for **AlphaESS solar inverters** (SMILE-M5, SMILE5, SMILE-G3, SMILE-Hi, SMILE-B3 series) via **Modbus TCP**.\n\nNo cloud account required. All communication is direct to the inverter on your local network.\n\nBased on the excellent YAML package by [Axel Koegler](https://projects.hillviewlodge.ie/alphaess/).\n\n\u003e **Disclaimer**\n\u003e This is an unofficial community integration, not affiliated with or supported by AlphaESS.\n\u003e The integration can write values directly to your inverter's Modbus registers. Incorrect\n\u003e values -- wrong power levels, bad SoC limits, or invalid dispatch parameters -- can\n\u003e damage your battery or cause unexpected inverter behaviour. Use this integration at your\n\u003e own risk. The author accepts no responsibility for damage to hardware or loss of data.\n\n---\n\n## Features\n\n- **94 sensor entities enabled by default** (159 total) — real-time power flows, battery SoC/SoH, cell voltages, temperatures, voltages, energy totals, dispatch diagnostics, grid safety parameters, faults \u0026 warnings\n- **Force Charging** — charge battery from grid at configurable power (kW), duration, and cutoff SoC\n- **Force Discharging** — discharge battery at configurable power, duration, and cutoff SoC; automatically stops 1% above the cutoff and resets dispatch so the inverter returns to self-consumption without any grid draw\n- **Force Export** — export to grid at a target feed-in rate (kW); battery discharge is dynamically adjusted for live house load and PV so the grid sees the configured power; stops automatically when the duration expires or battery reaches the cutoff SoC\n- **Force Export Hold** — keeps Force Export running indefinitely after the duration expires; turn on before starting Force Export for continuous export without a time limit\n- **Force Import** — import from grid at a configurable target kW, dynamically adjusting battery charge to offset live PV so total grid draw stays at the target; stops at cutoff SoC\n- **Excess Export** — charge the battery with PV power that would otherwise be clipped by the inverter AC output limit; automatically pauses when the house starts drawing from the grid and resumes once PV recovers\n- **Battery cell health** — min/max cell voltages polled every 60 s; charge/discharge cutoff voltages, module count, capacity, and type available as diagnostic sensors\n- **Dispatch diagnostics** — energy flow direction (human-readable), PV switch state, frequency dispatch flag, power, and frequency\n- **Charging / Discharging time periods** — configure up to two charge and discharge windows\n- **Dispatch mode selector** — Battery only, SoC Control, Load Following, Maximise Output, and more\n- **Max Feed to Grid** — set grid export limit as % of installed PV capacity\n- **Date \u0026 Time sync** — sync inverter clock to Home Assistant system time\n- **Sync Dispatch State** — reconcile HA switch states with the inverter after a restart\n\n---\n\n## Requirements\n\n- AlphaESS inverter with **Modbus TCP enabled** on port 502\n- Inverter reachable on your local network (wired LAN or powerline recommended)\n- Home Assistant **2024.10 or newer**\n- HACS installed\n\n---\n\n## Installation\n\n### Via HACS (recommended)\n\n1. Open HACS in Home Assistant\n2. Go to **Integrations** → click the three-dot menu → **Custom Repositories**\n3. Add `https://github.com/senalse/ha-alphaess-modbus` — category: **Integration**\n4. Click **Download** on the AlphaESS Modbus TCP card\n5. Restart Home Assistant\n\n### Manual\n\n1. Download the latest release from the [Releases page](https://github.com/senalse/ha-alphaess-modbus/releases)\n2. Copy the `custom_components/alphaess_modbus` folder into your HA config directory under `custom_components/`\n3. Restart Home Assistant\n\n---\n\n## Setup\n\n1. Go to **Settings → Devices \u0026 Services → Add Integration**\n2. Search for **AlphaESS Modbus TCP**\n3. Fill in the details:\n\n| Field | Default | Notes |\n|-------|---------|-------|\n| Inverter IP Address | — | Use a DHCP reservation for a stable address |\n| Modbus Port | `502` | Change only if you've modified the inverter setting |\n| Slave ID | `85` | Standard for AlphaESS inverters |\n\n4. Click **Submit** — Home Assistant will test the connection before saving\n\n### Multiple Inverters\n\nTo run two AlphaESS inverters with the same Home Assistant instance:\n\n1. Add the integration a second time: **Settings → Devices \u0026 Services → Add Integration**, search for **AlphaESS Modbus TCP**, and enter the second inverter's IP address.\n2. Immediately rename each device so entity IDs reflect the device name: **Settings → Devices \u0026 Services → [device] → pencil icon**. For example, rename one to \"AlphaESS Roof\" and the other to \"AlphaESS Garage\".\n3. Home Assistant updates all entity IDs automatically — `sensor.alphaess_inverter_*` becomes `sensor.alphaess_roof_*` and `sensor.alphaess_garage_*`.\n4. Each integration instance maintains its own Modbus TCP connection. The inverter one-connection limit applies per device — the two instances do not share a connection and do not interfere with each other.\n\n---\n\n## Poll Intervals\n\nEach sensor has a base poll interval. The coordinator runs a master loop (2 s by default); contiguous registers due in the same cycle are batched into a single Modbus read. Individual registers are skipped when their own `scan_interval` hasn't elapsed yet.\n\nThe base intervals in the table below are the minimum achievable intervals. A register can only be read when the master loop fires, so in Normal mode (2 s loop) the effective floor is 2 s -- the 1 s entries are only read every 1 s when Fast mode is active. Actual intervals also scale with the Poll Mode multiplier (see [Poll Speed](#poll-speed) below).\n\n| Base Interval | Sensors |\n|---------------|---------|\n| **1 s** | Grid Power, Battery Power, Active Power PV Meter, PV String 1–4 Power, PV Total Power *(disabled by default)* |\n| **5 s** | Grid Power Phase A/B/C, Grid Voltage Phase A/B/C, Inverter Work Mode, Inverter Power L1/L2/L3 + total, System Fault, Inverter Warning 1/2, Inverter Fault 1/2, Battery Warning/Fault, Max Feed to Grid, Dispatch registers (including Dispatch Energy Flow Direction, Freq Dispatch Flag), dispatch PV switch, freq dispatch power/frequency *(last two disabled by default)* |\n| **10 s** | Battery SoC, Battery SoH, Battery min/max cell temps, Battery max charge/discharge current, Charging Time Period Control, Charging Cutoff SoC |\n| **30 s** | Grid Frequency, Charging/Discharging period start/stop times, Discharging Cutoff SoC |\n| **60 s** | Inverter Temperature, Battery Voltage/Current/Status, Battery min/max cell voltages, Battery Remaining Time *(disabled)*, Battery relay status *(disabled)*, PV String Voltage \u0026 Current, Energy Totals, Version strings, Grid safety registers (OVP/UVP/OFP/UFP) *(disabled)*, Network settings *(disabled)* |\n| **300 s** | Battery charge/discharge cutoff voltages, Battery module count, Battery capacity, Battery type *(all disabled by default)* |\n\n### Poll Speed\n\nThe integration offers three poll speed presets, configurable via the integration's **Configure** button in Settings → Devices \u0026 Services:\n\n| Preset | Coordinator loop | Scan interval multiplier | Use case |\n|--------|-----------------|--------------------------|----------|\n| Slow | 2 s | 3.0 (configurable) | RS485 converters prone to timeouts; reduces Modbus transaction rate |\n| Normal | 2 s | 1.0 (fixed) | Default; suitable for wired LAN |\n| Fast | 1 s | 0.5 (configurable) | Tighter real-time control (Excess Export, SoC cutoffs); roughly doubles transaction rate |\n\nThe Slow and Fast multipliers can be adjusted in the options form (range 0.25-10.0, step 0.25). Fast mode on low-spec hardware (Raspberry Pi 3 or similar) may impact Home Assistant performance due to the increased polling rate.\n\n### Model Variants\n\nThe integration supports two model variants, configurable via the integration's **Configure** button in Settings → Devices \u0026 Services:\n\n| Variant | Inverter models |\n|---------|----------------|\n| Standard | All AlphaESS models except B3/B3PLUS (default) |\n| SMILE-B3 / SMILE-B3-PLUS | SMILE-B3 and SMILE-B3-PLUS only |\n\nB3 and B3PLUS inverters report some registers with different scale factors. Selecting the wrong variant will show incorrect values for grid voltage and inverter power registers. If you own a SMILE-B3 or SMILE-B3-PLUS, select that variant after installation.\n\n---\n\n## Entities\n\n### Sensors (read-only)\n\n94 sensors are enabled by default; the remaining 65 are disabled and can be turned on individually in HA under Settings → Devices \u0026 Services → [device] → entities. Sensors marked *(disabled)* below are off by default.\n\n#### Power (real-time)\n\nThese sensors have a 1 s `scan_interval` but the master loop runs at 2 s in Normal mode, so the effective update rate is 2 s by default. Selecting Fast mode reduces the loop to 1 s, achieving the full 1 s rate.\n\n| Entity | Unit | Poll | Description |\n|--------|------|------|-------------|\n| Grid Power | W | 2 s (1 s Fast) | Positive = import from grid, negative = export to grid |\n| Battery Power | W | 2 s (1 s Fast) | Power to/from battery |\n| Active Power PV Meter | W | 2 s (1 s Fast) | PV generation measured at the meter point |\n| PV String 1 Power | W | 2 s (1 s Fast) | |\n| PV String 2 Power | W | 2 s (1 s Fast) | |\n| PV String 3 Power | W | 2 s (1 s Fast) | |\n| PV String 4 Power | W | 2 s (1 s Fast) | |\n| PV Total Power (Inverter) *(disabled)* | W | 2 s (1 s Fast) | Sum of all PV strings per inverter register 0x0453 |\n| Current PV Production | W | calculated | Sum of all PV string powers + PV meter |\n| Current House Load | W | calculated | Net house consumption derived from grid, battery, and PV |\n\n#### Grid\n\n| Entity | Unit | Poll | Description |\n|--------|------|------|-------------|\n| Grid Frequency | Hz | 30 s | |\n| Grid Power Phase A | W | 5 s | |\n| Grid Power Phase B | W | 5 s | |\n| Grid Power Phase C | W | 5 s | |\n| Grid Voltage Phase A | V | 5 s | |\n| Grid Voltage Phase B | V | 5 s | |\n| Grid Voltage Phase C | V | 5 s | |\n| Max Feed to Grid | % | 5 s | Grid export limit as % of installed PV capacity |\n\n#### Inverter\n\n| Entity | Unit | Poll | Description |\n|--------|------|------|-------------|\n| Inverter Work Mode | - | 5 s | Operating mode code |\n| Inverter Power L1 | W | 5 s | |\n| Inverter Power L2 | W | 5 s | |\n| Inverter Power L3 | W | 5 s | |\n| Inverter Power | W | 5 s | Total AC output |\n| Inverter Temperature | °C | 60 s | |\n| Backup Inverter Power L1 *(disabled)* | W | 5 s | Backup output per phase |\n| Backup Inverter Power L2 *(disabled)* | W | 5 s | |\n| Backup Inverter Power L3 *(disabled)* | W | 5 s | |\n| Backup Inverter Power *(disabled)* | W | 5 s | Total backup output |\n\n#### PV Strings\n\n| Entity | Unit | Poll | Description |\n|--------|------|------|-------------|\n| PV String 1 Voltage | V | 60 s | |\n| PV String 1 Current | A | 60 s | |\n| PV String 2 Voltage | V | 60 s | |\n| PV String 2 Current | A | 60 s | |\n| PV String 3 Voltage | V | 60 s | |\n| PV String 3 Current | A | 60 s | |\n| PV String 4 Voltage | V | 60 s | |\n| PV String 4 Current | A | 60 s | |\n| PV Capacity Storage *(disabled)* | W | 60 s | Battery storage PV nameplate capacity |\n| PV Capacity of Grid Inverter *(disabled)* | W | 60 s | Grid inverter PV nameplate capacity |\n| CT Rate PV Meter *(disabled)* | - | 60 s | CT ratio for PV meter |\n| CT Rate Grid Meter *(disabled)* | - | 60 s | CT ratio for grid meter |\n\n#### Battery\n\n| Entity | Unit | Poll | Description |\n|--------|------|------|-------------|\n| Battery State of Charge | % | 10 s | |\n| Battery State of Health | % | 10 s | |\n| Battery Min Cell Temp | °C | 10 s | Lowest cell temperature in pack |\n| Battery Max Cell Temp | °C | 10 s | Highest cell temperature in pack |\n| Battery Max Charge Current | A | 10 s | BMS-reported maximum |\n| Battery Max Discharge Current | A | 10 s | BMS-reported maximum |\n| Battery Voltage | V | 60 s | Pack terminal voltage |\n| Battery Current | A | 60 s | Pack current |\n| Battery Status | - | 60 s | Human-readable BMS status with raw value, e.g. \"Charging + Discharging (257)\" |\n| Battery Remaining Time | min | 60 s | |\n| Battery Min Cell Voltage | V | 60 s | Lowest cell voltage in pack (3 d.p.) |\n| Battery Max Cell Voltage | V | 60 s | Highest cell voltage in pack (3 d.p.) |\n| Battery Relay Status *(disabled)* | - | 60 s | BMS relay state |\n| Battery Charge Cutoff Voltage *(disabled)* | V | 5 min | Hardware upper voltage limit from BMS |\n| Battery Discharge Cutoff Voltage *(disabled)* | V | 5 min | Hardware lower voltage limit from BMS |\n| Battery Module Count *(disabled)* | - | 5 min | Number of battery modules installed |\n| Battery Capacity *(disabled)* | kWh | 5 min | Pack nameplate capacity |\n| Battery Type *(disabled)* | - | 5 min | Battery type code from BMS |\n\n#### Energy Totals (lifetime)\n\n| Entity | Unit | Poll | Description |\n|--------|------|------|-------------|\n| Total Energy from PV | kWh | 60 s | Lifetime PV generation |\n| Total Energy Feed to Grid (Meter) | kWh | 60 s | Lifetime export measured at grid meter |\n| Total Energy Consumption from Grid (Meter) | kWh | 60 s | Lifetime import measured at grid meter |\n| Total Energy Feed to Grid (PV) | kWh | 60 s | Lifetime export measured at PV meter |\n| Total Energy Charge Battery | kWh | 60 s | Lifetime energy delivered into battery |\n| Total Energy Discharge Battery | kWh | 60 s | Lifetime energy drawn from battery |\n| Total Energy Charge Battery from Grid | kWh | 60 s | Lifetime grid-to-battery energy |\n\n#### Faults \u0026 Warnings\n\n| Entity | Unit | Poll | Description |\n|--------|------|------|-------------|\n| System Fault | - | 5 s | Active fault code (0 = no fault) |\n| Inverter Warning 1 | - | 5 s | Inverter warning bitmask |\n| Inverter Warning 2 | - | 5 s | |\n| Inverter Fault 1 | - | 5 s | Inverter fault bitmask |\n| Inverter Fault 2 | - | 5 s | |\n| Battery Warning | - | 5 s | BMS-level battery warning |\n| Battery Fault | - | 5 s | BMS-level battery fault |\n| Battery 1 Warning *(disabled)* | - | 5 s | Per-module warning, modules 1–6 |\n| Battery 2 Warning *(disabled)* | - | 5 s | |\n| Battery 3 Warning *(disabled)* | - | 5 s | |\n| Battery 4 Warning *(disabled)* | - | 5 s | |\n| Battery 5 Warning *(disabled)* | - | 5 s | |\n| Battery 6 Warning *(disabled)* | - | 5 s | |\n| Battery 1 Fault *(disabled)* | - | 5 s | Per-module fault, modules 1–6 |\n| Battery 2 Fault *(disabled)* | - | 5 s | |\n| Battery 3 Fault *(disabled)* | - | 5 s | |\n| Battery 4 Fault *(disabled)* | - | 5 s | |\n| Battery 5 Fault *(disabled)* | - | 5 s | |\n| Battery 6 Fault *(disabled)* | - | 5 s | |\n\n#### Dispatch \u0026 Diagnostics\n\n| Entity | Unit | Poll | Description |\n|--------|------|------|-------------|\n| Dispatch Start | - | 5 s | 1 = dispatch active, 0 = stopped |\n| Dispatch Active Power | W | 5 s | Current dispatch power (offset-decoded; negative = charge) |\n| Dispatch Reactive Power | W | 5 s | |\n| Dispatch Mode | - | 5 s | Current dispatch mode code |\n| Dispatch SoC | % | 5 s | Current SoC target |\n| Dispatch Time | s | 5 s | Remaining dispatch duration |\n| Dispatch Energy Flow Direction | - | 5 s | Human-readable flow direction: PV to Grid, Battery to Grid, Grid to Battery, etc. |\n| Freq Dispatch Flag | - | 5 s | 0 = Normal, 1 = frequency dispatch active |\n| Dispatch PV Switch | - | 5 s | PV switch state during dispatch |\n| Freq Dispatch Power *(disabled)* | W | 5 s | Frequency dispatch power setpoint |\n| Freq Dispatch Frequency *(disabled)* | Hz | 5 s | Frequency dispatch trigger frequency |\n| Force Charging Countdown | s | 5 s | Live inverter remaining time when Force Charging is active; 0 otherwise |\n| Force Discharging Countdown | s | 5 s | Live inverter remaining time when Force Discharging is active; 0 otherwise |\n| Force Export Countdown | s | 5 s | Live inverter remaining time when Force Export is active; 0 otherwise |\n| Force Import Countdown | s | 5 s | Live inverter remaining time when Force Import is active; 0 otherwise |\n\n#### Scheduling — Charging / Discharging Periods\n\nThese are read-only sensor views of the scheduling registers. The writable equivalents are the Time and Number entities listed under Controls below.\n\n| Entity | Unit | Poll | Description |\n|--------|------|------|-------------|\n| Charging Time Period Control | - | 10 s | Mode code: 0 = Disable, 1 = Grid Charging, 2 = Discharge Time Control, 3 = Both |\n| Charging Cutoff SoC | % | 10 s | Stop charging at this SoC |\n| Charging Period 1 Start Hour | h | 30 s | |\n| Charging Period 1 Stop Hour | h | 30 s | |\n| Charging Period 2 Start Hour | h | 30 s | |\n| Charging Period 2 Stop Hour | h | 30 s | |\n| Charging Period 1 Start Minute | min | 30 s | |\n| Charging Period 1 Stop Minute | min | 30 s | |\n| Charging Period 2 Start Minute | min | 30 s | |\n| Charging Period 2 Stop Minute | min | 30 s | |\n| Discharging Cutoff SoC | % | 30 s | Stop discharging at this SoC |\n| Discharging Period 1 Start Hour | h | 30 s | |\n| Discharging Period 1 Stop Hour | h | 30 s | |\n| Discharging Period 2 Start Hour | h | 30 s | |\n| Discharging Period 2 Stop Hour | h | 30 s | |\n| Discharging Period 1 Start Minute | min | 30 s | |\n| Discharging Period 1 Stop Minute | min | 30 s | |\n| Discharging Period 2 Start Minute | min | 30 s | |\n| Discharging Period 2 Stop Minute | min | 30 s | |\n\n#### Inverter \u0026 System Info\n\n| Entity | Unit | Poll | Description |\n|--------|------|------|-------------|\n| Inverter Serial Number | - | 60 s | |\n| Inverter Version | - | 60 s | DSP firmware version string |\n| Inverter ARM Version | - | 60 s | ARM firmware version string |\n| BMS Version | - | 60 s | Formatted as V1.65 |\n| LMU Version | - | 60 s | Formatted as V1.65 |\n| ISO Version | - | 60 s | Formatted as V1.65 |\n| EMS Version | - | 60 s | Combined from four sub-registers, e.g. V1.0.23R1 |\n| EMS Version High *(disabled)* | - | 60 s | Raw EMS major version component |\n| EMS Version Middle *(disabled)* | - | 60 s | |\n| EMS Version Low *(disabled)* | - | 60 s | |\n| EMS Version Low Suffix *(disabled)* | - | 60 s | |\n| System Time YYMM *(disabled)* | - | 5 s | Raw year/month packed register |\n| System Time DDHH *(disabled)* | - | 5 s | Raw day/hour packed register |\n| System Time MMSS *(disabled)* | - | 5 s | Raw minute/second packed register |\n\n#### Network (all disabled by default)\n\n| Entity | Unit | Poll | Description |\n|--------|------|------|-------------|\n| Modbus Baud Rate *(disabled)* | - | 60 s | |\n| IP Method *(disabled)* | - | 60 s | DHCP or Static |\n| Local IP *(disabled)* | - | 60 s | Dotted-decimal IP address, e.g. 10.0.0.209 |\n| Subnet Mask *(disabled)* | - | 60 s | Dotted-decimal subnet mask |\n| Gateway *(disabled)* | - | 60 s | Dotted-decimal gateway address |\n\n#### Grid Safety (all disabled by default)\n\n| Entity | Unit | Poll | Description |\n|--------|------|------|-------------|\n| Grid Regulation *(disabled)* | - | 60 s | Grid standard code |\n| Overvoltage Protection L1 *(disabled)* | V | 60 s | |\n| Overvoltage Protection L1 Time *(disabled)* | ms | 60 s | |\n| Overvoltage Protection L2 *(disabled)* | V | 60 s | |\n| Overvoltage Protection L2 Time *(disabled)* | ms | 60 s | |\n| Overvoltage Protection L3 *(disabled)* | V | 60 s | |\n| Overvoltage Protection L3 Time *(disabled)* | ms | 60 s | |\n| Overvoltage Protection 10min *(disabled)* | V | 60 s | 10-minute average overvoltage threshold |\n| Overvoltage Protection 10min Time *(disabled)* | s | 60 s | |\n| Undervoltage Protection L1 *(disabled)* | V | 60 s | |\n| Undervoltage Protection L1 Time *(disabled)* | ms | 60 s | |\n| Undervoltage Protection L2 *(disabled)* | V | 60 s | |\n| Undervoltage Protection L2 Time *(disabled)* | ms | 60 s | |\n| Undervoltage Protection L3 *(disabled)* | V | 60 s | |\n| Undervoltage Protection L3 Time *(disabled)* | ms | 60 s | |\n| Overfrequency Protection L1 *(disabled)* | Hz | 60 s | |\n| Overfrequency Protection L1 Time *(disabled)* | ms | 60 s | |\n| Overfrequency Protection L2 *(disabled)* | Hz | 60 s | |\n| Overfrequency Protection L2 Time *(disabled)* | ms | 60 s | |\n| Overfrequency Protection L3 *(disabled)* | Hz | 60 s | |\n| Overfrequency Protection L3 Time *(disabled)* | ms | 60 s | |\n| Underfrequency Protection L1 *(disabled)* | Hz | 60 s | |\n| Underfrequency Protection L1 Time *(disabled)* | ms | 60 s | |\n| Underfrequency Protection L2 *(disabled)* | Hz | 60 s | |\n| Underfrequency Protection L2 Time *(disabled)* | ms | 60 s | |\n| Underfrequency Protection L3 *(disabled)* | Hz | 60 s | |\n| Underfrequency Protection L3 Time *(disabled)* | ms | 60 s | |\n\n### Controls\n\n| Entity | Type | Description |\n|--------|------|-------------|\n| Force Charging | Switch | Charge battery from grid at configured power/duration/cutoff SoC |\n| Force Discharging | Switch | Discharge battery at configured power/duration/cutoff SoC; auto-stops ~1% above cutoff to guarantee no grid draw during transition |\n| Force Export | Switch | Export to grid at a target feed-in rate (kW); battery discharge dynamically adjusted for live house load and PV; stops when duration expires or battery hits cutoff SoC |\n| Force Export Hold | Switch | Keeps Force Export running indefinitely after the duration expires; turn on before starting Force Export for continuous export without a time limit |\n| Force Import | Switch | Import from grid at a target kW, dynamically adjusted for live PV so total grid draw stays at the target; stops at cutoff SoC |\n| Force Import Pause | Binary sensor | On when Force Import is automatically paused; resumes automatically when conditions are met |\n| Dispatch | Switch | Generic dispatch — mode, power, SoC target, and duration all configurable independently |\n| Excess Export | Switch | Charge battery with PV power that would otherwise be clipped by the AC output limit; auto-pauses when house draws from grid, auto-resumes when PV recovers |\n| Excess Export Pause | Binary sensor | On when Excess Export has automatically paused due to grid import |\n| Force Charging Power | Number | Charging power in kW (0–20) |\n| Force Charging Duration | Number | Duration in minutes (0–480, step 5) |\n| Force Charging Stop at SoC | Number | Stop charging at this SoC % |\n| Force Discharging Power | Number | Discharging power in kW (0–20) |\n| Force Discharging Duration | Number | Duration in minutes (0–480, step 5) |\n| Force Discharging Stop at SoC | Number | Stop discharging at this SoC % (switch auto-stops ~1% above this) |\n| Force Export Power | Number | Target grid feed-in rate in kW (0–20); battery discharge is calculated dynamically to achieve this |\n| Force Export Duration | Number | Duration in minutes (0–480, step 5) |\n| Force Export Stop at SoC | Number | Stop exporting at this SoC % (switch auto-stops ~1% above this) |\n| Force Import Power | Number | Target grid import in kW (0–20) |\n| Force Import Duration | Number | Duration in minutes (0–480, step 5) |\n| Force Import Stop at SoC | Number | Stop importing at this SoC % |\n| Dispatch Power | Number | Dispatch power in kW (−20 to +20; negative = charge, positive = discharge/export); defaults to 0 kW |\n| Dispatch Duration | Number | Duration in minutes (0–480, step 5) |\n| Dispatch Stop at SoC | Number | SoC target % for the generic Dispatch switch |\n| Dispatch Mode | Select | Operating mode for the generic Dispatch switch (Battery Only, SoC Control, Load Following, etc.) |\n| Charging / Discharging Settings | Select | Enable/disable time period control (Disable / Grid Charging / Discharge Time Control / Both) |\n| Inverter AC Limit | Select | Inverter AC output capacity (3–20 kW) — used by Excess Export to avoid overloading the inverter |\n| Max Feed to Grid | Number | Grid export limit (% of PV capacity) |\n| Charging Period 1 Start Time | Time | hh:mm — writes hour and minute registers independently |\n| Charging Period 1 Stop Time | Time | hh:mm |\n| Charging Period 2 Start Time | Time | hh:mm |\n| Charging Period 2 Stop Time | Time | hh:mm |\n| Discharging Period 1 Start Time | Time | hh:mm |\n| Discharging Period 1 Stop Time | Time | hh:mm |\n| Discharging Period 2 Start Time | Time | hh:mm |\n| Discharging Period 2 Stop Time | Time | hh:mm |\n| Dispatch Reset | Button | Reset all dispatch registers immediately |\n| Synchronise Date \u0026 Time | Button | Sync inverter clock to HA system time |\n| Sync Dispatch State | Button | Reconcile HA switch states with the inverter (use after HA restart if dispatch was running) |\n| Restart PCS | Button | Restart the Power Conversion System |\n| Restart EMS | Button | Restart the Energy Management System |\n| Reset Energy Totals | Button | **WARNING: clears all lifetime energy counters on the inverter.** Use only if you have intentionally replaced the inverter or need to zero out the totals. |\n\n#### Extending a Running Dispatch Duration\n\nTo extend the duration of an active Force Charging, Force Discharging, Force Export, or Force Import session without interruption:\n\n1. Set the Duration number entity to the new total time you want (e.g. 120 min).\n2. Turn the switch off.\n3. Turn the switch on again.\n\nThe integration immediately sends a fresh dispatch with the new duration. The per-mode countdown sensor reflects the new duration within the next 5 s poll.\n\n---\n\n## Network Setup\n\nFor reliable Modbus TCP connectivity:\n\n1. Connect the inverter's **LAN port** directly to your router (or via a switch)\n2. Set a **DHCP reservation** in your router so the inverter always gets the same IP\n3. If your inverter is on Wi-Fi, a **powerline adapter** or **Wi-Fi repeater in bridge mode** works well\n\nThe inverter's Modbus TCP port is `502` and the slave ID is `85` by default. These can be verified in the AlphaESS app under **Settings → Communication**.\n\n---\n\n## Troubleshooting\n\n**Integration won't connect**\n- Confirm the inverter IP is reachable: try `ping \u003cinverter-ip\u003e` from your HA host\n- Check that Modbus TCP is enabled on the inverter (AlphaESS app → Settings → Communication)\n- Make sure no firewall is blocking port 502\n- AlphaESS inverters only allow **one Modbus TCP connection at a time** — if another app (a second HA instance, a Modbus tool, Alpha2MQTT, etc.) is already connected, HA will be refused. Disconnect the other client and reload the integration\n\n**Entities show unavailable after some time**\n- This can happen if the inverter goes into sleep/standby mode at night — it recovers automatically when the inverter wakes up\n- Check HA logs for Modbus timeout errors\n\n**Force charging / dispatch not working**\n- Only one dispatch mode can be active at a time — activating one switch will deactivate any other active switch\n- Dispatch automatically resets after the configured duration expires\n\n---\n\n## Advanced: Writing Registers Directly\n\nThe `alphaess_modbus.write_register` service writes a raw integer value to any Modbus holding register using FC6 (Write Single Register). It is intended for use from Developer Tools or automations by advanced users and developers.\n\n\u003e **Warning:** Writing incorrect values to grid safety registers (overvoltage, undervoltage, frequency protection) or inverter configuration registers can cause the inverter to trip or behave unexpectedly. Use with care and consult the AlphaESS Modbus register documentation before writing to any register you are not certain about. This service is for developers only.\n\n```yaml\nservice: alphaess_modbus.write_register\ndata:\n  address: 2052    # register address as a decimal integer (hex: 0x0804)\n  value: 400       # raw integer to write (no scale or offset applied)\n```\n\nThe address must be provided as a decimal integer. Convert hex addresses from the register documentation using a calculator (for example, 0x0804 = 2052). The value is written as-is with no scale or offset applied.\n\nIf two inverters are configured, the service writes the same value to all instances.\n\n---\n\n## Dashboards\n\nExample Lovelace dashboard configurations are included in the [`examples/`](examples/) folder:\n\n| File | Description | Custom cards required |\n|------|-------------|----------------------|\n| `alphaess_dashboard_pfcp.yaml` | Sections-layout dashboard with live power flow diagram — battery controls, scheduling, dispatch, energy stats, system info | [power-flow-card-plus](https://github.com/flixlix/power-flow-card-plus) |\n| `alphaess_dashboard.yaml` | Sections-layout dashboard without custom cards — gauge + glance live view, battery controls, scheduling, dispatch, energy stats, system info | None |\n| `power_diagram.yaml` | Power flow chart for today | [ApexCharts Card](https://github.com/RomRider/apexcharts-card) |\n| `power_diagram_extended.yaml` | Extended power diagrams — today, yesterday, 3-day, string detail, instant, and hi-res views | [ApexCharts Card](https://github.com/RomRider/apexcharts-card) |\n\n### How to use\n\n1. Install any required custom cards via HACS (see table above):\n   - **power-flow-card-plus**: HACS → Frontend → search \"Power Flow Card Plus\" → Download\n   - **ApexCharts Card**: HACS → Frontend → search \"ApexCharts Card\" → Download\n2. In Home Assistant go to **Settings → Dashboards → Add Dashboard**\n3. Open the view you want to replace, click the three-dot menu → **Edit in YAML**, and paste the contents of the example file directly (the file starts with `title:` — no extra wrapping needed).\n\n4. Reload the dashboard browser tab after installing any custom cards\n\n\u003e **EV Charger entity:** `alphaess_dashboard_pfcp.yaml` includes `sensor.charger_power_active_import` in the power flow diagram. If you do not have an EV charger, remove the `individual:` block from the `custom:power-flow-card-plus` card.\n\n\u003e All entity IDs follow the pattern `sensor.alphaess_inverter_*`, `switch.alphaess_inverter_*`, etc. (the device name is \"AlphaESS Inverter\", which Home Assistant uses as the entity ID prefix).\n\n---\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full version history.\n\n---\n\n## Credits\n\nThis integration is based on the YAML package developed by **Axel Koegler** and documented at [projects.hillviewlodge.ie/alphaess](https://projects.hillviewlodge.ie/alphaess/). All Modbus register mappings are derived from that work and the AlphaESS Modbus register documentation.\n\nDocumentation and release notes assisted by [Claude](https://claude.ai) (Anthropic).\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsenalse%2Fha-alphaess-modbus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsenalse%2Fha-alphaess-modbus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsenalse%2Fha-alphaess-modbus/lists"}