@machinemetrics/io-adapter-lib 2.32.0

package/lib/transform/accumulate.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const _ = require('lodash');
+const TransformState = require('./transformState');
+
+/**
+ * Increments an accumulator by each incoming input amount.
+ *
+ * For every incoming value, the value will be added to the internal accumulator.
+ * This will happen even for repeated/non-state-changing inputs.  Make sure to control the
+ * input via transforms like resample, value-increase-diff, etc.
+ *
+ * The first value encountered after becoming available will be ignored, priming the accumulator state
+ */
+class AccumulateFilter extends TransformState {
+  constructor({ engine, path, args: { reset = {} } }) {
+    super();
+
+    this.engine = engine;
+    this.resetExpression = reset.compiledExpression;
+    this.resetSources = engine.expressionService.expressionTriggers(`${path}.reset`);
+
+    this.defaultValue = false;
+    this.initReset();
+  }
+
+  static op = 'accumulate';
+
+  static create(args) {
+    return new AccumulateFilter(args);
+  }
+
+  static parseConfig(configUtil, defn) {
+    configUtil.requireObjectParams(defn.args, 'accumulate', {
+      optional: true,
+      availableAttributes: ['reset'],
+    });
+
+    let reset = defn.args.reset;
+    if (reset !== undefined) {
+      try {
+        const expression = reset.toString();
+        const compiledExpression = configUtil.compileExpression(expression, this.op);
+        reset = { expression, compiledExpression };
+      } catch (err) {
+        configUtil.throwConfigError(`Problem evaluating expression: ${err.message}`, this.op);
+      }
+    }
+
+    defn.args = { reset };
+  }
+
+  initReset() {
+    this.value = false;
+    this.previousValue = false;
+    this.count = 0;
+  }
+
+  update(context, value, time) {
+    this.lastSuppliedValue = value;
+    this.lastSampleTime = time;
+    if (!this.available) {
+      this.available = true;
+    }
+
+    this.filter(context, +value, time);
+    this.emitUpdate(context);
+  }
+
+  emitUpdate(context) {
+    this.count += this.value;
+
+    // While resetExpression evals true, force count to 0
+    if (this.resetExpression) {
+      const localState = { this: this.coumt };
+      const unavailTerm = _.reduce(this.resetSources, (res, name) => {
+        const state = this.engine.getState(name);
+        localState[name] = state?.value;
+        return res || !state || !state.available;
+      }, false);
+
+      if (!unavailTerm && this.resetExpression.evaluate(localState)) {
+        this.count = 0;
+        this.emit('update', this.count, this.lastSampleTime, context);
+        return;
+      }
+    }
+
+    this.emit('update', this.count, this.lastSampleTime, context);
+  }
+
+  setUnavailable(context, time) {
+    super.setUnavailable(context, time);
+    this.initReset();
+  }
+}
+
+module.exports = AccumulateFilter;

package/lib/transform/average.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const _ = require('lodash');
+const TransformState = require('./transformState');
+const RingBuffer = require('./util/ringBuffer');
+
+// TODO: Consider changing count implementation to support non-clocked input
+
+/**
+ * For each incoming sample, emits the average of the last N samples seen.
+ *
+ * Average is based on the Simple Moving Average.
+ * See: https://en.wikipedia.org/wiki/Moving_average#Simple_moving_average
+ */
+class AverageFilter extends TransformState {
+  constructor(sampleCount) {
+    super();
+
+    this.size = sampleCount;
+    this.initReset();
+  }
+
+  static op = 'average';
+
+  static create(args) {
+    return new AverageFilter(args.args.count);
+  }
+
+  static parseConfig(configUtil, defn) {
+    const count = _.get(defn.args, 'count');
+    configUtil.requirePositive(count, this.op, this.op);
+
+    defn.args = { count };
+  }
+
+  initReset() {
+    this.buffer = new RingBuffer(this.size);
+    this.sma = 0;
+  }
+
+  filter(context, value, time) {
+    value /= this.size;
+    this.sma += value;
+    this.sma -= this.buffer.get(this.buffer.getTailIndex());
+    this.buffer.push(value);
+
+    this.commitValue(context, this.sma, time);
+  }
+
+  setUnavailable(context, time) {
+    super.setUnavailable(context, time);
+    this.initReset();
+  }
+}
+
+module.exports = AverageFilter;

