node-opcua-address-space 2.180.0 → 2.181.0

package/impl/alarms_and_conditions/ua_non_exclusive_limit_alarm_impl.ts

@@ -0,0 +1,232 @@
+/**
+ * @module node-opcua-address-space.AlarmsAndConditions
+ */
+
+import type { BaseNode, UAEventType, UAVariable } from "node-opcua-address-space-base";
+import { assert } from "node-opcua-assert";
+import { NodeClass } from "node-opcua-data-model";
+import type { NodeId } from "node-opcua-nodeid";
+import { StatusCodes } from "node-opcua-status-code";
+import type { VariantOptions } from "node-opcua-variant";
+import type { ConditionInfo } from "../../api/interfaces/alarms_and_conditions/condition_info_i.js";
+import type { InstantiateLimitAlarmOptions } from "../../api/interfaces/alarms_and_conditions/instantiate_limit_alarm_options.js";
+import type { UANonExclusiveLimitAlarmEx } from "../../api/interfaces/alarms_and_conditions/ua_non_exclusive_limit_alarm_ex.js";
+import type { UATwoStateVariableEx } from "../../api/ua_two_state_variable_ex.js";
+import type { NamespacePrivate } from "../namespace_private.js";
+import { _install_TwoStateVariable_machinery } from "../state_machine/ua_two_state_variable.js";
+import { ConditionInfoImpl } from "./condition_info_impl.js";
+import { UALimitAlarmImpl, UALimitAlarmImplBase } from "./ua_limit_alarm_impl.js";
+
+interface IState {
+    highHigh: boolean | "unset";
+    high: boolean | "unset";
+    low: boolean | "unset";
+    lowLow: boolean | "unset";
+}
+
+/** @internal */
+export class UANonExclusiveLimitAlarmImplBase extends UALimitAlarmImpl implements UANonExclusiveLimitAlarmEx {
+    /**
+     * The four limit states, all optional: which ones exist depends on the limits configured.
+     * Installed as child nodes by the address space, not assigned here - hence `declare`.
+     */
+    public declare readonly highHighState?: UATwoStateVariableEx;
+    public declare readonly highState?: UATwoStateVariableEx;
+    public declare readonly lowState?: UATwoStateVariableEx;
+    public declare readonly lowLowState?: UATwoStateVariableEx;
+
+    public static instantiate(
+        namespace: NamespacePrivate,
+        type: UAEventType | NodeId | string,
+        options: InstantiateLimitAlarmOptions,
+        data?: Record<string, VariantOptions>
+    ): UANonExclusiveLimitAlarmImpl {
+        const addressSpace = namespace.addressSpace;
+
+        options.optionals = options.optionals || [];
+
+        if (Object.hasOwn(options, "lowLowLimit")) {
+            options.optionals.push("LowLowLimit");
+            options.optionals.push("LowLowState");
+        }
+        if (Object.hasOwn(options, "lowLimit")) {
+            options.optionals.push("LowLimit");
+            options.optionals.push("LowState");
+        }
+        if (Object.hasOwn(options, "highLimit")) {
+            options.optionals.push("HighLimit");
+            options.optionals.push("HighState");
+        }
+        if (Object.hasOwn(options, "highHighLimit")) {
+            options.optionals.push("HighHighLimit");
+            options.optionals.push("HighHighState");
+        }
+        const nonExclusiveAlarmType = addressSpace.findEventType(type);
+
+        /* c8 ignore next */
+        if (!nonExclusiveAlarmType) {
+            throw new Error(` cannot find Alarm Condition Type for ${type}`);
+        }
+
+        const nonExclusiveLimitAlarmType = addressSpace.findEventType("NonExclusiveLimitAlarmType");
+        /* c8 ignore next */
+        if (!nonExclusiveLimitAlarmType) {
+            throw new Error("cannot find NonExclusiveLimitAlarmType");
+        }
+        // assert(type nonExclusiveLimitAlarmType.browseName.toString());
+
+        const alarm = UALimitAlarmImplBase.instantiate(namespace, type, options, data) as UANonExclusiveLimitAlarmImpl;
+        Object.setPrototypeOf(alarm, UANonExclusiveLimitAlarmImpl.prototype);
+        assert(alarm instanceof UALimitAlarmImpl);
+        assert(alarm instanceof UANonExclusiveLimitAlarmImpl);
+
+        // ---------------- install States
+        if (alarm.lowLowState) {
+            _install_TwoStateVariable_machinery(alarm.lowLowState, {
+                falseState: "LowLow inactive",
+                trueState: "LowLow active"
+            });
+            alarm.lowLowState.setValue(false);
+            assert(alarm.lowLowLimit !== undefined);
+        }
+        if (alarm.lowState) {
+            _install_TwoStateVariable_machinery(alarm.lowState, {
+                falseState: "Low inactive",
+                trueState: "Low active"
+            });
+            alarm.lowState.setValue(false);
+            assert(alarm.lowLimit !== undefined);
+        }
+        if (alarm.highState) {
+            _install_TwoStateVariable_machinery(alarm.highState, {
+                falseState: "High inactive",
+                trueState: "High active"
+            });
+            alarm.highState.setValue(false);
+            assert(alarm.highLimit !== undefined);
+        }
+        if (alarm.highHighState) {
+            _install_TwoStateVariable_machinery(alarm.highHighState, {
+                falseState: "HighHigh inactive",
+                trueState: "HighHigh active"
+            });
+            alarm.highHighState.setValue(false);
+            assert(alarm.highHighLimit !== undefined);
+        }
+
+        alarm.activeState.setValue(false);
+
+        alarm.updateState();
+
+        return alarm;
+    }
+
+    public calculateConditionInfo(
+        state: string | null,
+        isActive: boolean,
+        value: string,
+        _oldConditionInfo: ConditionInfo
+    ): ConditionInfo {
+        if (!isActive) {
+            return new ConditionInfoImpl({
+                message: "Back to normal",
+                quality: StatusCodes.Good,
+                retain: true,
+                severity: 0
+            });
+        } else {
+            return new ConditionInfoImpl({
+                message: `Condition is ${value} and state is ${state}`,
+                quality: StatusCodes.Good,
+                retain: true,
+                severity: 150
+            });
+        }
+    }
+
+    public _signalNewCondition2(states: IState, isActive: boolean, value: string): void {
+        const alarm = this as BaseNode;
+
+        if (typeof states === "string") {
+            return;
+        }
+
+        function _install(name: keyof IState) {
+            if (states[name] !== "unset") {
+                // browseName is PascalCase (e.g. HighHighState) while the IState key is camelCase
+                const browseName = `${name[0].toUpperCase()}${name.slice(1)}State`;
+                const state = alarm.getChildByName(browseName) as
+                    | (UAVariable & {
+                          setValue(value: boolean): void;
+                      })
+                    | null;
+                if (!state || state.nodeClass !== NodeClass.Variable || !state.setValue) {
+                    throw new Error(`expecting a ${browseName} component`);
+                }
+                state.setValue(states[name]);
+            }
+        }
+
+        _install("highHigh");
+        _install("high");
+        _install("low");
+        _install("lowLow");
+
+        // build-up state string
+        let state_str = Object.keys(states)
+            .map((s) => (states[s as keyof IState] ? s : null))
+            .filter((a) => a !== null)
+            .join(";"); //
+
+        state_str = JSON.stringify(states);
+
+        UALimitAlarmImpl.prototype._signalNewCondition.call(this, state_str, isActive, value);
+    }
+    protected _setStateBasedOnInputValue(value: number): void {
+        assert(Number.isFinite(value), "expecting a valid value here");
+
+        let isActive = false;
+
+        const states: IState = {
+            highHigh: this.highHighState ? this.highHighState.getValue() : "unset",
+            high: this.highState ? this.highState.getValue() : "unset",
+            low: this.lowState ? this.lowState.getValue() : "unset",
+            lowLow: this.lowLowState ? this.lowLowState.getValue() : "unset"
+        };
+
+        let count = 0;
+
+        function ___p(stateName: keyof typeof states, func_value: () => boolean) {
+            if (states[stateName] !== "unset") {
+                const val = func_value();
+                isActive = isActive || val;
+                if (states[stateName] !== val) {
+                    states[stateName] = val;
+                    count += 1;
+                }
+            }
+        }
+
+        ___p("highHigh", () => {
+            return this.getHighHighLimit() < value;
+        });
+        ___p("high", () => {
+            return this.getHighLimit() < value;
+        });
+        ___p("low", () => {
+            return this.getLowLimit() > value;
+        });
+        ___p("lowLow", () => {
+            return this.getLowLowLimit() > value;
+        });
+
+        if (count > 0) {
+            this._signalNewCondition2(states, isActive, value.toFixed(3));
+        }
+    }
+}
+
+/** @internal */
+export type UANonExclusiveLimitAlarmImpl = UANonExclusiveLimitAlarmImplBase;
+/** @internal */
+export const UANonExclusiveLimitAlarmImpl = UANonExclusiveLimitAlarmImplBase;

