node-opcua-aggregates 2.51.0

package/source/interval.ts

@@ -0,0 +1,199 @@
+/**
+ * @module node-opca-aggregates
+ */
+import { DataValue } from "node-opcua-data-value";
+import { StatusCode, StatusCodes } from "node-opcua-status-code";
+import { AggregateConfigurationOptions } from "node-opcua-types";
+export { AggregateConfigurationOptions } from "node-opcua-types";
+
+export interface AggregateConfigurationOptionsEx extends AggregateConfigurationOptions {
+    stepped?: boolean;
+}
+export function isGoodish(statusCode: StatusCode): boolean {
+    return statusCode.value < 0x40000000;
+}
+
+export function isBad(statusCode: StatusCode): boolean {
+    return statusCode.value >= 0x80000000;
+}
+
+export function isGood(statusCode: StatusCode): boolean {
+    return statusCode.value === 0x0;
+}
+
+export interface IntervalOptions {
+    startTime: Date;
+    dataValues: DataValue[];
+    index: number;
+    count: number;
+    isPartial: boolean;
+}
+
+interface DataValueWithIndex {
+    index: number;
+    dataValue: DataValue;
+}
+
+export function _findGoodDataValueBefore(
+    dataValues: DataValue[],
+    index: number,
+    bTreatUncertainAsBad: boolean
+): DataValueWithIndex {
+    index--;
+    while (index >= 0) {
+        const dataValue1 = dataValues[index];
+        if (!bTreatUncertainAsBad && !isBad(dataValue1.statusCode)) {
+            return { index, dataValue: dataValue1 };
+        }
+        if (bTreatUncertainAsBad && isGood(dataValue1.statusCode)) {
+            return { index, dataValue: dataValue1 };
+        }
+        index -= 1;
+    }
+    // not found
+    return {
+        dataValue: new DataValue({ statusCode: StatusCodes.BadNoData }),
+        index: -1
+    };
+}
+
+export function _findGoodDataValueAfter(dataValues: DataValue[], index: number, bTreatUncertainAsBad: boolean): DataValueWithIndex {
+    while (index < dataValues.length) {
+        const dataValue1 = dataValues[index];
+        if (!bTreatUncertainAsBad && !isBad(dataValue1.statusCode)) {
+            return {
+                dataValue: dataValue1,
+                index
+            };
+        }
+        if (bTreatUncertainAsBad && isGood(dataValue1.statusCode)) {
+            return {
+                dataValue: dataValue1,
+                index
+            };
+        }
+        index += 1;
+    }
+    // not found
+    return {
+        dataValue: new DataValue({ statusCode: StatusCodes.BadNoData }),
+        index: -1
+    };
+}
+
+export function adjustProcessingOptions(options: AggregateConfigurationOptionsEx | null): AggregateConfigurationOptionsEx {
+    options = options || {};
+    options.treatUncertainAsBad = options.treatUncertainAsBad || false;
+    options.useSlopedExtrapolation = options.useSlopedExtrapolation || false;
+    options.stepped = options.stepped! || false;
+    options.percentDataBad = parseInt(options.percentDataBad as any, 10);
+    options.percentDataGood = parseInt(options.percentDataGood as any, 10);
+    return options;
+}
+
+export class Interval {
+    public startTime: Date;
+    public dataValues: DataValue[];
+    public index: number;
+    public count: number;
+    public isPartial: boolean;
+
+    // startTime
+    // dataValues
+    // index:       index of first dataValue inside the interval
+    // count:       number of dataValue inside the interval
+    constructor(options: IntervalOptions) {
+        this.startTime = options.startTime;
+        this.dataValues = options.dataValues;
+        this.index = options.index;
+        this.count = options.count;
+        this.isPartial = options.isPartial;
+    }
+
+    public getPercentBad(): number {
+        return 100;
+    }
+
+    /**
+     * returns true if a raw data exists at start
+     */
+    public hasRawDataAsStart() {
+        const index = this.index;
+        if (index < 0) {
+            return false;
+        }
+        const dataValue1 = this.dataValues[index];
+        return this.startTime.getTime() === dataValue1!.sourceTimestamp!.getTime();
+    }
+
+    /**
+     * Find the first good or uncertain dataValue
+     * just preceding this interval
+     * @returns {*}
+     */
+    public beforeStartDataValue(bTreatUncertainAsBad: boolean) {
+        return _findGoodDataValueBefore(this.dataValues, this.index, bTreatUncertainAsBad);
+    }
+
+    public nextStartDataValue(bTreatUncertainAsBad: boolean) {
+        return _findGoodDataValueAfter(this.dataValues, this.index, bTreatUncertainAsBad);
+    }
+
+    public toString() {
+        let str = "";
+        str += "startTime " + this.startTime.toUTCString() + "\n";
+        str += "start     " + this.index + "  ";
+        str += "count     " + this.count + " ";
+        str += "isPartial " + this.isPartial + "\n";
+        if (this.index >= 0) {
+            for (let i = this.index; i < this.index + this.count; i++) {
+                const dataValue = this.dataValues[i];
+                str += " " + dataValue.sourceTimestamp!.toUTCString() + dataValue.statusCode.toString();
+                str += dataValue.value ? dataValue.value.toString() : "";
+                str += "\n";
+            }
+        }
+        return str;
+    }
+}
+
+export function getInterval(startTime: Date, duration: number, indexHint: number, dataValues: DataValue[]): Interval {
+    let count = 0;
+    let index = -1;
+    for (let i = indexHint; i < dataValues.length; i++) {
+        if (dataValues[i].sourceTimestamp!.getTime() < startTime.getTime()) {
+            continue;
+        }
+        index = i;
+        break;
+    }
+
+    if (index >= 0) {
+        for (let i = index; i < dataValues.length; i++) {
+            if (dataValues[i].sourceTimestamp!.getTime() >= startTime.getTime() + duration) {
+                break;
+            }
+            count++;
+        }
+    }
+
+    // check if interval is complete or partial (end or start)
+    let isPartial = false;
+    if (
+        index + count >= dataValues.length &&
+        dataValues[dataValues.length - 1].sourceTimestamp!.getTime() < startTime.getTime() + duration
+    ) {
+        isPartial = true;
+    }
+    if (index <= 0 && dataValues[0].sourceTimestamp!.getTime() > startTime.getTime()) {
+        isPartial = true;
+    }
+
+    return new Interval({
+        count,
+        dataValues,
+        index,
+        isPartial,
+        startTime
+    });
+}

