@aryacode/dsh-engineering 0.4.22 → 0.6.0

package/vendor/optix/netlogic/pages/execute-command.md

@@ -0,0 +1,202 @@
+# Calling or running commands
+
+## OPC/UA Methods
+
+See [here](./creating-objects.md)
+
+## Run external commands (CMD or external softwares)
+
+```csharp
+using System.Diagnostics;
+
+static void RunCommand(string command)
+{
+    int exitCode;
+    ProcessStartInfo processInfo;
+    Process process;
+    // Create the new command and launch it using the command prompt
+    processInfo = new ProcessStartInfo("cmd.exe", "/c " + command);
+    processInfo.CreateNoWindow = true;
+    processInfo.UseShellExecute = false;
+    //Redirect the output
+    processInfo.RedirectStandardError = true;
+    processInfo.RedirectStandardOutput = true;
+    // Start the process
+    process = Process.Start(processInfo);
+    process.WaitForExit();
+    // Read the streams
+    // Warning: This approach can lead to deadlocks
+    string output = process.StandardOutput.ReadToEnd();
+    string error = process.StandardError.ReadToEnd();
+    // Read the exit code
+    exitCode = process.ExitCode;
+    // Print some output
+    Log.Info("RunCommand", "output>>" + (String.IsNullOrEmpty(output) ? "(none)" : output));
+    Log.Info("RunCommand", "error>>" + (String.IsNullOrEmpty(error) ? "(none)" : error));
+    Log.Info("RunCommand", "ExitCode: " + exitCode.ToString());
+    // Close the process handler
+    process.Close();
+}
+```
+
+## Open a WebBrowser to a specific page
+
+```csharp
+[ExportMethod]
+public void OpenBrowser(string urlPath) {
+    //string destinationPath = new ResourceUri(urlPath).Uri;
+    string destinationPath = urlPath;
+    Process myProcess = new Process();
+
+    try {
+        // true is the default, but it is important not to set it to false
+        myProcess.StartInfo.UseShellExecute = true;
+        myProcess.StartInfo.FileName = destinationPath;
+        // Start the process
+        myProcess.Start();
+    } catch (Exception e) {
+        // Print any exception (if needed)
+        Log.Error("OpenInBrowser", e.Message);
+    }
+}
+```
+
+## Invoke FT Optix Core commands
+
+> [!NOTE]
+> Core commands can only be invoked at runtime.
+
+```csharp
+// Get the core commands object (exposed by FactoryTalk Optix APIs)
+var coreCommandsObject = InformationModel.GetObject(FTOptix.CoreBase.Objects.CoreCommands);
+// Call a specific command
+coreCommandsObject.ExecuteMethod("Close");
+```
+
+## Invoke FactoryTalk Optix Alarm commands
+
+> [!NOTE]
+> Alarm commands can only be invoked at runtime.
+
+```csharp
+// Get the alarms object
+var alarmCommands = InformationModel.GetObject(FTOptix.Alarm.Objects.AlarmCommands);
+// Acknowledge all alarms
+alarmCommands.ExecuteMethod("AcknowledgeAll");
+// Confirm all alarms
+alarmCommands.ExecuteMethod("ConfirmAll");
+```
+
+## Perform system shutdown (Windows only)
+
+```csharp
+/// <summary>
+/// Trigger a Windows shutdown using the system 'shutdown' command.
+/// Use with caution; this will stop the entire machine.
+/// </summary>
+[ExportMethod]
+public void SystemShutDown()
+{
+    var psi = new ProcessStartInfo("shutdown", "/s /t 0");
+    psi.CreateNoWindow = true;
+    psi.UseShellExecute = false;
+    Process.Start(psi);
+}
+```
+
+## Run a .BAT or external executable
+
+```csharp
+/// <summary>
+/// Start a BAT file or external program. Adjust filename and parameters as needed.
+/// On Windows, you can call cmd with /k or /c; /k keeps the window open.
+/// </summary>
+private void ExecuteExternalCommand()
+{
+    var Test = new Process();
+    string filename = @"C:\Path\To\Script.bat";
+    string parameters = $"/k \"{filename}\"";
+    Process.Start("cmd", parameters);
+}
+```
+
+```csharp
+// Example: launch VLC with parameters
+[ExportMethod]
+public void OpenVLC()
+{
+   Process VLC = new Process();
+   VLC.StartInfo.FileName = @"C:\Program Files (x86)\VideoLAN\VLC\vlc.exe";
+   VLC.StartInfo.Arguments = " --fullscreen --play-and-exit C:\\path\\to\\video.mp4";
+   VLC.Start();
+}
+```
+
+## Invoke a method from a different NetLogic
+
+Calling a NetLogic instance with `var myNetLogic = new MyNetLogic();` will create a new instance of the NetLogic, but it will not be the same as the one that is running in the project so it should be avoided. To call a method from a different NetLogic, you need to get the NetLogic object from the project and then call the method on that object.
+
+> [!NOTE]
+> Methods from other NetLogic instances can only be invoked at runtime.
+
+```csharp
+[ExportMethod]
+public void CallMethod1()
+{
+    // Get the NetLogic containing the method to invoke
+    var myScript = Project.Current.GetObject("NetLogic/RuntimeNetLogic1");
+    // Launch the method
+    myScript.ExecuteMethod("Method1");
+}
+```
+
+### Invoke a method from a different NetLogic with parameters
+
+#### NetLogic to be called
+
+```csharp
+public class AlarmGridLogic : BaseNetLogic
+{
+    [ExportMethod]
+    public void AckAllAlarmsWithMessage(object[] arguments)
+    {
+        var ackMessage = (LocalizedText) arguments[0];
+        var alarmsList = GetAllAlarms();
+        if (alarmsList.Count == 0)
+        {
+            Log.Warning("No alarms to acknowledge");
+            return;
+        }
+        ProcessAlarms(ackMessage, alarmsList, (alarm, message) => alarm.Acknowledge(message));
+    }
+}
+```
+
+#### Caller
+
+```csharp
+public class AckConfirmMessageLogic : BaseNetLogic
+{
+    [ExportMethod]
+    public void PerformAction()
+    {
+        // Get the target NetLogic object
+        var alarmsNetLogic = GetNetLogicObject();
+        // Get the action name to be invoked
+        string action = Owner.GetVariable("MethodName").Value;
+        // Get the comment to be added to the alarm
+        var comment = Owner.Get<TextBox>("Comment").LocalizedText;
+        // Create the object arguments to be passed to the method
+        object[] arguments = new object[] { comment };
+        alarmsNetLogic.ExecuteMethod(action, [arguments]);
+        (Owner as Dialog)?.Close();
+    }
+
+    private IUAObject GetNetLogicObject()
+    {
+        // Here the NetLogic is passed as a variable to the owner object,
+        // but it could be retrieved in a different way (like Project.Current.GetObject)
+        return InformationModel.GetObject(Owner.GetVariable("AlarmGridLogic").Value);
+    }
+}
+```