package/impl/alarms_and_conditions/ua_off_normal_alarm_impl.ts

@@ -0,0 +1,216 @@
+/**
+ * @module node-opcua-address-space.AlarmsAndConditions
+ */
+import type { INamespace, UAProperty, UAVariable, UAVariableT } from "node-opcua-address-space-base";
+import { assert } from "node-opcua-assert";
+import type { DataValue } from "node-opcua-data-value";
+import { NodeId, type NodeIdLike } from "node-opcua-nodeid";
+
+import type { UAOffNormalAlarm_Base } from "node-opcua-nodeset-ua";
+import { isNullOrUndefined } from "node-opcua-utils";
+import { DataType, type VariantOptions } from "node-opcua-variant";
+import type { InstantiateOffNormalAlarmOptions } from "../../api/interfaces/alarms_and_conditions/instantiate_off_normal_alarm_options.js";
+import type { UADiscreteAlarmEx } from "../../api/interfaces/alarms_and_conditions/ua_discrete_alarm_ex.js";
+import type { AddressSpacePrivate } from "../address_space_private.js";
+import { UADiscreteAlarmImplBase } from "./ua_discrete_alarm_impl.js";
+
+function isEqual(value1: unknown, value2: unknown): boolean {
+    return value1 === value2;
+}
+
+export declare interface UAOffNormalAlarmEx
+    extends Omit<
+            UAOffNormalAlarm_Base,
+            | "ackedState"
+            | "activeState"
+            | "confirmedState"
+            | "enabledState"
+            | "latchedState"
+            | "outOfServiceState"
+            | "shelvingState"
+            | "silenceState"
+            | "suppressedState"
+        >,
+        UADiscreteAlarmEx {
+    getNormalStateNode(): UAVariableT<NodeId, DataType.NodeId> | null;
+
+    getNormalStateValue(): NodeId | null;
+
+    setNormalStateValue(value: NodeIdLike): void;
+}
+
+/**
+ * The OffNormalAlarmType is a specialization of the DiscreteAlarmType intended to represent a
+ * discrete Condition that is considered to be not normal.
+ * This sub type is usually used to indicate that a discrete value is in an Alarm state, it is active as
+ * long as a non-normal value is present.
+ */
+export class UAOffNormalAlarmImplBase extends UADiscreteAlarmImplBase implements UAOffNormalAlarmEx {
+    /** installed as a child node by the address space, not assigned here - hence `declare` */
+    public declare readonly normalState: UAProperty<NodeId, DataType.NodeId>;
+
+    /**
+     * When the value of inputNode doesn't match the normalState node value, then the alarm is raised.
+     *
+     */
+    public static instantiate<_T, _DT extends DataType>(
+        namespace: INamespace,
+        limitAlarmTypeId: string | NodeId,
+        options: InstantiateOffNormalAlarmOptions,
+        data?: Record<string, VariantOptions>
+    ): UAOffNormalAlarmImpl {
+        const addressSpace = namespace.addressSpace as AddressSpacePrivate;
+
+        const offNormalAlarmType = addressSpace.findEventType("OffNormalAlarmType");
+        /* c8 ignore next */
+        if (!offNormalAlarmType) {
+            throw new Error("cannot find offNormalAlarmType");
+        }
+
+        assert(Object.hasOwn(options, "inputNode"), "must provide inputNode"); // must provide a inputNode
+        assert(Object.hasOwn(options, "normalState"), "must provide a normalState Node"); // must provide a inputNode
+        options.optionals = options.optionals || [];
+
+        assert(Object.hasOwn(options, "inputNode"), "must provide inputNode"); // must provide a inputNode
+        const alarmNode = UADiscreteAlarmImplBase.instantiate(namespace, limitAlarmTypeId, options, data) as UAOffNormalAlarmImpl;
+        Object.setPrototypeOf(alarmNode, UAOffNormalAlarmImpl.prototype);
+
+        /**
+         * The InputNode Property provides the NodeId of the Variable the Value of which is used as primary input in
+         * the calculation of the Alarm state.
+         *
+         * If this Variable is not in the AddressSpace, a NULL NodeId shall be provided.
+         *
+         * In some systems, an Alarm may be calculated based on multiple Variables Values;
+         * it is up to the system to determine which Variable’s NodeId is used.
+         */
+        const inputNode = addressSpace._coerceNode(options.inputNode) as UAVariable | null;
+        // note: alarmNode.inputNode.readValue() already set by DiscreteAlarmImpl.instantiate
+
+        if (inputNode) {
+            // install inputNode Node monitoring for change
+            alarmNode.installInputNodeMonitoring(options.inputNode);
+        }
+
+        /**
+         * The NormalState Property is a Property that points to a Variable which has a value that corresponds to one
+         * of the possible values of the Variable pointed to by the InputNode Property where the NormalState Property
+         * Variable value is the value that is considered to be the normal state of the Variable pointed to by the InputNode
+         * Property. When the value of the Variable referenced by the InputNode Property is not equal to the value of the
+         * NormalState Property the Alarm is Active.
+         *
+         * If this Variable is not in the AddressSpace, a NULL NodeId shall be provided.
+         *
+         */
+        if (options.normalState) {
+            const normalState = addressSpace._coerceNode(options.normalState) as UAVariable | null;
+            const normalStateNodeId = normalState ? normalState.nodeId : new NodeId();
+            alarmNode.normalState.setValueFromSource({ dataType: DataType.NodeId, value: normalStateNodeId });
+            alarmNode.normalState.on("value_changed", (_newDataValue: DataValue) => {
+                // The node that contains the normalState value has changed.
+                //   we must remove the listener on current normalState and replace
+                //   normalState with the new one and set listener again
+                //   to do:
+            });
+            if (normalState) {
+                // install normalState monitoring for change
+                normalState.on("value_changed", (newDataValue: DataValue /*, oldDataValue: DataValue*/) => {
+                    alarmNode._onNormalStateDataValueChange(newDataValue);
+                });
+            }
+        } else {
+            alarmNode.normalState.setValueFromSource({ dataType: DataType.NodeId, value: NodeId.nullNodeId });
+        }
+
+        alarmNode._mayBe_updateAlarmState();
+
+        return alarmNode;
+    }
+
+    // HasProperty Variable NormalState NodeId PropertyType Mandatory
+    // The NormalState Property is a Property that points to a Variable which has a value that
+    // corresponds to one of the possible values of the Variable pointed to by the InputNode
+    // Property where the NormalState Property Variable value is the value that is considered to be
+    // the normal state of the Variable pointed to by the InputNode Property. When the value of the
+    // Variable referenced by the InputNode Property is not equal to the value of the NormalState
+    // Property the Alarm is Active. If this Variable is not in the AddressSpace, a Null NodeId shall
+    // be provided.
+    public getNormalStateNode(): UAVariableT<NodeId, DataType.NodeId> | null {
+        const nodeId = this.normalState.readValue().value.value;
+        const node = this.addressSpace.findNode(nodeId) as UAVariableT<NodeId, DataType.NodeId>;
+        if (!node) {
+            return null;
+        }
+        return node;
+    }
+
+    /**
+     */
+    public getNormalStateValue(): NodeId | null {
+        const normalStateNode = this.getNormalStateNode();
+        if (!normalStateNode) {
+            return null;
+        }
+        return normalStateNode.readValue().value.value as NodeId;
+    }
+
+    /**
+     */
+    public setNormalStateValue(_value: NodeIdLike): void {
+        const _normalStateNode = this.getNormalStateNode();
+        throw new Error("Not Implemented yet");
+    }
+
+    public updateAlarmState(isActive: boolean, message: string) {
+        if (isActive === this.activeState.getValue()) {
+            // no change => ignore !
+            return;
+        }
+        const stateName = isActive ? "Active" : "Inactive";
+        // also raise the event
+        this._signalNewCondition(stateName, isActive, message);
+        if (!isActive) {
+            this.currentBranch().setRetain(false);
+        }
+    }
+
+    _mayBe_updateAlarmState(normalStateValue?: NodeId | null, inputValue?: unknown): void {
+        if (isNullOrUndefined(normalStateValue) || isNullOrUndefined(inputValue)) {
+            this.activeState.setValue(false);
+            return;
+        }
+        const isActive = !isEqual(normalStateValue, inputValue);
+        this.updateAlarmState(isActive, "automatique update");
+    }
+
+    protected _onInputDataValueChange(dataValue: DataValue): void {
+        if (dataValue.statusCode.isNotGood()) {
+            // what shall we do ?
+            return;
+        }
+        if (dataValue.value.dataType === DataType.Null) {
+            // what shall we do ?
+            return;
+        }
+        const inputValue = dataValue.value.value;
+        const normalStateValue = this.getNormalStateValue();
+        this._mayBe_updateAlarmState(normalStateValue, inputValue);
+    }
+
+    protected _onNormalStateDataValueChange(dataValue: DataValue): void {
+        if (dataValue.statusCode.isNotGood()) {
+            // what shall we do ?
+            return;
+        }
+        if (dataValue.value.dataType === DataType.Null) {
+            // what shall we do ?
+            return;
+        }
+        const normalStateValue = dataValue.value.value;
+        const inputValue = this.getInputNodeValue();
+        this._mayBe_updateAlarmState(normalStateValue, inputValue);
+    }
+}
+
+export type UAOffNormalAlarmImpl = UAOffNormalAlarmImplBase;
+export const UAOffNormalAlarmImpl = UAOffNormalAlarmImplBase;