package/lib/transform/debounce.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const TransformState = require('./transformState');
+
+/**
+ * Filters out spurious high and low signals with duration less than the debounce window.
+ *
+ * Effectively "latches" a digital signal to the predominant underlying signal.
+ * This filter is implemented with the same logic as the on-delay and off-delay filters, with the
+ * particular version chosen based on the current latched signal.
+ *
+ * This transform introduces lag into the signal equal to the window size.
+ */
+class DebounceFilter extends TransformState {
+  constructor(window) {
+    super();
+
+    this.window = window;
+    this.defaultValue = false;
+    this.initReset();
+  }
+
+  static op = 'debounce';
+
+  static create(args) {
+    return new DebounceFilter(args.args.window);
+  }
+
+  static parseConfig(configUtil, defn) {
+    const window = defn.args.window ?? defn.args[defn.func];
+    configUtil.requirePositive(window, this.op, this.op);
+
+    defn.args = { window };
+  }
+
+  initReset() {
+    this.value = false;
+    this.transitionTime = null;
+    this.lowStartTime = null;
+    this.highStartTime = null;
+    this.pendingChangeTime = null;
+  }
+
+  supportsPendingChanges() {
+    return true;
+  }
+
+  filter(context, value, time) {
+    if (this.value) {
+      this.highStartTime = null;
+      this.filterOff(context, value, time);
+    } else {
+      this.lowStartTime = null;
+      this.filterOn(context, value, time);
+    }
+  }
+
+  filterOff(context, value, time) {
+    // Whenever the real signal transitions to low, record a marker at that time.
+    if (!value && this.lowStartTime === null) {
+      this.lowStartTime = time;
+      this.pendingChangeTime = time + this.window;
+    }
+
+    const lowStart = this.lowStartTime || 0;
+    const insideOffDelayWindow = lowStart + this.window >= time;
+
+    if (value || (!value && time >= this.pendingChangeTime)) {
+      this.pendingChangeTime = null;
+    } else if (insideOffDelayWindow && !value) {
+      // When incoming signal is low but has not been held low long enough, skip
+      return;
+    }
+
+    if (!insideOffDelayWindow && value && this.value && this.lowStartTime !== null) {
+      // If we're outside of the delay window AND both the incoming signal and held signal are high,
+      // AND we recorded a lowStartTime marker, then there is high->low transition between this sample
+      // and the previous sample that must be recognized.
+
+      const offTime = lowStart + this.window;
+      this.commitValue(context, false, offTime);
+      this.emitCommittedUpdate(context);
+
+      this.lowStartTime = null;
+      return;
+    } else if (!insideOffDelayWindow && !value && this.value && this.lowStartTime !== null) {
+      const offTime = lowStart + this.window;
+      this.commitValue(context, false, offTime);
+      this.emitCommittedUpdate(context);
+
+      this.lowStartTime = null;
+    }
+
+    // When the real signal transitions to high, clear the low signal marker.
+    if (value && this.lowStartTime !== null) {
+      this.lowStartTime = null;
+    }
+
+    this.commitValue(context, value, time);
+  }
+
+  filterOn(context, value, time) {
+    // Whenever the real signal transitions to high, record a marker at that time.
+    if (value && this.highStartTime === null) {
+      this.highStartTime = time;
+      this.pendingChangeTime = time + this.window;
+    }
+
+    const highStart = this.highStartTime || 0;
+    const insideOnDelayWindow = highStart + this.window >= time;
+
+    if (!value || (value && time >= this.pendingChangeTime)) {
+      this.pendingChangeTime = null;
+    } else if (insideOnDelayWindow && value) {
+      // When incoming signal is high but has not been held high long enough, skip
+      return;
+    }
+
+    if (!insideOnDelayWindow && !value && !this.value && this.highStartTime !== null) {
+      // If we're outside of the delay window AND both the incoming signal and held signal are low,
+      // AND we recorded a highStartTime marker, then there is low->high transition between this sample
+      // and the previous sample that must be recognized.
+
+      const onTime = highStart + this.window;
+      this.commitValue(context, true, onTime);
+      this.emitCommittedUpdate(context);
+
+      this.highStartTime = null;
+      return;
+    } else if (!insideOnDelayWindow && value && !this.value && this.highStartTime !== null) {
+      const onTime = highStart + this.window;
+      this.commitValue(context, true, onTime);
+      this.emitCommittedUpdate(context);
+
+      this.highStartTime = null;
+    }
+
+    // When the real signal transitions to low, clear the high signal marker.
+    if (!value && this.highStartTime !== null) {
+      this.highStartTime = null;
+    }
+
+    this.commitValue(context, value, time);
+  }
+
+  setUnavailable(context, time) {
+    super.setUnavailable(context, time);
+    this.initReset();
+  }
+}
+
+module.exports = DebounceFilter;