package/vendor/optix/netlogic/pages/fto-studio-cli.md

@@ -0,0 +1,99 @@
+# FactoryTalk Optix Studio CLI
+
+## Export an application to be loaded in an Optix Panel via USB
+
+This script leverages the FactoryTalk Optix Studio CLI to export an application and prepare it to be imported in an Optix Panel via USB.
+
+> [!TIP]
+> The `LoadApplicationWidget` should be used to load the application in the Optix Panel, this script only prepares the ZIP file with the correct structure and encryption.
+
+```powershell
+$projectPath = "D:\temp\NewHMIProject12\NewHMIProject12.optix"
+$optixIdePath = "C:\Program Files\Rockwell Automation\FactoryTalk Optix\Studio 1.6.2.36\FTOptixStudio.exe"
+$7zipPath = "C:\Program Files\7-Zip\7z.exe"
+$outputPath = "C:\Users\LabUser\Downloads\"
+$platform = "Yocto_arm64"
+$optixPanelPassword = "YourOptixPanelAdminPassword"
+
+# Create a temporary directory for the export process
+Write-Host "Creating temporary directory for export..."
+$tempDir = New-Item -ItemType Directory -Path "$env:TEMP\OptixExportTemp" -Force
+Write-Host "Temporary directory created at $tempDir"
+
+# Export the project using Optix IDE
+Write-Host "Exporting project using Optix IDE..."
+Start-Process -FilePath "$optixIdePath" -ArgumentList "export `"$projectPath`" --platform=`"$platform`" --location=`"$tempDir`"" -Wait
+
+# Update the .optix file with the EncryptionMode
+Write-Host "Updating .optix file with EncryptionMode..."
+$optixFilePath = Get-ChildItem -Path $tempDir -Recurse -Filter "*.optix" | Select-Object -First 1
+if ($null -eq $optixFilePath) {
+	Write-Error "No .optix file found in the exported directory."
+	Write-Host "Searching for all files in temp directory for debugging:"
+	Get-ChildItem -Path $tempDir -Recurse | ForEach-Object { Write-Host $_.FullName }
+	exit 1
+}
+Write-Host "Found .optix file at: $($optixFilePath.FullName)"
+
+# Extract the CoreVersion from the .optix YAML file and add encryption settings
+$optixFileContent = Get-Content -Path $optixFilePath.FullName
+$coreVersionLine = $optixFileContent | Where-Object { $_ -match "CoreVersion:" }
+if ($null -eq $coreVersionLine) {
+	Write-Error "CoreVersion not found in the .optix file."
+	exit 1
+}
+
+$coreVersion = $coreVersionLine -replace "CoreVersion:\s*", ""
+Write-Host "CoreVersion found: $coreVersion"
+
+# Add encryption settings after CoreVersion line
+$updatedContent = @()
+foreach ($line in $optixFileContent) {
+    $updatedContent += $line
+    if ($line -match "CoreVersion:") {
+        $updatedContent += " EncryptionVersion: 1"
+        $updatedContent += " EncryptionMode: YAMLFiles"
+        Write-Host "Added encryption settings after CoreVersion: $coreVersion"
+    }
+}
+
+# Write the updated content back to the .optix file
+$updatedContent | Set-Content -Path $optixFilePath.FullName
+
+# Write the content of the XML file
+Write-Host "Creating DeviceConfiguration.xml..."
+$xmlFilePath = Join-Path -Path $tempDir -ChildPath "DeviceConfiguration.xml"
+$xmlContent = "<?xml version=""1.0"" encoding=""utf-8""?>
+<DeviceConfiguration>
+	<Actions>
+		<ImportFTOptixApplication EncryptProject=""true""/>
+	</Actions>
+</DeviceConfiguration>"
+
+try {
+    $xmlContent | Out-File -FilePath $xmlFilePath -Encoding Ascii
+    Write-Host "DeviceConfiguration.xml created successfully at: $xmlFilePath"
+} catch {
+    Write-Error "Failed to create XML file: $($_.Exception.Message)"
+    exit 1
+}
+
+# Create a zip archive of the exported project
+Write-Host "Creating ZIP archive..."
+$outputZipPath = Join-Path -Path $outputPath -ChildPath "FTOptixApplication.z"
+
+# Compress it to ZIP file with Fast method and AES-256 encryption
+Write-Host "Compressing to ZIP with AES-256 encryption..."
+& "$7zipPath" a -tzip -mx=3 "-p$optixPanelPassword" "$outputZipPath" "$tempDir\*"
+
+# Check if the compression was successful
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "Failed to create ZIP archive."
+    exit 1
+}
+
+# Clean up the temporary directory
+Remove-Item -Path $tempDir -Recurse -Force
+
+Write-Host "Export completed. The ZIP file is located at $outputZipPath"
+```

