HA PowerFlow

Plugin Documentation

Real-time Home Assistant power-flow dashboard for WordPress

Version 2.1

Christopher Wilmot — chriswilmot.co.uk

1. Overview
2. Requirements
3. Installation
4. Connecting to Home Assistant
5. Adding the Dashboard to a Page
6. Changing the Background Image
7. Using the Click-to-Coordinate Tool
8. Positioning Text Labels
9. Customising Flow Paths
10. Changing Colours
11. Configuration Backups
12. Entity Reference
13. Road Map
14. Change Log

1. Overview

HA PowerFlow is a WordPress plugin that displays a real-time animated power-flow diagram on your website, fed with live data from your Home Assistant installation. Energy values — solar generation, grid import/export, home consumption, battery charging/discharging, and EV charging — are shown as moving dots along SVG paths overlaid on a custom background image.

Key features:

Live data refreshed every 5 seconds from Home Assistant
Animated flow dots whose speed reflects power levels
Fully configurable background image, colours, label positions and flow paths
Your Home Assistant token is encrypted and never exposed to the browser
Configuration automatically saved to a YAML file on every save
Optional Solar, Battery and EV sections can be toggled on or off

2. Requirements

Setting	Description
WordPress	5.0 or later with Administrator access
PHP	7.4 or later with the OpenSSL extension enabled (for token encryption)
Home Assistant	Any recent version with a Long-Lived Access Token
HTTPS	Your WordPress site must be served over HTTPS. Home Assistant must also be accessible over HTTPS from your WordPress server.
PHP OpenSSL	Required for AES token encryption. Available on virtually all modern hosting. Check with your host if unsure.

3. Installation

Download the latest version.
Follow these steps to install HA PowerFlow on your WordPress site.

3.1 Upload and Activate

Log in to your WordPress admin dashboard.
Go to Plugins → Add New Plugin.
Click Upload Plugin and select the ha-powerflow.zip file.
Click Install Now, then Activate Plugin.

Note: After activation the plugin automatically creates two folders: wp-content/uploads/ha-powerflow/ (for background images) and wp-content/uploads/ha-powerflow/config/ (for configuration backups). You do not need to create these manually.

3.2 Verify Installation

Once activated, a new menu item called HA PowerFlow will appear in the left-hand WordPress admin sidebar. Click it to open the settings page.

4. Connecting to Home Assistant

The plugin communicates with Home Assistant from your WordPress server — not from the visitor’s browser. This means your Home Assistant token is never exposed in the page source.

4.1 Get a Long-Lived Access Token

In Home Assistant, click your profile icon (bottom left).
Click the security tab, scroll to the very bottom of the page to the Long-Lived Access Tokens section.
Click Create Token, give it a name (e.g. “WordPress PowerFlow”), and click OK.
Copy the token immediately — it will not be shown again.

Important: Store the token somewhere safe before closing the dialog. If you lose it you will need to delete it and create a new one.

4.2 Configure the Connection in WordPress

Go to HA PowerFlow in the WordPress admin sidebar.
In the Connection panel, enter your Home Assistant URL in the HA URL field. Include the port number if required.

Example: https://homeassistant.local:8123 https://ha.yourdomain.com

Paste your Long-Lived Access Token into the HA Token field. The field displays as a password field so the value is hidden. The token is encrypted with AES-256 before being stored.
If your Home Assistant uses a self-signed SSL certificate (common for local installs), untick SSL Verify. Leave it ticked for any publicly trusted certificate.
Click Save Settings.

4.3 Add Your WordPress URL to Home Assistant

Because the plugin makes server-to-server requests, Home Assistant does not need CORS configured. However, if you have a strict firewall or reverse proxy in front of Home Assistant, you may need to allow traffic from your WordPress server’s IP address.

If your Home Assistant is configured with an explicit allowed_hosts or cors_allowed_origins list, add your WordPress domain to configuration.yaml:

http:
cors_allowed_origins:
– https://your-wordpress-site.com

Replace your-wordpress-site.com with your actual WordPress domain. After editing configuration.yaml, restart Home Assistant for the change to take effect.

Note: This step is only required if Home Assistant returns a 403 Forbidden error when the plugin tries to fetch entity data. Most installations will not need it because the request comes from your server, not a browser.

5. Adding the Dashboard to a Page

The plugin works via a WordPress shortcode. You can place it on any page or post.

5.1 Add the Shortcode

Create or edit a WordPress page.
In the block editor, add a Shortcode block (search for “Shortcode” in the block inserter).
Type the shortcode into the block to produce the output below:

Publish or update the page.
Visit the page on the front end — the dashboard will appear, sized to the full width of the content area up to a maximum of 1000px.

