iobroker.sun2000 2.4.5 → 2.5.1

package/lib/json_helper.js

@@ -3,7 +3,7 @@
 /**
  * Serializes an object to JSON, converting functions to their string representation.
  *
- * @param {any} obj - The object to serialize.
+ * @param {object} obj - The object to serialize.
  * @returns {string} JSON string where functions are represented as strings.
  */
 function stringifyWithFunctions(obj) {
@@ -22,30 +22,8 @@ function stringifyWithFunctions(obj) {
 		2,
 	);
 }
-/*
-const FUNCTION_KEYS = ['formatter', 'render', 'parser'];
 
-function reviveFunctions(obj, key = '') {
-	if (typeof obj === 'string' && FUNCTION_KEYS.includes(key)) {
-		const str = obj.trim();
-
-		try {
-			return new Function(`return (${str})`)();
-		} catch {
-			return obj;
-		}
-	}
-
-	if (typeof obj === 'object' && obj !== null) {
-		for (const k in obj) {
-			obj[k] = reviveFunctions(obj[k], k);
-		}
-	}
-
-	return obj;
-}
-*/
-const FUNCTION_KEYS = ['formatter', 'parser', 'render', 'labelFormatter', 'valueFormatter', 'position'];
+const FUNCTION_KEYS = ['formatter', 'parser', 'render', 'labelFormatter', 'valueFormatter', 'position', 'interval'];
 
 function reviveFunctions(obj, key = '') {
 	if (typeof obj === 'string' && FUNCTION_KEYS.includes(key)) {
@@ -109,7 +87,7 @@ function deepMerge(target, source) {
  *
  * @param {object} obj - The object to modify.
  * @param {string} path - Dot‑separated path (e.g., "a.b.c").
- * @param {any} value - The value to set at the specified path.
+ * @param {string} value - The value to set at the specified path.
  */
 function setByPath(obj, path, value) {
 	const keys = path.split('.');

package/lib/modbus/modbus_server.js

@@ -194,7 +194,7 @@ class ModbusServer {
 	 * @param {number} startAddr The start address of the register.
 	 * @param {number} length The length of the register.
 	 * @param {number} unitId The modbus unitId.
-	 * @param {Function} callback The callback function.
+	 * @param {callback} callback The callback function.
 	 * @returns {Promise<void>}
 	 */
 
@@ -280,7 +280,7 @@ class ModbusServer {
 	}
 
 	wait(ms) {
-		return new Promise(resolve => setTimeout(resolve, ms));
+		return new Promise(resolve => this.adapter.setTimeout(resolve, ms));
 	}
 }
 

package/lib/register.js

@@ -4,7 +4,7 @@ const { deviceType, driverClasses, dataRefreshRate } = require(`${__dirname}/typ
 const { RiemannSum, StateMap } = require(`${__dirname}/tools.js`);
 const getDriverHandler = require(`${__dirname}/drivers/index.js`);
 const tools = require(`${__dirname}/tools.js`);
-const statistics = require(`${__dirname}/statistics.js`);
+const statistics = require(`${__dirname}/statistics/statistics.js`);
 
 class Registers {
 	constructor(adapterInstance) {
@@ -12,8 +12,17 @@ class Registers {
 		this.stateCache = new StateMap();
 
 		this.externalSum = new RiemannSum();
+		this.inPowerSum = new RiemannSum();
+		this.actPowerSum = new RiemannSum();
+		this.chargeSum = new RiemannSum();
+		this.dischargeSum = new RiemannSum();
+		this.houseConsumSum = new RiemannSum();
+		this.feedinSum = new RiemannSum();
+		this.feedoutSum = new RiemannSum();
+
 		this.statistics = new statistics(adapterInstance, this.stateCache);
 
+		/*
 		for (const device of this.adapter.devices) {
 			//DriverInfo Instance or Sdongle
 			const handler = getDriverHandler(device.driverClass);
@@ -21,6 +30,7 @@ class Registers {
 				device.instance = new handler(this, device);
 			}
 		}
+		*/
 
 		//Upgrade to v2.3.7 - deleted deprecated states
 		if (
@@ -34,9 +44,84 @@ class Registers {
 				}
 			})
 		);
+		//Upgrade to v2.5.0 - deleted deprecated states
+		/*
+		if (
+			tools.existsState(this.adapter, `collected.consumptionStart`, (err, exists) => {
+				if (!err && exists) {
+					tools.deleteState(this.adapter, `collected.consumptionStart`, (err, deleted) => {
+						if (!err && deleted) {
+							this.adapter.logger.debug('Deleted deprecated state collected.consumptionStart');
+						}
+					});
+				}
+			})
+		);
+		*/
 
 		//this.postProcessHooks = [];
 		this.postProcessHooks = [
+			{
+				refresh: dataRefreshRate.high,
+				states: [
+					{
+						id: 'collected.sumDaily.houseConsumption',
+						name: 'daily sum of House consumption',
+						type: 'number',
+						unit: 'kWh',
+						role: 'value.power.consumed',
+						desc: 'riemann sum of Load power',
+					},
+					{
+						id: 'collected.sumDaily.activePower',
+						name: 'daily sum of Active power',
+						type: 'number',
+						unit: 'kWh',
+						role: 'value.power.produced',
+						desc: 'riemann sum of Power currently used',
+					},
+					{
+						id: 'collected.sumDaily.inputPower',
+						name: 'daily sum of Input power',
+						type: 'number',
+						unit: 'kWh',
+						role: 'value.power.produced',
+						desc: 'riemann sum of Power from solar',
+					},
+					{
+						id: 'collected.sumDaily.chargePower',
+						name: 'daily sum of Charge power',
+						type: 'number',
+						unit: 'kWh',
+						role: 'value.power.consumed',
+						desc: 'riemann sum of Charge power',
+					},
+					{
+						id: 'collected.sumDaily.dischargePower',
+						name: 'daily sum of Discharge power',
+						type: 'number',
+						unit: 'kWh',
+						role: 'value.power.produced',
+						desc: 'riemann sum of Discharge power',
+					},
+					{
+						id: 'collected.sumDaily.feed-inPower',
+						name: 'daily sum of Feed-in power',
+						type: 'number',
+						unit: 'kWh',
+						role: 'value.power.consumed',
+						desc: 'riemann sum of Feed-in power',
+					},
+					{
+						id: 'collected.sumDaily.feed-outPower',
+						name: 'daily sum of Feed-out power',
+						type: 'number',
+						unit: 'kWh',
+						role: 'value.power.produced',
+						desc: 'riemann sum of Feed-out power',
+					},
+				],
+			},
 			{
 				refresh: dataRefreshRate.high,
 				states: [
@@ -175,6 +260,23 @@ class Registers {
 					if (houseConsum < 0) {
 						houseConsum = 0;
 					}
+
+					//dailySum
+					this.inPowerSum.add(inPower);
+					this.actPowerSum.add(actPower);
+					this.chargeSum.add(chargeDischarge > 0 ? chargeDischarge : 0);
+					this.dischargeSum.add(chargeDischarge < 0 ? -chargeDischarge : 0);
+					this.houseConsumSum.add(houseConsum);
+					this.feedinSum.add(feedinPower > 0 ? feedinPower : 0);
+					this.feedoutSum.add(feedinPower < 0 ? -feedinPower : 0);
+					this.stateCache.set('collected.sumDaily.houseConsumption', this.houseConsumSum.sum, { type: 'number' });
+					this.stateCache.set('collected.sumDaily.activePower', this.actPowerSum.sum, { type: 'number' });
+					this.stateCache.set('collected.sumDaily.inputPower', this.inPowerSum.sum, { type: 'number' });
+					this.stateCache.set('collected.sumDaily.chargePower', this.chargeSum.sum, { type: 'number' });
+					this.stateCache.set('collected.sumDaily.dischargePower', this.dischargeSum.sum, { type: 'number' });
+					this.stateCache.set('collected.sumDaily.feed-inPower', this.feedinSum.sum, { type: 'number' });
+					this.stateCache.set('collected.sumDaily.feed-outPower', this.feedoutSum.sum, { type: 'number' });
+
 					//Überschuss (Differenz)
 					const surplusArray = calcUsableSurplus.bind(this)();
 
@@ -203,7 +305,7 @@ class Registers {
 						name: 'Daily energy yield',
 						type: 'number',
 						unit: 'kWh',
-						role: 'value.power.consumption',
+						role: 'value.power.produced',
 						desc: 'daily energy yield of the inverters',
 					},
 					{
@@ -211,7 +313,7 @@ class Registers {
 						name: 'Daily input yield',
 						type: 'number',
 						unit: 'kWh',
-						role: 'value.power.consumption',
+						role: 'value.power.produced',
 						desc: 'yield from the portal',
 					},
 					{
@@ -219,32 +321,38 @@ class Registers {
 						name: 'Daily solar yield',
 						type: 'number',
 						unit: 'kWh',
-						role: 'value.power.consumption',
+						role: 'value.power.produced',
 						desc: 'Riemann sum of input power with efficiency loss',
 					},
-					{ id: 'collected.accumulatedEnergyYield', name: 'Accumulated energy yield', type: 'number', unit: 'kWh', role: 'value.power.consumption' },
-					{ id: 'collected.consumptionSum', name: 'Consumption sum', type: 'number', unit: 'kWh', role: 'value.power.consumption' },
-					{ id: 'collected.gridExportStart', name: 'Grid export start today', type: 'number', unit: 'kWh', role: 'value.power.consumption' },
-					{ id: 'collected.gridImportStart', name: 'Grid import start today', type: 'number', unit: 'kWh', role: 'value.power.consumption' },
-					{ id: 'collected.consumptionStart', name: 'Consumption start today', type: 'number', unit: 'kWh', role: 'value.power.consumption' },
-					{ id: 'collected.gridExportToday', name: 'Grid export today', type: 'number', unit: 'kWh', role: 'value.power.consumption' },
-					{ id: 'collected.gridImportToday', name: 'Grid import today', type: 'number', unit: 'kWh', role: 'value.power.consumption' },
-					{ id: 'collected.consumptionToday', name: 'Consumption today', type: 'number', unit: 'kWh', role: 'value.power.consumption' },
-					{ id: 'collected.totalCharge', name: 'Total charge of battery', type: 'number', unit: 'kWh', role: 'value.power.consumption' },
-					{ id: 'collected.totalDischarge', name: 'Total discharge of battery', type: 'number', unit: 'kWh', role: 'value.power.consumption' },
+					{ id: 'collected.accumulatedEnergyYield', name: 'Accumulated energy yield', type: 'number', unit: 'kWh', role: 'value.power.produced' },
+					{ id: 'collected.consumptionSum', name: 'Consumption sum', type: 'number', unit: 'kWh', role: 'value.power.consumed' },
+					{ id: 'collected.gridExportStart', name: 'Grid export start today', type: 'number', unit: 'kWh', role: 'value.power.produced' },
+					{ id: 'collected.gridImportStart', name: 'Grid import start today', type: 'number', unit: 'kWh', role: 'value.power.consumed' },
+					{
+						id: 'collected.consumptionStart',
+						name: 'deprecated - Consumption start today',
+						type: 'number',
+						unit: 'kWh',
+						role: 'value.power.consumed',
+					},
+					{ id: 'collected.gridExportToday', name: 'Grid export today', type: 'number', unit: 'kWh', role: 'value.power.produced' },
+					{ id: 'collected.gridImportToday', name: 'Grid import today', type: 'number', unit: 'kWh', role: 'value.power.consumed' },
+					{ id: 'collected.consumptionToday', name: 'Consumption today', type: 'number', unit: 'kWh', role: 'value.power.consumed' },
+					{ id: 'collected.totalCharge', name: 'Total charge of battery', type: 'number', unit: 'kWh', role: 'value.power.produced' },
+					{ id: 'collected.totalDischarge', name: 'Total discharge of battery', type: 'number', unit: 'kWh', role: 'value.power.produced' },
 					{
 						id: 'collected.currentDayChargeCapacity',
 						name: 'Current day charge capacity of battery',
 						type: 'number',
 						unit: 'kWh',
-						role: 'value.power.consumption',
+						role: 'value.power.consumed',
 					},
 					{
 						id: 'collected.currentDayDischargeCapacity',
 						name: 'Current day discharge capacity of battery',
 						type: 'number',
 						unit: 'kWh',
-						role: 'value.power.consumption',
+						role: 'value.power.produced',
 						desc: '',
 					},
 					{ id: 'collected.SOC', name: 'State of battery capacity', type: 'number', unit: '%', role: 'value.battery', desc: 'SOC' },
@@ -254,19 +362,9 @@ class Registers {
 						name: 'daily external yield',
 						type: 'number',
 						unit: 'kWh',
-						role: 'value.power.consumption',
+						role: 'value.power.produced',
 						desc: 'Riemann sum of external power',
 					},
-					/*
-					{
-						id: 'collected.dailyActiveEnergy',
-						name: 'Active Energy today',
-						type: 'number',
-						unit: 'kWh',
-						role: 'value.power.consumption',
-						desc: 'Amount of Riemann sum of sum of active power',
-					},
-					*/
 				],
 				fn: inverters => {
 					let inYield = 0;
@@ -280,17 +378,20 @@ class Registers {
 					let totalCharge = 0;
 					let ratedCap = 0;
 					let load = 0;
-					let feedinEnergy;
-					let supplyFromGrid;
+					let ready = false;
 
 					for (const inverter of inverters) {
 						if (inverter.driverClass != driverClasses.inverter) {
 							continue;
 						}
+						if (this.stateCache.get(`${inverter.path}.accumulatedEnergyYield`)?.value === undefined) {
+							continue; //wait until value is available - otherwise we would overwrite the value from the portal with 0
+						}
+						ready = true;
 						outYield += this.stateCache.get(`${inverter.path}.dailyEnergyYield`)?.value ?? 0;
-						inYield += this.stateCache.get(`${inverter.path}.derived.dailyInputYield`)?.value;
-						solarYield += this.stateCache.get(`${inverter.path}.derived.dailySolarYield`)?.value;
-						enYield += this.stateCache.get(`${inverter.path}.accumulatedEnergyYield`)?.value;
+						inYield += this.stateCache.get(`${inverter.path}.derived.dailyInputYield`)?.value ?? 0;
+						solarYield += this.stateCache.get(`${inverter.path}.derived.dailySolarYield`)?.value ?? 0;
+						enYield += this.stateCache.get(`${inverter.path}.accumulatedEnergyYield`)?.value ?? 0;
 						activeEnergy += this.stateCache.get(`${inverter.path}.derived.dailyActiveEnergy`)?.value ?? 0;
 						if (this.stateCache.get(`${inverter.path}.battery.ratedCapacity`)?.value > 0) {
 							charge += this.stateCache.get(`${inverter.path}.battery.currentDayChargeCapacity`)?.value ?? 0;
@@ -300,9 +401,12 @@ class Registers {
 							load +=
 								this.stateCache.get(`${inverter.path}.battery.ratedCapacity`)?.value *
 								this.stateCache.get(`${inverter.path}.battery.SOC`)?.value;
-							ratedCap += this.stateCache.get(`${inverter.path}.battery.ratedCapacity`)?.value;
+							ratedCap += this.stateCache.get(`${inverter.path}.battery.ratedCapacity`)?.value ?? 0;
 						}
 					}
+					if (!ready) {
+						return; //no inverter ready yet - do not set values
+					}
 					//this.stateCache.set('collected.dailyActiveEnergy', activeEnergy, { type: 'number' });
 					this.stateCache.set('collected.dailyExternalYield', this.externalSum.sum, { type: 'number' }); //of externalPower
 					this.stateCache.set('collected.dailyEnergyYield', outYield, { type: 'number' });
@@ -310,9 +414,10 @@ class Registers {
 					this.stateCache.set('collected.dailySolarYield', solarYield, { type: 'number' });
 					this.stateCache.set('collected.accumulatedEnergyYield', enYield, { type: 'number' });
 					const sign = this.stateCache.get('meter.derived.signConventionForPowerFeed-in')?.value ?? 1;
+					let feedinEnergy;
+					let supplyFromGrid;
 					if (sign === -1) {
 						//Emma Meter Power is positive when power is taken from grid
-						//Emma Meter Power is negative when power is feed in to grid
 						feedinEnergy = this.stateCache.get('meter.reverseActiveEnergy')?.value ?? 0;
 						supplyFromGrid = this.stateCache.get('meter.positiveActiveEnergy')?.value ?? 0;
 					} else {
@@ -354,7 +459,7 @@ class Registers {
 					this.stateCache.set('collected.currentDayChargeCapacity', charge, { type: 'number' });
 					this.stateCache.set('collected.currentDayDischargeCapacity', disCharge, { type: 'number' });
 					this.stateCache.set('collected.ratedCapacity', ratedCap, { type: 'number' });
-					this.stateCache.set('collected.SOC', Math.round(load / ratedCap), { type: 'number' });
+					this.stateCache.set('collected.SOC', ratedCap ? Math.round(load / ratedCap) : 0, { type: 'number' });
 				},
 			},
 		];
@@ -397,15 +502,14 @@ class Registers {
 
 	async storeStates() {
 		for (const stateEntry of this.stateCache.values()) {
-			//if (stateEntry?.storeType === storeType.never) continue;
 			if (stateEntry.stored) {
 				continue;
 			}
-			//if (stateEntry?.storeType !== storeType.always && stateEntry.stored) continue;
 			if (stateEntry.value !== null) {
 				try {
 					stateEntry.stored = true;
-					await this.adapter.setState(stateEntry.id, { val: stateEntry.value, ack: true });
+					const valueToStore = typeof stateEntry.value === 'number' ? this.stateCache.round(stateEntry.value, 3) : stateEntry.value;
+					await this.adapter.setState(stateEntry.id, { val: valueToStore, ack: true });
 					this.adapter.logger.debug(`Fetched ${stateEntry.id}, val=${stateEntry.value}`);
 				} catch (err) {
 					stateEntry.stored = false;
@@ -430,7 +534,7 @@ class Registers {
 	 * @returns {Promise<number>} - Returns a promise that resolves to the number of states updated.
 	 */
 	async updateStates(device, modbusClient, refreshRate, duration) {
-		//this.adapter.log.debug('### DeviceInfo: '+device.index+' '+JSON.stringify(device.instance.info));
+		//this.adapter.log.debug(`### DeviceInfo: ${device.index} ${JSON.stringify(device.instance?.info)}`);
 		if (!device.instance) {
 			const handler = getDriverHandler(device.driverClass);
 			if (handler) {
@@ -475,11 +579,34 @@ class Registers {
 		this.stateCache.set('collected.gridImportStart', state?.val, { type: 'number', stored: true });
 		state = await this.adapter.getState('collected.gridImportStart');
 		this.stateCache.set('collected.gridImportStart', state?.val, { type: 'number', stored: true });
+		//deprecated - only for compatibility reasons - will be removed in future versions
 		state = await this.adapter.getState('collected.consumptionStart');
 		this.stateCache.set('collected.consumptionStart', state?.val, { type: 'number', stored: true });
 		state = await this.adapter.getState('collected.dailyExternalYield');
+		//riemann sum - set start value and timestamp for correct computation of daily yield
 		this.stateCache.set('collected.dailyExternalYield', state?.val, { type: 'number', stored: true });
 		this.externalSum.setStart(state?.val, state?.ts);
+		state = await this.adapter.getState('collected.sumDaily.houseConsumption');
+		this.stateCache.set('collected.sumDaily.houseConsumption', state?.val, { type: 'number', stored: true });
+		this.houseConsumSum.setStart(state?.val, state?.ts);
+		state = await this.adapter.getState('collected.sumDaily.activePower');
+		this.stateCache.set('collected.sumDaily.activePower', state?.val, { type: 'number', stored: true });
+		this.actPowerSum.setStart(state?.val, state?.ts);
+		state = await this.adapter.getState('collected.sumDaily.inputPower');
+		this.stateCache.set('collected.sumDaily.inputPower', state?.val, { type: 'number', stored: true });
+		this.inPowerSum.setStart(state?.val, state?.ts);
+		state = await this.adapter.getState('collected.sumDaily.chargePower');
+		this.stateCache.set('collected.sumDaily.chargePower', state?.val, { type: 'number', stored: true });
+		this.chargeSum.setStart(state?.val, state?.ts);
+		state = await this.adapter.getState('collected.sumDaily.dischargePower');
+		this.stateCache.set('collected.sumDaily.dischargePower', state?.val, { type: 'number', stored: true });
+		this.dischargeSum.setStart(state?.val, state?.ts);
+		state = await this.adapter.getState('collected.sumDaily.feed-inPower');
+		this.stateCache.set('collected.sumDaily.feed-inPower', state?.val, { type: 'number', stored: true });
+		this.feedinSum.setStart(state?.val, state?.ts);
+		state = await this.adapter.getState('collected.sumDaily.feed-outPower');
+		this.stateCache.set('collected.sumDaily.feed-outPower', state?.val, { type: 'number', stored: true });
+		this.feedoutSum.setStart(state?.val, state?.ts);
 	}
 
 	//state
@@ -552,6 +679,7 @@ class Registers {
 		this.externalSum.reset(); //reset for next day
 		this.stateCache.set('collected.dailyExternalYield', 0, { type: 'number' });
 		// copy consumption Sum to Start for the next day
+		// deprecated - consumption start is not used anymore, but we set it to the current consumption sum to avoid confusion
 		this.stateCache.set('collected.consumptionStart', this.stateCache.get('collected.consumptionSum')?.value ?? 0, { type: 'number' });
 		for (const device of this.adapter.devices) {
 			if (device.instance.mitnightProcess) {
@@ -560,6 +688,17 @@ class Registers {
 		}
 		this.storeStates();
 	}
+
+	destroy() {
+		for (const device of this.adapter.devices) {
+			if (typeof device.instance.destroy === 'function') {
+				device.instance.destroy();
+			}
+		}
+		if (typeof this.statistics.destroy === 'function') {
+			this.statistics.destroy();
+		}
+	}
 }
 
 module.exports = Registers;

package/lib/statistics/breakdownChartHelper.js

@@ -0,0 +1,131 @@
+'use strict';
+
+/**
+ * breakdownChartHelper.js
+ *
+ * Provides all eCharts-specific helpers related to the consumption breakdown feature.
+ *
+ * Responsibilities:
+ *  - Building eCharts series objects for breakdown entries (stacked bars in the
+ *    lower consumption grid: xAxisIndex 1 / yAxisIndex 2)
+ *  - Merging breakdown series names into the chart legend array
+ *  - Replacing breakdown data placeholders in chart template strings
+ *    (%%targetPath%% → serialised data array)
+ *
+ * This module has no knowledge of ioBroker states, the stateCache, or scheduling.
+ * It receives everything it needs as arguments, which makes it easy to unit-test.
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Fallback colour palette applied when a breakdown entry does not specify a colour.
+ * Cycles through the list if more entries exist than colours.
+ */
+const DEFAULT_COLORS = ['#e91e63', '#9c27b0', '#673ab7', '#3f51b5', '#03a9f4', '#009688', '#8bc34a', '#ff5722', '#795548', '#607d8b'];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds an array of eCharts series configurations for the given breakdown entries.
+ *
+ * Each series is rendered as a stacked bar in the lower consumption sub-grid
+ * (xAxisIndex 1, yAxisIndex 2) with stack key "consumptionBreakdown", so all
+ * breakdown bars pile on top of one another.
+ *
+ * @param {import('./consumptionBreakdown').ConsumptionBreakdownEntry[]} entries
+ *   The currently active breakdown entries (from ConsumptionBreakdown.entries).
+ * @param {string} [seriesType]
+ *   eCharts series type passed in from the caller ('bar' or 'line').
+ * @param options - additional options to merge into each series config (e.g. for line styling)
+ * @param {string} valueFormatter string
+ * @returns {Array} eCharts series array (may be empty when entries is empty)
+ */
+function buildBreakdownSeries(entries, seriesType = 'bar', options = {}, valueFormatter) {
+	if (!entries || entries.length === 0) return [];
+
+	return entries.map((bd, idx) => {
+		const color = bd.color || DEFAULT_COLORS[idx % DEFAULT_COLORS.length];
+		//const unit = bd.unit || 'kWh';
+
+		return {
+			name: bd.name,
+			type: seriesType,
+			stack: 'consumptionBreakdown', // same stack key as the Consumption series
+			xAxisIndex: 1,
+			yAxisIndex: 2,
+			data: `%%${bd.targetPath}%%`, // ensure it's an array (empty if undefined)
+			itemStyle: { color },
+			emphasis: { focus: 'series' },
+			//tooltip: { valueFormatter: value => `${value} ${unit}` },
+			tooltip: { valueFormatter: valueFormatter },
+			...options,
+		};
+	});
+}
+
+/**
+ * Merges breakdown series names into an existing legend data array.
+ *
+ * Appends names that are not already present; mutates and returns the array.
+ *
+ * @param {string[]}                                                          legendData
+ *   Existing legend labels (built-in series names).
+ * @param {import('./consumptionBreakdown').ConsumptionBreakdownEntry[]}      entries
+ *   Active breakdown entries whose names should appear in the legend.
+ * @returns {string[]} The same legendData array with breakdown names appended.
+ */
+function mergeBreakdownLegend(legendData, entries) {
+	if (!entries || entries.length === 0) return legendData;
+
+	for (const bd of entries) {
+		if (!legendData.includes(bd.name)) {
+			legendData.push(bd.name);
+		}
+	}
+	return legendData;
+}
+
+/**
+ * Replaces breakdown data placeholders inside a serialised chart string.
+ *
+ * The template may contain placeholder tokens of the form  '%%targetPath%%'
+ * (with surrounding single-quotes, as produced by javascript-stringify).
+ * Each is replaced with the JSON-serialised numeric data array.
+ *
+ * This function is intentionally a string-level operation so it works both
+ * for custom user templates (loaded from the state) and for the built-in
+ * template produced by _buildDefaultTemplate().
+ *
+ * @param {string}                                                           chartStr
+ *   The chart configuration as a raw string (output of stringify()).
+ * @param {import('./consumptionBreakdown').ConsumptionBreakdownEntry[]}     entries
+ *   Active breakdown entries.
+ * @param {Record<string, number[]>}                                         seriesData
+ *   Map of targetPath → data array.
+ * @returns {string} The chart string with placeholders replaced.
+ */
+function replacePlaceholders(chartStr, entries, seriesData) {
+	if (!entries || entries.length === 0) return chartStr;
+
+	for (const bd of entries) {
+		const placeholder = `'%%${bd.targetPath}%%'`;
+		const value = JSON.stringify(seriesData[bd.targetPath] ?? []);
+		chartStr = chartStr.replaceAll(placeholder, value);
+	}
+	return chartStr;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+	buildBreakdownSeries,
+	mergeBreakdownLegend,
+	replacePlaceholders,
+};