package/vendor/optix/netlogic/pages/good-practices.md

@@ -0,0 +1,50 @@
+# Good practices
+
+Here is a list of convention our FactoryTalk Optix technicians uses when creating new projects, feel free to choose if this can apply to your project
+
+- Use significative names for every project element (no default names)
+    - Exception is made when creating object types, still remember to give meaningful name if possible
+    - Avoid using number at the end of item name
+    - Avoid abbreviations in object names to improve readability
+    - Examples:
+        - `Templates/SpinBox (Type)` -> BAD
+        - `Templates/SpinBoxWithGreenBorder (Type)` -> GOOD
+        - `MainWindow/SpinBox1` -> BAD
+        - `MainWindow/MotorSpeed_SpinBox` -> GOOD
+        - `MainWindow/MotorSP_SB` -> BAD
+- Nice to use same EmbeddedDatabase for every item to be stored
+    - Multiple tables can be used in same EmbeddedDatabase with different settings (RecordLimit, Names, etc)
+- Use `PascalCase` for object names
+- Use `camelCase` for variable names (Model, Session and Local variables)
+- All graphical elements should be in `UI` folder
+	- Here you can create standard folders to organize your work, such as:
+		- `UI/Templates`-> Contains all custom types used to create objects
+		- `UI/Screens` -> Contains the different pages that are used in the project
+	- Both subfolder can have children subfolder to organize elements if needed
+		- Example:
+			- `UI/Templates/MotorWidgets`
+			- `UI/Templates/PumpsWidgets`
+			- `UI/Screens/Filler`
+			- `UI/Screens/Settings`
+	- Nice to use Templates folder in any first level project folder (e.g. UI, Model, Converters, etc...) when creating custom types
+
+- Global variables should be created in the `Model` folder (and subfolder)
+- Nice to use HTML color palette if no special need for custom coloring
+	- Example:
+		- `red` -> GOOD
+		- `#FFA1C8` -> BAD
+- Object names and LocalizationDictionary keys should be in English
+- Nice to sort items by their type in project tree
+	- Exception is made when defining layers is necessary to build final interface (bottom most element is highest layer)
+- When creating a new page/container, avoid using a `Panel` with a `Rectangle` as coloured background to avoid doubling project nodes
+	- Use instead:
+		- `Screen` if the object is a whole screen that is going to be displayed in the HMI
+		- `Rectangle` if coloured background is needed
+		- `Panel` if background should be transparent (usually to group elements)
+- Nice to group items using Panel
+	- This is useful to reduce project complexity when assigning groups-based permissions and/or to trigger specific visual logics (enabling, visibility, etc)
+- Nice to use same `Label` name and `LocalizationDictionary` item key
+- Nice to use keyword in controls names to identify which variable/object is referring to 
+	- Example:
+		- `VoltageText` -> Label that shows the translation key for the _Voltage_ element
+		- `VoltageValue` -> Name for a LinearGauge controlling _Voltage_ value

