@@ -192,12 +382,11 @@ getEventInjectionCode(nodeName) {
`;
}
- /**
- * Get client-side HTML injection code
- */
getHtmlInjectionCode(nodeName) {
- const htmlTemplate = this.getHtmlTemplate().replace(/`/g, '\\`').replace(/\$/g, '\\$');
-
+ const htmlTemplate = this.getHtmlTemplate()
+ .replace(/`/g, '\\`')
+ .replace(/\$/g, '\\$');
+
return `
// Asset HTML injection for ${nodeName}
window.EVOLV.nodes.${nodeName}.assetMenu.injectHtml = function() {
@@ -210,33 +399,53 @@ getEventInjectionCode(nodeName) {
`;
}
- /**
- * Returns the JS that injects the saveEditor function
- */
getSaveInjectionCode(nodeName) {
return `
- // Asset Save injection for ${nodeName}
+ // Asset save handler for ${nodeName}
window.EVOLV.nodes.${nodeName}.assetMenu.saveEditor = function(node) {
- console.log('Saving asset properties for ${nodeName}…');
- const fields = ['supplier','category','assetType','model','unit'];
- const errors = [];
- fields.forEach(f => {
- const el = document.getElementById(\`node-input-\${f}\`);
- node[f] = el ? el.value : '';
- });
- if (node.assetType && !node.unit) errors.push('Unit must be set when type is specified.');
- if (!node.unit) errors.push('Unit is required.');
- errors.forEach(e=>RED.notify(e,'error'));
-
- // --- DEBUG: show exactly what was saved ---
- const saved = fields.reduce((o,f) => { o[f] = node[f]; return o; }, {});
- console.log('→ assetMenu.saveEditor result:', saved);
+ console.log('Saving asset properties for ${nodeName}');
+ const menuAsset = window.EVOLV.nodes.${nodeName}.menuData.asset || {};
+ const categories = menuAsset.categories || {};
+ const defaultCategory = menuAsset.defaultCategory || Object.keys(categories)[0] || null;
+ const resolveCategoryKey = () => {
+ if (node.softwareType && categories[node.softwareType]) {
+ return node.softwareType;
+ }
+ if (node.category && categories[node.category]) {
+ return node.category;
+ }
+ return defaultCategory || '';
+ };
- return errors.length===0;
+ node.category = resolveCategoryKey();
+
+ const fields = ['supplier', 'assetType', 'model', 'unit'];
+ const errors = [];
+
+ fields.forEach((field) => {
+ const el = document.getElementById(\`node-input-\${field}\`);
+ node[field] = el ? el.value : '';
+ });
+
+ if (node.assetType && !node.unit) {
+ errors.push('Unit must be set when a type is specified.');
+ }
+ if (!node.unit) {
+ errors.push('Unit is required.');
+ }
+
+ errors.forEach((msg) => RED.notify(msg, 'error'));
+
+ const saved = fields.reduce((acc, field) => {
+ acc[field] = node[field];
+ return acc;
+ }, {});
+ console.log('[AssetMenu] save result:', saved);
+
+ return errors.length === 0;
};
`;
}
-
}
module.exports = AssetMenu;
diff --git a/src/menu/asset_DEPRECATED.js b/src/menu/asset_DEPRECATED.js
new file mode 100644
index 0000000..5f0fa3c
--- /dev/null
+++ b/src/menu/asset_DEPRECATED.js
@@ -0,0 +1,243 @@
+// asset.js
+const fs = require('fs');
+const path = require('path');
+
+
+class AssetMenu {
+ /** Define path where to find data of assets in constructor for now */
+ constructor(relPath = '../../datasets/assetData') {
+ this.baseDir = path.resolve(__dirname, relPath);
+ this.assetData = this._loadJSON('assetData');
+ }
+
+ _loadJSON(...segments) {
+ const filePath = path.resolve(this.baseDir, ...segments) + '.json';
+ try {
+ return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+ } catch (err) {
+ throw new Error(`Failed to load ${filePath}: ${err.message}`);
+ }
+ }
+
+ /**
+ * ADD THIS METHOD
+ * Compiles all menu data from the file system into a single nested object.
+ * This is run once on the server to pre-load everything.
+ * @returns {object} A comprehensive object with all menu options.
+ */
+ getAllMenuData() {
+ // load the raw JSON once
+ const data = this._loadJSON('assetData');
+ const allData = {};
+
+ data.suppliers.forEach(sup => {
+ allData[sup.name] = {};
+ sup.categories.forEach(cat => {
+ allData[sup.name][cat.name] = {};
+ cat.types.forEach(type => {
+ // here: store the full array of model objects, not just names
+ allData[sup.name][cat.name][type.name] = type.models;
+ });
+ });
+ });
+
+ return allData;
+ }
+
+ /**
+ * Convert the static initEditor function to a string that can be served to the client
+ * @param {string} nodeName - The name of the node type
+ * @returns {string} JavaScript code as a string
+ */
+getClientInitCode(nodeName) {
+ // step 1: get the two helper strings
+ const htmlCode = this.getHtmlInjectionCode(nodeName);
+ const dataCode = this.getDataInjectionCode(nodeName);
+ const eventsCode = this.getEventInjectionCode(nodeName);
+ const saveCode = this.getSaveInjectionCode(nodeName);
+
+
+ return `
+ // --- AssetMenu for ${nodeName} ---
+ window.EVOLV.nodes.${nodeName}.assetMenu =
+ window.EVOLV.nodes.${nodeName}.assetMenu || {};
+
+ ${htmlCode}
+ ${dataCode}
+ ${eventsCode}
+ ${saveCode}
+
+ // wire it all up when the editor loads
+ window.EVOLV.nodes.${nodeName}.assetMenu.initEditor = function(node) {
+ // ------------------ BELOW sequence is important! -------------------------------
+ console.log('Initializing asset properties for ${nodeName}…');
+ this.injectHtml();
+ // load the data and wire up events
+ // this will populate the fields and set up the event listeners
+ this.wireEvents(node);
+ // this will load the initial data into the fields
+ // this is important to ensure the fields are populated correctly
+ this.loadData(node);
+ };
+ `;
+
+}
+
+getDataInjectionCode(nodeName) {
+ return `
+ // Asset Data loader for ${nodeName}
+ window.EVOLV.nodes.${nodeName}.assetMenu.loadData = function(node) {
+ const data = window.EVOLV.nodes.${nodeName}.menuData.asset;
+ const elems = {
+ supplier: document.getElementById('node-input-supplier'),
+ category: document.getElementById('node-input-category'),
+ type: document.getElementById('node-input-assetType'),
+ model: document.getElementById('node-input-model'),
+ unit: document.getElementById('node-input-unit')
+ };
+ function populate(el, opts, sel) {
+ const old = el.value;
+ el.innerHTML = '
';
+ (opts||[]).forEach(o=>{
+ const opt = document.createElement('option');
+ opt.value = o; opt.textContent = o;
+ el.appendChild(opt);
+ });
+ el.value = sel||"";
+ if(el.value!==old) el.dispatchEvent(new Event('change'));
+ }
+ // initial population
+ populate(elems.supplier, Object.keys(data), node.supplier);
+ };
+ `
+ }
+
+getEventInjectionCode(nodeName) {
+ return `
+ // Asset Event wiring for ${nodeName}
+ window.EVOLV.nodes.${nodeName}.assetMenu.wireEvents = function(node) {
+ const data = window.EVOLV.nodes.${nodeName}.menuData.asset;
+ const elems = {
+ supplier: document.getElementById('node-input-supplier'),
+ category: document.getElementById('node-input-category'),
+ type: document.getElementById('node-input-assetType'),
+ model: document.getElementById('node-input-model'),
+ unit: document.getElementById('node-input-unit')
+ };
+ function populate(el, opts, sel) {
+ const old = el.value;
+ el.innerHTML = '
';
+ (opts||[]).forEach(o=>{
+ const opt = document.createElement('option');
+ opt.value = o; opt.textContent = o;
+ el.appendChild(opt);
+ });
+ el.value = sel||"";
+ if(el.value!==old) el.dispatchEvent(new Event('change'));
+ }
+ elems.supplier.addEventListener('change', ()=>{
+ populate(elems.category,
+ elems.supplier.value? Object.keys(data[elems.supplier.value]||{}) : [],
+ node.category);
+ });
+ elems.category.addEventListener('change', ()=>{
+ const s=elems.supplier.value, c=elems.category.value;
+ populate(elems.type,
+ (s&&c)? Object.keys(data[s][c]||{}) : [],
+ node.assetType);
+ });
+ elems.type.addEventListener('change', ()=>{
+ const s=elems.supplier.value, c=elems.category.value, t=elems.type.value;
+ const md = (s&&c&&t)? data[s][c][t]||[] : [];
+ populate(elems.model, md.map(m=>m.name), node.model);
+ });
+ elems.model.addEventListener('change', ()=>{
+ const s=elems.supplier.value, c=elems.category.value, t=elems.type.value, m=elems.model.value;
+ const md = (s&&c&&t)? data[s][c][t]||[] : [];
+ const entry = md.find(x=>x.name===m);
+ populate(elems.unit, entry? entry.units : [], node.unit);
+ });
+ };
+ `
+ }
+
+/**
+ * Generate HTML template for asset fields
+ */
+ getHtmlTemplate() {
+ return `
+
+
+
Asset selection
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ `;
+ }
+
+ /**
+ * Get client-side HTML injection code
+ */
+ getHtmlInjectionCode(nodeName) {
+ const htmlTemplate = this.getHtmlTemplate().replace(/`/g, '\\`').replace(/\$/g, '\\$');
+
+ return `
+ // Asset HTML injection for ${nodeName}
+ window.EVOLV.nodes.${nodeName}.assetMenu.injectHtml = function() {
+ const placeholder = document.getElementById('asset-fields-placeholder');
+ if (placeholder && !placeholder.hasChildNodes()) {
+ placeholder.innerHTML = \`${htmlTemplate}\`;
+ console.log('Asset HTML injected successfully');
+ }
+ };
+ `;
+ }
+
+ /**
+ * Returns the JS that injects the saveEditor function
+ */
+ getSaveInjectionCode(nodeName) {
+ return `
+ // Asset Save injection for ${nodeName}
+ window.EVOLV.nodes.${nodeName}.assetMenu.saveEditor = function(node) {
+ console.log('Saving asset properties for ${nodeName}…');
+ const fields = ['supplier','category','assetType','model','unit'];
+ const errors = [];
+ fields.forEach(f => {
+ const el = document.getElementById(\`node-input-\${f}\`);
+ node[f] = el ? el.value : '';
+ });
+ if (node.assetType && !node.unit) errors.push('Unit must be set when type is specified.');
+ if (!node.unit) errors.push('Unit is required.');
+ errors.forEach(e=>RED.notify(e,'error'));
+
+ // --- DEBUG: show exactly what was saved ---
+ const saved = fields.reduce((o,f) => { o[f] = node[f]; return o; }, {});
+ console.log('→ assetMenu.saveEditor result:', saved);
+
+ return errors.length===0;
+ };
+ `;
+ }
+
+}
+
+module.exports = AssetMenu;
diff --git a/src/menu/index.js b/src/menu/index.js
index a6def7f..1a051d2 100644
--- a/src/menu/index.js
+++ b/src/menu/index.js
@@ -2,13 +2,17 @@ const AssetMenu = require('./asset.js');
const { TagcodeApp, DynamicAssetMenu } = require('./tagcodeApp.js');
const LoggerMenu = require('./logger.js');
const PhysicalPositionMenu = require('./physicalPosition.js');
+const ConfigManager = require('../configs');
class MenuManager {
constructor() {
this.registeredMenus = new Map();
+ this.configManager = new ConfigManager('../configs');
// Register factory functions
- this.registerMenu('asset', () => new AssetMenu()); // static menu to be replaced by dynamic one but later
+ this.registerMenu('asset', (nodeName) => new AssetMenu({
+ softwareType: this._getSoftwareType(nodeName)
+ })); // static menu to be replaced by dynamic one but later
//this.registerMenu('asset', (nodeName) => new DynamicAssetMenu(nodeName, new TagcodeApp()));
this.registerMenu('logger', () => new LoggerMenu());
this.registerMenu('position', () => new PhysicalPositionMenu());
@@ -23,6 +27,20 @@ class MenuManager {
this.registeredMenus.set(menuType, menuFactory);
}
+ _getSoftwareType(nodeName) {
+ if (!nodeName) {
+ return null;
+ }
+
+ try {
+ const config = this.configManager.getConfig(nodeName);
+ return config?.functionality?.softwareType || nodeName;
+ } catch (error) {
+ console.warn(`Unable to determine softwareType for ${nodeName}: ${error.message}`);
+ return nodeName;
+ }
+ }
+
/**
* Create a complete endpoint script with data and initialization functions
* @param {string} nodeName - The name of the node type
@@ -54,7 +72,7 @@ class MenuManager {
try {
const handler = instantiatedMenus.get(menuType);
if (handler && typeof handler.getAllMenuData === 'function') {
- menuData[menuType] = handler.getAllMenuData();
+ menuData[menuType] = handler.getAllMenuData(nodeName);
} else {
// Provide default empty data if method doesn't exist
menuData[menuType] = {};
@@ -172,4 +190,4 @@ class MenuManager {
}
}
-module.exports = MenuManager;
\ No newline at end of file
+module.exports = MenuManager;
diff --git a/src/menu/physicalPosition.js b/src/menu/physicalPosition.js
index effbe96..aab35e9 100644
--- a/src/menu/physicalPosition.js
+++ b/src/menu/physicalPosition.js
@@ -6,9 +6,9 @@ class PhysicalPositionMenu {
return {
positionGroups: [
{ group: 'Positional', options: [
- { value: 'upstream', label: '← Upstream', icon: '←'},
+ { value: 'upstream', label: '→ Upstream', icon: '→'}, //flow is then typically left to right
{ value: 'atEquipment', label: '⊥ in place' , icon: '⊥' },
- { value: 'downstream', label: '→ Downstream' , icon: '→' }
+ { value: 'downstream', label: '← Downstream' , icon: '←' }
]
}
],
diff --git a/src/pid/PIDController.js b/src/pid/PIDController.js
new file mode 100644
index 0000000..1f07ac4
--- /dev/null
+++ b/src/pid/PIDController.js
@@ -0,0 +1,279 @@
+'use strict';
+
+/**
+ * Discrete PID controller with optional derivative filtering and integral limits.
+ * Sample times are expressed in milliseconds to align with Node.js timestamps.
+ */
+class PIDController {
+ constructor(options = {}) {
+ const {
+ kp = 1,
+ ki = 0,
+ kd = 0,
+ sampleTime = 1000,
+ derivativeFilter = 0.15,
+ outputMin = Number.NEGATIVE_INFINITY,
+ outputMax = Number.POSITIVE_INFINITY,
+ integralMin = null,
+ integralMax = null,
+ derivativeOnMeasurement = true,
+ autoMode = true
+ } = options;
+
+ this.kp = 0;
+ this.ki = 0;
+ this.kd = 0;
+
+ this.setTunings({ kp, ki, kd });
+ this.setSampleTime(sampleTime);
+ this.setOutputLimits(outputMin, outputMax);
+ this.setIntegralLimits(integralMin, integralMax);
+ this.setDerivativeFilter(derivativeFilter);
+
+ this.derivativeOnMeasurement = Boolean(derivativeOnMeasurement);
+ this.autoMode = Boolean(autoMode);
+
+ this.reset();
+ }
+
+ /**
+ * Update controller gains at runtime.
+ * Accepts partial objects, e.g. setTunings({ kp: 2.0 }).
+ */
+ setTunings({ kp = this.kp, ki = this.ki, kd = this.kd } = {}) {
+ [kp, ki, kd].forEach((gain, index) => {
+ if (!Number.isFinite(gain)) {
+ const label = ['kp', 'ki', 'kd'][index];
+ throw new TypeError(`${label} must be a finite number`);
+ }
+ });
+
+ this.kp = kp;
+ this.ki = ki;
+ this.kd = kd;
+ return this;
+ }
+
+ /**
+ * Set the controller execution interval in milliseconds.
+ */
+ setSampleTime(sampleTimeMs = this.sampleTime) {
+ if (!Number.isFinite(sampleTimeMs) || sampleTimeMs <= 0) {
+ throw new RangeError('sampleTime must be a positive number of milliseconds');
+ }
+
+ this.sampleTime = sampleTimeMs;
+ return this;
+ }
+
+ /**
+ * Constrain controller output.
+ */
+ setOutputLimits(min = this.outputMin, max = this.outputMax) {
+ if (!Number.isFinite(min) && min !== Number.NEGATIVE_INFINITY) {
+ throw new TypeError('outputMin must be finite or -Infinity');
+ }
+ if (!Number.isFinite(max) && max !== Number.POSITIVE_INFINITY) {
+ throw new TypeError('outputMax must be finite or Infinity');
+ }
+ if (min >= max) {
+ throw new RangeError('outputMin must be smaller than outputMax');
+ }
+
+ this.outputMin = min;
+ this.outputMax = max;
+ this.lastOutput = this._clamp(this.lastOutput ?? 0, this.outputMin, this.outputMax);
+ return this;
+ }
+
+ /**
+ * Constrain the accumulated integral term.
+ */
+ setIntegralLimits(min = this.integralMin ?? null, max = this.integralMax ?? null) {
+ if (min !== null && !Number.isFinite(min)) {
+ throw new TypeError('integralMin must be null or a finite number');
+ }
+ if (max !== null && !Number.isFinite(max)) {
+ throw new TypeError('integralMax must be null or a finite number');
+ }
+ if (min !== null && max !== null && min > max) {
+ throw new RangeError('integralMin must be smaller than integralMax');
+ }
+
+ this.integralMin = min;
+ this.integralMax = max;
+ this.integral = this._applyIntegralLimits(this.integral ?? 0);
+ return this;
+ }
+
+ /**
+ * Configure exponential filter applied to the derivative term.
+ * Value 0 disables filtering, 1 keeps the previous derivative entirely.
+ */
+ setDerivativeFilter(value = this.derivativeFilter ?? 0) {
+ if (!Number.isFinite(value) || value < 0 || value > 1) {
+ throw new RangeError('derivativeFilter must be between 0 and 1');
+ }
+
+ this.derivativeFilter = value;
+ return this;
+ }
+
+ /**
+ * Switch between automatic (closed-loop) and manual mode.
+ */
+ setMode(mode) {
+ if (mode !== 'automatic' && mode !== 'manual') {
+ throw new Error('mode must be either "automatic" or "manual"');
+ }
+
+ this.autoMode = mode === 'automatic';
+ return this;
+ }
+
+ /**
+ * Force a manual output (typically when in manual mode).
+ */
+ setManualOutput(value) {
+ this._assertNumeric('manual output', value);
+ this.lastOutput = this._clamp(value, this.outputMin, this.outputMax);
+ return this.lastOutput;
+ }
+
+ /**
+ * Reset dynamic state (integral, derivative memory, timestamps).
+ */
+ reset(state = {}) {
+ const {
+ integral = 0,
+ lastOutput = 0,
+ timestamp = null
+ } = state;
+
+ this.integral = this._applyIntegralLimits(Number.isFinite(integral) ? integral : 0);
+ this.prevError = null;
+ this.prevMeasurement = null;
+ this.lastOutput = this._clamp(
+ Number.isFinite(lastOutput) ? lastOutput : 0,
+ this.outputMin ?? Number.NEGATIVE_INFINITY,
+ this.outputMax ?? Number.POSITIVE_INFINITY
+ );
+ this.lastTimestamp = Number.isFinite(timestamp) ? timestamp : null;
+ this.derivativeState = 0;
+
+ return this;
+ }
+
+ /**
+ * Execute one control loop iteration.
+ */
+ update(setpoint, measurement, timestamp = Date.now()) {
+ this._assertNumeric('setpoint', setpoint);
+ this._assertNumeric('measurement', measurement);
+ this._assertNumeric('timestamp', timestamp);
+
+ if (!this.autoMode) {
+ this.prevError = setpoint - measurement;
+ this.prevMeasurement = measurement;
+ this.lastTimestamp = timestamp;
+ return this.lastOutput;
+ }
+
+ if (this.lastTimestamp !== null && (timestamp - this.lastTimestamp) < this.sampleTime) {
+ return this.lastOutput;
+ }
+
+ const elapsedMs = this.lastTimestamp === null ? this.sampleTime : (timestamp - this.lastTimestamp);
+ const dtSeconds = Math.max(elapsedMs / 1000, Number.EPSILON);
+
+ const error = setpoint - measurement;
+ this.integral = this._applyIntegralLimits(this.integral + error * dtSeconds);
+
+ const derivative = this._computeDerivative({ error, measurement, dtSeconds });
+ this.derivativeState = this.derivativeFilter === 0
+ ? derivative
+ : this.derivativeState + (derivative - this.derivativeState) * (1 - this.derivativeFilter);
+
+ const output = (this.kp * error) + (this.ki * this.integral) + (this.kd * this.derivativeState);
+ this.lastOutput = this._clamp(output, this.outputMin, this.outputMax);
+
+ this.prevError = error;
+ this.prevMeasurement = measurement;
+ this.lastTimestamp = timestamp;
+
+ return this.lastOutput;
+ }
+
+ /**
+ * Inspect controller state for diagnostics or persistence.
+ */
+ getState() {
+ return {
+ kp: this.kp,
+ ki: this.ki,
+ kd: this.kd,
+ sampleTime: this.sampleTime,
+ outputLimits: { min: this.outputMin, max: this.outputMax },
+ integralLimits: { min: this.integralMin, max: this.integralMax },
+ derivativeFilter: this.derivativeFilter,
+ derivativeOnMeasurement: this.derivativeOnMeasurement,
+ autoMode: this.autoMode,
+ integral: this.integral,
+ lastOutput: this.lastOutput,
+ lastTimestamp: this.lastTimestamp
+ };
+ }
+
+ getLastOutput() {
+ return this.lastOutput;
+ }
+
+ _computeDerivative({ error, measurement, dtSeconds }) {
+ if (!(dtSeconds > 0) || !Number.isFinite(dtSeconds)) {
+ return 0;
+ }
+
+ if (this.derivativeOnMeasurement && this.prevMeasurement !== null) {
+ return -(measurement - this.prevMeasurement) / dtSeconds;
+ }
+
+ if (this.prevError === null) {
+ return 0;
+ }
+
+ return (error - this.prevError) / dtSeconds;
+ }
+
+ _applyIntegralLimits(value) {
+ if (!Number.isFinite(value)) {
+ return 0;
+ }
+
+ let result = value;
+ if (this.integralMin !== null && result < this.integralMin) {
+ result = this.integralMin;
+ }
+ if (this.integralMax !== null && result > this.integralMax) {
+ result = this.integralMax;
+ }
+ return result;
+ }
+
+ _assertNumeric(label, value) {
+ if (!Number.isFinite(value)) {
+ throw new TypeError(`${label} must be a finite number`);
+ }
+ }
+
+ _clamp(value, min, max) {
+ if (value < min) {
+ return min;
+ }
+ if (value > max) {
+ return max;
+ }
+ return value;
+ }
+}
+
+module.exports = PIDController;
diff --git a/src/pid/examples.js b/src/pid/examples.js
new file mode 100644
index 0000000..ea9cf63
--- /dev/null
+++ b/src/pid/examples.js
@@ -0,0 +1,87 @@
+const { PIDController } = require('./index');
+
+console.log('=== PID CONTROLLER EXAMPLES ===\n');
+console.log('This guide shows how to instantiate, tune, and operate the PID helper.\n');
+
+// ====================================
+// EXAMPLE 1: FLOW CONTROL LOOP
+// ====================================
+console.log('--- Example 1: Pump speed control ---');
+
+const pumpController = new PIDController({
+ kp: 1.1,
+ ki: 0.35,
+ kd: 0.08,
+ sampleTime: 250, // ms
+ outputMin: 0,
+ outputMax: 100,
+ derivativeFilter: 0.2
+});
+
+const pumpSetpoint = 75; // desired flow percentage
+let pumpFlow = 20;
+const pumpStart = Date.now();
+
+for (let i = 0; i < 10; i += 1) {
+ const timestamp = pumpStart + (i + 1) * pumpController.sampleTime;
+ const controlSignal = pumpController.update(pumpSetpoint, pumpFlow, timestamp);
+
+ // Simple first-order plant approximation
+ pumpFlow += (controlSignal - pumpFlow) * 0.12;
+ pumpFlow -= (pumpFlow - pumpSetpoint) * 0.05; // disturbance rejection
+
+ console.log(
+ `Cycle ${i + 1}: output=${controlSignal.toFixed(2)}% | flow=${pumpFlow.toFixed(2)}%`
+ );
+}
+
+console.log('Pump loop state:', pumpController.getState(), '\n');
+
+// ====================================
+// EXAMPLE 2: TANK LEVEL WITH MANUAL/AUTO
+// ====================================
+console.log('--- Example 2: Tank level handover ---');
+
+const tankController = new PIDController({
+ kp: 2.0,
+ ki: 0.5,
+ kd: 0.25,
+ sampleTime: 400,
+ derivativeFilter: 0.25,
+ outputMin: 0,
+ outputMax: 1
+}).setIntegralLimits(-0.3, 0.3);
+
+tankController.setMode('manual');
+tankController.setManualOutput(0.4);
+console.log(`Manual output locked at ${tankController.getLastOutput().toFixed(2)}\n`);
+
+tankController.setMode('automatic');
+
+let level = 0.2;
+const levelSetpoint = 0.8;
+const tankStart = Date.now();
+
+for (let step = 0; step < 8; step += 1) {
+ const timestamp = tankStart + (step + 1) * tankController.sampleTime;
+ const output = tankController.update(levelSetpoint, level, timestamp);
+
+ // Integrating process with slight disturbance
+ level += (output - 0.5) * 0.18;
+ level += 0.02; // inflow bump
+ level = Math.max(0, Math.min(1, level));
+
+ console.log(
+ `Cycle ${step + 1}: output=${output.toFixed(3)} | level=${level.toFixed(3)}`
+ );
+}
+
+console.log('\nBest practice tips:');
+console.log(' - Call update() on a fixed interval (sampleTime).');
+console.log(' - Clamp output and integral to avoid windup.');
+console.log(' - Use setMode("manual") during maintenance or bump-less transfer.');
+
+module.exports = {
+ pumpController,
+ tankController
+};
diff --git a/src/pid/index.js b/src/pid/index.js
new file mode 100644
index 0000000..7f2c82b
--- /dev/null
+++ b/src/pid/index.js
@@ -0,0 +1,11 @@
+const PIDController = require('./PIDController');
+
+/**
+ * Convenience factory for one-line instantiation.
+ */
+const createPidController = (options) => new PIDController(options);
+
+module.exports = {
+ PIDController,
+ createPidController
+};
diff --git a/src/state/movementManager.js b/src/state/movementManager.js
index 424c628..f949f48 100644
--- a/src/state/movementManager.js
+++ b/src/state/movementManager.js
@@ -81,11 +81,8 @@ class movementManager {
const direction = targetPosition > this.currentPosition ? 1 : -1;
const distance = Math.abs(targetPosition - this.currentPosition);
- // Speed is a fraction [0,1] of full-range per second
- this.speed = Math.min(Math.max(this.speed, 0), 1);
- const fullRange = this.maxPosition - this.minPosition;
- const velocity = this.speed * fullRange; // units per second
- if (velocity === 0) {
+ const velocity = this.getVelocity(); // units per second
+ if (velocity <= 0) {
return reject(new Error("Movement aborted: zero speed"));
}
@@ -154,11 +151,11 @@ class movementManager {
const direction = targetPosition > this.currentPosition ? 1 : -1;
const distance = Math.abs(targetPosition - this.currentPosition);
- // Ensure speed is a percentage [0, 1]
- this.speed = Math.min(Math.max(this.speed, 0), 1);
-
- // Calculate duration based on percentage of distance per second
- const duration = 1 / this.speed; // 1 second for 100% of the distance
+ const velocity = this.getVelocity();
+ if (velocity <= 0) {
+ return reject(new Error("Movement aborted: zero speed"));
+ }
+ const duration = distance / velocity;
this.timeleft = duration; //set this so other classes can use it
this.logger.debug(
@@ -217,13 +214,16 @@ class movementManager {
const direction = targetPosition > this.currentPosition ? 1 : -1;
const totalDistance = Math.abs(targetPosition - this.currentPosition);
const startPosition = this.currentPosition;
- this.speed = Math.min(Math.max(this.speed, 0), 1);
+ const velocity = this.getVelocity();
+ if (velocity <= 0) {
+ return reject(new Error("Movement aborted: zero speed"));
+ }
const easeFunction = (t) =>
t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
let elapsedTime = 0;
- const duration = totalDistance / this.speed;
+ const duration = totalDistance / velocity;
this.timeleft = duration;
const interval = this.interval;
@@ -273,6 +273,20 @@ class movementManager {
constrain(value) {
return Math.min(Math.max(value, this.minPosition), this.maxPosition);
}
+
+ getNormalizedSpeed() {
+ const rawSpeed = Number.isFinite(this.speed) ? this.speed : 0;
+ const clampedSpeed = Math.max(0, rawSpeed);
+ const hasMax = Number.isFinite(this.maxSpeed) && this.maxSpeed > 0;
+ const effectiveSpeed = hasMax ? Math.min(clampedSpeed, this.maxSpeed) : clampedSpeed;
+ return effectiveSpeed / 100; // convert %/s -> fraction of range per second
+ }
+
+ getVelocity() {
+ const normalizedSpeed = this.getNormalizedSpeed();
+ const fullRange = this.maxPosition - this.minPosition;
+ return normalizedSpeed * fullRange;
+ }
}
module.exports = movementManager;
diff --git a/src/state/state.js b/src/state/state.js
index 2ad0229..abe7508 100644
--- a/src/state/state.js
+++ b/src/state/state.js
@@ -52,7 +52,11 @@ class state{
return this.stateManager.getRunTimeHours();
}
+ getMaintenanceTimeHours(){
+ return this.stateManager.getMaintenanceTimeHours();
+ }
+
async moveTo(targetPosition) {
// Check for invalid conditions and throw errors
diff --git a/src/state/stateConfig.json b/src/state/stateConfig.json
index 99d398f..548e797 100644
--- a/src/state/stateConfig.json
+++ b/src/state/stateConfig.json
@@ -127,7 +127,7 @@
}
},
"maxSpeed": {
- "default": 10,
+ "default": 1000,
"rules": {
"type": "number",
"description": "Maximum speed setting."
@@ -205,6 +205,10 @@
{
"value": "off",
"description": "Machine is off."
+ },
+ {
+ "value": "maintenance",
+ "description": "Machine locked for inspection or repair; automatic control disabled."
}
],
"description": "Current state of the machine."
@@ -216,7 +220,7 @@
"type": "object",
"schema": {
"idle": {
- "default": ["starting", "off","emergencystop"],
+ "default": ["starting", "off","emergencystop","maintenance"],
"rules":{
"type": "set",
"itemType": "string",
@@ -280,7 +284,7 @@
}
},
"off": {
- "default": ["idle","emergencystop"],
+ "default": ["idle","emergencystop","maintenance"],
"rules":{
"type": "set",
"itemType": "string",
@@ -288,12 +292,20 @@
}
},
"emergencystop": {
- "default": ["idle","off"],
+ "default": ["idle","off","maintenance"],
"rules":{
"type": "set",
"itemType": "string",
"description": "Allowed transitions from emergency stop state."
}
+ },
+ "maintenance": {
+ "default": ["maintenance","idle","off"],
+ "rules":{
+ "type": "set",
+ "itemType": "string",
+ "description": "Allowed transitions for maintenance mode"
+ }
}
},
"description": "Allowed transitions between states."
diff --git a/src/state/stateManager.js b/src/state/stateManager.js
index 4549308..9b3139f 100644
--- a/src/state/stateManager.js
+++ b/src/state/stateManager.js
@@ -48,10 +48,14 @@ class stateManager {
// Define valid transitions (can be extended dynamically if needed)
this.validTransitions = config.state.allowedTransitions;
- // NEW: Initialize runtime tracking
+ //runtime tracking
this.runTimeHours = 0; // cumulative runtime in hours
this.runTimeStart = null; // timestamp when active state began
+ //maintenance tracking
+ this.maintenanceTimeStart = null; //timestamp when active state began
+ this.maintenanceTimeHours = 0; //cumulative
+
// Define active states (runtime counts only in these states)
this.activeStates = config.state.activeStates;
}
@@ -59,7 +63,7 @@ class stateManager {
getCurrentState() {
return this.currentState;
}
-
+
transitionTo(newState,signal) {
return new Promise((resolve, reject) => {
if (signal && signal.aborted) {
@@ -73,8 +77,9 @@ class stateManager {
); //go back early and reject promise
}
- // NEW: Handle runtime tracking based on active states
+ //Time tracking based on active states
this.handleRuntimeTracking(newState);
+ this.handleMaintenancetimeTracking(newState);
const transitionDuration = this.transitionTimes[this.currentState] || 0; // Default to 0 if no transition time
this.logger.debug(
@@ -100,7 +105,7 @@ class stateManager {
}
handleRuntimeTracking(newState) {
- // NEW: Handle runtime tracking based on active states
+ //Handle runtime tracking based on active states
const wasActive = this.activeStates.has(this.currentState);
const willBeActive = this.activeStates.has(newState);
if (wasActive && !willBeActive && this.runTimeStart) {
@@ -120,6 +125,28 @@ class stateManager {
}
}
+ handleMaintenancetimeTracking(newState) {
+ //is this maintenance time ?
+ const wasActive = (this.currentState == "maintenance"? true:false);
+ const willBeActive = ( newState == "maintenance" ? true:false );
+
+ if (wasActive && this.maintenanceTimeStart) {
+ // stop runtime timer and accumulate elapsed time
+ const elapsed = (Date.now() - this.maintenanceTimeStart) / 3600000; // hours
+ this.maintenanceTimeHours += elapsed;
+ this.maintenanceTimeStart = null;
+ this.logger.debug(
+ `Maintenance timer stopped; elapsed=${elapsed.toFixed(
+ 3
+ )}h, total=${this.maintenanceTimeHours.toFixed(3)}h.`
+ );
+ } else if (willBeActive && !this.runTimeStart) {
+ // starting new runtime
+ this.maintenanceTimeStart = Date.now();
+ this.logger.debug("Runtime timer started.");
+ }
+ }
+
isValidTransition(newState) {
this.logger.debug(
`Check 1 Transition valid ? From ${
@@ -150,7 +177,6 @@ class stateManager {
return this.descriptions[state] || "No description available.";
}
- // NEW: Getter to retrieve current cumulative runtime (active time) in hours.
getRunTimeHours() {
// If currently active add the ongoing duration.
let currentElapsed = 0;
@@ -159,6 +185,15 @@ class stateManager {
}
return this.runTimeHours + currentElapsed;
}
+
+ getMaintenanceTimeHours() {
+ // If currently active add the ongoing duration.
+ let currentElapsed = 0;
+ if (this.maintenanceTimeStart) {
+ currentElapsed = (Date.now() - this.maintenanceTimeStart) / 3600000;
+ }
+ return this.maintenanceTimeHours + currentElapsed;
+ }
}
module.exports = stateManager;