iobroker.prosoft_flow 0.1.0

package/main.js

@@ -0,0 +1,832 @@
+'use strict';
+
+const utils = require('@iobroker/adapter-core');
+const { load } = require('./lib/engineBridge');
+
+class ProsoftFlow extends utils.Adapter {
+	/**
+	 * @param {Partial<utils.AdapterOptions>} [options={}]
+	 */
+	constructor(options = {}) {
+		super({
+			...options,
+			name: 'prosoft_flow',
+		});
+
+		this.engine = null;
+		this.tagMap = new Map();
+		this.dailyTagMap = new Map();
+		this.hourlyTagMap = new Map();
+		this.snapshotTagMap = new Map();
+		this.customTagMap = new Map();
+
+		// AFC Clock and schedule tracking
+		this.afcClocks = new Map();
+		this.groupJobStates = new Map();
+		this.pollingTimers = new Map();
+		this.resetTimers = new Map();
+
+		this.on('ready', this.onReady.bind(this));
+		this.on('stateChange', this.onStateChange.bind(this));
+		this.on('unload', this.onUnload.bind(this));
+	}
+
+	/**
+	 * Is called when databases are connected and adapter received configuration.
+	 */
+	async onReady() {
+		this.log.info('Starting Prosoft Flow Computer Adapter...');
+
+		// 1. Load Native AOT Engine
+		try {
+			this.engine = load(this.log);
+			this.log.info(`Native Engine loaded successfully (version: ${this.engine.Version()})`);
+		} catch (err) {
+			this.log.error(`Failed to load native engine addon: ${err.message}`);
+			this.setState('info.connection', { val: false, ack: true });
+			return;
+		}
+
+		// 2. Machine Hardware ID & Environment & Licensing (RFC-005)
+		try {
+			const hwId = this.engine.GetHardwareId();
+			const envType = this.engine.GetEnvironmentType();
+			const licInfoRaw = this.engine.GetLicenseInfo(this.config.licenseKey || '');
+			const licInfo = JSON.parse(licInfoRaw);
+
+			await this.setState('info.hardwareId', { val: hwId, ack: true });
+			await this.setState('info.environmentType', { val: envType, ack: true });
+			await this.setState('info.licenseStatus', {
+				val: licInfo.valid ? `Valid (${licInfo.edition || 'licensed'})` : licInfo.message,
+				ack: true,
+			});
+			await this.setState('info.licenseKey', { val: this.config.licenseKey || '', ack: true });
+			await this.setState('info.licenseValid', { val: Boolean(licInfo.valid), ack: true });
+			await this.setState('info.licenseExpired', { val: Boolean(licInfo.expired), ack: true });
+			await this.setState('info.licenseExpiresAt', { val: licInfo.expiresAt || '', ack: true });
+			await this.setState('info.licenseTimeSource', { val: this.config.licenseTimeSource || 'afc', ack: true });
+			await this.setState('info.ready', { val: Boolean(licInfo.valid && !licInfo.expired), ack: true });
+
+			this.log.info(`RFC-005 Hardware ID: ${hwId} | Environment: ${envType}`);
+			if (licInfo.valid) {
+				this.log.info(`License valid: Edition=${licInfo.edition}, MaxTags=${licInfo.maxTags || 'unlimited'}`);
+			} else {
+				this.log.warn(`License notice: ${licInfo.message}`);
+			}
+		} catch (err) {
+			this.log.warn(`Error probing licensing information: ${err.message}`);
+		}
+
+		// 3. Register Engine Event Callback
+		this.engine.OnEvent((evtJson) => {
+			this.handleNativeEvent(evtJson);
+		});
+
+		// 4. Create State Tree for Polling Tags, Dynamic Groups and Reports
+		await this.initializeStateObjects();
+
+		// 5. Build Engine Configuration & Start
+		const engineConfig = this.buildEngineConfig();
+		try {
+			this.engine.Init(JSON.stringify(engineConfig));
+			this.engine.Start();
+			this.setState('info.pollActive', { val: true, ack: true });
+			this.setState('info.pollPaused', { val: false, ack: true });
+			this.log.info('Native Modbus Polling Engine started.');
+		} catch (err) {
+			this.log.error(`Failed to initialize/start engine: ${err.message}`);
+		}
+
+		// 6. Setup Polling Timers for groups configured with readMode === 'polling'
+		this.setupGroupPolling();
+
+		// 7. Subscribe to control states & writable licenseKey state
+		this.subscribeStates('info.licenseKey');
+		this.subscribeStates('reports.set*');
+
+		// Subscribe to any writable tag states
+		const tags = this.config.tags || [];
+		for (const tag of tags) {
+			const stateId = this.getTagStateId(tag);
+			this.subscribeStates(stateId);
+		}
+	}
+
+	/**
+	 * Formats tag state ID with group hierarchy.
+	 */
+	getTagStateId(tag) {
+		const group = (tag.group || '').trim().replace(/[^a-zA-Z0-9_-]/g, '_');
+		const name = (tag.name || '').trim().replace(/[^a-zA-Z0-9_-]/g, '_');
+		return group ? `${group}.${name}` : name;
+	}
+
+	/**
+	 * Safe formula evaluator: x is replaced by raw numeric value.
+	 */
+	applyFormula(formula, val) {
+		if (!formula || typeof formula !== 'string' || !formula.trim()) return val;
+		if (val === null || val === undefined || typeof val !== 'number') return val;
+		try {
+			const fn = new Function('x', 'Math', `"use strict"; return (${formula});`);
+			const res = fn(val, Math);
+			return typeof res === 'number' && !isNaN(res) ? res : val;
+		} catch (err) {
+			this.log.debug(`Formula evaluation error on '${formula}': ${err.message}`);
+			return val;
+		}
+	}
+
+	/**
+	 * Maps Modbus data type to ioBroker common state definition.
+	 */
+	getTypeDefinition(dt) {
+		const type = (dt || 'float').toLowerCase();
+		if (type === 'bool') {
+			return { type: 'boolean', role: 'indicator' };
+		}
+		if (type === 'dt' || type.startsWith('ascii')) {
+			return { type: 'string', role: 'text' };
+		}
+		return { type: 'number', role: 'value' };
+	}
+
+	/**
+	 * Initializes all objects and state channels in ioBroker.
+	 */
+	async initializeStateObjects() {
+		this.log.info('Initializing ioBroker state objects...');
+
+		// Polling Tags
+		const tags = this.config.tags || [];
+		const groupsCreated = new Set();
+
+		for (const tag of tags) {
+			if (!tag.name) continue;
+			this.tagMap.set(tag.name, tag);
+
+			const group = (tag.group || '').trim().replace(/[^a-zA-Z0-9_-]/g, '_');
+			if (group && !groupsCreated.has(group)) {
+				await this.setObjectNotExistsAsync(group, {
+					type: 'channel',
+					common: { name: tag.group || group },
+					native: {},
+				});
+				groupsCreated.add(group);
+			}
+
+			const stateId = this.getTagStateId(tag);
+			const typeDef = this.getTypeDefinition(tag.dataType);
+
+			await this.setObjectNotExistsAsync(stateId, {
+				type: 'state',
+				common: {
+					name: tag.description || tag.name,
+					type: typeDef.type,
+					role: typeDef.role,
+					read: true,
+					write: true,
+					unit: tag.unit || '',
+				},
+				native: {
+					address: tag.address,
+					dataType: tag.dataType,
+					formula: tag.formula || '',
+				},
+			});
+		}
+
+		// Ensure Dynamic Report Group Channels and Flags
+		const reportGroups = this.config.reportGroups || [];
+		for (const rg of reportGroups) {
+			if (!rg.name) continue;
+			const grpKey = rg.name.toLowerCase().replace(/[^a-zA-Z0-9_-]/g, '_');
+
+			await this.setObjectNotExistsAsync(`reports.${grpKey}`, {
+				type: 'channel',
+				common: { name: `${rg.name} Report Channel` },
+				native: {},
+			});
+			await this.setObjectNotExistsAsync(`reports.${grpKey}.readStarted`, {
+				type: 'state',
+				common: { role: 'indicator', name: `${rg.name} read cycle started`, type: 'boolean', read: true, write: true, def: false },
+				native: {},
+			});
+			await this.setObjectNotExistsAsync(`reports.${grpKey}.readFinished`, {
+				type: 'state',
+				common: { role: 'indicator', name: `${rg.name} read cycle finished`, type: 'boolean', read: true, write: true, def: false },
+				native: {},
+			});
+			await this.setObjectNotExistsAsync(`reports.${grpKey}.status`, {
+				type: 'state',
+				common: { role: 'text', name: `${rg.name} lifecycle status`, type: 'string', read: true, write: false, def: 'idle' },
+				native: {},
+			});
+			await this.setObjectNotExistsAsync(`reports.${grpKey}.lastReadTime`, {
+				type: 'state',
+				common: { role: 'text', name: `${rg.name} last read timestamp`, type: 'string', read: true, write: false, def: '' },
+				native: {},
+			});
+			await this.setObjectNotExistsAsync(`reports.set${rg.name}`, {
+				type: 'state',
+				common: { role: 'button', name: `Trigger ${rg.name} Report Read`, type: 'boolean', read: true, write: true, def: false },
+				native: {},
+			});
+		}
+
+		// Daily report tags
+		const dailyTags = this.config.dailyTags || [];
+		for (const tag of dailyTags) {
+			if (!tag.name) continue;
+			this.dailyTagMap.set(tag.name, tag);
+			const sId = `reports.daily.${tag.name.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+			const typeDef = this.getTypeDefinition(tag.dataType);
+			await this.setObjectNotExistsAsync(sId, {
+				type: 'state',
+				common: {
+					name: tag.name,
+					type: typeDef.type,
+					role: typeDef.role,
+					read: true,
+					write: false,
+				},
+				native: { ...tag },
+			});
+		}
+
+		// Hourly report tags
+		const hourlyTags = this.config.hourlyTags || [];
+		for (const tag of hourlyTags) {
+			if (!tag.name) continue;
+			this.hourlyTagMap.set(tag.name, tag);
+			const sId = `reports.hourly.${tag.name.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+			const typeDef = this.getTypeDefinition(tag.dataType);
+			await this.setObjectNotExistsAsync(sId, {
+				type: 'state',
+				common: {
+					name: tag.name,
+					type: typeDef.type,
+					role: typeDef.role,
+					read: true,
+					write: false,
+				},
+				native: { ...tag },
+			});
+		}
+
+		// Snapshot report tags
+		const snapshotTags = this.config.snapshotTags || [];
+		for (const tag of snapshotTags) {
+			if (!tag.name) continue;
+			this.snapshotTagMap.set(tag.name, tag);
+			const sId = `reports.snapshot.${tag.name.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+			const typeDef = this.getTypeDefinition(tag.dataType);
+			await this.setObjectNotExistsAsync(sId, {
+				type: 'state',
+				common: {
+					name: tag.name,
+					type: typeDef.type,
+					role: typeDef.role,
+					read: true,
+					write: false,
+				},
+				native: { ...tag },
+			});
+		}
+
+		// Custom report tags (Prover and user-added groups)
+		const customReportTags = this.config.customReportTags || [];
+		for (const tag of customReportTags) {
+			if (!tag.name || !tag.groupName) continue;
+			const grpKey = tag.groupName.toLowerCase().replace(/[^a-zA-Z0-9_-]/g, '_');
+			this.customTagMap.set(`${grpKey}.${tag.name}`, tag);
+
+			const sId = `reports.${grpKey}.${tag.name.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+			const typeDef = this.getTypeDefinition(tag.dataType);
+			await this.setObjectNotExistsAsync(sId, {
+				type: 'state',
+				common: {
+					name: tag.name,
+					type: typeDef.type,
+					role: typeDef.role,
+					read: true,
+					write: false,
+				},
+				native: { ...tag },
+			});
+		}
+
+		this.log.info(`Initialized ${tags.length} polling tags and report groups.`);
+	}
+
+	/**
+	 * Builds native engine configuration JSON.
+	 */
+	buildEngineConfig() {
+		const reportGroupsConfig = [];
+		const definedGroups = this.config.reportGroups || [];
+
+		for (const rg of definedGroups) {
+			if (!rg.name) continue;
+			const grpNameLower = rg.name.toLowerCase();
+
+			let tagsForGroup = [];
+			if (grpNameLower === 'daily') {
+				tagsForGroup = (this.config.dailyTags || []).map((t) => ({
+					name: t.name,
+					meterNumber: t.meter,
+					addressAge0: Number(t.addressAge0),
+					addressAgeOthers: Number(t.addressAgeOthers),
+					dataType: t.dataType,
+					formula: t.formula || '',
+				}));
+			} else if (grpNameLower === 'hourly') {
+				tagsForGroup = (this.config.hourlyTags || []).map((t) => ({
+					name: t.name,
+					meterNumber: t.meter,
+					addressAge0: Number(t.addressAge0),
+					addressAgeOthers: Number(t.addressAgeOthers),
+					dataType: t.dataType,
+					formula: t.formula || '',
+				}));
+			} else if (grpNameLower === 'snapshot') {
+				tagsForGroup = (this.config.snapshotTags || []).map((t) => ({
+					name: t.name,
+					meterNumber: t.meter,
+					addressAge0: Number(t.address),
+					addressAgeOthers: Number(t.address),
+					dataType: t.dataType,
+					formula: t.formula || '',
+				}));
+			} else {
+				// Filter customReportTags for this group
+				const customTags = (this.config.customReportTags || []).filter(
+					(t) => (t.groupName || '').equalsIgnoreCase ? t.groupName.equalsIgnoreCase(rg.name) : (t.groupName || '').toLowerCase() === grpNameLower
+				);
+				tagsForGroup = customTags.map((t) => ({
+					name: t.name,
+					meterNumber: t.meter,
+					addressAge0: Number(t.addressAge0),
+					addressAgeOthers: Number(t.addressAgeOthers),
+					dataType: t.dataType,
+					formula: t.formula || '',
+				}));
+			}
+
+			reportGroupsConfig.push({
+				name: rg.name,
+				ageRegisterM1: Number(rg.ageRegisterM1) || 0,
+				ageRegisterM2: Number(rg.ageRegisterM2) || 0,
+				ageRegisterM3: Number(rg.ageRegisterM3) || 0,
+				tags: tagsForGroup,
+			});
+		}
+
+		return {
+			connectionType: this.config.connectionType || 'serial',
+			serialPort: this.config.serialPort || 'COM1',
+			baudRate: Number(this.config.baudRate) || 9600,
+			dataBits: Number(this.config.dataBits) || 8,
+			stopBits: Number(this.config.stopBits) || 1,
+			parity: this.config.parity || 'none',
+			tcpHost: this.config.tcpHost || '127.0.0.1',
+			tcpPort: Number(this.config.tcpPort) || 502,
+			tcpTimeout: Number(this.config.tcpTimeout) || 2000,
+			reconnectInterval: Number(this.config.reconnectInterval) || 5000,
+			slaveId: Number(this.config.slaveId) || 244,
+			pollInterval: Number(this.config.pollInterval) || 1000,
+			licenseKey: this.config.licenseKey || '',
+			licenseTimeSource: this.config.licenseTimeSource || 'afc',
+			licenseTimeAddress: Number(this.config.licenseTimeAddress) || 9950,
+			tags: (this.config.tags || []).map((t) => ({
+				name: t.name,
+				address: Number(t.address),
+				registerType: t.dataType === 'bool' ? 'coil' : 'holding',
+				dataType: t.dataType || 'float',
+				poll: t.poll !== false,
+				formula: t.formula || '',
+			})),
+			reportGroups: reportGroupsConfig,
+		};
+	}
+
+	/**
+	 * Handles events emitted by the native C# AOT engine.
+	 */
+	handleNativeEvent(jsonStr) {
+		try {
+			const evt = JSON.parse(jsonStr);
+			if (evt.type === 'state') {
+				this.setState('info.connection', { val: Boolean(evt.connected), ack: true });
+			} else if (evt.type === 'license_state') {
+				this.setState('info.licenseValid', { val: Boolean(evt.valid), ack: true });
+				this.setState('info.licenseExpired', { val: Boolean(evt.expired), ack: true });
+				this.setState('info.licenseStatus', { val: evt.status || '', ack: true });
+				if (evt.expiresAt !== undefined) {
+					this.setState('info.licenseExpiresAt', { val: evt.expiresAt || '', ack: true });
+				}
+				if (evt.referenceTime) {
+					this.setState('info.referenceTime', { val: evt.referenceTime, ack: true });
+				}
+				if (evt.timeSource) {
+					this.setState('info.licenseTimeSource', { val: evt.timeSource, ack: true });
+				}
+				const isReady = Boolean(evt.valid && !evt.expired);
+				this.setState('info.ready', { val: isReady, ack: true });
+				this.setState('info.pollPaused', { val: !isReady, ack: true });
+			} else if (evt.type === 'values' && Array.isArray(evt.data)) {
+				for (const item of evt.data) {
+					const tag = this.tagMap.get(item.id);
+					if (!tag) continue;
+					const stateId = this.getTagStateId(tag);
+					let val = item.val;
+					if (tag.formula && typeof val === 'number') {
+						val = this.applyFormula(tag.formula, val);
+					}
+					this.setState(stateId, { val, ack: true, ts: item.ts });
+				}
+			} else if (evt.type === 'afc_time') {
+				// AFC Clock Event: address + time string
+				const addr = evt.address ? Number(evt.address) : 9900;
+				const timeStr = evt.time || '';
+				this.processAfcClock(addr, timeStr);
+			} else if (evt.type === 'report_ready') {
+				this.handleReportReady(evt.data);
+			} else if (evt.type === 'log') {
+				const lvl = evt.level === 'error' ? 'error' : evt.level === 'warn' ? 'warn' : 'info';
+				this.log[lvl](`[Native Engine] ${evt.msg}`);
+			}
+		} catch (err) {
+			this.log.error(`Error parsing native event: ${err.message}`);
+		}
+	}
+
+	/**
+	 * Parses DateTime string formatted as "YYYY-MM-DD HH:mm:ss"
+	 */
+	parseTimeString(timeStr) {
+		if (!timeStr || typeof timeStr !== 'string') return null;
+		const parts = timeStr.trim().split(' ');
+		if (parts.length < 2) return null;
+
+		const dateParts = parts[0].split('-');
+		const timeParts = parts[1].split(':');
+		if (dateParts.length < 3 || timeParts.length < 3) return null;
+
+		const year = parseInt(dateParts[0], 10);
+		const month = parseInt(dateParts[1], 10);
+		const day = parseInt(dateParts[2], 10);
+		const hour = parseInt(timeParts[0], 10);
+		const minute = parseInt(timeParts[1], 10);
+		const second = parseInt(timeParts[2], 10);
+
+		if (isNaN(hour) || isNaN(minute) || isNaN(second)) return null;
+
+		return { year, month, day, hour, minute, second, timeStr };
+	}
+
+	/**
+	 * Processes AFC real-time clock updates and drives schedules.
+	 */
+	processAfcClock(address, timeStr) {
+		const parsed = this.parseTimeString(timeStr);
+		if (!parsed) return;
+
+		this.afcClocks.set(address, parsed);
+
+		const defaultReg = Number(this.config.afcTimeRegister || 9900);
+		if (address === defaultReg) {
+			this.setState('info.afcTime', { val: timeStr, ack: true });
+		}
+
+		// Check schedule for all enabled groups that bind to this register
+		const groups = this.config.reportGroups || [];
+		for (const group of groups) {
+			if (!group.enabled) continue;
+			if (group.readMode !== 'schedule') continue;
+
+			const targetReg = Number(group.timeRegister || defaultReg);
+			if (targetReg === address) {
+				this.evaluateGroupSchedule(group, parsed);
+			}
+		}
+	}
+
+	/**
+	 * Evaluates schedule matching condition for a group against the bound AFC clock.
+	 */
+	evaluateGroupSchedule(group, afcClock) {
+		const { hour, minute, second, day } = afcClock;
+		const grpKey = group.name.toLowerCase();
+
+		const targetMinute = Number(group.scheduleMinute ?? 0);
+		const targetHour = Number(group.scheduleHour ?? 0);
+		const targetDay = Number(group.scheduleDay ?? 1);
+		const schedType = group.scheduleType || 'daily';
+
+		let isMatch = false;
+
+		if (schedType === 'hourly') {
+			isMatch = (minute === targetMinute && second >= 0);
+		} else if (schedType === 'daily') {
+			isMatch = (hour === targetHour && minute === targetMinute && second >= 0);
+		} else if (schedType === 'monthly') {
+			isMatch = (day === targetDay && hour === targetHour && minute === targetMinute && second >= 0);
+		}
+
+		const state = this.groupJobStates.get(grpKey) || 0;
+
+		if (isMatch) {
+			if (state === 0) {
+				this.groupJobStates.set(grpKey, 1);
+				const age = group.age !== undefined ? Number(group.age) : 1;
+				this.log.info(`[AFC Schedule Match] Group '${group.name}' matched bound AFC clock (Reg=${group.timeRegister || this.config.afcTimeRegister}, Day=${day}, Hour=${hour}, Min=${minute}). Reading Age ${age}...`);
+				this.executeReportRead(group.name, age);
+			}
+		} else {
+			// Reset edge trigger once the minute advances
+			if (minute !== targetMinute && state > 0) {
+				this.groupJobStates.set(grpKey, 0);
+			}
+		}
+	}
+
+	/**
+	 * Starts interval timers for groups configured with readMode === 'polling'.
+	 */
+	setupGroupPolling() {
+		// Clear previous timers
+		for (const timer of this.pollingTimers.values()) {
+			clearInterval(timer);
+		}
+		this.pollingTimers.clear();
+
+		const groups = this.config.reportGroups || [];
+		for (const group of groups) {
+			if (!group.name || !group.enabled) continue;
+			if (group.readMode === 'polling') {
+				const intervalSec = Math.max(2, Number(group.pollInterval) || 30);
+				this.log.info(`[Group Polling] Starting periodic polling for '${group.name}' every ${intervalSec}s (Age: ${group.age || 0}).`);
+
+				const timer = setInterval(() => {
+					this.log.info(`[Group Polling] Periodic trigger for '${group.name}'...`);
+					this.executeReportRead(group.name, Number(group.age || 0));
+				}, intervalSec * 1000);
+
+				this.pollingTimers.set(group.name.toLowerCase(), timer);
+			}
+		}
+	}
+
+	/**
+	 * Sets lifecycle flags when reading starts.
+	 */
+	async setReportStartFlags(groupName) {
+		const grp = groupName.toLowerCase().replace(/[^a-zA-Z0-9_-]/g, '_');
+
+		if (this.resetTimers.has(grp)) {
+			clearTimeout(this.resetTimers.get(grp));
+			this.resetTimers.delete(grp);
+		}
+
+		// Global flags
+		await this.setState('reports.readStarted', { val: true, ack: true });
+		await this.setState('reports.readFinished', { val: false, ack: true });
+		await this.setState('reports.status', { val: 'reading', ack: true });
+		await this.setState('reports.activeGroup', { val: groupName, ack: true });
+		await this.setState('reports.lastStartedGroup', { val: groupName, ack: true });
+		await this.setState('info.pollPaused', { val: true, ack: true });
+
+		// Per-group flags
+		await this.setState(`reports.${grp}.readStarted`, { val: true, ack: true });
+		await this.setState(`reports.${grp}.readFinished`, { val: false, ack: true });
+		await this.setState(`reports.${grp}.status`, { val: 'reading', ack: true });
+	}
+
+	/**
+	 * Sets lifecycle flags when reading finishes, with 3-second auto-pulse reset.
+	 */
+	async setReportFinishFlags(groupName, isSuccess) {
+		const grp = groupName.toLowerCase().replace(/[^a-zA-Z0-9_-]/g, '_');
+		const nowStr = new Date().toISOString();
+
+		// Global finish
+		await this.setState('reports.readStarted', { val: false, ack: true });
+		await this.setState('reports.readFinished', { val: isSuccess, ack: true });
+		await this.setState('reports.status', { val: isSuccess ? 'success' : 'error', ack: true });
+		await this.setState('reports.lastFinishedGroup', { val: groupName, ack: true });
+		await this.setState('info.pollPaused', { val: false, ack: true });
+
+		// Per-group finish
+		await this.setState(`reports.${grp}.readStarted`, { val: false, ack: true });
+		await this.setState(`reports.${grp}.readFinished`, { val: isSuccess, ack: true });
+		await this.setState(`reports.${grp}.status`, { val: isSuccess ? 'success' : 'error', ack: true });
+		if (isSuccess) {
+			await this.setState(`reports.${grp}.lastReadTime`, { val: nowStr, ack: true });
+		}
+
+		// Reset Logic (Pulse Handshake):
+		// After 3 seconds, automatically reset readFinished to false and status to 'idle'
+		const timer = setTimeout(async () => {
+			try {
+				await this.setState(`reports.${grp}.readFinished`, { val: false, ack: true });
+				await this.setState(`reports.${grp}.status`, { val: 'idle', ack: true });
+				await this.setState('reports.readFinished', { val: false, ack: true });
+				await this.setState('reports.status', { val: 'idle', ack: true });
+				await this.setState('reports.activeGroup', { val: '', ack: true });
+				this.resetTimers.delete(grp);
+			} catch {
+				// Ignore if shutting down
+			}
+		}, 3000);
+
+		this.resetTimers.set(grp, timer);
+	}
+
+	/**
+	 * Manual or scheduled report read.
+	 * Polling is automatically paused inside native engine (_ioLock).
+	 */
+	async executeReportRead(groupName, age) {
+		if (!this.engine) {
+			this.log.warn('Engine not available to read report.');
+			return;
+		}
+
+		this.log.info(`[Report Execution] Reading '${groupName}' (Age: ${age}). Polling paused, flags: started=true, finished=false`);
+		await this.setReportStartFlags(groupName);
+
+		try {
+			const resJson = this.engine.ReadReportWithAge(groupName, Number(age));
+			const res = JSON.parse(resJson);
+			if (res.ok) {
+				await this.handleReportReady(res);
+				await this.setReportFinishFlags(groupName, true);
+				this.log.info(`[Report Execution] '${groupName}' read successfully! Flags: started=false, finished=true (auto-resets in 3s)`);
+			} else {
+				this.log.error(`[Report Execution] '${groupName}' read failed: ${res.error}`);
+				await this.setReportFinishFlags(groupName, false);
+			}
+		} catch (err) {
+			this.log.error(`[Report Execution] Exception during ReadReportWithAge: ${err.message}`);
+			await this.setReportFinishFlags(groupName, false);
+		}
+	}
+
+	/**
+	 * Populates report values into ioBroker states.
+	 */
+	async handleReportReady(reportData) {
+		if (!reportData || !reportData.ok) {
+			return;
+		}
+
+		const group = (reportData.group || '').toLowerCase().replace(/[^a-zA-Z0-9_-]/g, '_');
+		const items = reportData.items || [];
+		const age = reportData.age;
+		const ts = reportData.timestamp;
+
+		await this.setState('reports.lastReportGroup', { val: reportData.group, ack: true });
+		await this.setState('reports.lastReportTime', { val: ts || new Date().toISOString(), ack: true });
+
+		for (const item of items) {
+			const sanitizedName = (item.name || '').replace(/[^a-zA-Z0-9_-]/g, '_');
+			const stateId = `reports.${group}.${sanitizedName}`;
+
+			let val = item.value;
+			// Check formula if configured
+			let map = null;
+			if (group === 'daily') map = this.dailyTagMap;
+			else if (group === 'hourly') map = this.hourlyTagMap;
+			else if (group === 'snapshot') map = this.snapshotTagMap;
+
+			let cfg = null;
+			if (map && map.has(item.name)) {
+				cfg = map.get(item.name);
+			} else {
+				const customKey = `${group}.${item.name}`;
+				if (this.customTagMap.has(customKey)) {
+					cfg = this.customTagMap.get(customKey);
+				}
+			}
+
+			if (cfg && cfg.formula && typeof val === 'number') {
+				val = this.applyFormula(cfg.formula, val);
+			}
+
+			await this.setState(stateId, { val, ack: true });
+		}
+	}
+
+	/**
+	 * Is called if a subscribed state changes.
+	 */
+	async onStateChange(id, state) {
+		if (!state || state.ack) return;
+
+		// Dynamic License Key / Expired Hash Update (Writable state: info.licenseKey)
+		if (id.endsWith('info.licenseKey')) {
+			const newKey = String(state.val || '').trim();
+			this.log.info(`[License Update] Processing submitted key/hash (${newKey.slice(0, 20)}...)...`);
+			if (this.engine) {
+				try {
+					const resJson = this.engine.SetLicenseKey(newKey);
+					const res = JSON.parse(resJson);
+					await this.setState('info.licenseValid', { val: Boolean(res.valid), ack: true });
+					await this.setState('info.licenseExpired', { val: Boolean(res.expired), ack: true });
+					await this.setState('info.licenseStatus', { val: res.status, ack: true });
+					await this.setState('info.licenseExpiresAt', { val: res.expiresAt || '', ack: true });
+					await this.setState('info.referenceTime', { val: res.referenceTime || '', ack: true });
+					await this.setState('info.licenseTimeSource', { val: res.timeSource || 'afc', ack: true });
+					const isReady = Boolean(res.valid && !res.expired);
+					await this.setState('info.ready', { val: isReady, ack: true });
+
+					if (isReady) {
+						await this.setState('info.connection', { val: true, ack: true });
+						await this.setState('info.pollActive', { val: true, ack: true });
+						await this.setState('info.pollPaused', { val: false, ack: true });
+						this.log.info(`[License Activated] Key valid! Status: ${res.status}. Modbus polling & scheduled reports resumed.`);
+					} else {
+						await this.setState('info.pollPaused', { val: true, ack: true });
+						this.log.warn(`[License Inactive] Status: ${res.status} - ${res.message}. Modbus I/O halted.`);
+					}
+					await this.setState(id, { val: newKey, ack: true });
+				} catch (err) {
+					this.log.error(`[License Error] Failed to evaluate license key: ${err.message}`);
+				}
+			}
+			return;
+		}
+
+		// Dynamic Manual Report Triggers for any group: "reports.set<GroupName>"
+		if (id.includes('.reports.set')) {
+			const match = id.match(/reports\.set([a-zA-Z0-9_-]+)$/);
+			if (match && state.val) {
+				const groupName = match[1];
+				if (groupName !== 'AgeNumber') {
+					const ageState = await this.getStateAsync('reports.setAgeNumber');
+					const age = ageState && ageState.val !== undefined ? Number(ageState.val) : 1;
+					await this.executeReportRead(groupName, age);
+					await this.setState(id, { val: false, ack: true });
+					return;
+				}
+			}
+		}
+
+		// Write to AFC Modbus Tag
+		if (this.engine) {
+			const stateParts = id.split('.');
+			const tagName = stateParts[stateParts.length - 1];
+			if (this.tagMap.has(tagName)) {
+				this.log.info(`Writing value ${state.val} to tag ${tagName}...`);
+				const resJson = this.engine.Write(tagName, JSON.stringify(state.val));
+				try {
+					const res = JSON.parse(resJson);
+					if (res.ok) {
+						await this.setState(id, { ack: true });
+					} else {
+						this.log.error(`Write to tag ${tagName} failed: ${res.error}`);
+					}
+				} catch {
+					// Raw response
+				}
+			}
+		}
+	}
+
+	/**
+	 * Is called when adapter shuts down.
+	 */
+	onUnload(callback) {
+		try {
+			for (const timer of this.pollingTimers.values()) {
+				clearInterval(timer);
+			}
+			this.pollingTimers.clear();
+
+			for (const timer of this.resetTimers.values()) {
+				clearTimeout(timer);
+			}
+			this.resetTimers.clear();
+
+			if (this.engine) {
+				this.engine.Stop();
+				this.engine = null;
+			}
+			this.setState('info.connection', { val: false, ack: true });
+			this.setState('info.pollActive', { val: false, ack: true });
+			this.setState('info.pollPaused', { val: false, ack: true });
+			this.log.info('Prosoft Flow adapter cleanly stopped.');
+			callback();
+		} catch {
+			callback();
+		}
+	}
+}
+
+if (require.main !== module) {
+	module.exports = (options) => new ProsoftFlow(options);
+} else {
+	new ProsoftFlow();
+}
+