package/impl/alarms_and_conditions/ua_system_off_normal_alarm_impl.ts

@@ -0,0 +1,26 @@
+/**
+ * @module node-opcua-address-space.AlarmsAndConditions
+ */
+import type { INamespace } from "node-opcua-address-space-base";
+import type { NodeId } from "node-opcua-nodeid";
+import type { VariantOptions } from "node-opcua-variant";
+import type { InstantiateOffNormalAlarmOptions } from "../../api/interfaces/alarms_and_conditions/instantiate_off_normal_alarm_options.js";
+import { UAOffNormalAlarmImpl, UAOffNormalAlarmImplBase } from "./ua_off_normal_alarm_impl.js";
+
+/**
+ *
+ * This Condition is used by a Server to indicate that an underlying system that is providing  Alarm information is
+ * having a communication problem and that the Server may have invalid or incomplete Condition state in the
+ * Subscription.
+ *
+ */
+export class UASystemOffNormalAlarmImpl extends UAOffNormalAlarmImpl {
+    public static instantiate(
+        namespace: INamespace,
+        limitAlarmTypeId: string | NodeId,
+        options: InstantiateOffNormalAlarmOptions,
+        data?: Record<string, VariantOptions>
+    ): UASystemOffNormalAlarmImpl {
+        return UAOffNormalAlarmImplBase.instantiate(namespace, limitAlarmTypeId, options, data) as UASystemOffNormalAlarmImpl;
+    }
+}