Tip: You can place the shortcode in a full-width page template or inside a Gutenberg Group block set to full width for best visual results.

6. Changing the Background Image

The dashboard overlays flow paths and data labels on top of a background image. The default image ships with the plugin, but you can replace it with any PNG image — typically a diagram of your energy system.

6.1 Image Requirements

Format: PNG (recommended for transparency support)
Dimensions: the SVG canvas is 1000 × 750 pixels. Your image should match this aspect ratio for best results.
The image is scaled to fill the canvas — exact pixel dimensions are not critical.

6.2 Uploading a New Image

Go to HA PowerFlow → Settings.
In the Connection panel, locate the Background Image section.
Click Select Image. The WordPress media library will open.
Upload a new image or select an existing one from the library, then click Use this image.
The image is copied into wp-content/uploads/ha-powerflow/ and the URL is saved automatically.
A preview of the selected image appears below the field.
Click Save Settings to apply.

Note: The image is copied to the plugin’s own upload folder so it is not affected if the original media library entry is deleted.

7. Using the Click-to-Coordinate Tool

The plugin includes a built-in tool to help you find the correct x/y coordinates for positioning text labels and defining flow paths. When enabled, clicking anywhere on the dashboard reports the exact SVG coordinates to the browser console.

7.1 Enable the Tool

Go to HA PowerFlow → Settings.
Scroll down to the Developer Tools card.
Tick Enable click-to-coordinate tool.
Click Save Settings.

7.2 Using the Tool

Navigate to the page on your website that contains the shortcode.
Open your browser’s developer tools. In Chrome or Edge press F12, or right-click the page and choose Inspect. Switch to the Console tab.
Click anywhere on the dashboard image. Two things happen immediately:

A red dot appears at the exact point you clicked, with the coordinates printed next to it in red text.
A styled log entry appears in the console: [HA PowerFlow] Clicked at x: 740, y: 210

Use these coordinates to fill in the X and Y position fields in the settings for each text label (see Section 8).
Double-click anywhere on the diagram to clear all the red marker dots.
When you have finished positioning labels, return to Settings, untick the tool, and click Save. The crosshair cursor and click listener are completely removed.

Important: Leave the tool disabled when your site is live. While it does not expose any sensitive information, it places red markers when visitors click the diagram and changes the cursor to a crosshair, which looks unintentional.

7.3 Understanding SVG Coordinates

The dashboard uses an SVG canvas of 1000 × 750 units. The origin (0, 0) is the top-left corner. X increases to the right; Y increases downward. These are not pixel coordinates — they remain consistent regardless of how large or small the dashboard is displayed on screen.

8. Positioning Text Labels

Each entity (Grid Power, PV Power, Battery SOC, etc.) has a text label that is drawn directly onto the SVG. You can control the x position, y position, and rotation of each label independently.

8.1 Position Fields

Each entity in the settings table has three position fields alongside its entity ID:

Setting	Description
Rot	Rotation in degrees. Positive values rotate clockwise; negative values rotate anti-clockwise. 0 means horizontal. Use small values like −15 to −15 to align labels with diagonal lines on the diagram.
X	Horizontal position of the label’s left edge on the SVG canvas (0–1000). Use the click-to-coordinate tool to find this value.
Y	Vertical position of the label’s baseline on the SVG canvas (0–750). Use the click-to-coordinate tool to find this value.

8.2 Workflow for Positioning a Label

Enable the click-to-coordinate tool (see Section 7.1).
Go to your dashboard page and click approximately where you want the label to appear.
Note the x and y values from the console or the red marker.
Return to HA PowerFlow → Settings and enter those values into the X and Y fields for that entity.
If the label needs to follow a diagonal line, add a small Rot value. Start with the angle of the line (e.g. −9 for a line running slightly upward to the right).
Click Save Settings and check the result on the front end.
Repeat until all labels are positioned correctly, then disable the click-to-coordinate tool.

Tip: The rotation pivot point is the label’s own x/y position. If a rotated label appears in the wrong place, adjust X and Y first, then add rotation.

9. Customising Flow Paths

Flow paths are the lines along which the animated dots travel. Each flow (Grid, Load, PV, Battery, EV) has a Forward path (energy flowing in the normal direction) and a Reverse path (energy flowing back — e.g. exporting to the grid).

The paths are defined using standard SVG path notation. You do not need to know SVG in depth — the coordinate tool makes it straightforward.

9.1 Default Paths

If you leave the path fields blank, the plugin uses its built-in defaults which are matched to the default background image. Only change these if you are using a custom background image.

