@aryacode/dsh-engineering 0.5.0 → 0.6.0

package/vendor/optix/netlogic/pages/async-tasks.md

@@ -0,0 +1,236 @@
+# Asynchronous tasks
+
+Asynchronous tasks are very common when running special or long tasks that may negatively impact the overall operation. Asynchronous tasks were mostly designed to be used at Runtime. It is quite frequent to use `LongRunningTask` to run a long process without freezing the FactoryTalk Optix Studio interface even with a DesignTime NetLogic though.
+
+> [!WARNING]
+> Avoid modifying the project structure (pages, tags, etc) while asynchronous tasks are running, especially at DesignTime. This can cause unexpected behavior—for example, editing the project while a task is importing/exporting data may result in conflicts or errors.
+
+## General concepts about Asynchronous tasks
+
+Standard C# language provides multiple ways to run asynchronous operations (such as the `async` modifier for some methods), these can be used in FactoryTalk Optix as long as those methods does not access any of the project structure (pages, tags, etc).
+
+- Example:
+    - async method to read/write a CSV -> GOOD
+    - async method to read a CSV and import it into the TranslationDictionary -> BAD
+
+## Using FactoryTalk Optix Asynchronous tasks
+
+These asynchronous tasks are InformationModel-safe and can be used to access project nodes without concerns
+
+### PeriodicTask
+
+This kind of task allows a specific method to be run every `x` milliseconds, for example to blink a LED or to handle a watchdog.
+
+Please note: the specified interval, is actually the delay between two consecutive runs of the method, and the operation is impacted by the length of the instruction to process. The next run is delayed until the task is completed, for example:
+
+Having a task:
+- PeriodicTask declared every 50mS
+- Method run by the PeriodicTask takes 100mS to process
+
+With this timings, the task is actually run every 150mS, as the interval is actually the delay after which the task is run again.
+
+```csharp
+public override void Start()
+{
+    // Creates a task that runs every second without impacting the UI
+    myPeriodicTask = new PeriodicTask(IncrementVariable, 1000, LogicObject);
+    myPeriodicTask.Start();
+}
+
+public override void Stop()
+{
+    // When the NetLogic is disposed, kill the task too
+    myPeriodicTask?.Dispose();
+}
+
+private void IncrementVariable()
+{
+    // Action to be run every tick of the periodic task
+    …
+}
+
+private PeriodicTask myPeriodicTask;
+```
+
+### DelayedTask
+
+This kind of task will trigger a method after `x` milliseconds it is called, this can be useful for example to hide a toast notification after some time
+
+```csharp
+public override void Start()
+{
+    // Create an action that is run after 10s the page is loaded
+    // this could also be a method called by a button or any trigger
+    myDelayedTask = new DelayedTask(ResetLabelText, 10000, LogicObject);
+    myDelayedTask.Start();
+}
+
+public override void Stop()
+{
+    // Make sure to dispose the task when the NetLogic is stopped
+    myDelayedTask?.Dispose();
+}
+
+private void ResetLabelText()
+{
+    // Action to be run after the delay
+    …
+}
+
+private DelayedTask myDelayedTask;
+```
+
+### LongRunningTask
+
+This is the most similar approach to the `async` modifier of the standard C# scripting, it allows to create a dedicated thread and run it without affecting the main code operation.
+An `async` modifier can also be used, but an async method **cannot** access any project node (it may cause concurrency issues), in such cases, use a LongRunningTask instead.
+
+```csharp
+class public override void Start()
+{
+    // Create a dedicated thread to run a long or demanding process
+    // Without stopping the FactoryTalk Optix Runtime or Studio
+    myLongRunningTask = new LongRunningTask(ProcessCSVFile, LogicObject);
+    myLongRunningTask.Start();
+}
+
+public override void Stop()
+{
+    // Make sure to dispose the thread once the NetLogic is stopped
+    myLongRunningTask?.Dispose();
+}
+
+private void ProcessCsvFile(LongRunningTask task)
+{
+    // Process that takes long time to be run
+    …
+}
+
+private LongRunningTask myLongRunningTask;
+```
+
+#### Passing arguments to a LongRunningTask
+
+An overload of the LongRunningTask constructor accepts a task and an object, the task can be used to check if a cancellation was requested, while the object can be used to pass arguments to the thread that is being generated
+
+```csharp
+[ExportMethod]
+public void StartExam(bool free, string clientID = "", string examCode = "")
+{
+    Log.Debug(examCode == "" ? "ExamLogic.StartExam" : "ExamLogic.StartExamCertification", "Starting exam");
+    startExamTask?.Dispose();
+    var argumentsObject = new StartExamParameters { isFree = free, clientID = clientID, examCode = examCode };
+    startExamTask = new LongRunningTask(StartExamMethod, argumentsObject, LogicObject);
+    startExamTask.Start();
+    Log.Debug(examCode == "" ? "ExamLogic.StartExam" : "ExamLogic.StartExamCertification", "Leaving method");
+}
+
+private void StartExamMethod(LongRunningTask task, object examParameters)
+{
+    // Get the parameters
+    var argumentsObject = (StartExamParameters)examParameters;
+    string clientID = argumentsObject.clientID;
+    string examCode = argumentsObject.examCode;
+    bool free = argumentsObject.isFree;
+    // Do other stuff
+    // ...
+}
+
+private sealed class StartExamParameters
+{
+    public bool isFree;
+    public string clientID;
+    public string examCode;
+}
+
+private LongRunningTask startExamTask = null;
+```
+
+## Some general notes on asynchronous tasks
+
+### Cancellation token
+
+When a task is called asynchronously (especially in LongRunningTask), then the method itself should check if a cancellation request is pending (see [documentation here](https://learn.microsoft.com/en-us/dotnet/standard/parallel-programming/task-cancellation)) and act accordingly, for example:
+
+```csharp
+public class LongRunningLogic : BaseNetLogic
+{
+    public override void Start()
+    {
+        // Create the new LongRunningTask and run it
+        myTask = new LongRunningTask(MyMethod, LogicObject);
+        myTask.Start();
+    }
+
+    public override void Stop()
+    {
+        // Request a cancellation event to the async task
+        myTask?.Dispose();
+    }
+
+    public void MyMethod()
+    {
+        for (int i = 0; i < 1000; i++)
+        {
+            // Check if the somebody requested to dispose this task
+            if (myTask.IsCancellationRequested)
+                return;
+            // Do some work here
+            Thread.Sleep(1000);
+            Owner.Get<Led>("LED1").Active = !Owner.Get<Led>("LED1").Active;
+        }
+    }
+
+    private LongRunningTask myTask;
+}
+```
+
+### Check if a task is running
+
+> [!WARNING]
+> This is a non-public API (accessed using C# reflections) and may be subject to changes, please refer to the official documentation to access the publicly available APIs which are guaranteed to be maintained.
+
+```csharp
+[ExportMethod]
+public void DoStuff()
+{
+    // Initialize the LongRunningTask
+    var myTask = new LongRunningTask(MyMethod, LogicObject);
+
+    // Do some stuff
+
+    // Check if the task is still running
+    while (IsTaskRunning(task))
+    {
+        Log.Info("The task is still running...");
+        Thread.Sleep(100);
+    }
+}
+
+private void MyMethod(LongRunningTask task)
+{
+    // Do some work
+    throw new NotImplementedException();
+}
+
+private static bool IsTaskRunning(LongRunningTask task)
+{
+    // Get the type of the LongRunningTask
+    Type taskType = task.GetType();
+
+    // Get the FieldInfo object for the isRunning field
+    FieldInfo isRunningField = taskType.GetField("isRunning", BindingFlags.NonPublic | BindingFlags.Instance);
+
+    // Check if the field was found
+    if (isRunningField != null)
+    {
+        // Get the value of the isRunning field
+        bool isRunning = (bool) isRunningField.GetValue(task);
+        return isRunning;
+    }
+    else
+    {
+        throw new InvalidOperationException("The isRunning field was not found on the LongRunningTask type.");
+    }
+}
+```

package/vendor/optix/netlogic/pages/audit-signature.md

@@ -0,0 +1,91 @@
+# Audit Signature (CFR21 workflow)
+
+The Audit Signature is a special type of object that can be added to any variable in FactoryTalk Optix, it allows to track the changes on the variable and who made those changes, this is specially useful for CFR21 compliance.
+
+The following APIs are intended to be used at DesignTime to prepare the InformationModel with the necessary Audit Signatures.
+
+## Add signature to a variable
+
+```csharp
+[ExportMethod]
+public void AddSignatureToVariable()
+{
+    var sourceVarPointer = LogicObject.GetVariable("SourceVariable") ?? throw new ArgumentException("Cannot find source variable");
+    var sourceVar = InformationModel.GetVariable(sourceVarPointer.Value) ?? throw new ArgumentException("Cannot find source variable");
+    // Create the audit variable
+    var sourceVar = InformationModel.Make<AuditInfo>("AuditSigning Signature");
+    sourceVar.Add(auditVar);
+}
+```
+
+## Add signature on all bits of a word
+
+```csharp
+[ExportMethod]
+public void CreateAuditOnVariableSingleBits()
+{
+    // Check if InputVariable is populated
+    var sourceVarPointer = LogicObject.GetVariable("SourceVariable") ?? throw new ArgumentException("Cannot find source variable");
+    var sourceVar = InformationModel.GetVariable(sourceVarPointer.Value) ?? throw new ArgumentException("Cannot find source variable");
+
+    // Check if TargetFolder is populated
+    var targetFolderPointer = LogicObject.GetVariable("TargetFolder") ?? throw new ArgumentException("Cannot find target folder");
+    var targetFolder = InformationModel.Get<Folder>(targetFolderPointer.Value) ?? throw new ArgumentException("Cannot find target folder");
+
+    // Prepare object for the method
+    var methodArguments = new object[] { sourceVar, targetFolder };
+
+    // Run the method in a separate thread
+    var myTask = new LongRunningTask(CreateSingleBits, methodArguments, LogicObject);
+    myTask.Start();
+}
+
+private void CreateSingleBits(LongRunningTask task, object methodArgumentsObj)
+{
+    // Extract the method arguments
+    var methodArguments = (object[]) methodArgumentsObj;
+    var sourceVar = (IUAVariable) methodArguments[0];
+    var targetFolder = (Folder) methodArguments[1];
+
+    // Variable to store the number of bits
+    var numberOfBits = 0;
+
+    // Get the type of the source variable. Add new datatypes if needed
+    if (sourceVar.DataType == OpcUa.DataTypes.Int32 || sourceVar.DataType == OpcUa.DataTypes.UInt32)
+        numberOfBits = 32;
+    else if (sourceVar.DataType == OpcUa.DataTypes.Int16 || sourceVar.DataType == OpcUa.DataTypes.UInt16)
+        numberOfBits = 16;
+    else if (sourceVar.DataType == OpcUa.DataTypes.Float)
+        numberOfBits = 32;
+    else if (sourceVar.DataType == OpcUa.DataTypes.Double)
+        numberOfBits = 64;
+    else
+        throw new ArgumentException("Unsupported data type");
+
+    // Create the variable for each bit and add the auditing
+    for (int i = 0; i < numberOfBits; i++)
+    {
+        // Create the new variable
+        var newVariable = InformationModel.MakeVariable($"{sourceVar.BrowseName}_Bit{i}", OpcUa.DataTypes.Boolean);
+        newVariable.SetDynamicLink(sourceVar, DynamicLinkMode.ReadWrite);
+
+        // Modify the dynamic link to read only the bit using HasDynamicLink reference
+        var dynamicLinkVariable = newVariable.Refs.GetVariable(FTOptix.CoreBase.ReferenceTypes.HasDynamicLink) as IUAVariable;
+        if (dynamicLinkVariable != null)
+        {
+            dynamicLinkVariable.Value = (string)dynamicLinkVariable.Value + $".{i}";
+        }
+
+        // Create the audit variable
+        var auditVar = InformationModel.Make<AuditInfo>("AuditSigning Signature");
+        newVariable.Add(auditVar);
+
+        // Check if the variable already exists and delete it
+        if (targetFolder.Children.OfType<IUAVariable>().Any(v => v.BrowseName == newVariable.BrowseName))
+            targetFolder.Get(newVariable.BrowseName).Delete();
+
+        // Add the variable to the target folder
+        targetFolder.Add(newVariable);
+    }
+}
+```

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

@@ -0,0 +1,122 @@
+# Colors
+
+FactoryTalk Optix allows you to set colors on UI objects (such as `Led`, `Rectangle`, `Panel`, etc.) using the `Color` struct. You can assign colors using pre-defined named colors or create custom colors with specific RGB/ARGB values.
+
+## The Color Struct
+
+The `Color` struct has the following properties:
+- `A` (byte) - Alpha channel (transparency): 0 = fully transparent, 255 = fully opaque
+- `R` (byte) - Red channel: 0-255
+- `G` (byte) - Green channel: 0-255
+- `B` (byte) - Blue channel: 0-255
+- `ARGB` (uint) - Combined ARGB value as a single 32-bit unsigned integer
+
+## Creating Colors
+
+### Using Pre-defined Named Colors
+
+FT Optix provides hundreds of named colors through the `Colors` static class, such as:
+- `Colors.Red`
+- `Colors.Blue`
+- `Colors.Green`
+- `Colors.Goldenrod`
+- `Colors.Cyan`
+- `Colors.Black`
+- And many more...
+
+```csharp
+// Create a LED widget
+var ledWidget = InformationModel.Make<Led>("statusIndicator");
+
+// Set the LED color using a pre-defined named color
+ledWidget.Color = Colors.Red;
+
+// Add the LED to your UI
+...
+```
+
+### Using ARGB Constructor (Explicit Bytes)
+
+Create a custom color by specifying the Alpha, Red, Green, and Blue channels as individual bytes:
+
+```csharp
+// Create a LED widget
+var ledWidget = InformationModel.Make<Led>("statusIndicator");
+
+// Create a custom color: semi-transparent orange
+// Parameters: (Alpha, Red, Green, Blue)
+// Alpha = 0xff (fully opaque), Red = 0xff, Green = 0xaa, Blue = 0xbb
+var customOrange = new Color(0xff, 0xff, 0xaa, 0xbb);
+
+// Assign the custom color to the LED
+ledWidget.Color = customOrange;
+
+// Add the LED to your UI
+...
+```
+
+### Using ARGB Constructor (Hex Value)
+
+Create a custom color by providing a 32-bit ARGB value as a hex number:
+
+```csharp
+// Create a LED widget
+var ledWidget = InformationModel.Make<Led>("statusIndicator");
+
+// Create a semi-transparent blue color using a 32-bit ARGB hex value
+// Format: 0xAARRGGBB (AA=Alpha, RR=Red, GG=Green, BB=Blue)
+// 0x80 = 128 (50% transparent), 0x00=Red, 0x00=Green, 0xff=Blue
+var semiTransparentBlue = new Color(0x800000ff);
+
+// Assign the custom color to the LED
+ledWidget.Color = semiTransparentBlue;
+
+// Add the LED to your UI
+...
+```
+
+### Using System.Drawing.Color
+
+You can convert .NET's standard `System.Drawing.Color` to FT Optix `Color` using the `ToArgb()` method:
+
+```csharp
+// Create a LED widget
+var ledWidget = InformationModel.Make<Led>("statusIndicator");
+
+// Convert a System.Drawing.Color to FT Optix Color
+// Goldenrod is a pre-defined System.Drawing color
+var systemGoldenrod = System.Drawing.Color.Goldenrod;
+var goldenrodColor = new Color(systemGoldenrod.ToArgb());
+
+// Assign the color to the LED
+ledWidget.Color = goldenrodColor;
+
+// Add the LED to your UI
+...
+```
+
+## Complete Example
+
+```csharp
+[ExportMethod]
+public void SetupStatusLights()
+{
+    // Create three status indicator LEDs
+    var operationalLed = InformationModel.Make<Led>("operationalIndicator");
+    var warningLed = InformationModel.Make<Led>("warningIndicator");
+    var errorLed = InformationModel.Make<Led>("errorIndicator");
+    
+    // Use pre-defined colors for standard status states
+    operationalLed.Color = Colors.Green;
+    warningLed.Color = Colors.Yellow;
+    errorLed.Color = Colors.Red;
+    
+    // Create a custom semi-transparent overlay color
+    var overlayColor = new Color(0x80, 0xff, 0xff, 0xff); // 50% transparent white
+    
+    // Add the LEDs to your UI panel
+    Owner.Add(operationalLed);
+    Owner.Add(warningLed);
+    Owner.Add(errorLed);
+}
+```

package/vendor/optix/netlogic/pages/companion-specs.md

@@ -0,0 +1,77 @@
+# Companion Specifications
+
+## Load Companion Specifications
+
+- Companion Specifications files can be downloaded from [https://github.com/OPCFoundation/UA-Nodeset](https://github.com/OPCFoundation/UA-Nodeset)
+- Add them to FactoryTalk Optix in one of these paths (make sure to replace your username or the proper FactoryTalk Optix setup folder):
+    - `C:\Users\<username>\Documents\Rockwell Automation\FactoryTalk Optix\CompanionSpecifications`
+    - `C:\Program Files\Rockwell Automation\FactoryTalk Optix\Studio <version number>\CompanionSpecifications`
+- Restart the IDE after adding files to one of those paths to load new files
+    - Check the FactoryTalk Optix output if any error was reported after loading the files
+
+> [!NOTE]
+> Companion specifications can only be loaded at design time, so the XML files need to be added before starting the IDE.
+
+## Create an instance of a Companion Specs type
+
+Please make sure the proper XML file was added to FactoryTalk Optix before starting the script
+
+We will load an instance of the BlockType object from the DI specifications, the XML relevant part is:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+    <UANodeSet LastModified="2023-04-13T14:49:52.318Z" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://opcfoundation.org/UA/2011/03/UANodeSet.xsd" xmlns:uax="http://opcfoundation.org/UA/2008/02/Types.xsd" xmlns:si="http://www.siemens.com/OPCUA/2017/SimaticNodeSetExtensions" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:s1="http://opcfoundation.org/UA/Machinery/ProcessValues/Types.xsd" xmlns:s2="http://opcfoundation.org/UA/PADIM/Types.xsd" xmlns:ua="http://unifiedautomation.com/Configuration/NodeSet.xsd">
+    <NamespaceUris>
+        <Uri>http://opcfoundation.org/UA/DI/</Uri>
+    </NamespaceUris>
+
+...
+
+    <UAObjectType IsAbstract="true" NodeId="ns=1;i=1003" BrowseName="1:BlockType">
+        <DisplayName>BlockType</DisplayName>
+        <Description>Adds the concept of Blocks needed for block-oriented FieldDevices</Description>
+        <Documentation>https://reference.opcfoundation.org/v105/DI/v103/docs/4.11</Documentation>
+        <References>
+            <Reference ReferenceType="HasSubtype" IsForward="false">ns=1;i=1001</Reference>
+            <Reference ReferenceType="HasProperty">ns=1;i=6009</Reference>
+            <Reference ReferenceType="HasProperty">ns=1;i=6010</Reference>
+            <Reference ReferenceType="HasProperty">ns=1;i=6011</Reference>
+            <Reference ReferenceType="HasProperty">ns=1;i=6012</Reference>
+            <Reference ReferenceType="HasProperty">ns=1;i=6013</Reference>
+        </References>
+    </UAObjectType>
+    
+...
+```
+
+From the XML we can see that the numeric identifier for the BlockType is `1003`, now in FactoryTalk Optix we need to read the NameSpaceIndex. We will also need the NamespaceUri for that CompanionSpecs, in this case is `http://opcfoundation.org/UA/DI/`
+
+```csharp
+[ExportMethod]
+public void CreateCompanionSpecsInstance()
+{
+    Log.Info("Create Companion Specs NetLogic", "Searching NameSpaceIndex for companion spec");
+    // Get the NameSpaceIndex URI from the XML file
+    var nameSpaceIndex = LogicObject.Context.GetNamespaceIndex("http://opcfoundation.org/UA/DI/");
+    if (nameSpaceIndex == -1 || nameSpaceIndex == null)
+    {
+        Log.Error("Create Companion Specs NetLogic", "NameSpaceIndex not found, make sure the CompanionSpecification was properly loaded");
+        return;
+    }
+    else
+    {
+        Log.Info("Create Companion Specs NetLogic", "NameSpaceIndex found: " + nameSpaceIndex);
+    }
+    // The ID of the Type we want to add is 1003 - we can get this value from the specs XML file
+    var companionSpecsTypeNodeId = new NodeId(nameSpaceIndex, 1003);
+    // Create an instance of the element
+    Log.Info("Create Companion Specs NetLogic", "Type definition NodeId: " + companionSpecsTypeNodeId);
+    var instanceName = InformationModel.Get(companionSpecsTypeNodeId).BrowseName + "Instance";
+    var companionSpecsInstance = InformationModel.MakeObject(instanceName, companionSpecsTypeNodeId);
+    Project.Current.Get($"Model/{instanceName}")?.Delete();
+    // Optional, set a value to a children variable set as "optional" in the CompanionSpecs
+    // companionSpecsInstance.GetOrCreateVariable("RevisionCounter").Value = 100;
+    Project.Current.Get("Model").Add(companionSpecsInstance);
+    Log.Info("Create Companion Specs NetLogic", $"Companion Specs instance \"{instanceName}\" created and added to the model");
+}
+```