node-opcua-address-space 2.51.0

package/src/data_access/add_dataItem_stuff.ts

@@ -0,0 +1,75 @@
+/**
+ * @module node-opcua-address-space.DataAccess
+ */
+// Release 1.02  5  OPC Unified Architecture, Part 8
+
+// HasProperty  Variable  Definition  String  PropertyType  Optional
+// HasProperty  Variable  ValuePrecision  Double  PropertyType  Optional
+
+// Clients may read or write  DataItems, or monitor them for value changes. The services needed for
+// these  operations are specified in  Part  4. Changes are defined as a change in status (quality) or a
+// change in value that exceeds a client - defined range called a  Deadband. To detect the value change,
+// the difference between the current value and   the last reported value is compared to the  Deadband.
+
+// Definition   is a vendor - specific, human readable string that specifies how the value of this  DataItem  is
+// calculated.  Definition  is non - localized and will often contain an equation that can be parsed by
+// certain clients.
+//    Example:    Definition ::= “(TempA – 25) + TempB”
+
+// ValuePrecision  specifies  the maximum precision that the server can maintain for the item   based on
+// restrictions in the target environment.
+// ValuePrecision  can be used for the following  DataTypes:
+//   * For Float and Double values  it specifies   the number of   digits after the decimal place.
+//   * For DateTime values it indicates the minimum time difference in nanoseconds. For example,
+//     a ValuePrecision of 20   000  000 defines a precision of 20 ms.
+//     The  ValuePrecision  Property  is an approximation that is intended to prov ide guidance to a  Client. A
+//     Server  is expected to silently round any value with more precision that it supports. This implies that
+//     a  Client  may encounter cases where the value read back from a  Server  differs from the value that it
+//     wrote to the Server. This   difference shall be no more than the difference suggested by this  Property
+
+import { assert } from "node-opcua-assert";
+import { DataType, Variant } from "node-opcua-variant";
+
+import { UAVariable, ModellingRuleType } from "node-opcua-address-space-base";
+
+const definition_Description =
+    "Definition  is a vendor - specific," + " human readable string that specifies how the value of this  DataItem  is calculated.";
+const valuePrecision_Description = "";
+
+interface add_dataItem_stuffOptions {
+    definition?: string;
+    valuePrecision?: number;
+    modellingRule?: ModellingRuleType;
+}
+export function add_dataItem_stuff(variable: UAVariable, options: add_dataItem_stuffOptions) :void{
+    const addressSpace = variable.addressSpace;
+    const namespace = addressSpace.getNamespace(variable.nodeId.namespace);
+
+    if (Object.prototype.hasOwnProperty.call(options,"definition")) {
+        namespace.addVariable({
+            browseName: { name: "Definition", namespaceIndex: 0 },
+            dataType: "String",
+            description: definition_Description,
+            minimumSamplingInterval: 0,
+            modellingRule: options.modellingRule ? "Mandatory" : undefined,
+            propertyOf: variable,
+            typeDefinition: "PropertyType",
+            value: new Variant({ dataType: DataType.String, value: options.definition })
+        });
+    }
+
+    if (Object.prototype.hasOwnProperty.call(options,"valuePrecision")) {
+        assert(typeof options.valuePrecision === "number");
+
+        namespace.addVariable({
+            browseName: { name: "ValuePrecision", namespaceIndex: 0 },
+            dataType: "Double",
+            description: valuePrecision_Description,
+            minimumSamplingInterval: 0,
+            modellingRule: options.modellingRule ? "Mandatory" : undefined,
+            propertyOf: variable,
+            typeDefinition: "PropertyType",
+            value: new Variant({ dataType: DataType.Double, value: options.valuePrecision })
+        });
+    }
+}

package/src/data_access/check_variant_compatibility_ua_analog_item.ts