package/lib/transform/downsample.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const TransformState = require('./transformState');
+
+// Deprecated: Use resample instead
+
+/**
+ * Takes an analog stream and downsamples it to a lower sample rate.
+ *
+ * Downsampling is calculated by taking every N-th sample seen in the stream.  If N is not a whole number,
+ * new samples will be interpolated between adjacent samples.
+ */
+class DownsampleFilter extends TransformState {
+  constructor(factor) {
+    super();
+
+    this.factor = factor;
+    this.initReset();
+  }
+
+  static op = 'downsample';
+
+  static create(args) {
+    return new DownsampleFilter(args.args.factor);
+  }
+
+  static parseConfig(configUtil, defn) {
+    const { value: factor, usingShorthand } = configUtil.getArgOrShorthand(defn, 'factor');
+    configUtil.requirePositive(factor, usingShorthand ? this.op : 'factor', this.op);
+
+    defn.args = { factor };
+  }
+
+  initReset() {
+    this.count = 0;
+    this.previousValue = 0;
+    this.previousTime = 0;
+  }
+
+  filter(context, value, time) {
+    this.count += 1;
+
+    if (this.count === this.factor) {
+      this.commitValue(context, value, time);
+    } else if (this.count > this.factor) {
+      const lerp = this.count - this.factor;
+      const lerpValue = (this.previousValue * lerp) + (value * (1 - lerp));
+      const lerpTime = (this.previousTime * lerp) + (time * (1 - lerp));
+      this.commitValue(context, lerpValue, lerpTime);
+    }
+
+    this.previousValue = value;
+    this.previousTime = time;
+  }
+
+  emitUpdate(context) {
+    if (this.count >= this.factor) {
+      this.count -= this.factor;
+      super.emitCommittedUpdate(context);
+    }
+  }
+
+  setUnavailable(context, time) {
+    super.setUnavailable(context, time);
+    this.initReset();
+  }
+}
+
+module.exports = DownsampleFilter;

package/lib/transform/edge.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const TransformState = require('./transformState');
+
+/**
+ * Finds all edges (T->F and F->T) in a digital stream.
+ *
+ * For every incoming sample, the outgoing sample will be false.  When an edge is found, an additional true value
+ * will be emitted before the false value, resulting in a 0-duration "event".
+ */
+class EdgeFilter extends TransformState {
+  constructor() {
+    super();
+
+    this.defaultValue = false;
+    this.value = false;
+    this.previousValue = false;
+  }
+
+  static op = 'edge';
+
+  static create(_args) {
+    return new EdgeFilter();
+  }
+
+  emitUpdate(context) {
+    if (this.valueTime === this.lastSampleTime) {
+      this.emit('update', true, this.lastSampleTime, context);
+    }
+    this.emit('update', false, this.lastSampleTime, context);
+  }
+}
+
+module.exports = EdgeFilter;