Setting	Description
Grid Forward	M 787 366 L 805 375 L 633 439
Grid Reverse	M 633 439 L 805 375 L 787 366
Load Forward	M 590 427 L 673 396 L 612 369
Load Reverse	M 590 427 L 673 396 L 612 369
PV Forward	M 331 417 L 510 486
PV Reverse	M 510 486 L 331 417
Battery Forward	M 532 500 L 364 563
Battery Reverse	M 364 563 L 532 500
EV Forward	M 618 497 L 713 532 L 786 499
EV Reverse	M 786 499 L 713 532 L 618 497

9.2 Path Syntax

Paths use a subset of SVG path commands:

Setting	Description
M x y	Move to the starting point. Every path must start with M.
L x y	Draw a straight line to this point.
C x1 y1 x2 y2 x y	Draw a cubic Bézier curve (for smooth curves).

Example — a simple two-point straight line:

M 331 417 L 510 486

Example — a path with a midpoint (three-point line):

M 787 366 L 805 375 L 633 439

9.3 Workflow for Custom Paths

Enable the click-to-coordinate tool (see Section 7).
Click on your background image at the start of where you want the flow line to begin. Note the coordinates.
Click at any intermediate waypoints. Note the coordinates.
Click at the end of the flow line. Note the coordinates.
Build the path string. For a start point of (331, 417) and end point of (510, 486): M 331 417 L 510 486
Paste this into the Forward path field for the relevant flow.
For the Reverse path, simply list the same points in reverse order:

M 510 486 L 331 417

Click Save Settings and verify the dots travel along the correct line.

10. Changing Colours

The Colour Settings panel lets you change the three main colours used across the entire dashboard.

10.1 Available Colour Settings

Setting	Description
Text Colour	The fill colour of all data label text (entity names and values). Default: #5EC766 (green).
Line Colour	The stroke colour of all flow path lines. Default: #5EC766 (green).
Dot Colour	The fill colour of the animated dots that travel along flow paths. Default: #5EC766 (green).

10.2 Changing a Colour

