Installation Guide

HA-EMS HomeAssistant Integration

HA-EMS is a local energy-management integration built for Home Assistant, designed for smart-home scenarios. The current version supports local mode only: EMS devices are discovered over mDNS on the same LAN and polled in real time over TCP for power and energy data. This guide walks you through everything — before-you-start, the package, six installation steps, troubleshooting, and uninstall.

1. Before You Start
Local mode only. The current version discovers EMS devices over mDNS and polls them over TCP for real-time data. No AEC Cloud account is required.
  • ✓ Home Assistant and the EMS devices must be on the same local network (same subnet; nothing in between may block mDNS/UDP broadcast).
  • ✓ Supported device types: 85, 90, 99, 131, and 174. More types are being added.
  • ✓ Prepare a way to access the Home Assistant configuration directory /config — for example, the Samba share, the File Editor or Studio Code Server add-on, or an SSH terminal.
2. The Installation Package: ha_ems.zip
Obtain the ha_ems.zip package. After extraction it contains the following structure:
ha_ems.zip ├── custom_components/ │ └── ha_ems/ │ ├── manifest.json │ ├── __init__.py │ ├── config_flow.py │ ├── local_mdns.py │ ├── local_protocol.py │ ├── sensor.py │ ├── services.yaml │ ├── strings.json │ └── translations/ └── www/ └── ha_ems/ ├── ha_ems.yaml ├── ha-ems-local-devices-card.js └── *.svg
1
Step 1: Put the files into /config
Extract the ZIP into /config. Afterwards you should have these two directories:
/config/custom_components/ha_ems   ← the integration (manifest.json etc.)
/config/www/ha_ems   ← the dashboard card (ha_ems.yaml, JS card, ...)
Copying the two directories manually works just as well. When finished, confirm these key files exist:
/config/custom_components/ha_ems/manifest.json
/config/custom_components/ha_ems/local_mdns.py
/config/www/ha_ems/ha-ems-local-devices-card.js
/config/www/ha_ems/ha_ems.yaml
2
Step 2: Enable the dashboard in configuration.yaml
Add a standalone YAML dashboard to /config/configuration.yaml:
lovelace: dashboards: ha-ems: mode: yaml title: HA EMS icon: mdi:home-lightning-bolt show_in_sidebar: true filename: www/ha_ems/ha_ems.yaml
It is fine to skip this step for now; you can add it later (that will need one more restart).
3
Step 3: Restart Home Assistant
The only restart in this guide
Open Home Assistant in a browser and sign in (usually http://homeassistant.local:8123). Then go to Developer tools → YAML and click Restart Home Assistant.
  • The integration files are loaded by Home Assistant.
  • If you did Step 2, the "HA EMS" dashboard appears in the sidebar. It has no data yet — that is normal; it fills in automatically after Step 4.
4
Step 4: Add the integration
  • Open Home Assistant in a browser and sign in (usually http://homeassistant.local:8123; if the page is still open from Step 3, just continue).
  • Go to Settings → Devices & services → Add integration.
  • Search for HA EMS and submit.
  • The config flow creates the local-mode entry directly — no account or password needed.
Once added, device discovery and dashboard data start automatically — no second restart. The dashboard includes the device list, connection status, live power, the energy-flow diagram, control parameters, and diagnostics.
5
Step 5: Check the frontend resource
The integration registers the card resource automatically when it loads; normally no manual action is needed. If a page says the custom card cannot be found, add it manually under Settings → Dashboards → Resources:
URL:  /local/ha_ems/ha-ems-local-devices-card.js?v=0.6.2
Type: JavaScript Module
Add the same resource only once. After updating the card files, force refresh the browser (Ctrl+F5).
6
Step 6: Verify the installation
In Developer tools → States, search for these entities:
sensor.ha_ems_mode
sensor.ha_ems_local_devices
sensor.ha_ems_local_device_issues
The devices attribute of sensor.ha_ems_local_devices lists the discovered devices. Every supported device gets a sensor.ha_ems_<device>_energy_parameters entity. The device overview shows the energy-flow diagram once data arrives; if it says "waiting for EnergyParameter data", check the device connection and port first, then the Home Assistant logs.
Troubleshooting
SymptomWhat to do
HA EMS not listed when adding an integration Check /config/custom_components/ha_ems/manifest.json exists, then restart.
No devices discovered Confirm HA and the devices share the same subnet and nothing blocks mDNS/UDP broadcast.
Device connected but no energy-flow diagram The diagram needs an EnergyParameter response; check the entity's protocol_status, protocol_error, and the logs.
Page says the custom card is missing Confirm the JS file is in /config/www/ha_ems/, the resource type is JavaScript Module, then press Ctrl+F5.
Entities show "unavailable" Find the first Python exception in the HA logs, fix it, then restart the integration.
Uninstall
  • ✓ Delete the HA EMS config entry under Settings → Devices & services (this stops local scanning and TCP connections).
  • ✓ Delete /config/custom_components/ha_ems and /config/www/ha_ems.
  • ✓ Restart Home Assistant.
👉 Contact us to get the integration package download link or technical support. 👈
Contact Us