package/lib/transform/expression.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const _ = require('lodash');
+const TransformState = require('./transformState');
+const ChainSource = require('./util/chainSource');
+
+/**
+ * Transforms each value by a pre-parsed mathjs expression.
+ *
+ * Filter must be provided with the backing engine to have access to current variable states, which can
+ * be referenced in expressions by name.  The special name 'this' refers to the input value at this stage
+ * of the transform chain.
+ *
+ * MathJS expressions are capable of dealing with any input types, and may produce output of differing type.
+ */
+class ExpressionFilter extends TransformState {
+  constructor({ engine, path, rootPath, baseTransform, args: { expression, compiledExpression } }) {
+    super();
+
+    if (baseTransform) {
+      this.origin = new ChainSource(this, { engine, path, rootPath }, {
+        onWatchSource: (name) => {
+          if (expression === name) {
+            this.simpleExpression = true;
+          }
+        },
+      });
+    }
+
+    this.engine = engine;
+    this.compiledExpression = compiledExpression;
+    this.selfSources = engine.expressionService.expressionTriggers(path);
+  }
+
+  static op = 'expression';
+
+  static create(args) {
+    return new ExpressionFilter(args);
+  }
+
+  static parseConfig(configUtil, defn) {
+    const expression = (defn.args[defn.func] ?? '').toString();
+    const compiledExpression = configUtil.compileExpression(expression, this.op);
+
+    defn.args = { expression, compiledExpression };
+  }
+
+  static getExpressions(configUtil, body, info) {
+    return configUtil.getExpressions(body, info);
+  }
+
+  update(context, value, time) {
+    if (value === 'UNAVAILABLE') {
+      this.setUnavailable(context, time);
+    } else {
+      super.update(context, value, time);
+    }
+  }
+
+  filter(context, value, time) {
+    if (this.constantSource || this.simpleSource) {
+      this.commitValue(context, value, time);
+      return;
+    }
+
+    const localState = {};
+    const unavailTerm = _.reduce(this.selfSources, (res, name) => {
+      const state = this.engine.getState(name);
+      localState[name] = state?.value;
+      return res || !state || !state.available;
+    }, false);
+
+    if (unavailTerm) {
+      this.setUnavailable(context, time);
+      return;
+    }
+
+    try {
+      if (!this.origin) {
+        localState.this = value;
+      }
+      this.commitValue(context, this.compiledExpression.evaluate(localState), time);
+    } catch (err) {
+      // Probably a type error in one of the arguments.
+      this.recordError(context, err, time);
+      this.setUnavailable(context, time);
+    }
+  }
+}
+
+module.exports = ExpressionFilter;

package/lib/transform/fallingEdge.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const _ = require('lodash');
+const TransformState = require('./transformState');
+
+/**
+ * Finds all falling edges (T->F) in a digital stream.
+ *
+ * For every incoming sample, the outgoing sample will be false.  When a falling edge is found, an additional true
+ * value will be emitted before the false value, resulting in a 0-duration "event".
+ *
+ * The filter can be modified with a min-dwell and max-dwell property, which will only emit edge events if the
+ * preceding state duration was within the window of time bounded by min-dwell and max-dwell.
+ */
+class FallingEdgeFilter extends TransformState {
+  constructor({ minDwell, maxDwell } = {}) {
+    super();
+
+    this.defaultValue = false;
+    this.value = false;
+    this.previousValue = false;
+
+    this.minDwell = minDwell;
+    this.maxDwell = maxDwell;
+  }
+
+  static op = 'falling-edge';
+
+  static create(args) {
+    return new FallingEdgeFilter(args.args);
+  }
+
+  static parseConfig(configUtil, defn) {
+    configUtil.requireObjectParams(defn.args, this.op, {
+      optional: true,
+      availableAttributes: ['min-dwell', 'max-dwell'],
+    });
+
+    const minDwell = defn.args['min-dwell'];
+    if (!_.isUndefined(minDwell)) {
+      configUtil.requireZeroPositive(minDwell, 'min-dwell', this.op);
+    }
+
+    const maxDwell = defn.args['max-dwell'];
+    if (!_.isUndefined(maxDwell)) {
+      configUtil.requireZeroPositive(maxDwell, 'max-dwell', this.op);
+      if (_.isNumber(minDwell) && maxDwell <= minDwell) {
+        configUtil.throwConfigError('max-dwell must be greater than min-dwell', this.op);
+      }
+    }
+
+    defn.args = { minDwell, maxDwell };
+  }
+
+  emitUpdate(context) {
+    if (!this.value && this.valueTime === this.lastSampleTime) {
+      const duration = this.valueTime - this.previousValueTime;
+      const pass = true
+        && (!this.minDwell || duration >= this.minDwell)
+        && (!this.maxDwell || duration <= this.maxDwell);
+
+      if (pass) {
+        this.emit('update', true, this.lastSampleTime, context);
+      }
+    }
+    this.emit('update', false, this.lastSampleTime, context);
+  }
+}
+
+module.exports = FallingEdgeFilter;