package/impl/apply_condition_refresh.ts

@@ -0,0 +1,56 @@
+import type { UAObject, UAVariable } from "../api/index.js";
+import type { UAObjectImpl } from "./ua_object_impl.js";
+
+export type ConditionRefreshCache = Map<string, UAObjectImpl>;
+
+/**
+ * The condition subsystem is recognised structurally rather than with
+ * `instanceof UAConditionImpl`.
+ *
+ * Importing that class as a value from here closed an eight-file import cycle:
+ * ua_object_impl and ua_variable_impl both import this module, this module imported
+ * UAConditionImpl, and UAConditionImpl reaches back to both of them through
+ * `extends UABaseEventImplBase` and `extends UAObjectImpl`.
+ *
+ * Under CommonJS that is survivable, because the second module to load sees a partially
+ * populated exports object and nothing touches the missing half until a function runs.
+ * Under ESM a class in a cycle is in the temporal dead zone while the cycle is being
+ * evaluated, so `class UABaseEventImplBase extends UAObjectImpl` would throw a
+ * ReferenceError as the graph loads.
+ *
+ * `_resend_conditionEvents` is declared only on UAConditionImpl, so this test selects
+ * exactly what the `instanceof` selected, subclasses included. It is also the idiom this
+ * same function already uses for `notifier._conditionRefresh` below.
+ */
+interface ConditionLike {
+    _resend_conditionEvents(): 0 | 1;
+}
+
+function isCondition(node: object): node is ConditionLike {
+    return typeof (node as Partial<ConditionLike>)._resend_conditionEvents === "function";
+}
+
+export function apply_condition_refresh(this: UAObject | UAVariable, cache?: ConditionRefreshCache): void {
+    // visit all notifiers recursively
+    cache = cache || new Map();
+    const notifiers = this.getNotifiers();
+    const eventSources = this.getEventSources();
+
+    const conditions = this.findReferencesAsObject("HasCondition", true);
+    for (const condition of conditions) {
+        if (isCondition(condition)) {
+            condition._resend_conditionEvents();
+        }
+    }
+    const arr = [...notifiers, ...eventSources] as UAObjectImpl[];
+
+    for (const notifier of arr) {
+        const key = notifier.nodeId.toString();
+        if (!cache.has(key)) {
+            cache.set(key, notifier);
+            if (notifier._conditionRefresh) {
+                notifier._conditionRefresh(cache);
+            }
+        }
+    }
+}