@aryacode/dsh-engineering 0.5.0 → 0.6.0

package/vendor/optix/netlogic/pages/opcua.md

@@ -0,0 +1,325 @@
+# OPC/UA
+
+## Node's references
+
+In OPC/UA, some nodes may have additional references are explicit relationship (a named pointer) from one Node to another
+
+```csharp
+[ExportMethod]
+public void ReadReference(NodeId element)
+{
+    // Get to the element where we want to investigate the OPC/UA references
+    IUANode targetNode = InformationModel.Get(element);
+    // Assuming the node exists
+    if (targetNode != null)
+    {
+        // Loop per each reference and list it in the console output
+        foreach (var item in targetNode.Refs.GetReferences())
+        {
+            Log.Info("References", $"ReferenceTypeId: {item.ReferenceTypeId}, TargetNodeId: {item.TargetNodeId}, TargetNode: {item.TargetNode.BrowseName}");
+        }
+    }
+    else
+    {
+        Log.Info("References", "Cannot find such node in the current project");
+    }
+}
+```
+
+## Read arbitrary tag from an OPC/UA Server
+
+> [!WARNING]
+> This method involves some low-level OPC/UA operations and may not be recommended for production usage. It is recommended to use the OPC/UA Client TagImporter instead.
+
+> [!NOTE]
+> This method can only be used at runtime.
+
+This method allows to read any OPC/UA variables from a remote server knowing its `NameSpaceIndex` and `ID`. The following examples reads the `Server > ServerStatus > State` (0/2259) variable from the UaAnsiCServer from the OPC Foundation 
+
+### FactoryTalk Optix 1.6.x or older
+
+```csharp
+// This list comes from the OPC/UA specification
+enum OpcAttributes
+{
+    NodeId = 1,
+    NodeClass = 2,
+    BrowseName = 3,
+    DisplayName = 4,
+    Description = 5,
+    WriteMask = 6,
+    UserWriteMask = 7,
+    IsAbstract = 8,
+    Symmetric = 9,
+    InverseName = 10,
+    ContainsNoLoops = 11,
+    EventNotifier = 12,
+    Value = 13,
+    DataType = 14,
+    ValueRank = 15,
+    ArrayDimensions = 16,
+    AccessLevel = 17,
+    UserAccessLevel = 18,
+    MinimumSamplingInterval = 19,
+    Historizing = 20,
+    Executable = 21,
+    UserExecutable = 22,
+    DataTypeDefinition = 23,
+    RolePermissions = 24,
+    UserRolePermissions = 25,
+    AccessRestrictions = 26,
+    AccessLevelEx = 27,
+    BrowsePath = 64,
+    Quality = 65,
+    StatusCode = 66,
+    SourceTimestamp = 67,
+    ServerTimestamp = 68,
+    ActualDataType = 69,
+    ActualArrayDimensions = 70
+};
+
+[ExportMethod]
+public void ReadArbitraryValueFromRemoteOpcUaServer(int nameSpaceIndex, uint identifier)
+{
+    // Get the OPC/UA Client from the project
+    var opc = Project.Current.Get<OPCUAClient>("OPC-UA/OPCUAClient1");
+
+    // OPC/UA Variable to read from the remote server
+    object[] opcVariable = new object[3]
+    {
+        new NodeId(nameSpaceIndex, identifier), // NodeId of the variable to read (UaExpert can be used to get these values)
+        OpcAttributes.Value,                    // Attribute ID to read (13 = Value), see enumeration above
+        new uint[0]                             // Indexes, for simple scalar tags this is an empty array
+    };
+
+    // Create a Struct object that holds the information of the remote variable to be passed to the OPC/UA Client
+    // Syntax: new Struct(NodeId dataTypeId, object[] values)
+    // Where:
+    // - DataTypeId is the NodeId of the DataType expected as input argument of the method (50 is the ReadValues DataType)
+    // - Values is an array containing the information of the variable to read
+    UAManagedCore.Struct asd = new Struct(new NodeId(FTOptix.OPCUAClient.ObjectTypes.OPCUAClient.NamespaceIndex, 50), opcVariable);
+
+    // The ExecuteMethod method of the OPC/UA Client is used to call the ReadValues method of the OPC/UA Server
+    // This expects an object[] as input parameters, so we will create a mono-dimensional array with the Struct object
+    object[] inputArgs = new object[1];
+    // The first element of the array is the Struct object that we created
+    inputArgs[0] = new UAManagedCore.Struct[1];
+    // The first element of the Struct array is the variable information to read
+    ((UAManagedCore.Struct[])inputArgs[0])[0] = asd;
+
+    // The ExecuteMethod method returns an object[] with the output parameters of the method
+    object[] outputArgs = new object[1];
+
+    // Call the ReadValues method of the OPC/UA Server
+    opc.ExecuteMethod("ReadValues", inputArgs, out outputArgs); // OPCUA\OPCUAClient\OPCUAClient\Module.xml.in
+
+    // The outputArgs array contains the output parameters of the ReadValues method
+    var output = (UAManagedCore.Struct[])outputArgs[0];
+    Log.Info(output[0].Values[0].ToString());
+}
+```
+
+### FactoryTalk Optix 1.7.x or newer
+
+```csharp
+struct ReadResult
+{
+    public object Value;
+    public uint StatusCode;
+
+    public ReadResult(UAManagedCore.Struct s)
+    {
+        Value = s.Values[0];
+        StatusCode = (uint)s.Values[1];
+    }
+
+    public bool IsGood => (StatusCode & 0xC0000000) == 0;
+
+    public string StatusName
+    {
+        get
+        {
+            if (Enum.IsDefined(typeof(OpcUaStatusCode), StatusCode))
+                return ((OpcUaStatusCode)StatusCode).ToString();
+            return $"0x{StatusCode:X8}";
+        }
+    }
+}
+
+enum OpcUaStatusCode : uint
+{
+    Good = 0x00000000,
+    BadUnexpectedError = 0x80010000,
+    BadInternalError = 0x80020000,
+    BadNodeIdInvalid = 0x80330000,
+    BadAttributeIdInvalid = 0x80350000,
+    BadNodeIdUnknown = 0x80340000,
+    BadNotReadable = 0x803A0000,
+    BadNotWritable = 0x803B0000,
+    BadTypeMismatch = 0x80740000,
+    BadInvalidArgument = 0x80AB0000,
+    BadOutOfRange = 0x803C0000,
+    BadNoCommunication = 0x80310000,
+    BadTimeout = 0x800A0000,
+    BadServerNotConnected = 0x800D0000,
+    BadSessionIdInvalid = 0x80250000,
+    BadUserAccessDenied = 0x801F0000,
+    BadSecurityModeInsufficient = 0x80E60000,
+    BadServiceUnsupported = 0x800B0000,
+}
+
+// This list comes from the OPC/UA specification
+enum OpcAttributes
+{
+    NodeId = 1,
+    NodeClass = 2,
+    BrowseName = 3,
+    DisplayName = 4,
+    Description = 5,
+    WriteMask = 6,
+    UserWriteMask = 7,
+    IsAbstract = 8,
+    Symmetric = 9,
+    InverseName = 10,
+    ContainsNoLoops = 11,
+    EventNotifier = 12,
+    Value = 13,
+    DataType = 14,
+    ValueRank = 15,
+    ArrayDimensions = 16,
+    AccessLevel = 17,
+    UserAccessLevel = 18,
+    MinimumSamplingInterval = 19,
+    Historizing = 20,
+    Executable = 21,
+    UserExecutable = 22,
+    DataTypeDefinition = 23,
+    RolePermissions = 24,
+    UserRolePermissions = 25,
+    AccessRestrictions = 26,
+    AccessLevelEx = 27,
+    BrowsePath = 64,
+    Quality = 65,
+    StatusCode = 66,
+    SourceTimestamp = 67,
+    ServerTimestamp = 68,
+    ActualDataType = 69,
+    ActualArrayDimensions = 70
+};
+
+[ExportMethod]
+public void ReadArbitraryValueFromRemoteOpcUaServer(string namespaceUri, string identifier)
+{
+    // Change this to read a different OPC UA attribute
+    var attribute = OpcAttributes.Value;
+
+    // Get the OPC/UA Client from the project
+    var opc = Project.Current.Get<OPCUAClient>("OPC-UA/OPCUAClient1");
+
+    // Find the local namespace index by searching all registered namespaces.
+    // FTOptix builds aggregated URIs for dynamic namespaces as "{clientGuid}#{remoteNamespaceUri}",
+    // so we match a namespace URI that equals or ends with the provided remote namespace URI.
+    var context = LogicObject.Context;
+    var localNsIndex = context.GetNamespaceIndexes()
+        .Cast<int>()
+        .FirstOrDefault(i => {
+            var uri = context.GetNamespaceUri(i);
+            return uri == namespaceUri || uri.EndsWith("#" + namespaceUri);
+        }, -1);
+
+    if (localNsIndex < 0)
+    {
+        Log.Error($"Namespace URI '{namespaceUri}' not found. Have you imported some tags in the Optix project?");
+        return;
+    }
+
+    FTOptix.Core.ElementAccess ea = new FTOptix.Core.ElementAccess();
+    UAValue eaValue = ea; // implicit conversion to UAValue
+    var emptyElementAccess = (UAManagedCore.Struct)eaValue.Value;
+
+    var nodeIdStr = $"ns={localNsIndex};s={identifier}";
+
+    object[] opcVariable = new object[3]
+    {
+        new NodeId(localNsIndex, identifier),
+        (uint)attribute,
+        emptyElementAccess               // ElementAccess struct, NOT uint[]
+    };
+
+    // Create a Struct object that holds the information of the remote variable to be passed to the OPC/UA Client
+    // Syntax: new Struct(NodeId dataTypeId, object[] values)
+    // Where:
+    // - DataTypeId is the NodeId of the DataType expected as input argument of the method (50 is the ReadValues DataType)
+    // - Values is an array containing the information of the variable to read
+    UAManagedCore.Struct asd = new Struct(new NodeId(FTOptix.OPCUAClient.ObjectTypes.OPCUAClient.NamespaceIndex, 50), opcVariable);
+
+    // The ExecuteMethod method of the OPC/UA Client is used to call the ReadValues method of the OPC/UA Server
+    // This expects an object[] as input parameters, so we will create a mono-dimensional array with the Struct object
+    object[] inputArgs = new object[1];
+    // The first element of the array is the Struct object that we created
+    inputArgs[0] = new UAManagedCore.Struct[1];
+    // The first element of the Struct array is the variable information to read
+    ((UAManagedCore.Struct[])inputArgs[0])[0] = asd;
+
+    // The ExecuteMethod method returns an object[] with the output parameters of the method
+    object[] outputArgs = new object[1];
+
+    // Call the ReadValues method of the OPC/UA Server
+    opc.ExecuteMethod("ReadValues", inputArgs, out outputArgs);
+
+    // The outputArgs array contains the output parameters of the ReadValues method
+    // ReadValueResult struct has 2 fields: [0] = Value, [1] = StatusCode (UInt32)
+    var output = (UAManagedCore.Struct[])outputArgs[0];
+    var result = new ReadResult(output[0]);
+
+    if (!result.IsGood)
+    {
+        Log.Error($"Reading attribute `{attribute}` for `{nodeIdStr}` failed: {result.StatusName} (0x{result.StatusCode:X8})");
+        return;
+    }
+
+    Log.Info($"Reading attribute `{attribute}` for `{nodeIdStr}` returned: `{result.Value}`");
+}
+```
+
+## Change the Status property of a Tag (changing the DataValue structure)
+
+This may be needed in some OPC/UA companion specifications where the Status of a tag is used to detect other status that are not only good or bad
+
+> [!NOTE]
+> This method can only be used at runtime. 
+
+```csharp
+[ExportMethod]
+public void UpdateStatusCode()
+{
+    var myVariable = Project.Current.GetVariable("Model/MyFolder/Test");
+    // The StatusCode shortcut is read-only
+    Log.Info($"Original status code: {myVariable.StatusCode}");
+    // new DataValue(UAValue value, uint statusCode, DateTime sourceTimestamp)
+    // new DataValue(UAValue value, uint statusCode, DateTime sourceTimestamp, DateTime serverTimestamp)
+    myVariable.DataValue = new DataValue(myVariable.Value, 100, DateTime.UtcNow);
+    // The StatusCode shortcut is read-only
+Log.Info($"New status code: {myVariable.StatusCode}");
+}
+```
+
+## Manually create an OPC/UA Client Tag
+
+This script presumes that the OPC/UA Client is already configured in the project and at least a tag was imported (needed to get the NameSpaceIndex). It creates a new tag in the project that will be used to read a variable from the OPC/UA Server.
+
+> [!NOTE]
+> This method can only be used at designtime. 
+
+```csharp
+[ExportMethod]
+public void CreateArbitraryTag()
+{
+    // Get the NameSpaceIndex of the OPC/UA Client, the best solution would be to read it from an imported tag.
+    // This must be in the `.optix` file of the project, so it must be a known index.
+    var nxIndex = LogicObject.Context.GetNamespaceIndex("0ccdea9893ed5102b4fae754ef1732f7#http://www.unifiedautomation.com/DemoServer/");
+    // Create a new variable in the project with the NodeId of the OPC/UA variable to read in the remote server
+    var variable = LogicObject.Context.NodeFactory.MakeVariable(new NodeId(nxIndex, "Demo.Static.Scalar.Double"), "Double", OpcUa.DataTypes.Double, OpcUa.VariableTypes.BaseDataVariableType);
+    // Add the variable to the Objects folder of the OPC/UA client project
+    LogicObject.Owner.GetObject("Objects").Add(variable);
+}

package/vendor/optix/netlogic/pages/plc-tags.md

@@ -0,0 +1,219 @@
+# Field tags
+
+Field tags are functionally identical to Model variables (global variables), but with some additions.
+
+Field tags can be forced to read or write a value to the field device (a.k.a. PLC) or to force the value to be synched to the controller with a specific refresh time.
+
+> [!NOTE]
+> Tags are automatically synchronized with the controller when they are used in:
+> - A page being displayed in any of the UI sessions
+> - Used in a DataLogger or EventLogger
+> - Used as InputVariable of an Alarm
+> - A ValueChange event is subscribed to the tag
+>
+> If none of these conditions are met, the tag will not be synchronized with the controller and will not be updated, so the following techniques to read or write values to the controller are needed.
+
+> [!NOTE]
+> Communication drivers are only loaded at runtime, so all the methods described in this page to read/write/force values to the controller can only be used at runtime, they will not work at design time.
+
+## Introduction
+
+Field tags in FactoryTalk Optix provide several methods for efficiently communicating with PLCs, each with different performance characteristics and use cases. Understanding these methods helps optimize both application performance and network traffic.
+
+### Tags access methods
+
+1. **RemoteVariableSynchronizer**
+
+   - Optimizes data exchange by bundling requests and minimizing network traffic
+   - Efficient for continuous monitoring of multiple tags at specified intervals
+   - Expensive during initial setup but provides optimized ongoing communication
+   - After setup, exchanges tag values in the most optimized way possible
+   - Best for scenarios requiring regular polling of many dispersed tags
+
+2. **RemoteRead/RemoteWrite**
+
+   - Provides synchronous, on-demand reading/writing of specific tags
+   - Best for atomic operations when immediate values are needed
+   - Less efficient for large numbers of tags
+   - InformationModel.RemoteRead() can bundle multiple tag reads for better performance
+
+### RA Ethernet/IP Controller Array Reading (Optix 1.6+)
+
+Starting from FactoryTalk Optix 1.6.x, a major optimization was introduced in the RA Ethernet/IP driver, which allows reading large arrays directly from the controller, significantly improving performance for bulk data operations. The user does not need to manually specify the read mode, as the system automatically optimizes the read operation for large arrays if possible.
+
+This new algorithm:
+- Is highly efficient for reading large blocks of contiguous data
+- Can read large arrays (e.g., 10K DINT array) in ~200ms
+- Requires data to be organized in arrays within the controller
+
+Example:
+
+```csharp
+var tag = Project.Current.Get<Tag>("CommDrivers/RAEtherNet_IPDriver1/RAEtherNet_IPStation1/Tags/Controller Tags/DINT_A10K");
+var value = tag.RemoteRead();
+var arrayInts = (int[])value.Value;
+```
+
+### Performance Considerations
+
+- **Network Traffic**: The `RemoteVariableSynchronizer` drastically reduces network load. For example, reading 10K DINTs with the RA Ethernet/IP driver will require 10x less network traffic when using a `RemoteVariableSynchronizer` compared to a `RemoteRead`.
+- **Cached Values**: Using `Project.Current.GetVariable("MyTag").Value` accesses the last cached value without triggering new controller communication
+- **Hardware Impact**: Consider your network infrastructure, PLC capabilities and host machine capabilities when designing communication patterns
+- **Synchronization Frequency**: Always specify appropriate refresh intervals in Remote Variable Synchronizer to prevent overwhelming the controller (`TimeSpan.FromSeconds()`)
+
+Learning to use these methods effectively can greatly enhance the performance and responsiveness of your FactoryTalk Optix applications, especially in scenarios involving large datasets or frequent updates.
+
+For example:
+
+- A `RemoteVariableSynchronizer` can be created in a global NetLogic to continuously monitor and synchronize multiple tags, ensuring they are always up-to-date without excessive network traffic.
+- All the NetLogic in the project can simply access the synchronized variables using the `Project.Current.GetVariable("MyTag").Value` (either getting or setting the value) method without needing to perform individual reads, which is particularly useful for applications with many tags that need regular updates.
+
+## Remote Variable synchronizer
+
+The `RemoteVariableSynchronizer` allows users to keep some variables synched even if not in use by any current page, it will keep all the children elements updated with the field. This method handles an automatic optimization of the Tags in order to minimize the number of read/write from the controller (while the `RemoteRead` performs a request per each tag and it is much slower)
+
+> [!NOTE]
+> When the `RemoteVariableSynchronizer` is created, it will collect all the children variables and create an optimized read request to the controller, so it is important to create it only once and not every time a page is opened or a variable is needed.
+
+> [!WARNING]
+> The `RemoteVariableSynchronizer` might have significant impact on the communication driver, especially if used with a large number of tags. It is recommended to use it wisely and only for a small number of tags.
+
+### Providing a TimeSpan argument
+
+The `TimeSpan` argument of the `RemoteVariableSynchronizer` should be used to avoid overloading the field device. If the `RemoteVariableSynchronizer` is created without any arguments, it defaults to full-speed synchronization, which can be too fast for the field device to handle. This can lead to performance issues because the iPC (industrial PC) is typically faster than the controller. By specifying a `TimeSpan` argument, you define a refresh interval between subsequent reads, which helps in managing the load on the field device and ensures smoother operation.
+
+Avoid this constructor: `variableSynchronizer = new RemoteVariableSynchronizer();`
+Use this instead: `variableSynchronizer = new RemoteVariableSynchronizer(new TimeSpan.FromSeconds(5));`
+
+The argument can be configure as needed, depending on the speed of the synchronization which is required.
+
+### RemoteVariableSynchronizer example
+
+```csharp
+public override void Start() 
+{
+    // Get the field variable
+    motorSpeed = LogicObject.Owner.GetVariable("Speed");
+    // Create the VariableSynchronizer object and request the update every 5 seconds
+    var updateRate = TimeSpan.FromSeconds(5);
+    variableSynchronizer = new RemoteVariableSynchronizer(updateRate);
+    // Add the variables to the synchronizer
+    variableSynchronizer.Add(motorSpeed);
+    // Add the event to listen to value changes
+    motorSpeed.VariableChange += MotorSpeed_VariableChange;
+}
+public override void Stop() 
+{
+    // Destroy the synchronized on stop
+    variableSynchronizer?.Dispose();
+}
+private void MotorSpeed_VariableChange(object sender, VariableChangeEventArgs e) 
+{
+    // Event listener when value change is detected
+    if (motorSpeed.Value > 200) {
+        Log.Warning("Speed limit reached!");
+    }
+}
+private IUAVariable motorSpeed;
+private RemoteVariableSynchronizer variableSynchronizer;
+```
+
+## RemoteRead
+
+Remote read is a inline read of the field value, code is stopped to read the value, once the variable is updated, the code keeps running
+
+> [!NOTE]
+> The `ChildrenRemoteRead` is just as "slow" as the `RemoteRead`, it is just a recursive approach to a normal `RemoteRead`
+
+### Read simple tags
+
+```csharp
+[ExportMethod]
+public void ReadBitFromPlcInteger(out int value)
+{
+    // Get the plc tag to read
+    var tag1 = Project.Current.GetVariable("CommDrivers/RAEtherNet_IPDriver1/RAEtherNet_IPStation1/Tags/Program:CustomUdtProgram/program_dint_1D");
+    // Read the new values
+    var variableValue = tag1.RemoteRead();
+    // Do something with the values
+    Log.Info($"Value of the plc tag is: {variableValue}");
+}
+```
+
+### Read arrays
+
+```csharp
+[ExportMethod]
+public void ReadBitFromPlcInteger(out int value)
+{
+    // Get the plc tag to read
+    var tag1 = Project.Current.Get<FTOptix.RAEtherNetIP.Tag>("CommDrivers/RAEtherNet_IPDriver1/RAEtherNet_IPStation1/Tags/Program:CustomUdtProgram/program_dint_1D");
+    // Create the remote read object
+    var remoteVariables = new List<RemoteVariable>()
+    {
+        // Add the variables to read to the list
+        new RemoteVariable(tag1),
+    };
+    // Read the new values
+    var values = InformationModel.RemoteRead(remoteVariables).ToList();
+    // Get the field values to a C# variable
+    var plcArray = (int[])values[0].Value.Value;
+    // Do something with the values
+    Log.Info($"Value of first element of the array is {plcArray[0]}");
+    Log.Info($"Bit 5 of first element of the array is {GetBitValue(plcArray[0], 5)}");
+}
+
+private bool GetBitValue(int inputValue, int bitPosition)
+{
+    // Read a specific bit from a word
+    var array = new BitArray(new int[] { inputValue });
+    return array[bitPosition];
+}
+```
+
+### Adding a timeout
+
+```csharp
+// Get the variable to update
+var currentSpeed = Project.Current.GetVariable("Model/Motor/Speed");
+// Try to get the most updated value with a timeout of 100ms
+var newValue = currentSpeed.RemoteRead(100.0);
+```
+
+## RemoteWrite
+
+Similar to the `RemoteRead`, when a value should be sent immediately to the field, a `RemoteWrite` method can be used
+
+### Write a simple value
+
+```csharp
+// Which tag to update
+var currentSpeed = Project.Current.GetVariable("Model/Motor/Speed");
+// Write the new value (no write timeout)
+currentSpeed.RemoteWrite(42);
+```
+
+### Write multiple values
+
+```csharp
+// Which tags to update
+var tag1 = Project.Current.Get<Tag>("CommDrivers/CodesysDriver1/CodesysStation1/Tags/Application/PLC_PRG/VAR1");
+var tag3 = Project.Current.Get<Tag>("CommDrivers/CodesysDriver1/CodesysStation1/Tags/Application/PLC_PRG/VAR3");
+// Create the RemoteWrite object
+var remoteVariableValues = new List<RemoteVariableValue>()
+{
+    new RemoteVariableValue(tag3, 0),
+    new RemoteVariableValue(tag1, 123)
+};
+// Perform the write operation (no write timeout)
+InformationModel.RemoteWrite(remoteVariableValues);
+```
+
+### Adding a timeout
+
+```csharp
+// Get the variable to update
+var currentSpeed = Project.Current.GetVariable("Model/Motor/Speed");
+// Try to write the value 150 with a timeout of 100ms
+currentSpeed.RemoteWrite(150, 100.0);
+```