node-red-contrib-energycalcplus 2.0.0

A professional grade 3D energy integration node that integrates multiple power sources.

npm install node-red-contrib-energycalcplus

energyCalcPlus v2.0.0 PRO: User Documentation (README)

@arcfrankye 22-jul-2026
License: MIT

OVERVIEW

energyCalcPlus is a production-grade HAOS-safe Node-RED node designed to accept live power data from multiple defined sources and calculate distinct accumulated energy outputs. This enables users to easily visualize and monitor their home or premises' energy usage in real-time. The node seamlessly bridges the gap between instantaneous power readings (Watts/Kilowatts) and long-term energy accumulation (kWh) using precise mathematical integration. Designed for complex hybrid energy architectures, the node functions as an aggregator, Riemann sum integrator, and dynamic data router. It thrives in off-grid renewable energy (e.g. Solar), battery backup, and hybrid generator setups.

NEW FEATURES IN v2.0.0 PRO

• Dynamic Port Spawning: The node breathes and expands based on what you own. It guarantees 7 core physical ports for fundamental system math, but dynamically sprouts specific ports for Generators, Non-Essential Loads, JSON Masters, and Databases only if you configure them.
• Energy Export: The node tracks energy export to Grid if enabled. Enabling Energy Exports automatically spawns an Export Port and Export Cost per kWh editor.
• The 10-Source Engine: Map up to 10 independent power sources: Utility Grid, Backup Generator, 4 distinct Renewable Energy Arrays, 2 Battery Banks, and 2 separate Consumption Loads. energyCalcPlus accepts both msg.payload and msg.topic strings (i.e. MQTT topics, HA entities, HTTP API calls, Modbus TCP and even Manual Inject Node), A mixture of these input standards accross Sources is also supported.
• Hybrid "Off-Grid" Bypass: A simple UI toggle allows you to drop the utility grid from the math engine entirely. Prevents disconnected utility meters from throwing false system faults or ruining system health stats.
• Deadband Ghost Filter: Built-in adjustable deadband filters out electromagnetic "ghost" noise on physically disconnected wires (e.g., 20W readings on a tripped breaker).
• Live RAM Data Editor: A beautiful 3D Neumorphic interface allows you to query the live Node.js RAM directly from the Node-RED canvas, surgically amend any specific energy bucket (e.g., fixing a faulty meter spike), and overwrite the hard drive file.
• HAOS-Safe Persistence: Safely caches state to a user-defined .json directory. Automatically handles proper Timezone-aware Midnight Rollovers to build an internal history log.
• Archive Mode (selectable); Features Native InfluxDB Protocol formatting, pure CSV strings, or perfectly rounded standard JSON objects.
• Native InfluxDB Protocol: Forget complex function nodes. The node natively complies with the official InfluxDB node protocol, feeding pure Measurements, Tags, and Fields via an optional Database port.
• Speedometers vs. Odometers Output: Every port on the node outputs a combined object containing BOTH the instantaneous live power (msg.power_live_kW) and the accumulated energy (msg.payload). You can wire a single port into two different UI gauges simultaneously. E.g.,

{
  "payload": 142.55,       // The Odometer: 142.55 kWh accumulated today
  "power_live_kW": 2.4,    // The Speedometer: 2.4 kW being generated right now
  "topic": "SolarGen"
}

#### 🟢 4-Tier Node Canvas Status
The node intelligently displays its health directly on your canvas:
* 🔴 **Offline (0/X Active):** No valid data received from *any* configured sensor within the `Max Age` window.
* 🟡 **Degraded (2/X Active):** Some sensors are live, but one or more have flatlined.
* 🔵 **Live (Off-Grid) (X/X Active):** Node is fully healthy, but you have manually toggled "Isolate Grid" (indicating you have gone or are in Off-Grid Mode), the Utility inputs are thus mathematically ignored.
* 🟢 **Live (Grid-Mode) (X/X Active):** Flawless system operation.

