👋 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%).

🔋 Battery Intelligence Pro

The HUD can predict exactly how long your battery will last or how soon it will be full. To enable this, enter your battery’s Capacity (kWh) and Minimum State of Charge (%) in the Sensors tab.

• Time-to-Empty: Shown when your house is discharging the battery (e.g. 4h 20m remaining).
• Time-to-Full: Shown when solar is charging the battery.

☀️ Solar Forecasting

Link your Solcast or Forecast.Solar entity to see a progress ring around your PV icon. The ring fills as you reach your daily predicted generation, with the total forecast displayed clearly (e.g. 18.5 kWh Forecast).

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. Smart Pricing & Grid Logic New

If you use a smart tariff like Octopus Agile, the HUD can dynamically react to real-time electricity prices.

Price-Driven Flow

By entering your Grid Price Import entity, the grid flow lines will change color automatically:

• 🟢 Green Flow: When the price is below your “Cheap Energy” threshold (e.g. 10p). Great for free or plunge pricing events!
• 🔴 Red Flow: When the price exceeds your “Peak Energy” threshold (e.g. 35p). A visual warning to avoid heavy usage.

Configure these thresholds under Settings → Sensors → Grid Pricing.

🚗 4. EV Charging & User Tracking

The EV module tracks every charging session automatically, calculating costs and efficiency whilst you charge.

Fixed Price Overrides Pro

If your Home Assistant price sensor is unavailable (e.g. returns £0.00 during off-peak hours), you can set a Manual Override in the EV History tab. This ensures your session costs are calculated accurately regardless of sensor availability.

• Peak Price: Used automatically for any charging outside your defined off-peak window.
• Off-Peak Price: Used when charging falls within your window (e.g. 23:30–05:30). Leave empty to use dynamic rates.

The HUD will automatically combine your base override with any Markup Ranges you’ve configured for total transparency.

EV Charge Summary Shortcode

Place this shortcode on any page 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:

EV History Tab (Admin)

• Summary stats — total sessions, energy, and costs recorded.
• User Assignment — link sessions to WordPress accounts via dropdown.
• Export CSV — download a dated .csv for accounting or reimbursement.
• Clear All History — clean up completed sessions while preserving active ones.

🎨 5. Design & Appearance

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

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, Power, and Energy text to keep them legible over any background image. You can also adjust the Font Size (px) for additional HUD sensors individually.

🚀 6. 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 sensor can have a custom font size to fit your layout perfectly.

🛠️ Maintenance & Health

Open the Maintenance tab to monitor your plugin’s performance:

• Latency: How fast Home Assistant is responding.
• Success Rate: Percentage of successful data checks.
• Last Seen: The exact time of the last successful data poll.
• Snapshots: Automatically created before every save—restore any previous configuration with one click.

🗓️ EV Booking Calendar New

Coordinate charging with other users using the simple 7-day booking tool. Any logged-in user can reserve a 30-minute slot.

• Privacy: Regular users only see if a slot is “Booked”.
• Admin View: Administrators see the name of the user who booked each slot and can cancel any session.
• Interactive: Click any available slot to book instantly.
• Estimates: Real-time cost forecasting based on grid price, markup tiers, and the new **Fixed Price Overrides** (supporting Intelligent Octopus Go).

⚡ User Dashboard New

Users can manage their upcoming charges and sync them to their personal devices.

• Dynamic Cards: View date, time, and session costs at a glance.
• iCal Sync: Export any booking to Google, Apple, or Outlook calendars.
• Self-Service: Cancel upcoming sessions directly from the dashboard.
• Automation: Receive instant email confirmations and reminders.

Shortcode Reference

Shortcode	Description
[ha_powerflow]	The main live HUD displaying real-time energy flows using Automated Data.
[ha_powerflow_manual]	This comprehensive technical guide and feature manual.
[ev_charge_summary]	Complete EV charging history with interactive charts, costs, and stats.
[ev_booking_calendar]	7-day interactive reservation calendar for EV charger sharing.
[my_ev_bookings]	Personal user dashboard for managing and syncing upcoming charges.