EnergyMeterPlus Node Version 2.0.0 - Stable Release

@ arcfrankye 14-jul-26

OVERVIEW

EnergyMeterPlus node converts instantaneous power readings into accumulated energy totals and cost, with robust baseline handling and safer editor UX. EnergyMeterPlus integrates power over time, applies one-time baseline offsets, prevents accidental double application, handles rollovers, persists state, and writes snapshots to disk.

Version numbers indicate the quality of the build. Main numbers are used for stable and tested builds; sub numbers are used for test editions still undergoing debugging. Use EnergyMeterPlus at your own risk. This is a finalized stable release, published as version 2.0.0 due to the editor, core maths and rollover changes which behaves remarkable differently from the version 1.x.x.series

NEW FEATURES IN v2.0.0

• Complete refresh of the Editor UI/UX for easier use and better productivity.
• 3D coloured buttons and notification badges with sound cues to give clear visual and audio feedbacks to baseline editor actions.
• File Path editor with Change Directory button to specify desired folder. This functionality supports Windows, Linux and Home Assistant (HAOS) environments. Depending on operating (sand boxing) environment restrictions, Change Directory might default to a "manual entry" dialog box.
• Hub-and-Spoke Rollover Architecture: Replaced the flawed hierarchical rollover model (which suffered from weeks spanning across months double counts or missing data) with a parallel distribution system.
• Live power ONLY updates the Daily Hub. At exactly midnight, the Daily Hub simultaneously pushes its total to the Weekly, Monthly, and Yearly buckets (the Spokes) archives, whilst outputting in real-time accuracy across all segments at all time. The real time output updates enables realtime dashboard view accuracy.
• Independent Boundary Resets: Higher-level segments no longer pour into one another. Instead, they empty themselves strictly on their own calendar boundaries, permanently eliminating double-counting and dropped days.
• Separate Bucket Baseline Architecture: Live accumulated energy and user-defined baselines are stored in separate memory buckets.
• Immediate Baseline Updates: Changes to baselines in the editor are reflected immediately upon the next message. No "delta" calculations are required, eliminating complex state management bugs.
• Auto-Burnout Baselines: Baselines are automatically cleared upon the designated rollover period, ensuring offsets don't persist indefinitely across node restart cycles.
• Optional Baseline Reset on Rollover functionality ensure you can reset Baseline Offsets edits automatically on Rollover events to prevent double counting.
• Safe Lifecycle: All editor interactions now respect the standard Node-RED "Deploy" cycle.
• Background Health: Added a 60-second heartbeat timer for automatic retry of failed InfluxDB archives and stale-status detection.
• Automatic Time Zone detection ensures synchronization of operations with local time. This feature is also editable by Clicking on the Time Zone label.

HOW IT WORKS

1. Buckets: Total = Accumulated + Baseline.
2. Persistence: The node maintains a snapshot of both buckets to disk to survive reboots.
3. Application: When you click "Apply", the baseline values are locked.
4. Distribution & Rollover : Every midnight, the node calculates the Daily Total (Live + Baseline) and distributes it in parallel to the Weekly, Monthly, and Yearly buckets. It then checks the calendar to see if a period boundary was crossed (e.g., Sunday, end of month, end of year). If a boundary is met, that specific bucket is archived and reset to zero independently of the others.
5. Enable Auto-Burnout Baselines by selecting Reset offsets Globally on Rollover (automatically selects all the Reset on Rollover checkboxes), this activates the resetBaseline function or; alternatively, you can choose which Offsets values you want to keep by unchecking its corresponding Reset on Rollover checkbox.

KEY FEATURES

• Time integration of power (W or kW) into energy (kWh).
• Daily, weekly, monthly, yearly energy totals.
• Cost calculations using a configurable unit cost and currency symbol.
• One-time baseline offsets: editor lets you apply offsets once; runtime applies only the delta and stores what was applied.
• Editor UX improvements: inputs show saved values, an Apply button greys inputs and marks them applied, and a Reset button re-enables inputs.
• Safe deploy behavior: editor changes are saved to node config; runtime applies offsets on Deploy only when flagged applied.
• Runtime messages for immediate control: applyBaseline and resetEditorApplied.
• Rollover handling for day, week, month, year, with yearly archiving.
• Persistence: counters and timestamps in Node-RED context; snapshots written to JSON file; directories auto-created.
• Defensive parsing and logging: numeric guards, error handling, and clear log messages for deploy and runtime actions.
• Configurable Weekly Rollover Startday: Weekly rollover start day is now configurable. Default is Monday, but users can now choose which weekday starts the week. Choose Sunday - Saturday
• Multiple Archiving Options: Selectable archive options now support JSON, CSV, InfluxDB or None.
• Customizable InfluxDB Archiving: Node supports Periodic (batch writes to InfluxDB at configured intervals) or Rollover (write to InfluxDB only owhen period boundaries are crossed) Please EnergyMeterPlus supports disk buffering for failsafe writing operations but does not support continous writes to InfluxDB by design.
• Changed the rollover logic to heirarchical daily only model.Only daily totals are live. Weekly/Monthly/Yearly values are now always sums of completed lower level periods. (This feature has been removed and replaced with Hub and Spokes architecture in version 2.0.0)
• Ordered rollups: rollovers run in the sequence day → week → month → year, so higher-level totals are always built from completed lower-level totals and never double-count the same energy.
• Added support for "Custom" user defined currency.