Go to HA PowerFlow → Settings.
Scroll down to the Colour Settings panel.
Click the colour swatch next to the setting you want to change. A colour picker will open.
Choose your colour. The hex value updates automatically.
To revert to the default green (#5EC766), click the Reset button next to the swatch.
Click Save Settings.

Tip: All three colours default to the same green (#5EC766). For a more distinct look, consider using a lighter colour for lines and a brighter colour for dots so the animation stands out from the static lines.

11. Configuration Backups

Every time you press Save Settings, the plugin automatically writes a complete snapshot of your current configuration to a YAML file. This happens in the background — you do not need to do anything to trigger it.

11.1 Where Backups Are Stored

Backup files are saved to:

wp-content/uploads/ha-powerflow/config/

Each file is named using the date and time of the save:

260222-143000-config.yaml (format: YYMMDD-hhmmss-config.yaml)

You can access this folder via FTP, SFTP, or your hosting control panel’s file manager. The files are plain text and can be opened in any text editor.

11.2 What Is Saved

The backup file contains every plugin setting in a structured YAML format, including:

Plugin version and export timestamp
Home Assistant URL and token (the token is AES-256 encrypted — see note below)
Feature toggles (Solar, Battery, EV)
Background image URL
All three colour settings
All flow path overrides (forward and reverse for each flow)
All entity IDs with their label position (X, Y, rotation)
SSL verify preference

Security note: The HA token is encrypted using AES-256-CBC before being written to the YAML file. It is stored as ENC:<encrypted-value> rather than as plain text. The encryption key is derived from your WordPress site’s unique AUTH_KEY constant, so the token can only be decrypted by the same WordPress installation that created the file. If you copy the YAML to a different site, you will need to re-enter the token.

11.3 Backup Retention

The plugin keeps the 50 most recent backup files. When a new file is written and there are more than 50 files in the folder, the oldest files are automatically deleted. This prevents the folder from growing indefinitely.

If you want to keep a particular backup permanently, copy the file out of the config folder to a safe location before it is pruned.

11.4 Example Backup File

# HA PowerFlow configuration snapshot
# Generated by HA PowerFlow v2.1.0
# Import: Settings > HA PowerFlow > Import Config
#
# The ha_token value is AES-256-CBC encrypted using this
# site’s AUTH_KEY. It will only decrypt correctly on the
# same WordPress installation that created it.

meta:
plugin_version: “2.1.0”
exported_at: “2026-02-22 15:22:16”
site_url: “https://chriswilmot.co.uk”

connection:
ha_url: “https://ha.wilmot.co”
ha_token: “”
ssl_verify: true

features:
enable_solar: true
enable_battery: true
enable_ev: true

appearance:
image_url: “https://chriswilmot.co.uk/wp-content/uploads/ha-powerflow/ha-powerflow-life-like.png”
text_colour: “#5ec766”
line_colour: “#5ec766”
dot_colour: “#5ec766”

flow_paths:
grid:
forward: “M 778 448 L 377 509”
reverse: “M 377 509 L 778 448”
load:
forward: “M 377 509 L 601 476 L 502 467”
reverse: “M 502 467 L 601 476 L 377 509”
pv:
forward: “M 162 460 L 175 485 L 316 517”
reverse: “M 316 517 L 175 485 L 162 460”
battery:
forward: “M 309 547 L 167 576”
reverse: “M 167 576 L 309 547”
ev:
forward: “M 400 553 L 723 641 L 721 599”
reverse: “M 721 599 L 723 641 L 400 553”

entities:
grid_power:
entity_id: “sensor.myenergi_59_manor_road_power_grid”
rot: 0
x_pos: 728
y_pos: 333
grid_energy_in:
entity_id: “sensor.myenergi_59_manor_road_grid_import_today”
rot: 0
x_pos: 747
y_pos: 60
grid_energy_out:
entity_id: “sensor.myenergi_59_manor_road_grid_export_today”
rot: 0
x_pos: 747
y_pos: 80
load_power:
entity_id: “sensor.current_load_power”
rot: 8
x_pos: 390
y_pos: 286
load_energy:
entity_id: “sensor.deye_sunsynk_sol_ark_load_energy”
rot: 0
x_pos: 363
y_pos: 60
pv_power:
entity_id: “sensor.deye_sunsynk_sol_ark_pv_power”
rot: 0
x_pos: 78
y_pos: 403
pv_energy:
entity_id: “sensor.deye_sunsynk_sol_ark_pv_energy”
rot: 0
x_pos: 15
y_pos: 60
battery_power:
entity_id: “sensor.deye_sunsynk_sol_ark_battery_power”
rot: 0
x_pos: 70
y_pos: 625
battery_energy_in:
entity_id: “sensor.deye_sunsynk_sol_ark_battery_energy_in”
rot: 0
x_pos: 15
y_pos: 80
battery_energy_out:
entity_id: “sensor.deye_sunsynk_sol_ark_battery_energy_out”
rot: 0
x_pos: 15
y_pos: 100
battery_soc:
entity_id: “sensor.deye_sunsynk_sol_ark_battery_state_of_charge”
rot: 0
x_pos: 70
y_pos: 645
ev_power:
entity_id: “sensor.myenergi_59_manor_road_power_charging”
rot: 0
x_pos: 770
y_pos: 650
ev_soc:
entity_id: “sensor.lsjw74091pz231814_soc”
rot: 0
x_pos: 770
y_pos: 670

preferences:
delete_uploads: false

12. Entity Reference

This table lists every entity the plugin can display, the label shown on the dashboard, and the default text position. All entities expect a Home Assistant sensor entity ID in the format domain.entity_name.

12.1 Mandatory Entities (always required)

Setting Field	Label Shown	Expected Unit	Default X	Default Y	Default Rot	Typical Entity
grid_power	Grid	W	740	210	0	sensor.grid_power
grid_energy_in	Grid In	kWh	740	70	0	sensor.grid_energy_in
grid_energy_out	Grid Out	kWh	740	90	0	sensor.grid_energy_out
load_power	Load	W	360	180	-6	sensor.load_power
load_energy	Load Energy	kWh	360	70	0	sensor.load_energy

12.2 Solar Entities (require Enable Solar toggle)

Setting Field	Label Shown	Expected Unit	Default X	Default Y	Default Rot	Typical Entity
pv_power	PV	W	49	312	-9	sensor.pv_power
pv_energy	PV Energy	kWh	14	70	0	sensor.pv_energy

12.3 Battery Entities (require Enable Battery toggle)

Setting Field	Label Shown	Expected Unit	Default X	Default Y	Default Rot	Typical Entity
battery_power	Battery	W	360	665	0	sensor.battery_power
battery_energy_in	Battery In	kWh	14	685	0	sensor.battery_energy_in
battery_energy_out	Battery Out	kWh	14	665	0	sensor.battery_energy_out
battery_soc	Battery SOC	%	360	685	0	sensor.battery_soc

12.4 EV Entities (require Enable EV toggle)

Setting Field	Label Shown	Expected Unit	Default X	Default Y	Default Rot	Typical Entity
ev_power	EV	W	750	460	15	sensor.ev_power
ev_soc	SOC	%	750	480	15	sensor.ev_soc

13. Road Map

13.1 Allow the upload of the config file to be distributed with the image.

14. Change Log

Version 2.1 is the first official release

HA PowerFlow v2.1 — chriswilmot.co.uk

Contents