package/lib/transform/fromBuffer.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const _ = require('lodash');
+const Buffer = require('buffer/').Buffer;
+const TransformState = require('./transformState');
+
+const OFFSET_PATTERN = /(^|(offset=))(?<offset>\d+)/i;
+const TYPE_PATTERN = /(type=)?(?<type>((u?int)(8|16|32|64))|(float(32|64)?)|double|string)/i;
+const ORDER_PATTERN = /((order=)|(8|16|32|64|float|double)|,\s*|\s+)(?<order>be|le)(,|,?\s+|$)/i;
+const LENGTH_PATTERN = /((length=)|string\s*)(?<length>\d+)/i;
+
+/**
+ * Extracts a value from a buffer
+ */
+class FromBufferFilter extends TransformState {
+  constructor(spec) {
+    super();
+
+    this.spec = spec;
+    this.offset = +(this.matchPattern(spec, OFFSET_PATTERN, 'offset') ?? 0);
+    this.type = (this.matchPattern(spec, TYPE_PATTERN, 'type') ?? 'uint8').toUpperCase();
+    this.order = (this.matchPattern(spec, ORDER_PATTERN, 'order') ?? 'be').toUpperCase();
+    this.length = +(this.matchPattern(spec, LENGTH_PATTERN, 'length') ?? 0);
+  }
+
+  static op = 'from-buffer';
+
+  static create(args) {
+    return new FromBufferFilter(args.args.spec);
+  }
+
+  static parseConfig(configUtil, defn) {
+    const spec = _.get(defn.args, 'spec', defn.args[defn.func]);
+
+    defn.args = { spec };
+  }
+
+  filter(context, value, time) {
+    if (!Buffer.isBuffer(value)) {
+      return;
+    }
+
+    try {
+      const pulled = this.readValue(value);
+      this.commitValue(context, pulled, time);
+    } catch (err) {
+      this.recordError(context, err, time);
+      this.setUnavailable(context, time);
+    }
+  }
+
+  matchPattern(spec, pattern, group) {
+    const match = spec.match(pattern) ?? { };
+    return match?.groups?.[group];
+  }
+
+  readValue(buf) {
+    switch (this.type) {
+      case 'INT8':
+        return buf.readInt8(this.offset);
+      case 'UINT8':
+        return buf.readUInt8(this.offset);
+      case 'INT16':
+        return this.order === 'BE' ? buf.readInt16BE(this.offset) : buf.readInt16LE(this.offset);
+      case 'UINT16':
+        return this.order === 'BE' ? buf.readUInt16BE(this.offset) : buf.readUInt16LE(this.offset);
+      case 'INT32':
+        return this.order === 'BE' ? buf.readInt32BE(this.offset) : buf.readInt32LE(this.offset);
+      case 'UINT32':
+        return this.order === 'BE' ? buf.readUInt32BE(this.offset) : buf.readUInt32LE(this.offset);
+      case 'INT64':
+        return this.order === 'BE' ? buf.readBigInt64BE(this.offset) : buf.readBigInt64LE(this.offset);
+      case 'UINT64':
+        return this.order === 'BE' ? buf.readBigUInt64BE(this.offset) : buf.readBigUInt64LE(this.offset);
+      case 'FLOAT':
+      case 'FLOAT32':
+        return this.order === 'BE' ? buf.readFloatBE(this.offset) : buf.readFloatLE(this.offset);
+      case 'DOUBLE':
+      case 'FLOAT64':
+        return this.order === 'BE' ? buf.readDoubleBE(this.offset) : buf.readDoubleLE(this.offset);
+      case 'STRING':
+        return buf.toString('utf8', this.offset, this.length > 0 ? this.offset + this.length : buf.length);
+      default:
+        return null;
+    }
+  }
+}
+
+module.exports = FromBufferFilter;

package/lib/transform/hash.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const md5 = require('md5');
+const sha1 = require('sha1');
+const TransformState = require('./transformState');
+
+const ALGOS = {
+  md5, sha1,
+};
+
+/**
+ * Calculates the hash of a value in the data stream
+ */
+class HashFilter extends TransformState {
+  constructor(algo) {
+    super();
+
+    this.algo = algo;
+  }
+
+  static op = 'hash';
+
+  static create(args) {
+    return new HashFilter(args.args.algo);
+  }
+
+  static parseConfig(configUtil, defn) {
+    const algo = defn.args.algorithm ?? defn.args[defn.func];
+    if (!ALGOS[algo]) {
+      configUtil.throwConfigError(`hash must be one of [${Object.keys(ALGOS).join(', ')}]`, this.op);
+    }
+    defn.args = { algo };
+  }
+
+  filter(context, value, time) {
+    value = ALGOS[this.algo](value);
+    this.commitValue(context, value, time);
+  }
+}
+
+module.exports = HashFilter;