package/source/minmax.ts

@@ -0,0 +1,231 @@
+/**
+ * @module node-opca-aggregates
+ */
+//  excert from OPC Unified Architecture, Part 13 21 Release 1.04
+// 5.4.3.10 Minimum
+// The Minimum Aggregate defined in Table 21 retrieves the minimum Good raw value within the
+// interval, and returns that value with the timestamp at the start of the interval. Note that if the
+// same minimum exists at more than one timestamp the MultipleValues bit is set.
+//
+// Unless otherwise indicated, StatusCodes are Good, Calculated. If the minimum value is on
+// the start time the status code will be Good, Raw. If only Bad quality values are available then
+// the status is returned as Bad_NoData.
+//
+// The timestamp of the Aggregate will always be the start of the interval for every
+// ProcessingInterval.
+//
+// Table 21 – Minimum Aggregate summary
+//
+// Minimum Aggregate Characteristics
+//
+// Type                     Calculated
+// Data                     Type Same as Source
+// Use Bounds               None
+// Timestamp                StartTime
+//
+// Status Code  Calculations
+//
+// Calculation Method       Custom
+// If no Bad values then the Status is Good. If Bad values exist then
+// the Status is Uncertain_SubNormal. If an Uncertain value is less
+// than the minimum Good value the Status is Uncertain_SubNormal.
+//
+// Partial                  Set Sometimes
+// If an interval is not a complete interval
+//
+// Calculated               Set Sometimes
+// If the Minimum value is not on the StartTime of the interval or if the
+// Status was set to Uncertain_SubNormal because of non-Good
+// values in the interval
+//
+// Interpolated             Not Set
+// Raw                      Set Sometimes
+// If Minimum value is on the StartTime of the interval
+//
+// Multi Value              Set Sometimes
+// If multiple Good values exist with the Minimum value
+//
+// Status Code Common Special Cases
+// Before Start of Data     Bad_NoData
+// After End of Data        Bad_NoData
+// No Start Bound           Not Applicable
+// No End Bound             Not Applicable
+// Bound Bad                Not Applicable
+// Bound Uncertain          Not Applicable
+import { UAVariable } from "node-opcua-address-space";
+import { DataValue } from "node-opcua-data-value";
+import { StatusCode, StatusCodes } from "node-opcua-status-code";
+import { Variant } from "node-opcua-variant";
+
+import { getAggregateData } from "./common";
+import { AggregateConfigurationOptions, Interval, isGood } from "./interval";
+
+function calculateIntervalMinOrMaxValue(
+    interval: Interval,
+    options: AggregateConfigurationOptions,
+    predicate: (a: Variant, b: Variant) => "equal" | "select" | "reject"
+): DataValue {
+
+    //   console.log(interval.toString());
+
+    const indexStart = interval.index;
+    let selectedValue: Variant | null = null;
+
+    let counter = 0;
+    let statusCode: StatusCode;
+    let isPartial = interval.isPartial;
+
+    let isRaw = false;
+    let hasBad = false;
+
+    for (let i = indexStart; i < indexStart + interval.count; i++) {
+        const dataValue = interval.dataValues[i];
+
+        if (dataValue.statusCode === StatusCodes.BadNoData) {
+            isPartial = true;
+            continue;
+        }
+
+        if (!isGood(dataValue.statusCode)) {
+            hasBad = true;
+            continue;
+        }
+
+        if (!selectedValue) {
+            selectedValue = dataValue.value;
+            counter = 1;
+            if (i === indexStart && dataValue.sourceTimestamp!.getTime() === interval.startTime.getTime()) {
+                isRaw = true;
+            }
+            continue;
+        }
+        const compare = predicate(selectedValue, dataValue.value);
+        if (compare === "equal") {
+            counter = 1;
+            continue;
+        }
+        if (compare === "select") {
+            selectedValue = dataValue.value;
+            counter = 1;
+        }
+    }
+
+    if (!selectedValue) {
+        return new DataValue({
+            sourceTimestamp: interval.startTime,
+            statusCode: StatusCodes.BadNoData
+        });
+    }
+    if (isRaw) {
+        if (hasBad) {
+            statusCode = StatusCodes.UncertainDataSubNormal;
+        } else {
+            statusCode = StatusCodes.Good;
+        }
+    } else if (hasBad) {
+        statusCode = StatusCode.makeStatusCode(StatusCodes.UncertainDataSubNormal, "HistorianCalculated");
+    } else {
+        statusCode = StatusCode.makeStatusCode(StatusCodes.Good, "HistorianCalculated");
+    }
+
+    if (counter > 1) {
+        statusCode = StatusCode.makeStatusCode(statusCode, "HistorianMultiValue");
+    }
+    if (isPartial || interval.isPartial) {
+        statusCode = StatusCode.makeStatusCode(statusCode, "HistorianPartial");
+    }
+
+    return new DataValue({
+        sourceTimestamp: interval.startTime,
+        statusCode: statusCode as StatusCode,
+        value: selectedValue!
+    });
+}
+
+export function calculateIntervalMinValue(interval: Interval, options: AggregateConfigurationOptions): DataValue {
+    return calculateIntervalMinOrMaxValue(interval, options,
+        (a: Variant, b: Variant) =>
+            a.value > b.value ? "select" : (a.value === b.value ? "equal" : "reject"));
+}
+
+export function calculateIntervalMaxValue(interval: Interval, options: AggregateConfigurationOptions): DataValue {
+    return calculateIntervalMinOrMaxValue(interval, options,
+        (a: Variant, b: Variant) =>
+            a.value < b.value ? "select" : (a.value === b.value ? "equal" : "reject"));
+}
+
+// From OPC Unified Architecture, Part 13 26 Release 1.04
+// 5.4.3.11 Maximum
+// The Maximum Aggregate defined in Table 22 retrieves the maximum Good raw value within
+// the interval, and returns that value with the timestamp at the start of the interval. Note that if
+// the same maximum exists at more than one timestamp the MultipleValues bit is set.
+// Unless otherwise indicated, StatusCodes are Good, Calculated. If the minimum value is on
+// the interval start time the status code will be Good, Raw. If only Bad quality values are
+// available then the status is returned as Bad_NoData.
+// The timestamp of the Aggregate will always be the start of the interval for every
+//
+// ProcessingInterval.
+//
+// Table 22 – Maximum Aggregate summary
+// Maximum Aggregate Characteristics
+//
+// Type                     Calculated
+// Data Type                Same as Source
+// Use Bounds               None
+// Timestamp                StartTime
+//
+// Status Code Calculations
+// Calculation              Method Custom
+// If no Bad values then the Status is Good. If Bad values exist then
+// the Status is Uncertain_SubNormal. If an Uncertain value is greater
+// than the maximum Good value the Status is Uncertain_SubNormal
+//
+// Partial                  Set Sometimes
+// If an interval is not a complete interval
+//
+// Calculated               Set Sometimes
+// If the Maximum value is not on the startTime of the interval or if the
+// Status was set to Uncertain_SubNormal because of non-Good
+// values in the interval
+//
+// Interpolated             Not Set
+//
+// Raw                      Set Sometimes
+// If Maximum value is on the startTime of the interval
+// Multi Value Set Sometimes
+// If multiple Good values exist with the Maximum value
+//
+// Status Code Common Special Cases
+// Before Start of Data     Bad_NoData
+// After End of Data        Bad_NoData
+// No Start Bound           Not Applicable
+// No End Bound             Not Applicable
+// Bound Bad                Not Applicable
+// Bound Uncertain             Not Applicable
+/**
+ *
+ * @param node
+ * @param processingInterval
+ * @param startDate
+ * @param endDate
+ * @param callback
+ */
+export function getMinData(
+    node: UAVariable,
+    processingInterval: number,
+    startDate: Date,
+    endDate: Date,
+    callback: (err: Error | null, dataValues?: DataValue[]) => void
+) {
+    return getAggregateData(node, processingInterval, startDate, endDate, calculateIntervalMinValue, callback);
+}
+
+export function getMaxData(
+    node: UAVariable,
+    processingInterval: number,
+    startDate: Date,
+    endDate: Date,
+    callback: (err: Error | null, dataValues?: DataValue[]) => void
+) {
+    return getAggregateData(node, processingInterval, startDate, endDate, calculateIntervalMaxValue, callback);
+}

