Monitor and control your GivEnergy solar and battery system from your own computer — no cloud account needed.
Home Energy Manager connects directly to your inverter over your home network and shows you live data in real time. You can check your solar generation, battery charge, and energy costs, set charge schedules, and automate your battery — all without sending any data to the internet.
💬 Got a question or hit a snag? Try asking your favourite AI assistant first — just point it at the installation guide and ask your question. If you don't get your answer, feel free to raise an issue.
Status Dashboard |
Status — Mobile |
Power Chart |
Battery Detail |
Inverter Info |
Meters |
Energy History |
History — Solar |
Planner |
Planner — Solar Forecast |
History — Home |
Control Panel |
Settings |
Developer Console |
Consumption Reports |
Consumption Report (PDF) |
Go to the Releases page and download the file for your system:
| Your computer | Look for the file name containing |
|---|---|
| 🪟 Windows | Windows-MSI-...msi |
| 🍎 Mac with Apple Silicon (M1/M2/M3/M4) | macOS-Apple-Silicon-...dmg |
| 🍎 Mac with Intel processor | macOS-Intel-...dmg |
| 🐧 Linux x86_64 (Ubuntu, Debian, etc.) | Linux-Debian-x86_64-...deb |
| 🐧 Linux x86_64 (Fedora, openSUSE, etc.) | Linux-RPM-x86_64-...rpm |
| 🍓 Raspberry Pi / ARM64 Linux (Ubuntu, Debian) | Linux-Debian-ARM64-...deb |
| 🍓 Raspberry Pi / ARM64 Linux (Fedora, openSUSE) | Linux-RPM-ARM64-...rpm |
Windows users — Windows SmartScreen may show "Windows protected your PC" because the app is not code-signed. This is open-source software you can inspect on GitHub, and the installer is scanned clean by VirusTotal. If your antivirus flags it as malware, please report a security vulnerability at https://github.com/psylsph/home-energy-manager/issues.
To run the MSI if SmartScreen appears:
- Click "More info" on the SmartScreen screen
- Click "Run anyway"
If the installer itself won't open, right-click the .msi → Properties → check the "Unblock" box → OK, then run it again. The Windows-Store-MSIX-...msix asset is an unsigned Microsoft Store submission package and is not intended for direct installation.
Mac users — after opening the .dmg, drag the app to your Desktop or Home folder (not /Applications). On first launch, right-click the app → Open → Open to bypass Gatekeeper. See the FAQ if you get stuck.
Linux users — packaged installs may need two runtime libraries, while building desktop bundles from source requires additional Linux development packages. See INSTALL.md for details.
Proxmox users — a first-party helper can create an unprivileged Debian 13 LXC and run Home Energy Manager headlessly without Docker. See the Proxmox VE LXC instructions.
The app needs the IP address of the small WiFi or Ethernet dongle connected to your inverter. You can find this in your router's device list — look for a device named "GivEnergy" or check the MAC address printed on the dongle.
Not sure? Don't worry — the app can find it for you (see step 4 below).
- Open the app and go to Settings (the ⚙️ icon at the bottom)
- Enter your inverter's IP address in the Host field
- Click Connect
Live data should appear on the Status page within a few seconds. The serial number is detected automatically.
Click Scan Network on the Settings page. The app will search your local network for GivEnergy data adapters and list any it finds. Click on one to auto-fill the IP address.
Tip: If the connection keeps dropping or data looks wrong, try a wired Ethernet connection between your data adapter and router. The WiFi dongles can be unreliable.
Home Energy Manager connects directly to your inverter over your home network. It never sends data to the internet and doesn't need a GivEnergy Cloud account. (Your WiFi dongle keeps reporting to the GivEnergy cloud as it always has, and it also passes on each reading the app asks for, so a short refresh interval makes your cloud history finer-grained.)
- Real-time dashboard — see solar generation, battery charge level, grid import/export, and home consumption updating live
- Energy flow diagram — animated visual showing where your power is flowing right now (solar → battery → home → grid)
- Power chart — live chart tracking solar, battery, grid, and home power with selectable time ranges from 15 minutes to 7 days. Click legend labels to show or hide individual lines.
- Battery detail — individual cell voltages, temperatures, and health per battery module
- Solar page — voltage, current, and power for each solar string (supports dual-string systems)
- Inverter page — model name, firmware versions, serial number, temperatures, and all electrical readings at a glance
- Meters page — external meter readings with per-phase voltage, current, and power, plus a CT clamp status card
- Cold battery warning — alerts you when your battery temperature drops near freezing so you can protect it
- Time-range charts — 7 selectable ranges from 15 minutes to 7 days, covering solar, battery, grid, and home energy
- Energy breakdown views — separate charts for solar, home, grid, and battery with shared time-range selection
- Month calendar view — daily energy totals at a glance for the whole month
- Cost tracking — enter your import and export tariffs to see running cost estimates on your charts
- CSV export — download your energy history as a spreadsheet
- PDF consumption reports — generate formatted reports with charts and summary tables for solar, home, grid, and battery energy, including cost breakdowns. Open Consumption Report from the Power page, then choose Print / save as PDF. The History page exports CSV only.
- Consumption Reports — summary statistics for any time range including total energy, peak power, solar coverage percentage, and grid dependency, with time-bucketed breakdowns exportable as CSV
The Planner tab looks three days ahead and tells you whether tonight's cheap-rate window needs a grid charge, and how much.
- Today's recommendation — the plan card leads the page with the overnight charge to make, its time window, the lowest the battery will fall and what the charge will cost. It's the smallest charge that keeps your battery above the minimum level you choose, placed in your cheapest import window, and one click applies it to the inverter
- Automatic planning — switch it on and the app re-sizes and writes the charge slot shortly before each cheap window (30 minutes by default, adjustable up to two hours) from your live battery level, then sends you a notification saying what it did (or why no charge was needed)
- Export opportunities — when your export tariff pays more at certain times, the Planner shows how much you can sell from the battery, when, and what it should earn, without dropping below your minimum
- Solar forecast — a 72-hour generation forecast built from live weather data (Open-Meteo — free, no account or API key needed) and automatically calibrated against your own generation history, so it learns your panels' real-world performance over the first couple of weeks
- Consumption profile — your household's typical hourly electricity usage, learned from your own history and shown with typical low/high ranges
- Battery projection — see where your battery is heading hour by hour if you rely on solar alone, if you follow the plan, or if you leave your current inverter schedule as it is
- Tomorrow at a glance — expected solar, house consumption, export and import for tomorrow, with the plan's charge included
- Charge & discharge schedules — set time slots for when your battery charges from the grid or discharges to power your home (up to 10 slots on supported models)
- Battery modes — switch between Eco (automatic self-consumption), Timed Discharge, and Pause Discharge, which holds stored energy while still allowing solar or scheduled grid charging
- Force Charge / Force Discharge — mutually exclusive manual controls with live start/stop confirmation; stop the active action before starting the opposite one
- SOC control — adjust battery reserve level, charge/discharge power limits, and charge target
- Battery calibration — start calibration from the app when your battery needs it (auto-detected)
- Load Discharge Limiter — pause battery discharge during high-demand periods with a configurable power threshold and time window
- Inverter Temperature Limiter — pause discharge at a configurable heatsink temperature and restore normal Eco after the inverter cools
- Octopus Cosy (beta) — enter your three Cosy cheap-rate windows and the app automatically charges your battery during each one, switching back to Eco mode in between. Survives an app restart mid-slot.
- Octopus Agile (beta) — enter your postcode and price thresholds. The app charges when Agile prices are low, discharges when they're high, and stays in Eco the rest of the time. Includes a live 24-hour price forecast grid with daily savings estimates.
- Auto Winter Mode — protects your battery from cold by automatically charging it from the grid when the temperature drops. You set the temperature threshold and target charge level. Works the same way as GivEnergy Cloud's winter mode, but runs entirely on your own machine.
- Alert notifications (Telegram, ntfy & Pushover) — set thresholds for battery temperature, inverter temperature, SOC, solar clipping, grid offline, and battery over-temp. Get an alert message when something's wrong — and another when it's back to normal. Send
/status,/today, or/reportin your Telegram chat for a live system snapshot, today's cost summary, or yesterday's full consumption report. Choose between a Telegram bot, ntfy or Pushover push notifications, or any combination. - Octopus smart-meter dashboard — add your Octopus account number and API key to see supplier-recorded electricity import, export, and gas usage alongside your inverter data, including billing costs, monthly and yearly summaries, and a comparison against the app's own readings. Export as CSV or PDF. The Octopus tab stays hidden until configured.
- Works with supported GivEnergy inverter models — Gen 1, Gen 2, Gen 3, Gen 4, Three Phase, AC Three Phase, HV Gen 3, residential All-in-One, AIO Hybrid, and Gateway
- Three-phase systems — supported, including the GIV-3HY family and residential All-in-One units
- Commercial AIO/EMS systems are not currently supported — their EMS-C uses a different standard Modbus TCP interface and register map.
- Smart meter detection — handles LoRA-linked meters and slow-responding CT clamps so nothing gets missed at startup
Home Energy Manager supports the inverter models listed below. Real-time monitoring, Force Charge/Discharge, Cosy and Agile automation, and Auto Winter Mode are available according to each model's capabilities. The main difference between models is how many charge/discharge schedule slots you can set:
Full control — live data, up to 10 charge + 10 discharge slots, all limits and modes
| Model | Notes |
|---|---|
| Gen 3 Hybrid (5kW/8kW/10kW) | Most common. Extended 10-slot schedules require ARM firmware ≥ 303. |
| Gen 4 Hybrid | Latest generation |
| Three Phase (e.g. GIV-3HY-11 11kW) | Full three-phase support |
| AC Three Phase | AC-coupled three-phase |
| HV Gen 3 | High-voltage hybrid |
| All-in-One (3.6kW/5kW/6kW) | Residential All-in-One units |
| All-in-One Hybrid | Combined hybrid + AIO |
| Gateway (experimental) | System controller / AC hub for 1–3 AIO units. Full schedule, mode, and rate-limit control via the three-phase register set. |
Full control with the simpler 2-slot layout
| Model | Notes |
|---|---|
| Gen 2 Hybrid | Standard home hybrid inverter |
| Gen 3 Plus Hybrid / Polar Hybrid | Newer single-phase variants |
| PV Inverter (no battery) | Solar-only — battery controls are hidden |
Live data, power limits, SOC, and modes — but only one charge + one discharge slot
| Model | Notes |
|---|---|
| Gen 1 Hybrid | Older generation |
| AC Coupled (standard & Mk2) | Retrofit battery system |
Not sure which model you have? Just connect the app to your inverter and check the Inverter tab — it shows the detected model name and details automatically.
| Platform | Available as |
|---|---|
| Windows | .msi installer |
| macOS (Apple Silicon & Intel) | .dmg |
| Linux (x86_64) | .deb and .rpm packages |
| Raspberry Pi (64-bit OS) | .deb (ARM64) |
| Any device with a browser | Access the web UI at http://your-pi-ip:7337 when running headless |
The app also runs as a headless server — a background service with no window, serving the full UI to any browser on your network. Great for Raspberry Pi or an always-on server. See INSTALL.md for setup instructions.
External software can use an authenticated integration API for battery status and optional Quick Actions — see Authenticated API below. Configure its key, separate port and default-off battery-control permission under Settings → Remote / Mobile Network Access (Developer Mode not required).
For detailed setup, status-field explanations, curl commands, JavaScript/Python examples and troubleshooting, see the Remote Battery Control API guide.
A separate HTTP server (default port 7338, Bearer-token authenticated) lets external software read inverter data and — with explicit permission — use the app's battery controls, including Force Charge, Force Discharge and finite native Pause windows. Legacy AC3 units use the confirmed HR318-only pause path, with the finite timer enforced by HEM. The main dashboard server is unchanged by any of this.
- Settings → Remote / Mobile Network Access → Authenticated API: click Generate API key (shown once — copy it), choose a port and listen address. New installs listen on
127.0.0.1only; Apply network settings rebinds the running listener without a restart (only starting the API for the first time on an older install needs an app restart). - Reading data needs only the key. To allow battery writes, toggle on Allow battery control through the authenticated API — it applies immediately (off by default, including after upgrades). A started action can still be stopped remotely after revocation; revocation never strands the inverter in a forced mode.
- These settings can only be changed from the machine running HEM, and Bearer tokens are not encrypted over plain HTTP — prefer a listen address of
127.0.0.1behind a trusted reverse proxy or VPN; direct LAN exposure is an explicit compatibility choice. - Browsing HEM from another machine (headless server, Proxmox LXC, VM, Docker)? The key-generation and network settings are refused with a
403by design — a remote, unauthenticated browser must not be able to mint itself an API credential. See Generating your first key on a remote/headless install for the one-time SSH or console workaround.
| Method | Path | Body | Write permission |
|---|---|---|---|
| GET | /api/snapshot |
None | No |
| GET | /api/control/status |
None | No |
| GET | /api/commands/{command_id} |
None | No |
| POST | /api/control/force-charge |
{"minutes":60} |
Yes |
| POST | /api/control/force-charge/stop |
None | Recovery always allowed; otherwise yes |
| POST | /api/control/force-discharge |
{"minutes":60} |
Yes |
| POST | /api/control/force-discharge/stop |
None | Recovery always allowed; otherwise yes |
| POST | /api/control/pause-mode |
{"mode":"charge","minutes":60} |
Yes, on supported models |
| POST | /api/control/pause-mode/stop |
None | Recovery always allowed; otherwise yes |
Every POST needs an Idempotency-Key header (16–128 characters; a UUID is ideal). Retries must reuse the same key — HEM replays the original response instead of queuing anything; the same key with a different payload is rejected with 409. Starts act immediately (duration 1–1439 minutes; extra fields are rejected), and a start while the same action is already running returns 409 with the running command's id. The actions reuse the Quick Action handlers exactly: same model-aware registers, restore behaviour, configured power limits, and mutual exclusion (stop one direction before starting the other). Native Pause is aggregate inverter/plant control with modes charge, discharge and both (the pause_-prefixed spellings are also accepted), for 1–1439 minutes. It is limited to confirmed model/firmware combinations and restores the exact prior pause state on Stop or expiry; unsupported devices return 422, and unavailable baseline state returns 503.
A mutation response carries a command_id meaning accepted and queued — not confirmed by the inverter. Poll GET /api/commands/{command_id} until the state is readback_confirmed (failed, expired and unknown are the honest alternatives). Other errors: 400 invalid input, 401 bad key, 403 control disabled, 409 idempotency or active-control conflict, 422 unsupported control, 503 unavailable inverter state, 429 rate limited (with Retry-After).
HEM_API='http://localhost:7338'
HEM_KEY='replace-with-your-key'
IDEM_KEY="$(uuidgen 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())')"
curl --fail-with-body "$HEM_API/api/control/force-charge" \
-H "Authorization: Bearer $HEM_KEY" -H "Idempotency-Key: $IDEM_KEY" \
-H 'Content-Type: application/json' \
--data '{"minutes":60}'
curl --fail-with-body -X POST "$HEM_API/api/control/force-charge/stop" \
-H "Authorization: Bearer $HEM_KEY" -H "Idempotency-Key: $IDEM_KEY"
curl --fail-with-body "$HEM_API/api/control/force-discharge" \
-H "Authorization: Bearer $HEM_KEY" -H "Idempotency-Key: $IDEM_KEY" \
-H 'Content-Type: application/json' \
--data '{"minutes":30}'
curl --fail-with-body -X POST "$HEM_API/api/control/force-discharge/stop" \
-H "Authorization: Bearer $HEM_KEY" -H "Idempotency-Key: $IDEM_KEY"
curl --fail-with-body "$HEM_API/api/control/status" \
-H "Authorization: Bearer $HEM_KEY"GET /api/control/status reports cached state only (no Modbus reads, no writes; Cache-Control: no-store). Mode, measured activity, controlling automation, schedules and restrictions are reported independently because they coexist — a force-charge window can be active while the battery is idle, and discharging is not necessarily grid export:
{
"ok": true,
"summary": "Force Charge — charging; 58 minutes remaining",
"mode": "eco",
"activity": "charging",
"control_source": "force_charge",
"control_phase": "active",
"remaining_minutes": 58,
"schedules": {"charge": "active", "export": "off", "demand_discharge": "off"},
"conditions": [],
"connection": "connected",
"stale": false,
"observed_at": "2027-01-15T12:00:00+00:00"
}summaryis for display; integrate against the structured fields (wording may change).mode:eco,eco_paused,timed_demand,timed_export,export_paused,unknown.activity:charging,discharging,idle,unavailable— observed operation, not requested action or inferred cause.control_source/control_phase: HEM's best-known controller (Quick Action, safety limiter, Timed Export, Cosy/Agile/Adaptive/winter automation, or the inverter's own schedule) and its phase. A Quick Action readspendinguntil a newer snapshot confirms it, thenactivefor the window duration even if the battery is idle;expiredwhen the recorded deadline passes.remaining_minutes: time left in a known Quick Action window (rounded up), otherwisenull— the window, not time-to-full.schedules: each of charge / export / demand-discharge isoff,armed(outside its window),active, orunknown, evaluated on the inverter's clock. A HEM-managed export schedule staysarmedoutside windows even when physical slots are temporarily cleared.automation,calibration,maintenance,limits: configuration and phase detail for Cosy, Agile, Adaptive Charge, winter automation, managed Timed Export, battery calibration/maintenance, and configured SOC/rate limits.conditions: all simultaneous faults, protections, pauses and unknown states as{code, label}— never collapsed into one label.- Readings older than three poll intervals (minimum 60s), implausibly future-dated readings, and disconnected/reconnecting states set
stale/ok: falseand refuse to present a current mode or activity;conditionsis then not a health statement.
- Repeating a start resets its duration and can replace the original restore point — don't build blind automatic retries.
- Timed charging does not auto-restore the previous schedule when its window ends; the slot stays configured until changed.
- Restore state doesn't survive a HEM restart; a repeated Stop can't always replay failed restore writes.
- Stop restores per existing Quick Action logic (Stop Charge may restore a pre-action non-Eco mode); it is not a separate integration-specific default.
Home Energy Manager has a built-in web server, so you can access it from your phone's browser. Combined with Tailscale (a free, zero-config VPN), you can check your system from anywhere — no cloud dependency, no port forwarding, no static IP.
- Install Tailscale on the machine running Home Energy Manager and on your phone
- Both devices join the same Tailscale network
- Open your phone browser to
http://<tailscale-ip>:7337 - Tap Share → Add to Home Screen for an app-like icon
Tailscale encrypts everything end-to-end, so your inverter data stays private.
📋 Detailed instructions
Install Tailscale on your server machine:
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
# Note the Tailscale IP shown (or find it later with: tailscale ip -4)Then on your phone:
- Install the Tailscale app from the App Store / Play Store
- Log in to the same account — your devices appear automatically
- Open Safari / Chrome and go to
http://<tailscale-ip>:7337 - Tap Share → Add to Home Screen for a native-app-like experience
💡 Tip: Set Home Energy Manager to run on boot so it's always available.
🔧 Alternative: Tailscale Funnel (no app needed on phone)
If you don't want Tailscale on your phone, you can expose the web UI via a public .ts.net URL:
sudo tailscale serve --bg --https 443 127.0.0.1:7337
sudo tailscale funnel --bg 443Your app will be available at https://<machine-name>.<tailnet-name>.ts.net. Tailscale handles HTTPS. Note: Funnel is a paid Tailscale feature.
| Cloud portal | Home Energy Manager + Tailscale | |
|---|---|---|
| Speed | 1–3 second delay | Real-time |
| Internet needed? | Always | Only when away from home |
| Cloud dependency | Depends on GivEnergy servers | None |
| Privacy | Data via GivEnergy | End-to-end encrypted |
| Cost | Free | Free |
This project was originally called GivEnergy-Local. The user-facing name is now Home Energy Manager, but the internal executable is still called givenergy-local and your settings and history are stored in the same place (~/.givenergy-local). Upgrading is seamless — everything carries over.
🙏 Huge thanks to the open-source projects that made this possible:, this project would not exist without the pioneering reverse-engineering work of the GivEnergy open-source community.
-
GivTCP — the original GivEnergy Modbus integration for Home Assistant. This app builds on the protocol mapping and write methodology that GivTCP established.
-
givenergy-modbus — the definitive Python reference library for the GivEnergy Modbus protocol. Its detailed register map and working reference implementation were invaluable.
Both projects are open-source and available on GitHub. If you find this app useful, consider giving them a star too ⭐
MIT — see LICENSE.