#### 📊 The Historical Query System 
Historical data tracking utilizes a **Query System**. The node automatically builds a history log internally at midnight. If your dashboard requires Weekly, Monthly, or Yearly aggregations, you can fetch them instantly without bloating your main data stream.
* Use a standard Node-RED **Inject** node.
* Set `msg.topic` to one of the following: `"getWeekly"`, `"getMonthly"`, or `"getYearly"`.
* Wire it into the `energyCalcPlus` input.
* The node will instantly emit a highly formatted, 2-decimal JSON report out of **Port 1**, neatly tagged with your requested topic (e.g. `getMonthly_Report`).

#### HOW IT WORKS
**The Canvas Centipede**: The node utilizes a multi-port architecture for zero-configuration wiring. You physically wire your raw data streams into the input port on the left, and the node pushes calculated energy out of the categorized and labelled output ports on the right.
**Hub-and-Spoke Rollover**: Live power updates strictly increment the "Daily" total. At exactly midnight (based on your selected timezone), the Daily total is perfectly distributed to the Weekly, Monthly, and Yearly buckets to prevent double-counting.
**Unit Normalization**: You can feed the node a mix of Watts and Kilowatts. Simply select the input unit in the Editor UI, and the node will automatically normalize everything internally.
**Fault Tolerance**: If a sensor goes offline, the node uses a maxAge parameter to drop stale data, treating it as 0 kW to prevent phantom energy from accumulating.
**THE OUTPUT PORTS** (Right Side):The node actively calculates and outputs accumulated energy (kWh) across 8 distinct ports.
* Utility Energy
* Renewable Energy: The integrated sum of all active renewable inputs.
* Battery Charging
* Battery Discharging
* Essential Load
* Lost Energy: A mathematical residual calculated by subtracting total energy consumed/stored from total energy generated. Note: For this to be accurate, every physical load in your system must be metered.
* Total Energy
* Comprehensive JSON: Outputs the complete system status and all energy metrics as a single JSON object for easy dashboarding or database routing.

#### **DATA ARCHIVING & PERSISTENCE**
State Saving: energyCalcPlus utilizes atomic file writing to save snapshots of your energy totals to your local disk. This ensures no data is lost during Node-RED restarts or host reboots.

#### USAGE & CONFIGURATION
The Core 7 Constants (Always Present): 1. Utility Import; 2. Renewables Total (Aggregates all 4 inputs); 3. Battery Charge; 4. Battery Discharge; 5. Essential Load; 6. Total Load (Essential + Non-Essential); and 7. Lost Energy (The mathematical efficiency balance of the entire house).
**Opt-In Complexity (Dynamic Ports):**
To keep your canvas clean, the following ports only spawn if you configure them in the Editor:
* Generator: Spawns if a topic is mapped to the Generator input.
* Non-Essential Load: Spawns if a topic is mapped to the Non-Essential input.
* Master JSON: Spawns if checked in the Advanced tab. Delivers all data in a single unified JSON object.
* Archive Payload: Spawns if enabled in the Advanced tab. Select between pure JSON, CSV Strings, or InfluxDB formats for direct database ingestion.
* Grid Export: Spawns if enabled in the Advanced tab. Dedicated solely to negative utility flows for easy automations (e.g. "If Export > 2kW, run water heater").This will also spawn a Export Cost editor for cost tracking.

#### **INSTALLATION & SAFETY**
This node features HAOS (Home Assistant OS) safe paths and Atomic Writes. It dynamically locates your Node-RED user directory and ensures that even during unexpected power failures, your accumulated energy states are not corrupted during disk writes.

#### GETTING STARTED
1. Drag the energyCalcPlus node onto your canvas.
2. Wire your live power data nodes (MQTT, Modbus, Home Assistant, etc.) into the left-hand input port.
3. Double-click the node to open the 3D Editor UI.
4. Set your **Timezone** (if automatically selected timezone is incorrect), click on the **Timezone** label to edit if needed. Define your Input Units (W or kW) and other variables etc.
5. Enter your msg.payload for your live power sensors into the sources editor. Any unconfigured source will be ignored by the node. You can also configure the Source's label by clicking on them. Adjust or configure your **Advanced** settings as needed.
6. Click Done and Deploy. The node is now live and calculating energy. To correct any bucket values or enter legacy data, go to **Editor** tab, click on "Fetch Live Data" and enter corrected values into the desired buckets. This will overwrite the node RAM and snapshot.