@@ -0,0 +1,41 @@
+/**
+ * @module node-opcua-address-space.DataAccess
+ */
+import { assert } from "node-opcua-assert";
+import { UAAnalogItem } from "node-opcua-nodeset-ua";
+import { StatusCodes } from "node-opcua-status-code";
+import { StatusCode } from "node-opcua-status-code";
+import { Range } from "node-opcua-types";
+import { DataType, Variant } from "node-opcua-variant";
+import { UAVariableImpl } from "../ua_variable_impl";
+
+function validate_value_range(range: Range, variant: Variant) {
+    if (variant.value < range.low || variant.value > range.high) {
+        return false;
+    }
+    return true;
+}
+
+
+function checkVariantCompatibilityUAAnalogItem(this: UAVariableImpl, value: Variant): StatusCode {
+
+        assert(value instanceof Variant);
+        // test dataType
+        if (!this._validate_DataType(value.dataType)) {
+            return StatusCodes.BadTypeMismatch;
+        }
+        const analogItem = this as unknown as  UAAnalogItem<any, any>;
+        // AnalogDataItem
+        if (analogItem.instrumentRange) {
+            if (!validate_value_range(analogItem.instrumentRange.readValue().value.value as Range, value)) {
+                return StatusCodes.BadOutOfRange;
+            }
+        }
+        return StatusCodes.Good;
+    }
+
+
+/**
+ * extend default checkVariantCompatibility on base class with this one
+ */
+UAVariableImpl.prototype.checkVariantCompatibility = checkVariantCompatibilityUAAnalogItem;

package/src/data_access/ua_multistate_discrete_impl.ts