QUICK START

1. Install / Update
   Add or update the EnergyMeterPlus node in your Node‑RED environment.

2. Configure storage
   Set the base environment variable to define the allowed base directory for file storage.

   • Windows: C:\node_red\data
   • Linux: /var/lib/node_red
   • HAOS: /config

3. Use the editor

   • File Path is greyed out until you press Change directory.
   • Select or manually enter a folder, then set a file name (default: solargen_data.json).
   • Apply or Reset baselines as needed.
   • Click Done and Deploy to persist changes.

USAGE NOTES

• Baseline handling

  • Apply button sets applied = true and shows the Applied badge.
  • Reset button clears applied, shows Reset badge briefly, and marks baseline for reapply on next Deploy.

• File storage

  • Configure base environment variable to set the allowed base directory.
  • File Path browsing is restricted to this base; symlink escapes and .. are denied.

• Editor UX

  • Buttons provide tactile feedback and accessibility support.

DEPLOYMENT

1. Install/update the node in your Node‑RED environment.
2. Set base directory in your runtime environment.
3. Open the node editor:
   • Use Change directory to select a folder.
   • Enter a file name (default: solargen_data.json).
   • Apply or Reset baselines as needed.
4. Click Done and Deploy to persist changes made in the Editor.
5. Wire in live power reading and OUTPUT nodes as required

CONFIGURATION OPTIONS

Unit Cost:

• Cost per kWh (e.g., 0.15 for $0.15/kWh).

Currency:

• Choose USD, EUR, or NGN. The node uses a symbol for display, no currency conversion. If "Custom" is selected, user can define currency with any 3 letters. Letters will be automatically normalised to uppercase.

File Path:

• Path to write snapshots (default: /config/node_red/solargen_data.json). Directories are created automatically.

Input Unit:

• "W" (Watts) or "kW" (kilowatts). If using Watts, the node converts to kW internally.

Baseline Offsets

• Baseline Daily, Weekly, Monthly, Yearly: enter offsets in appropriate segments in the editor.

Apply Workflow:

• Click Apply in the editor to mark offsets as applied (inputs grey out). Click Done, then Deploy to persist and have the runtime apply the offsets once.

Reset:

• Click Reset in the editor to re-enable inputs; on the next Deploy, the runtime will allow reapply. You can also send a runtime reset message to clear memory immediately.

Runtime Messages:

• Immediate apply without Deploy. Send a message to the node: json { "topic": "applyBaseline", "payload": { "daily": 2, "weekly": 0, "monthly": 0, "yearly": 0 } }. This applies the provided offsets immediately (additive).

Clear Remembered Editor Application:

• Send a message to the node: json { "topic": "resetEditorApplied" }. This clears the runtime lastAppliedEditor so the same editor values can be applied again on the next Deploy.

Rollover Start Day:

• Choose which day resets the weekly totals. Choose from Sunday to Saturday.

Archive Mode:

• Choose JSON, CSV, InfluxDB, or NONE. If InfluxDB is selected, you will be requested to enter Login details for the database and Choose archiving strategy, "Periodic" or "Rollover"" are available.

OUTPUT PAYLOAD

The node outputs a msg.payload object with rounded values (two decimals):

"energyDaily": 4.53,

"energyWeekly": 32.18,

"energyMonthly": 128.74,

"energyYearly": 1024.56,

"daily_cost": 0.68,

"weekly_cost": 4.83,

"monthly_cost": 19.31,

"yearly_cost": 153.68,

"currency": "?"

Note: field names are energyDaily, energyWeekly, energyMonthly, energyYearly in the runtime implementation.

ROLLOVER RULES (Hub-and-Spoke)

• Daily (The Hub): Distributes its accumulated totals to all other segments at exactly midnight, archives itself, and immediately resets to zero.
• Weekly (Spoke): Accumulates daily midnight updates. Archives and resets to zero when the user-configured rollover start day is reached.
• Monthly (Spoke): Accumulates daily midnight updates. Archives and resets to zero on the 1st day of a new month.
• Yearly (Spoke): Accumulates daily midnight updates. Archives to a dedicated yearly_archive.json file and resets to zero on January 1st.

PERSISTENCE & SAFETY

• Context storage: baseline, accumulated totals, last check timestamp, and lastAppliedEditor are stored in Node-RED context.
• File snapshots: written to the configured JSON file on each output.
• Robustness: numeric parsing guards, try/catch around file I/O, and logs for deploy/runtime actions to help debugging.

EDITOR UX BEHAVIOUR

