👋 Welcome to HA Powerflow

The HA Powerflow HUD is a high-performance, real-time visualisation tool for your WordPress site. It connects directly to your Home Assistant instance to display live energy flows (Solar, Battery, Grid, and House) in a beautiful, high-tech interface.

Core Concepts

HUD

Heads-Up Display. The visual interface that shows your data.

Entity

A specific sensor in Home Assistant (e.g. your solar production or battery percentage).

Refresh Rate

How often (in seconds) the widget asks Home Assistant for new data. 5–10 seconds is usually ideal.

Session

A complete EV charging event — from plug-in to disconnect — automatically recorded by the plugin.

🔌 1. Connecting to Home Assistant

The plugin needs two things: the URL of your HA server and a Security Token.

Step A: The URL

• Local access: http://192.168.1.50:8123
• Nabu Casa: https://your-unique-id.ui.nabu.casa

Step B: The Access Token Vital

1. Open your Home Assistant dashboard.
2. Click your Profile Name (bottom of the sidebar).
3. Scroll to Long-Lived Access Tokens and click CREATE TOKEN.
4. Name it “WordPress Site” and copy it immediately — you will only see it once.

Step C: Test the Connection

Paste the URL and Token into the plugin settings and click Test Connection. A green success message means you are ready to configure your sensors.

🛰️ 2. Setting Up Your Sensors

Tell the plugin which Home Assistant entities represent your power sources and consumers.

The Core Four

1. Grid Power: Positive = importing from grid, negative = exporting solar.
2. House Power: Real-time load/demand of your home.
3. Solar Power: Current output of your solar panels.
4. Battery SOC: State of charge percentage (0–100%).

Currency Symbol

Set your default currency symbol (e.g. £, €, $) under Sensors → Defaults. This is used across all cost displays in the widget and EV charge summary.

Quick Modules

Use the toggles at the top of the settings page to enable or disable modules. If you don’t have an EV or Heat Pump, turn them off to keep your HUD clean. Note that the EV History tab only appears when the EV module is enabled.

🚗 3. EV Charging — Extended Telemetry New

The EV module goes beyond Power and SOC. Four additional fields can be pulled from your charger and displayed on the HUD. Each has its own Visible toggle so you can show or hide them independently.

Configure these under Settings → Modules → EV.

How Session Tracking Works

The plugin tracks charging sessions automatically in the background — no configuration needed beyond entering your sensor entity IDs above.

Plug Status received	What happens
Charging, Eco+, Boost, Waiting, or any other value	Session continues. All states except Disconnected count as the same session.
Contains “Disconnected”	Session ends and is saved as completed.
unavailable, unknown, N/A, empty	Ignored — never starts or ends a session.

EV Charge Summary Shortcode

Place this shortcode on any page or post to show a full history of your charging sessions:

To auto-refresh the page during an active session, add the refresh attribute with the number of seconds:

The refresh only fires whilst a live session is in progress — when the EV disconnects, auto-refresh stops automatically.

What the Summary Shows

Total Cost is always calculated as Charge Added (kWh) × Co Charger Cost (rate) using your Currency Symbol.

EV History Tab (Admin)

When the EV module is enabled, an ⚡ EV History tab appears in plugin settings. It provides:

• Summary stats — total sessions, total energy, total cost across all recorded sessions
• Full session table with date, times, duration, kWh, cost, avg/peak rates, and status
• Per-row delete button to remove individual sessions
• Clear All History — removes completed sessions, preserves any active session
• Export CSV — downloads a dated .csv of the full table instantly

🎨 4. Design & Appearance

Make the HUD yours. The display is split into Labels (text) and Lines (the animated flow).

Smart Palette

If you leave the Line Color fields blank, the plugin uses its Smart Logic to automatically colour flows:

The Live Preview

Toggle Live Preview in the admin settings to see your changes in real time. Colour adjustments, module visibility, and label positions all update instantly without saving.

Custom Labels

Set independent colours for the Title (e.g. “SOLAR”), Power (e.g. “4.2 kW”), and Energy (e.g. “12.5 kWh”) text to keep them legible over any background image. The EV extended telemetry fields (Charge Added, Plug Status, Charge Mode, Co Charger Cost) use the Energy colour.

🚀 5. Advanced HUD Mastery

🎯 Drag & Drop Positioning

Enable 🐛 Debug Mode at the bottom of the settings page, then click and drag any entity label or module icon in the Live Preview. Coordinates update automatically when you drop.

Additional HUD Entities

Want to show your pool temperature or greenhouse humidity? Use the Additional HUD Entities section under the Sensors tab. Add unlimited extra sensors with custom labels and place them anywhere on the canvas. Each has its own Visible toggle.

Shortcode Reference

Shortcode	Description
HA_POWERFLOW (shortcode)	The main live power flow widget.
EV_CHARGE_SUMMARY (shortcode)	EV charging session history with charts and stats.
EV_CHARGE_SUMMARY refresh=60 (shortcode)	Same as above but auto-refreshes every 60 seconds whilst a session is active. Any number of seconds is accepted.

Snapshots & Encrypted Backups

Every time you click Save, the plugin creates an automatic Snapshot. To roll back, open the Maintenance tab, pick a previous snapshot, and click Restore.