@@ -0,0 +1,168 @@
+/**
+ * @module node-opcua-address-space.DataAccess
+ */
+import { assert } from "node-opcua-assert";
+import { VariableTypeIds } from "node-opcua-constants";
+import { coerceLocalizedText, LocalizedText } from "node-opcua-data-model";
+import { StatusCode, StatusCodes } from "node-opcua-status-code";
+import { DataType, VariantArrayType, Variant } from "node-opcua-variant";
+import { BindVariableOptions, INamespace, UAVariable, UAProperty } from "node-opcua-address-space-base";
+
+import { UAMultiStateDiscrete, UAMultiStateDiscrete_Base } from "node-opcua-nodeset-ua";
+import { registerNodePromoter } from "../../source/loader/register_node_promoter";
+import { UAVariableImpl } from "../ua_variable_impl";
+import { AddMultiStateDiscreteOptions } from "../../source/address_space_ts";
+import { add_dataItem_stuff } from "./add_dataItem_stuff";
+
+export { UAMultiStateDiscrete } from "node-opcua-nodeset-ua";
+
+export interface UAMultiStateDiscreteEx<T, DT extends DataType> extends UAMultiStateDiscrete_Base<T, DT> {
+    //------------ helpers ------------------
+    getValue(): number;
+    getValueAsString(): string;
+    getIndex(value: string): number;
+    setValue(value: string | number): void;
+    checkVariantCompatibility(value: Variant): StatusCode;
+}
+
+export interface UAMultiStateDiscreteImpl<T, DT extends DataType> {
+    enumStrings: UAProperty<LocalizedText[], DataType.LocalizedText>;
+}
+/**
+ * @class UAMultiStateDiscrete
+ */
+export class UAMultiStateDiscreteImpl<T, DT extends DataType> extends UAVariableImpl implements UAMultiStateDiscreteEx<T, DT> {
+    public getValue(): number {
+        return this.readValue().value.value;
+    }
+
+    public getValueAsString(): string {
+        const index = this.getValue();
+        const arr = this.enumStrings.readValue().value.value;
+        assert(Array.isArray(arr));
+        return arr[index].text ? arr[index].text!.toString() : "????";
+    }
+
+    public getIndex(value: string): number {
+        const arr = this.enumStrings.readValue().value.value;
+        assert(Array.isArray(arr));
+        const index = arr.findIndex((a: LocalizedText) => a.text === value);
+        return index;
+    }
+
+    public setValue(value: string | number): void {
+        if (typeof value === "string") {
+            const index = this.getIndex(value);
+            if (index < 0) {
+                throw new Error("UAMultiStateDiscrete#setValue invalid multi state value provided : " + value);
+            }
+            return this.setValue(index);
+        }
+        const arrayEnumStrings = this.enumStrings.readValue().value.value;
+        if (value >= arrayEnumStrings.length) {
+            throw new Error("UAMultiStateDiscrete#setValue BadOutOfRange " + value);
+        }
+        assert(isFinite(value));
+        return this.setValueFromSource(new Variant({ dataType: DataType.UInt32, value }));
+    }
+
+    public checkVariantCompatibility(value: Variant): StatusCode {
+        if (!this._validate_DataType(value.dataType)) {
+            return StatusCodes.BadTypeMismatch;
+        }
+        if (this.enumStrings) {
+            const arrayEnumStrings = this.enumStrings.readValue().value.value;
+            // MultiStateDiscreteType
+            assert(value.dataType === DataType.UInt32);
+            if (value.value >= arrayEnumStrings.length) {
+                return StatusCodes.BadOutOfRange;
+            }
+        }
+        return StatusCodes.Good;
+    }
+
+    public _post_initialize(): void {
+        /* empty */
+    }
+
+    public clone<T, DT extends DataType>(options1: any, optionalFilter: any, extraInfo: any): UAMultiStateDiscreteImpl<T, DT> {
+        const variable1 = UAVariableImpl.prototype.clone.call(this, options1, optionalFilter, extraInfo);
+        return promoteToMultiStateDiscrete(variable1);
+    }
+}
+
+export function promoteToMultiStateDiscrete<T, DT extends DataType>(node: UAVariable): UAMultiStateDiscreteImpl<T, DT> {
+    if (node instanceof UAMultiStateDiscreteImpl) {
+        return node; // already promoted
+    }
+    Object.setPrototypeOf(node, UAMultiStateDiscreteImpl.prototype);
+    assert(node instanceof UAMultiStateDiscreteImpl, "should now  be a State Machine");
+    const _node = node as UAMultiStateDiscreteImpl<T, DT>;
+
+    _node._post_initialize();
+
+    assert(_node.enumStrings.browseName.toString() === "EnumStrings");
+    const handler = _node.handle_semantic_changed.bind(_node);
+    _node.enumStrings.on("value_changed", handler);
+    _node.install_extra_properties();
+    return node as UAMultiStateDiscreteImpl<T, DT>;
+}
+registerNodePromoter(VariableTypeIds.MultiStateDiscreteType, promoteToMultiStateDiscrete);
+
+export function _addMultiStateDiscrete<T,DT extends DataType>(namespace: INamespace, options: AddMultiStateDiscreteOptions): UAMultiStateDiscreteImpl<T,DT> {
+    const addressSpace = namespace.addressSpace;
+    assert(Object.prototype.hasOwnProperty.call(options,"enumStrings"));
+    assert(!Object.prototype.hasOwnProperty.call(options,"ValuePrecision"));
+
+    const multiStateDiscreteType = addressSpace.findVariableType("MultiStateDiscreteType");
+    if (!multiStateDiscreteType) {
+        throw new Error("Cannot find MultiStateDiscreteType");
+    }
+    // todo : if options.typeDefinition is specified, check that type is SubTypeOf MultiStateDiscreteType
+
+    options.value = options.value === undefined ? 0 : options.value;
+
+    let value: undefined | BindVariableOptions;
+    if (typeof options.value === "number") {
+        value = new Variant({
+            dataType: DataType.UInt32,
+            value: options.value
+        });
+    } else {
+        value = options.value;
+    }
+
+    const variable = namespace.addVariable({
+        ...options,
+
+        dataType: "Number",
+        typeDefinition: multiStateDiscreteType.nodeId,
+        value,
+
+        valueRank: -2
+    });
+
+    add_dataItem_stuff(variable, options);
+
+    const enumStrings = options.enumStrings.map((value: string) => {
+        return coerceLocalizedText(value);
+    });
+
+    const enumStringsNode = namespace.addVariable({
+        accessLevel: "CurrentRead", // | CurrentWrite",
+        browseName: { name: "EnumStrings", namespaceIndex: 0 },
+        dataType: "LocalizedText",
+        minimumSamplingInterval: 0,
+        modellingRule: options.modellingRule ? "Mandatory" : undefined,
+        propertyOf: variable,
+        typeDefinition: "PropertyType",
+        userAccessLevel: "CurrentRead", // CurrentWrite",
+        value: new Variant({
+            arrayType: VariantArrayType.Array,
+            dataType: DataType.LocalizedText,
+            value: enumStrings
+        })
+    });
+
+    return promoteToMultiStateDiscrete(variable);
+}