• Inputs show saved values when opening the editor, so you can see what was last applied.
• Apply button greys inputs and sets an applied flag; click **Done** then **Deploy** to have runtime apply offsets once.
• Reset button re-enables inputs and clears the applied flag; **Deploy** will then allow reapply.
• One-time semantics: runtime computes delta = editor - lastAppliedEditor and applies only non-zero delta. Repeated **Deploy**s with identical editor values do not reapply offsets.

TROUBLESHOOTING TIPS

• If baseline edits do not mark the flow dirty, ensure the editor oneditsave saves values to this.baseline and this.applied.
• Use Full Deploy when testing editor/runtime changes to ensure constructors run.
• Check Node-RED logs for messages like Editor baseline applied on deploy (delta) or Comms applyBaseline: no delta to apply.
• If you need immediate effect without Deploy, use the applyBaseline inject message shown above.

EXAMPLES

• Apply 5 kWh daily offset via editor: enter 5 in Baseline Daily, click Apply, Done, then Deploy. Runtime will add the delta once.
• Immediate runtime apply: inject { topic: "applyBaseline", payload: { "daily": 2 } } to add 2 kWh immediately.

CHANGELOG

v2.0.0

• Comprehensive Editor UX redesign
• Added Applied/Reset badges with auto‑hide.
• Introduced 3D Apply/Reset buttons with tactile and audio cues and mute option.
• Implemented Change Directory button with secure browsing.
• Improved editor layout (inline labels, consistent widths).
• Hardened path validation for Windows/Linux/HAOS Node Red environments.

v1.1.5

• Added configurable rollover start day.
• Added archiving options (JSON, CSV, InfluxDB, NONE)
• Fixed Baseline editor not accepting decimals bug
• General Polish of the Editor

v1.1.1

• fixed bug whereby cost was not outputting

v1.1.0

• Changed rollover logic to daily hierarchical. Segments no longer continuousl update, except daily. Other segments update on appropriate rollovers. This makes it easier to understand the energy total and graphically represent them as needed.
• Added support for custom currency. Let user input any 3 letters to represent currency.

v1.0.1

• Major UI and runtime overhaul. Editor shows saved values, adds Apply and Reset controls, greys inputs after Apply, and persists an applied flag. Runtime applies editor offsets exactly once using delta logic and stores lastAppliedEditor. Added safer rollover and logging.

v0.2.5

• Fixed internal counter bug.

v0.2.4

• Fixed incremental counter update bug. Added payload validation. Baselines captured once and survive UI clearing.

v0.2.3

• Fixed baseline visibility bug after applying. Fixed rollover double-counting. Baselines are applied once and stored in context. Counters updated continuously.

v0.0.3

• Initial release: integrates power to energy, cost calc, rollovers, persistence, and basic baseline support.

Quick Start Demo Flow

To help you get started with EnergyMeterPlus, here is a small demo flow you can import directly into Node RED. It shows how to use the new Apply and Reset features, as well as runtime messages.

Steps Open Node RED.

Click the menu (top right) → Import → Clipboard.

Paste the JSON below into the box.

Click Import.

You should see two Inject nodes wired into EnergyMeterPlus and a "Energy Output" debug node.

Click the Inject buttons to test Apply/Reset and watch the payloads in the Debug sidebar.

Demo Flow JSON json [ { "id": "inject-apply", "type": "inject", "z": "flow1", "name": "Apply Baseline (2 kWh daily)", "props": [ { "p": "payload" }, { "p": "topic", "vt": "str" } ], "payload": "{"daily":2,"weekly":0,"monthly":0,"yearly":0}", "payloadType": "json", "topic": "applyBaseline", "x": 180, "y": 120, "wires": [["energyMeterPlus"]] }, { "id": "inject-reset", "type": "inject", "z": "flow1", "name": "Reset Editor Applied", "props": [ { "p": "topic", "vt": "str" } ], "topic": "resetEditorApplied", "x": 170, "y": 180, "wires": [["energyMeterPlus"]] }, { "id": "energyMeterPlus", "type": "energyMeterPlus", "z": "flow1", "name": "EnergyMeterPlus", "unitCost": "0.15", "currency": "USD", "filePath": "/config/node_red/solargen_data.json", "inputUnit": "W", "baselineDaily": "0", "baselineWeekly": "0", "baselineMonthly": "0", "baselineYearly": "0", "applied": false, "x": 420, "y": 150, "wires": [["debug-output"]] }, { "id": "debug-output", "type": "debug", "z": "flow1", "name": "Energy Output", "active": true, "tosidebar": true, "console": false, "tostatus": false, "complete": "payload", "targetType": "msg", "x": 650, "y": 150, "wires": [] } ] What it does Apply Baseline (2 kWh daily) → sends a runtime applyBaseline message that adds 2 kWh to the daily baseline immediately.

Reset Editor Applied → clears the remembered editor baseline so the same values can be applied again on next Deploy.

Debug Output → shows the updated payload with energy totals and costs.