package/source/read_processed_details.ts

@@ -0,0 +1,139 @@
+import * as async from "async";
+import { AggregateFunction } from "node-opcua-constants";
+import { ISessionContext, ContinuationPoint, UAVariable } from "node-opcua-address-space";
+import { NumericRange } from "node-opcua-numeric-range";
+import { QualifiedNameLike } from "node-opcua-data-model";
+import { CallbackT, StatusCodes } from "node-opcua-status-code";
+import { DataValue } from "node-opcua-data-value";
+import { ObjectIds } from "node-opcua-constants";
+import { NodeId } from "node-opcua-nodeid";
+import { getMinData, getMaxData } from "./minmax";
+import {
+    HistoryData,
+    HistoryReadResult,
+    ReadAtTimeDetails,
+    ReadEventDetails,
+    ReadProcessedDetails,
+    ReadRawModifiedDetails
+} from "node-opcua-service-history";
+
+import { getInterpolatedData } from "./interpolate";
+import { getAverageData } from "./average";
+
+export function readProcessedDetails(
+    variable: UAVariable,
+    context: ISessionContext,
+    historyReadDetails: ReadProcessedDetails,
+    indexRange: NumericRange | null,
+    dataEncoding: QualifiedNameLike | null,
+    continuationPoint: ContinuationPoint | null,
+    callback: CallbackT<HistoryReadResult>
+) {
+    // OPC Unified Architecture, Part 11 27 Release 1.03
+    //
+    // This structure is used to compute Aggregate values, qualities, and timestamps from data in
+    // the history database for the specified time domain for one or more HistoricalDataNodes. The
+    // time domain is divided into intervals of duration ProcessingInterval. The specified Aggregate
+    // Type is calculated for each interval beginning with startTime by using the data within the next
+    // ProcessingInterval.
+    // For example, this function can provide hourly statistics such as Maximum, Minimum , and
+    // Average for each item during the specified time domain when ProcessingInterval is 1 hour.
+    // The domain of the request is defined by startTime, endTime, and ProcessingInterval. All three
+    // shall be specified. If endTime is less than startTime then the data shall be returned in reverse
+    // order with the later data coming first. If startTime and endTime are the same then the Server
+    // shall return Bad_InvalidArgument as there is no meaningful way to interpret such a case. If
+    // the ProcessingInterval is specified as 0 then Aggregates shall be calculated using one interval
+    // starting at startTime and ending at endTime.
+    // The aggregateType[] parameter allows a Client to request multiple Aggregate calculations per
+    // requested NodeId. If multiple Aggregates are requested then a corresponding number of
+    // entries are required in the NodesToRead array.
+    // For example, to request Min Aggregate for NodeId FIC101, FIC102, and both Min and Max
+    // Aggregates for NodeId FIC103 would require NodeId FIC103 to appear twice in the
+    // NodesToRead array request parameter.
+    // aggregateType[] NodesToRead[]
+    // Min FIC101
+    // Min FIC102
+    // Min FIC103
+    // Max FIC103
+    // If the array of Aggregates does not match the array of NodesToRead then the Server shall
+    // return a StatusCode of Bad_AggregateListMismatch.
+    // The aggregateConfiguration parameter allows a Client to override the Aggregate configuration
+    // settings supplied by the AggregateConfiguration Object on a per call basis. See Part 13 for
+    // more information on Aggregate configurations. If the Server does not support the ability to
+    // override the Aggregate configuration settings then it shall return a StatusCode of Bad_
+    // AggregateConfigurationRejected. If the Aggregate is not valid for the Node then the
+    // StatusCode shall be Bad_AggregateNotSupported.
+    // The values used in computing the Aggregate for each interval shall include any value that
+    // falls exactly on the timestamp at the beginning of the interval, but shall not include any value
+    // that falls directly on the timestamp ending the interval. Thus, each value shall be included
+    // only once in the calculation. If the time domain is in reverse order then we consider the later
+    // timestamp to be the one beginning the sub interval, and the earlier timestamp to be the one
+    // ending it. Note that this means that simply swapping the start and end times will not result in
+    // getting the same values back in reverse order as the intervals being requested in the two
+    // cases are not the same.
+    // If an Aggregate is taking a long time to calculate then the Server can return partial results
+    // with a continuation point. This might be done if the calculation is going to take more time th an
+    // the Client timeout hint. In some cases it may take longer than the Client timeout hint to
+    // calculate even one Aggregate result. Then the Server may return zero results with a
+    // continuation point that allows the Server to resume the calculation on the next Client read
+    // call.
+    const startTime = historyReadDetails.startTime;
+    const endTime = historyReadDetails.endTime;
+    if (!startTime || !endTime) {
+        return callback(null, new HistoryReadResult({ statusCode: StatusCodes.BadInvalidArgument }));
+    }
+    if (startTime.getTime() === endTime.getTime()) {
+        // Start = End Int = Anything No intervals. Returns a Bad_InvalidArgument StatusCode,
+        // regardless of whether there is data at the specified time or not
+        return callback(null, new HistoryReadResult({ statusCode: StatusCodes.BadInvalidArgument }));
+    }
+
+    const aggregateTypes: NodeId[] = historyReadDetails.aggregateType || [];
+
+    // If the ProcessingInterval is specified as 0 then Aggregates shall be calculated using one interval
+    // starting at startTime and ending at endTime.
+    const processingInterval = historyReadDetails.processingInterval || endTime.getTime() - startTime.getTime();
+
+    // tslint:disable-next-line: prefer-for-of
+
+    function applyAggregate(aggregateType: NodeId, callback2: (err: Error | null, result: HistoryReadResult) => void) {
+        function buildResult(err: Error | null, dataValues?: DataValue[]) {
+            if (err) {
+                return callback2(null, new HistoryReadResult({ statusCode: StatusCodes.BadInternalError }));
+            }
+            const result = new HistoryReadResult({
+                historyData: new HistoryData({
+                    dataValues
+                }),
+                statusCode: StatusCodes.Good
+            });
+            return callback2(null, result);
+        }
+
+        if (!startTime || !endTime) {
+            return buildResult(new Error("Invalid date time"));
+        }
+        switch (aggregateType.value) {
+            case AggregateFunction.Minimum:
+                getMinData(variable, processingInterval, startTime, endTime, buildResult);
+                break;
+            case AggregateFunction.Maximum:
+                getMaxData(variable, processingInterval, startTime, endTime, buildResult);
+                break;
+            case AggregateFunction.Interpolative:
+                getInterpolatedData(variable, processingInterval, startTime, endTime, buildResult);
+                break;
+            case AggregateFunction.Average:
+                getAverageData(variable, processingInterval, startTime, endTime, buildResult);
+                break;
+            case AggregateFunction.Count:
+            default:
+                // todo provide correct implementation
+                return callback2(null, new HistoryReadResult({ statusCode: StatusCodes.BadAggregateNotSupported }));
+        }
+    }
+    if (historyReadDetails.aggregateType?.length !== 1) {
+        return callback(null, new HistoryReadResult({ statusCode: StatusCodes.BadInternalError }));
+    }
+    return applyAggregate(aggregateTypes[0], callback);
+}