package/src/data_access/ua_multistate_value_discrete.ts

@@ -0,0 +1,299 @@
+/**
+ * @module node-opcua-address-space.DataAccess
+ */
+import { assert } from "node-opcua-assert";
+import { DataType, Variant, VariantArrayType } from "node-opcua-variant";
+import { coerceInt32, coerceUInt64, Int64, isValidUInt64 } from "node-opcua-basic-types";
+import { coerceLocalizedText, LocalizedText, QualifiedNameLike } from "node-opcua-data-model";
+import { DataValue, DataValueT } from "node-opcua-data-value";
+import { StatusCodes } from "node-opcua-status-code";
+import { StatusCode } from "node-opcua-status-code";
+import { NumericRange } from "node-opcua-numeric-range";
+import { DTEnumValue } from "node-opcua-nodeset-ua";
+import { BindVariableOptions, INamespace, UAVariable, UAProperty, ISessionContext } from "node-opcua-address-space-base";
+import { VariableTypeIds } from "node-opcua-constants";
+
+import { registerNodePromoter } from "../../source/loader/register_node_promoter";
+import { coerceEnumValues } from "../../source/helpers/coerce_enum_value";
+import { UAMultiStateValueDiscreteEx } from "../../source/interfaces/data_access/ua_multistate_value_discrete_ex";
+import { AddMultiStateValueDiscreteOptions } from "../../source/address_space_ts";
+import { UAVariableImpl } from "../ua_variable_impl";
+
+import { add_dataItem_stuff } from "./add_dataItem_stuff";
+
+function install_synchronization<T, DT extends DataType>(variable: UAMultiStateValueDiscreteEx<T, DT>) {
+    const _variable = variable as UAMultiStateValueDiscreteEx<T, DT>;
+    _variable.on("value_changed", (value: DataValue) => {
+        const valueAsTextNode = variable.valueAsText || (_variable.getComponentByName("ValueAsText") as UAVariable);
+        if (!valueAsTextNode) {
+            return;
+        }
+        const valueAsText1 = _variable.findValueAsText(value.value.value);
+        valueAsTextNode.setValueFromSource(valueAsText1);
+    });
+    _variable.emit("value_changed", _variable.readValue());
+}
+
+export interface UAMultiStateValueDiscreteImpl<T, DT extends DataType> {
+    enumValues: UAProperty<DTEnumValue[], DataType.ExtensionObject>;
+    valueAsText: UAProperty<LocalizedText, DataType.LocalizedText>;
+
+    readValue(
+        context?: ISessionContext | null,
+        indexRange?: NumericRange,
+        dataEncoding?: QualifiedNameLike | null
+    ): DataValueT<T, DT>;
+
+    readValueAsync(context: ISessionContext | null, callback?: any): any;
+}
+export class UAMultiStateValueDiscreteImpl<T, DT extends DataType>
+    extends UAVariableImpl
+    implements UAMultiStateValueDiscreteEx<T, DT>
+{
+    public setValue(value: string | number | Int64): void {
+        if (typeof value === "string") {
+            const enumValues = this.enumValues.readValue().value.value;
+            const selected = enumValues.filter((a: any) => a.displayName.text === value)[0];
+            if (selected) {
+                this._setValue(selected.value);
+            } else {
+                throw new Error("cannot find enum string " + value + " in " + enumValues.toString());
+            }
+        } else {
+            this._setValue(coerceUInt64(value));
+        }
+    }
+
+    public getValueAsString(): string {
+        return this.valueAsText.readValue().value.value.text || "";
+    }
+
+    public getValueAsNumber(): number {
+        return this.readValue().value.value as unknown as number;
+    }
+
+    public checkVariantCompatibility(value: Variant): StatusCode {
+        if (this.enumValues) {
+            if (!this._isValueInRange(coerceInt32(value.value))) {
+                return StatusCodes.BadOutOfRange;
+            }
+        }
+        return StatusCodes.Good;
+    }
+
+    public clone<T, DT extends DataType>(options1: any, optionalFilter: any, extraInfo: any): UAMultiStateValueDiscreteImpl<T, DT> {
+        const variable1 = UAVariableImpl.prototype.clone.call(this, options1, optionalFilter, extraInfo);
+        return promoteToMultiStateValueDiscrete(variable1);
+    }
+
+    /**
+     * @private
+     */
+    public _isValueInRange(value: number): boolean {
+        // MultiStateValueDiscreteType
+        const enumValues = this.enumValues.readValue().value.value as DTEnumValue[];
+        const e = enumValues.findIndex((x: DTEnumValue) => coerceInt32(x.value) === value);
+        return !(e === -1);
+    }
+    /**
+     *
+     * @private
+     */
+    public _enumValueIndex(): any {
+        // construct an index to quickly find a EnumValue from a value
+        const enumValues = this.enumValues.readValue().value.value;
+        const enumValueIndex: any = {};
+        if (!enumValues || !enumValues.forEach) {
+            return enumValueIndex;
+        }
+        enumValues.forEach((e: any) => {
+            enumValueIndex[e.value[1]] = e;
+        });
+        return enumValueIndex;
+    }
+
+    /**
+     *
+     * @private
+     */
+    public _setValue(value: Int64): void {
+        // check that value is in bound
+        if (!this._isValueInRange(coerceInt32(value))) {
+            throw new Error("UAMultiStateValueDiscrete#_setValue out of range " + value);
+        }
+
+        const dataType = this._getDataType();
+        if (dataType === DataType.Int64 || dataType === DataType.UInt64) {
+            this.setValueFromSource({ dataType, value });
+        } else {
+            const valueN = value[1];
+            this.setValueFromSource({ dataType, value: valueN });
+        }
+    }
+
+    /**
+     *
+     * @private
+     */
+    public findValueAsText(value?: number | Int64): Variant {
+        const enumValueIndex = this._enumValueIndex();
+
+        if (value === undefined) {
+            throw new Error("Unexpected undefined value");
+        }
+        if (value instanceof Array) {
+            value = value[1];
+        }
+        assert(!((value as any) instanceof Variant));
+        let valueAsText1 = "Invalid";
+        if (enumValueIndex[value]) {
+            valueAsText1 = enumValueIndex[value].displayName;
+        }
+        const result = new Variant({
+            dataType: DataType.LocalizedText,
+            value: coerceLocalizedText(valueAsText1)
+        });
+        return result;
+    }
+    public _getDataType(): DataType {
+        if (this.dataType.value === 26 /* Number */) {
+            return DataType.UInt32;
+        }
+        const dataTypeStr = DataType[this.dataType.value as number] as string;
+        return (DataType as any)[dataTypeStr] as DataType;
+    }
+
+    /**
+     *
+     * @private
+     */
+    public _post_initialize():void {
+        // MultiStateValueDiscrete Variables can have any numeric Data Type;
+        // this includes signed and unsigned integers from 8 to 64 Bit length.
+
+        // istanbul ignore next
+        if (
+            typeof this.dataType.value !== "number" ||
+            [
+                DataType.UInt64,
+                DataType.Int64,
+                DataType.UInt32,
+                DataType.Int32,
+                DataType.UInt16,
+                DataType.Int16,
+                DataType.Byte,
+                DataType.Byte,
+                DataType.SByte,
+                26 /*Number*/
+            ].indexOf(this.dataType.value as number) <= 0
+        ) {
+            throw new Error("Invalid DataType in UAMultiStateValueDiscrete =>" + this.dataType.toString());
+        }
+        // find the enum value type
+        install_synchronization(this);
+    }
+}
+
+export function promoteToMultiStateValueDiscrete<T, DT extends DataType>(node: UAVariable): UAMultiStateValueDiscreteImpl<T, DT> {
+    if (node instanceof UAMultiStateValueDiscreteImpl) {
+        return node; // already promoted
+    }
+    Object.setPrototypeOf(node, UAMultiStateValueDiscreteImpl.prototype);
+    assert(node instanceof UAMultiStateValueDiscreteImpl, "should now  be a State Machine");
+    (node as UAMultiStateValueDiscreteImpl<T, DT>)._post_initialize();
+    return node as UAMultiStateValueDiscreteImpl<T, DT>;
+}
+
+registerNodePromoter(VariableTypeIds.MultiStateValueDiscreteType, promoteToMultiStateValueDiscrete);
+
+export function _addMultiStateValueDiscrete<T, DT extends DataType>(
+    namespace: INamespace,
+    options: AddMultiStateValueDiscreteOptions
+): UAMultiStateValueDiscreteEx<T, DT> {
+    assert(Object.prototype.hasOwnProperty.call(options, "enumValues"));
+    assert(!Object.prototype.hasOwnProperty.call(options, "ValuePrecision"));
+
+    const addressSpace = namespace.addressSpace;
+
+    const multiStateValueDiscreteType = addressSpace.findVariableType("MultiStateValueDiscreteType");
+    if (!multiStateValueDiscreteType) {
+        throw new Error("expecting MultiStateValueDiscreteType to be defined , check nodeset xml file");
+    }
+
+    // todo : if options.typeDefinition is specified, check that type is SubTypeOf MultiStateDiscreteType
+
+    // EnumValueType
+    //   value: Int64, displayName: LocalizedText, Description: LocalizedText
+    const enumValues = coerceEnumValues(options.enumValues);
+
+    if (options.value === undefined && enumValues[0]) {
+        options.value = enumValues[0].value; // Int64
+    }
+    let value: undefined | BindVariableOptions;
+    if (typeof options.value === "number" || isValidUInt64(options.value as number | number[])) {
+        if (isValidUInt64(options.value as number | number[])) {
+            value = new Variant({
+                dataType: DataType.UInt32,
+                value: (options.value as Int64)[1] // Low word
+            });
+        } else {
+            value = new Variant({
+                dataType: DataType.UInt32,
+                value: options.value
+            });
+        }
+    } else {
+        value = options.value as any;
+    }
+
+    const cloned_options = {
+        ...options,
+        dataType: DataType.UInt32,
+        typeDefinition: multiStateValueDiscreteType.nodeId,
+        // valueRank:
+        // note : OPCUA Spec 1.03 specifies -1:Scalar (part 8 page 8) but nodeset file specifies -2:Any
+        value,
+        valueRank: -1 // -1 : Scalar
+    };
+
+    const variable = namespace.addVariable(cloned_options) as UAMultiStateValueDiscreteEx<T, DT>;
+
+    add_dataItem_stuff(variable, options);
+
+    namespace.addVariable({
+        accessLevel: "CurrentRead",
+        browseName: { name: "EnumValues", namespaceIndex: 0 },
+        dataType: "EnumValueType",
+        minimumSamplingInterval: 0,
+        modellingRule: options.modellingRule ? "Mandatory" : undefined,
+        propertyOf: variable,
+        typeDefinition: "PropertyType",
+        userAccessLevel: "CurrentRead",
+        value: new Variant({
+            arrayType: VariantArrayType.Array,
+            dataType: DataType.ExtensionObject,
+            value: enumValues
+        })
+    });
+
+    namespace.addVariable({
+        accessLevel: "CurrentRead",
+        browseName: { name: "ValueAsText", namespaceIndex: 0 },
+        dataType: DataType.LocalizedText,
+        minimumSamplingInterval: 0,
+        modellingRule: options.modellingRule ? "Mandatory" : undefined,
+        propertyOf: variable,
+        typeDefinition: "PropertyType",
+        userAccessLevel: "CurrentRead"
+        // value: valueAsText
+    });
+
+    // install additional helpers methods
+    variable.install_extra_properties();
+
+    promoteToMultiStateValueDiscrete(variable);
+
+    assert(variable.enumValues.browseName.toString() === "EnumValues");
+    assert(variable.valueAsText.browseName.toString() === "ValueAsText");
+    return variable;
+}