package/vendor/optix/netlogic/pages/information-model.md

@@ -0,0 +1,89 @@
+# The Information Model
+
+## Overview
+
+In FactoryTalk Optix, each and every object is a `node`, the definition of a node comes from the OPC/UA specifications which states that an OPC/UA node is like an entity representing information. Some Nodes are Variables, DataType, References, Object, Methods... depending of what they are used for.
+
+The OPC/UA specifications can be found at the following link [opcfoundation resources](https://opcfoundation.org/developer-tools/documents/?type=Specification) and search for [OPC 10000-1 UA Part 1: Overview and Concepts](https://opcfoundation.org/developer-tools/documents/view/158) and [OPC 10000-3 UA Part 3: Address Space Model](https://opcfoundation.org/developer-tools/documents/view/160)
+
+Understanding the concept of nodes is crucial when working with FactoryTalk Optix because it forms the backbone of the OPC/UA information model, which FactoryTalk Optix leverages for data representation and interaction. Nodes represent various types of information and their relationships, enabling a standardized way to access and manipulate data within the system. This allows integration and interoperability between different components and devices, ensuring that data can be efficiently managed and utilized across the entire project.
+
+### The Information Model of OPC/UA
+
+The OPC Unified Architecture (OPC/UA) defines a rich information model that allows for complex data representation and interaction. At the core of this model is the concept of a "node". A node is an entity that represents information and can be of various types, each serving a different purpose within the information model. The major properties of a node include:
+
+- **NodeId**: A unique identifier for the node within the address space.
+- **BrowseName**: A human-readable name used for browsing the node.
+- **DisplayName**: A localized name intended for display purposes.
+- **Description**: A localized text description of the node.
+
+Nodes can be of different types, including:
+
+- **Object**: Represents physical or abstract entities.
+- **Variable**: Holds a value and can have a data type.
+- **Method**: Represents callable functions or procedures.
+- **ObjectType**: Defines the type of an object.
+- **VariableType**: Defines the type of a variable.
+- **ReferenceType**: Defines the type of a reference between nodes.
+- **DataType**: Defines the data type of a variable.
+- **View**: Represents a subset of the address space for browsing.
+
+These nodes and their properties form the foundation of the OPC/UA information model, enabling a standardized way to represent and interact with data across different systems and devices.
+
+### The Information Model of FactoryTalk Optix
+
+As everything in FactoryTalk Optix is actually an OPC/UA node, we can implement some complex scenarios like:
+
+- Allowing other applications (both FactoryTalk Optix or third-parties) to read and write project nodes
+    - This includes exposing project elements like Databases, PLC Tags, Model variables, UI objects, etc
+- Allowing other applications to produce and consume alarms and events using the OPC/UA A&E protocol
+- Manipulating parts of the project using NetLogic or an external OPC/UA client
+
+## Project context
+
+Accessing the path of the node will return the project-level node, this is good for global elements (Model Variables, PLC Tags, etc) but it cannot be used to access session-based elements, as each user session will have a unique instance of windows and pages with uniques NodeIds
+
+### Overview
+
+![Project vs session](../images/session-concept.png)
+
+FactoryTalk Optix graphical interface is based on the object's oriented paradigm, this means that when defining UI elements at design-time, these are actually created as object types. When the runtime starts, and a session is created (NativePresentationEngine creates automatically one UI instance, each client of the WebPresentationEngine creates one UI instance), this session is derived from the UI type that was designed, thus becoming an instance.
+
+Each session lives as an independent object, each session can interact with global objects (such as Model variables or PLC tags) but cannot access other sessions, when calling methods that targets a session object (such as the refresh of a DataGrid), it can only affect the session where the method was called, other instances and sessions are unaffected.
+
+NetLogic are also affected by this functionality:
+- When using the `Project.Current.Get` syntax, only the project definition can be accessed, if a UI element is manipulated using such syntax, the session instance must be destroyed and recreated in order to inherit the new changes (for example navigating to a different page and then coming back)
+- When placing the NetLogic inside a page (which can be something like a Screen, a Panel, a Rectangle, or any UI object) and using the `Owner.Get` syntax, the specific instance where the NetLogic is created gets accessed and the UI is immediately refreshed. Only the instance where the NetLogic exists can be accessed, a session-based NetLogic cannot interact with other sessions, only with elements in the current session or global objects (such as PLC tags or Model variables).
+
+### Summary
+
+- Each session of a PresentationEngine creates an instance of the UI types
+- Each session is completely independent from other session
+- A session can only interact with:
+    - Elements in the same session
+    - Global objects (Model variables, PLC tags, alarms, etc)
+- A session cannot interact with other sessions
+- Session changes are discarded when the instance is destroyed (page is changed or reloaded)
+    - Retentivity cannot be applied to session objects
+    - Retentivity should never be applied to any UI object
+- A session can access global objects, but global objects cannot access session objects, for example:
+    - A global NetLogic cannot refresh the DataGrid of a session, a global NetLogic can only access nodes at the project level (such as alarms, PLC tags, Model variables, etc)
+    - A session NetLogic can access all global objects, all elements of the current UI session but cannot access other sessions.
+
+### Examples
+
+#### Refreshing a DataGrid
+
+As the DataGrid is a session object, the NetLogic to refresh a DataGrid must be placed at a session level
+
+#### Creating a new alarm
+
+As the Alarm is a global object, the NetLogic can be either at the session level or at a global level
+
+#### Performing an SQL query
+
+Here it depends on the final goal:
+
+- If just inserting data to a database, the NetLogic can be either at the session level or at a global level, the data can be passed as global variable or as argument of the called method
+- If performing a query (such as a SELECT) depending on some parameters from the user, the NetLogic must be placed at the session level (where TextBox or other controls can be accessed)
+- If performing a query (such as a SELECT or an INSERT) depending on some values from the controller (PLC), the NetLogic can be placed either at a global or session level

package/vendor/optix/netlogic/pages/log-output.md

@@ -0,0 +1,22 @@
+# Log messages
+
+Log messages can be displayed both at RunTime and DesignTime, at DesignTime logs will appear in `Optix Studio Output` while at RunTime they will appear in the `Emulator output` or the RunTime log
+
+## General syntax
+
+`Log . [level] ( [optional category] , [ message content] );`
+
+## Examples
+
+Different log levels can be triggered and then filtered in `Optix Studio Output` and `Emulator output`. Specifying an optional custom `Category` helps you understanding where this line was generated (for example the NetLogic name and/or the method name)
+
+- `Log.Error(category, message);`
+- `Log.Warning(category, message);`
+- `Log.Info(category, message);`
+- `Log.Debug(category, message);`
+- `Log.Verbose1(category, message);`
+- `Log.Verbose2(category, message);`
+
+## Get the node path for any project node
+
+- `Log.Node(IUANode);` -> Returns a string containing the node path for a specific element

package/vendor/optix/netlogic/pages/managing-aliases.md

@@ -0,0 +1,22 @@
+# Managing Aliases
+
+## Delete the value from an Alias
+
+```csharp
+Project.Current.Get("UI/Pages/MainPage").SetAlias("MainBoilerAlias", NodeId.Empty);
+```
+
+## Delete the Kind property of an Alias
+
+```csharp
+Project.Current.Get<Alias>("UI/Pages/MainPage/MainBoilerAlias").Kind = NodeId.Empty;
+```
+
+## Connect an Alias to a node
+
+```csharp
+// Get the target variable
+var targetVariable = Project.Current.Get<Tag>("CommDriver/RAEthernetIP/Station1/InletPump");
+// Set the alias to the target value
+Project.Current.Get("UI/Pages/MainPage").SetAlias("MainBoilerAlias", targetVariable.NodeId);
+```

package/vendor/optix/netlogic/pages/manipulate-nodes.md

@@ -0,0 +1,72 @@
+# Manipulate Optix nodes
+
+> [!WARNING]
+> This page describes low-level features and should be used with caution as they can potentially lead to unexpected results or even break your project. 
+> These features are not officially supported and may be subject to changes in future releases.
+
+> [!NOTE]
+> Nodes behavior can only be manipulated at runtime.
+
+## Stopping an Optix node
+
+Once nodes are stopped, they stop interacting with the system for example an ODBC database node will stop processing queries, a Trend node will stop logging data, an Alarm node will stop monitoring conditions, etc.
+
+This can be useful in some scenarios to disable some components (like the `Signing Workflow` node) or to temporarily stop some processes (like a `Trend` node) without deleting them.
+
+```csharp
+/// <summary>
+/// Stops an Optix node if it is started
+/// </summary>
+/// <param name="node">The node to be stopped</param>
+private void StopNode(IUANode node)
+{
+    // Only objects can be started/stopped
+    if (node is IUAObject nodeObject && node.Status == NodeStatus.Started)
+    {
+        // Stop the node
+        nodeObject.Stop();
+    }
+        
+}
+```
+
+## Starting an Optix node
+
+```csharp
+/// <summary>
+/// Starts an Optix node if it is stopped
+/// </summary>
+/// <param name="node">The node to be started</param>
+private void StartNode(IUANode node)
+{
+    // Only objects can be started/stopped
+    if (node is IUAObject nodeObject && node.Status != NodeStatus.Started)
+    {
+        // Start the node
+        nodeObject.Start();
+    }
+        
+}
+```
+
+## Restarting an Optix node
+
+This is simply a combination of the previous two methods
+
+```csharp
+/// <summary>
+/// Restarts an Optix node if it is started
+/// </summary>
+/// <param name="node">The node to be restarted</param>
+private void RestartNode(IUANode node)
+{
+    // Only objects can be started/stopped
+    if (node is IUAObject nodeObject && node.Status == NodeStatus.Started)
+    {
+        // Restart the node
+        nodeObject.Stop();
+        nodeObject.Start();
+    }
+        
+}
+```