@aryacode/dsh-engineering 0.4.22 → 0.6.0

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

@@ -0,0 +1,240 @@
+# MQTT
+
+The MQTT (Message Queuing Telemetry Transport) protocol is a lightweight messaging protocol designed for constrained devices and low-bandwidth, high-latency, or unreliable networks. It is widely used in IoT (Internet of Things) applications for its efficiency and simplicity.
+
+Starting from FactoryTalk Optix 1.6.X, the MQTT module provides built-in support for MQTT, allowing you to easily integrate MQTT messaging into your applications.
+
+> [!NOTE]
+> The MQTT module is only loaded at the Runtime startup, so MQTT features are not available at design time.
+
+## General Concepts about MQTT in FactoryTalk Optix
+
+FactoryTalk Optix provides a robust MQTT module that allows you to:
+- Publish and subscribe to topics using the `MQTTClient` and `MQTTPublisher` classes.
+- Manage incoming and outgoing messages efficiently.
+- Dynamically configure MQTT clients and publishers.
+
+## Using MQTT in FactoryTalk Optix
+
+### Managing MQTT Client IDs
+
+The `MQTTClient` class allows you to dynamically set the `ClientId` for an MQTT client. This is useful for ensuring unique identifiers for clients in a network.
+
+```csharp
+public override void Start()
+{
+    // Retrieve the MQTT client instance from the project
+    var mqttClient = Project.Current.Get<MQTTClient>("MQTT/MQTTClient");
+    
+    // Check if the default ClientId is set and update it to a unique value
+    if (mqttClient.ClientId == "FTOptix-1")
+    {
+        mqttClient.ClientId = $"OptixUser-{Guid.NewGuid().ToString().Split("-")[0]}";
+        
+        // Restart the client to apply the new ClientId
+        mqttClient.Stop();
+        mqttClient.Start();
+        
+        // Log the updated ClientId
+        Log.Info("ClientIdGeneratorLogic", $"ClientId was set to {mqttClient.ClientId}");
+    }
+}
+```
+
+### Handling Incoming MQTT Messages
+
+As the `MQTTSubscriber`, when set to `PlainTextSubscription` allows to read messages from a topic and write the received data to a Model variable, you can use the `VariableChange` event to process incoming MQTT messages. This ensures that your application can react to new messages in real-time.
+
+```csharp
+public override void Start()
+{
+    // Get the variable that stores incoming MQTT messages
+    mqttIncomingMessage = Project.Current.GetVariable("Model/Data/MQTT/IncomingMessage");
+    
+    // Attach an event handler to process changes in the variable
+    mqttIncomingMessage.VariableChange += MqttIncomingMessagePile_VariableChanged;
+}
+
+private void MqttIncomingMessagePile_VariableChanged(object sender, VariableChangeEventArgs e)
+{
+    // Ensure the new value is not null
+    if (e.NewValue == null)
+        return;
+
+    // Retrieve the incoming message as a string
+    var incomingMessage = (string)e.NewValue;
+    
+    // Log the received message for debugging purposes
+    Log.Debug("MqttChatLogic", $"Received MQTT message: {incomingMessage}");
+}
+```
+
+### Displaying MQTT Messages in the UI
+
+The `ScrollView` and `ColumnLayout` classes can be used to dynamically display incoming MQTT messages in the user interface. These classes are part of the FactoryTalk Optix UI framework and allow developers to create flexible and dynamic layouts for displaying data.
+
+- **`ScrollView`**: This is a container that provides scrolling functionality for its child elements. It ensures that the user can view all messages even if the content exceeds the visible area.
+- **`ColumnLayout`**: This layout organizes its child elements vertically, making it ideal for displaying a list of messages.
+- **`MqttChatMessage`**: This is a custom UI element that represents a single MQTT message. It includes variables such as `Content` to store the message text.
+
+The following code demonstrates how to use these classes:
+
+```csharp
+private void MqttIncomingMessagePile_VariableChanged(object sender, VariableChangeEventArgs e)
+{
+    // Create a new column layout to organize messages vertically
+    var newColumnLayout = InformationModel.Make<ColumnLayout>("VerticalLayout");
+    
+    // Retrieve the pile of messages from the variable
+    var messagesPile = (string[])mqttIncomingMessagePile.Value.Value;
+    
+    foreach (var message in messagesPile)
+    {
+        // Skip empty messages
+        if (string.IsNullOrEmpty(message))
+            continue;
+        
+        // Create a new UI element for the message
+        var textBlock = InformationModel.Make<MqttChatMessage>(Guid.NewGuid().ToString());
+        
+        // Deserialize the message content
+        var mqttMessage = MqttChatLogic.SampleChatMessage.Deserialize(message);
+        
+        // Set the content of the text block
+        textBlock.GetVariable("Content").Value = mqttMessage.Content;
+        
+        // Add the text block to the column layout
+        newColumnLayout.Add(textBlock);
+    }
+    
+    // Clear the existing layout and add the new one
+    scrollView.Get("VerticalLayout")?.Delete();
+    scrollView.Add(newColumnLayout);
+}
+```
+
+#### Serialization and Deserialization
+
+The `SampleChatMessage` class is used to represent an MQTT message. It includes properties such as `Sender`, `Content`, and `Timestamp`. This class uses JSON serialization to convert the message into a string format for transmission and deserialization to reconstruct the object from the string.
+
+- **Serialization**: Converts the object into a JSON string using `JsonSerializer.Serialize`.
+- **Deserialization**: Converts the JSON string back into an object using `JsonSerializer.Deserialize`.
+
+> [!NOTE]
+> The MQTT publisher works with any kind of string message as payload, but using serialization allows to structure the data and include multiple fields in a single message and it is widely used in IoT applications. Creating a custom class and using the serialization/deserialization methods makes it easier to manage the message content.
+
+```csharp
+public class SampleChatMessage
+{
+    public string Sender { get; }
+    public string Content { get; }
+    public string Timestamp { get; }
+
+    [JsonConstructor]
+    public SampleChatMessage(string sender, string content, string timestamp)
+    {
+        this.Sender = sender;
+        this.Content = content;
+        this.Timestamp = timestamp ?? new DateTime(0).ToString("yyyy/MM/dd HH:mm:ss");
+    }
+
+    public string Serialize()
+    {
+        return JsonSerializer.Serialize(this);
+    }
+
+    public static SampleChatMessage Deserialize(string json)
+    {
+        try
+        {
+            return JsonSerializer.Deserialize<SampleChatMessage>(json);
+        }
+        catch (JsonException ex)
+        {
+            Log.Warning("MqttChatLogic", $"Failed to deserialize MQTT message: {ex.Message}, content: {json}");
+            return null;
+        }
+    }
+}
+```
+
+### Sending MQTT Messages
+
+You can publish messages to an MQTT topic using the `MQTTPublisher` class. This allows you to send data to other clients or systems. The `MQTTPublisher` is configured with a topic, quality of service (QoS), and retain flag, which determine how the message is delivered.
+
+The following code demonstrates how to send a message:
+
+```csharp
+[ExportMethod]
+public void SendMessage(string content)
+{
+    // Retrieve the MQTT publisher and client instances
+    var mqttPublisher = Project.Current.Get<MQTTPublisher>("MQTT/Mosquitto_MQTTClient/MQTTPublisher");
+    var mqttClient = Project.Current.Get<MQTTClient>("MQTT/Mosquitto_MQTTClient");
+    
+    // Create a new MQTT message with the provided content
+    var dateTime = DateTime.UtcNow.ToString("yyyy/MM/dd HH:mm:ss");
+    var mqttMessage = new SampleChatMessage("ClientId", content, dateTime);
+    
+    // Serialize the MQTT configuration and message payload
+    var mqttConfigJson = new OptixMqttConfig(mqttPublisher).Serialize();
+    var mqttMessageJson = mqttMessage.Serialize();
+    
+    // Publish the message to the configured topic
+    mqttClient.Publish(mqttConfigJson, mqttMessageJson);
+}
+```
+
+#### Why Serialization is Needed
+
+Serialization is essential for converting the `SampleChatMessage` object into a format that can be transmitted over the MQTT protocol. The JSON format is lightweight and widely supported, making it ideal for IoT applications. By serializing the message, you ensure that all its properties are preserved during transmission.
+
+#### Understanding `OptixMqttConfig`
+
+The `OptixMqttConfig` class is a helper class designed to encapsulate the configuration details of an MQTT publisher. It simplifies the process of serializing and transmitting the configuration data required for publishing messages.
+
+```csharp
+public class OptixMqttConfig
+{
+    public string Topic { get; }
+    public int QoS { get; }
+    public bool Retain { get; }
+
+    public OptixMqttConfig(MQTTPublisher mqttPublisher)
+    {
+        Topic = mqttPublisher.Topic;
+        QoS = (int) mqttPublisher.QoS;
+        Retain = mqttPublisher.Retain;
+    }
+
+    public string Serialize()
+    {
+        return JsonSerializer.Serialize(this);
+    }
+}
+```
+
+##### Key Properties
+
+- **`Topic`**: The MQTT topic to which the message will be published. This is a string that acts as the address for the message.
+- **`QoS`**: The Quality of Service level for the message. It determines the guarantee of message delivery
+- **`Retain`**: A boolean flag indicating whether the message should be retained by the broker. Retained messages are delivered to new subscribers immediately upon subscription.
+
+##### Example Usage
+
+The `OptixMqttConfig` class is used in the `SendMessage` method to serialize the MQTT publisher's configuration:
+
+```csharp
+var mqttPublisher = Project.Current.Get<MQTTPublisher>("MQTT/Mosquitto_MQTTClient/MQTTPublisher");
+var mqttConfig = new MqttChatLogic.OptixMqttConfig(mqttPublisher);
+var mqttConfigJson = mqttConfig.Serialize();
+```
+
+This serialized configuration is then passed as the first argument to the `Publish` method of the `MQTTClient` class.
+
+## Best Practices for MQTT in FactoryTalk Optix
+
+- **Dispose Resources:** Always dispose of MQTT clients and tasks when they are no longer needed to free up resources.
+- **Handle Errors Gracefully:** Use try-catch blocks to handle exceptions during MQTT operations.
+- **Use Unique Client IDs:** Ensure that each MQTT client has a unique `ClientId` to avoid conflicts.
+- **Optimize Message Handling:** Use efficient data structures and algorithms to process incoming messages.

package/vendor/optix/netlogic/pages/netlogic-lifecycle.md

@@ -0,0 +1,270 @@
+# NetLogic Lifecycle
+
+Understanding how FactoryTalk Optix manages threads is essential to writing reliable NetLogic code, especially in projects with complex pages, many widgets, or heavy processing requirements.
+
+## Overview
+
+FactoryTalk Optix runtime operates with two primary execution contexts that are always present:
+
+| Thread | Responsible for |
+|--------|----------------|
+| **UI thread** | Rendering all graphical objects, handling user input events |
+| **Behavior/Core thread** | Calling `Start()` and `Stop()` on all behaviors (including NetLogic), sequentially |
+
+These two threads are **independent** from each other. The UI can render while behaviors are being initialized, and vice versa.
+
+## Start() lifecycle
+
+### When is Start() called?
+
+`Start()` is invoked by the FactoryTalk Optix runtime when a node (page, object, widget) is activated - either at application startup or when a page is navigated to.
+
+The fundamental rule is: **all `Start()` methods are called sequentially, one at a time, on the behavior thread**. There is no parallelism between different NetLogic `Start()` calls.
+
+> [!WARNING]
+> The `Start()` method of a Runtime NetLogic should not add or remove nodes from the page tree, as this can cause unpredictable behavior in the loading sequence. If dynamic modification of the tree is needed, it should be done on the page type definition, and then load the page on the session.
+
+### Execution order
+
+The runtime determines the execution order based on the priority of the objects type (DynamicLinks, EURange, NetLogic, etc.) in the page tree. The general principle is: **deeper nodes start before their parents**. This allows child components to initialize before their containers, which is usually desirable.
+
+The practical outcome for a page where multiple NetLogic exist, is: the most deeply nested NetLogic starts first, and execution proceeds upward through the tree until the page-level NetLogic is last. This is the common case.
+
+If multiple NetLogics have the same depth, their order is determined by the tree traversal (i.e., top to bottom as they appear in the project tree), but this cannot be relied upon for deterministic behavior.
+
+```
+Example tree (all same priority):
+
+Page  (depth 1)
+├── PanelA  (depth 2)
+│   └── NetLogic_A  (depth 3)   <- starts FIRST
+├── PanelB  (depth 2)
+│   ├── NetLogic_B  (depth 3)   <- starts SECOND
+│   └── NetLogic_PanelB         <- starts THIRD (same depth as PanelB, ordered by tree traversal)
+└── NetLogic_Page  (depth 1)    <- starts LAST
+```
+
+### 2-second threshold warning
+
+If a `Start()` method takes longer than **2000 ms** to return, the runtime logs a warning:
+
+```text
+Start method on <NodeName> took too long to execute, Long tasks should alternatively be implemented inside a LongRunningTask.
+```
+
+This is not an error - the runtime will wait for `Start()` to finish before moving on to the next behavior. However, until all behaviors have started, any other behavior whose `Start()` is queued will be blocked.
+
+> [!WARNING]
+> A slow `Start()` on one NetLogic delays the `Start()` of every other NetLogic that comes after it in the queue. On pages with many components, this can cause a visible freeze during page load.
+
+```csharp
+// BAD: blocking operation in Start() delays everything after it
+public override void Start()
+{
+    // This blocks the behavior thread for potentially seconds
+    var data = File.ReadAllText("/mnt/slow-nfs/data.csv");
+    ProcessData(data);
+}
+
+// GOOD: offload to LongRunningTask
+public override void Start()
+{
+    loadTask = new LongRunningTask(LoadData, LogicObject);
+    loadTask.Start();
+}
+
+private void LoadData()
+{
+    var data = File.ReadAllText("/mnt/slow-nfs/data.csv");
+    ProcessData(data);
+}
+
+private LongRunningTask loadTask;
+```
+
+## Stop() lifecycle
+
+`Stop()` is called in the **exact reverse order** of `Start()`. This is guaranteed by the runtime regardless of how many NetLogics are present on the page.
+
+- `Stop()` is also called sequentially on the behavior thread
+- Exceptions thrown in `Stop()` are caught and logged; they do not interrupt the stop sequence of other behaviors
+- After `Stop()`, the NetLogic instance is disposed
+
+```csharp
+public override void Stop()
+{
+    // Always dispose tasks and observers here
+    myPeriodicTask?.Dispose();
+    myLongRunningTask?.Dispose();
+    myVariableObserver?.Dispose();
+}
+```
+
+### Stop() ordering during page navigation
+
+When navigating from **SCREEN1** to **SCREEN2**, the runtime prioritizes loading the new page to minimize time-to-first-content for the user. As a consequence, **`Stop()` on SCREEN1's NetLogics may execute *after* `Start()` has already been called on SCREEN2's NetLogics**.
+
+This is by design: the destruction and cleanup of nodes belonging to the previous page is intentionally deferred in favor of the new page becoming interactive as quickly as possible.
+
+> [!WARNING]
+> Do not assume that all `Stop()` calls from the previous page have completed before `Start()` begins on the new page. If SCREEN1 and SCREEN2 share any global/static state, session variables, or external resources, this overlap can cause unexpected behavior.
+
+```
+Page transition timeline:
+
+User behavior:      [Navigate to SCREEN2]
+                    ↑ user clicks on the NavigationPanel tab
+
+Behavior thread:        [Start NL_A (SCREEN2)][Start NL_B (SCREEN2)]
+                        ↑ new page load starts first
+
+                            [Stop NL_A (SCREEN1)][Stop NL_B (SCREEN1)]
+                            ↑ old page cleanup follows asynchronously
+```
+
+Practical guidelines:
+- **Do not rely on SCREEN1's `Stop()` having run** before SCREEN2's `Start()` initializes shared resources.
+- **Release exclusive resources** (serial ports, file handles, database connections) as early as possible within `Stop()`, and acquire them as late as possible in `Start()`, to minimize the overlap window.
+- If a clean handoff is required, use a shared session variable or a global synchronization flag to signal that SCREEN1 has fully torn down before SCREEN2 proceeds with the conflicting initialization.
+
+## ExportMethod execution
+
+Methods decorated with `[ExportMethod]` are called synchronously on **whichever thread triggered them**:
+
+| Trigger | Thread used |
+|---------|-------------|
+| Button click / UI interaction | UI thread |
+| Called from another NetLogic's `Start()` | Behavior thread |
+| Called from a `LongRunningTask` | That task's dedicated thread |
+| Called from a `PeriodicTask` | That task's dedicated thread |
+
+```csharp
+// BAD: performs blocking operation on the UI thread
+// While the UI remains responsive, other methods executed from the same UI session 
+// (including page switches) will wait for this method to complete
+[ExportMethod]
+public void GenerateReport()
+{
+    Thread.Sleep(5000); // blocks the UI thread, other operations from this session must wait
+    WriteReportFile();
+}
+
+// GOOD: return immediately, do the work in background
+[ExportMethod]
+public void GenerateReport()
+{
+    reportTask?.Dispose();
+    reportTask = new LongRunningTask(WriteReportFile, LogicObject);
+    reportTask.Start();
+}
+
+private LongRunningTask reportTask;
+```
+
+### ExportMethod and thread safety
+
+When an `[ExportMethod]` runs on a thread different from the one that owns a shared variable, concurrent access can occur. The safest pattern is to keep all model-node reads/writes inside the method call itself (the FactoryTalk Optix information model is thread-safe at the node level)
+
+```csharp
+// Sharing a plain C# object between a PeriodicTask and an ExportMethod: use a lock
+private readonly object _lock = new object();
+private List<double> _buffer = new();
+
+private void SampleData()
+{
+    lock (_lock)
+    {
+        _buffer.Add(GetSensorValue());
+    }
+}
+
+[ExportMethod]
+public void FlushBuffer()
+{
+    List<double> snapshot;
+    lock (_lock)
+    {
+        snapshot = new List<double>(_buffer);
+        _buffer.Clear();
+    }
+    // Work on snapshot safely
+}
+```
+
+## Pages with many widgets or NetLogics
+
+### What happens at page load
+
+When a page is navigated to, the runtime:
+
+1. Instantiates and renders all graphical widgets on the **UI thread** (independent, non-blocking for the behavior thread)
+2. Traverses the page subtree on the **behavior thread** and calls all `Start()` methods in priority order - **sequentially**
+
+These two activities happen **concurrently** but on separate threads. The UI may already be partially visible while NetLogics are still starting up.
+
+### Practical implications for complex pages
+
+- **Many NetLogics + fast `Start()` methods**: no meaningful issue. Each `Start()` completes in milliseconds and the total startup time is the sum of all of them.
+- **One slow `Start()`**: blocks the startup of every NetLogic that follows it in the queue. Use `LongRunningTask` to move the slow work off the behavior thread.
+- **Many heavy widgets**: the UI thread handles all rendering; a heavy widget (e.g., a large DataGrid populating from a database) may cause the UI to feel sluggish, but it does not block `Start()` on other NetLogics.
+  - Having multiple heavy widget might cause the Start() of the NetLogic to be delayed until the node is created, so multiple heavy widgets can cause a longer delay before the some NetLogic starts.
+
+```
+Page load timeline (simplified):
+
+UI thread:     [render widget 1][render widget 2]...[render widget N]
+Behavior thread:  [Start NL_A][Start NL_B]...[Start NL_N]
+                   ↑ these are sequential, not parallel
+```
+
+### Avoid cascading Start() delays
+
+If you have, for example, 10 NetLogics each doing a 300 ms blocking operation in `Start()`, total startup time is **3 seconds** during which any NetLogic not yet started is completely inert. This can cause:
+- Variables remaining at their default value longer than expected
+- Observers not yet registered, missing initial state changes
+- Timers not yet running
+
+Offload anything non-trivial to `LongRunningTask`:
+
+```csharp
+public override void Start()
+{
+    // Register observers immediately (fast)
+    myVar = LogicObject.GetVariable("MyVar");
+    observer = new RemoteVariableSynchronizer();
+    observer.Add(myVar);
+    observer.VariableChange += OnVarChanged;
+
+    // Defer heavy initialization
+    initTask = new LongRunningTask(HeavyInit, LogicObject);
+    initTask.Start();
+}
+
+private void HeavyInit()
+{
+    // Connect to database, read config file, etc.
+}
+```
+
+## Async tasks and their threads
+
+For a detailed reference, see [async-tasks.md](./async-tasks.md). Quick summary:
+
+| Task type | Creates a new thread? | Can access info model? | When to use |
+|-----------|----------------------|----------------------|-------------|
+| `LongRunningTask` | Yes, dedicated | Yes (thread-safe) | Long/blocking operations |
+| `PeriodicTask` | Yes, dedicated | Yes (thread-safe) | Recurring work (polling, watchdog) |
+| `DelayedTask` | Yes, dedicated | Yes (thread-safe) | One-shot deferred action |
+| `async/await` (C# native) | Uses ThreadPool | **No** - avoid accessing nodes | Pure computation, I/O without node access |
+
+> [!NOTE]
+> All FactoryTalk Optix task types (`LongRunningTask`, `PeriodicTask`, `DelayedTask`) are [information-model](./information-model.md)-safe. Native C# `async/await` or `Task.Run()` should only be used for operations that do not touch any project node.
+
+## DesignTime NetLogic and ExportMethod
+
+DesignTime NetLogics follow a different loading strategy:
+- The .NET assembly is **reloaded from disk on every `[ExportMethod]` call** (to pick up freshly compiled changes)
+- `Start()` is **never called** for DesignTime NetLogics (and, it is not even created by the IDE when adding a new DesignTime NetLogic, the instance is only created when an `[ExportMethod]` is invoked)
+- `[ExportMethod]` runs synchronously on the thread that triggered it (typically the Studio UI thread) - this means blocking operations inside a DesignTime `[ExportMethod]` will freeze Optix Studio until it returns.
+  - A DesignTime NetLogic can have multiple `[ExportMethod]`s, but they are all executed only on when the user invokes them by the context menu
+  - Asynchronous operations are allowed using `LongRunningTask`, but they will still execute on the same project, so it is advisable not to change the project tree or access project nodes from them to avoid concurrency issues with the IDE thread

package/vendor/optix/netlogic/pages/netlogic-overview.md

@@ -0,0 +1,155 @@
+# NetLogic overview
+
+- NetLogic are C# scripts that help you implementing custom and/or advanced logic in FactoryTalk Optix with custom code.
+- There are no limits on the amount of C# snippet you can add to a project
+- There are some limitations on the packages you can add to a NetLogic
+    - Example:
+        - `WPF` (WindowsForms) -> These are not supported as they are not cross platform in the way FactoryTalk Optix works
+        - `ActiveX` -> These are not supported as they are old and unsecure
+        - `MSSQL` (Microsoft SQL) -> This is not supported as FactoryTalk Optix APIs offers a common syntax to access both EmbeddedDatabase and ODBC with same syntax by translating the output query for you. This is needed to make SQL independents from the type of database you are accessing
+            - This limitation was removed starting from FactoryTalk Optix 1.6.0.44, assuming at least one ODBC Connector is added to the project (even if unused)
+- NetLogic can be RunTime or DesignTime
+    - `RunTime NetLogic` -> This is the most common type of NetLogic, you can use it to trigger custom logic when the RunTime is running
+    - `DesignTime NetLogic` -> These king of NetLogic are typically used to make the designer's life easier by automating some repetitive operations (such as creating hundreds of alarms, variables, assigning DynamicLink and more)   
+- Distinction between the two kind of NetLogic only exists in the YAML definition, the same APIs can be used both at DesignTime and/or at RunTime
+    - DesignTime NetLogic can only access elements that exists at DesignTime, you cannot access a `CommDriver` or a `Database` if the application is not running
+
+## Methods visible to FactoryTalk Optix
+
+Not all methods in a NetLogic class are exposed to the runtime in the same way. FactoryTalk Optix distinguishes three categories:
+
+### Start() and Stop()
+
+These are the two lifecycle methods inherited from `BaseNetLogic`. They are always called by the runtime automatically - you never invoke them yourself.
+
+- `Start()` is called when the node (page, object) is activated
+- `Stop()` is called when the node is deactivated, in reverse order relative to `Start()`
+- Both must return quickly; slow implementations block the startup of subsequent NetLogics (see [thread-model.md](thread-model.md))
+
+> [!NOTE]
+> `Start()` and `Stop()` are not decorated with `[ExportMethod]` because they are not meant to be called manually. They are automatically invoked by the runtime based on the lifecycle of the NetLogic's parent node.
+
+> [!NOTE]
+> Only Runtime NetLogic can have `Start()` and `Stop()` methods, DesignTime NetLogic are meant to be triggered manually via `[ExportMethod]`, if `Start()`/`Stop()` methods are defined in a DesignTime NetLogic, they will not be called automatically.
+
+```csharp
+public override void Start()
+{
+    // Setup: register observers, create tasks, read initial values
+}
+
+public override void Stop()
+{
+    // Teardown: dispose tasks, unregister observers
+}
+```
+
+### `[ExportMethod]` - callable from the UI or other NetLogics
+
+Methods decorated with `[ExportMethod]` are **registered as OPC UA Methods** on the NetLogic node. This makes them:
+- Callable from buttons, event handlers, and other UI controls in Studio (they appear in the method picker)
+- Callable from other NetLogics via `ExecuteMethod`
+- Callable by external OPC UA clients
+
+Rules for `[ExportMethod]`:
+- Must be `public`
+- Can have input parameters (mapped to OPC UA input arguments)
+- Can have `out` parameters to return a value (which gets mapped to OPC UA output arguments)
+  - All methods must be `void` return type, use `out` parameters to return values instead
+- The method name must be unique within the NetLogic class
+
+```csharp
+// Simple ExportMethod with no parameters
+[ExportMethod]
+public void ResetCounter()
+{
+    LogicObject.GetVariable("Counter").Value = 0;
+}
+
+// ExportMethod with input and output
+[ExportMethod]
+public void Multiply(double a, double b, out double result)
+{
+    result = a * b;
+}
+```
+
+> [!WARNING]
+> If called from a UI button, an `[ExportMethod]` runs on the **UI thread**. Blocking operations will freeze the UI. See [thread-model.md](./thread-model.md) for the correct pattern.
+
+### Public methods - internal use only
+
+`public` methods that are **not** decorated with `[ExportMethod]` are plain C# class members. They are:
+- **Not visible** to Studio, event handlers, or OPC UA clients
+- Callable only from C# code within the same NetLogic or from other NetLogics via direct object reference
+
+Use them to factor out reusable logic within the class without exposing it to the outside world.
+
+```csharp
+// Visible to Studio and OPC UA clients
+[ExportMethod]
+public void TriggerAlarm(string message)
+{
+    SetAlarmState(true, message); // calls the private helper below
+}
+
+// NOT visible to Studio - internal helper only
+public void SetAlarmState(bool active, string message)
+{
+    LogicObject.GetVariable("AlarmActive").Value = active;
+    LogicObject.GetVariable("AlarmMessage").Value = message;
+}
+```
+
+### Private and internal methods
+
+`private` (and `internal`) methods are standard C# - not accessible from outside the class at all. Use them freely for implementation details.
+
+### Summary table
+
+| Method type | Visible in Studio? | Called by runtime? | Callable from other NetLogics? |
+|-------------|-------------------|-------------------|-------------------------------|
+| `Start()` / `Stop()` | No (automatic) | Yes, automatically | No (use ExportMethod instead) |
+| `[ExportMethod]` public | **Yes** | No (on-demand) | Yes, via `ExecuteMethod` |
+| `public` (no attribute) | No | No | Yes, via object reference |
+| `private` / `internal` | No | No | No |
+
+---
+
+## Things to remember
+
+- NetLogic class name is the same of the NetLogic object name
+    - Don't change the NetLogic name from any external editor, rename it from Studio instead!
+- NetLogic objects can be browsed from the NetSolution
+    - Don't delete a NetLogic from the solution, remove it from Studio instead!
+    - Don't move a NetLogic from any external editor, move it from Studio (better to copy paste the NetLogic in the new position and then delete it from the unused place)
+
+## DesignTime helper: create a Runtime NetLogic (Blinker example)
+
+```csharp
+/// <summary>
+/// DesignTime helper that scaffolds a runtime NetLogic source file and supporting model nodes (Blinkers example).
+/// Inputs: none. This is executed at DesignTime (Exported method).
+/// Output: new folder/variables under Model, a NetLogic object under NetLogic and a .cs file written into NetSolution.
+/// Caution: This writes files into the project - use only in design phase.
+/// </summary>
+[ExportMethod]
+public void AddBlinkers() {
+    var varModelFolder = Project.Current.Get("Model");
+    varModelFolder.Add(InformationModel.Make<Folder>("Blinkers"));
+
+    var varBlinkersFolder = Project.Current.Get("Model/Blinkers");
+    varBlinkersFolder.Add(InformationModel.MakeVariable("P1ms", OpcUa.DataTypes.Boolean));
+    varBlinkersFolder.Add(InformationModel.MakeVariable("P10ms", OpcUa.DataTypes.Boolean));
+    varBlinkersFolder.Add(InformationModel.MakeVariable("P100ms", OpcUa.DataTypes.Boolean));
+    varBlinkersFolder.Add(InformationModel.MakeVariable("P1s", OpcUa.DataTypes.Boolean));
+    varBlinkersFolder.Add(InformationModel.MakeVariable("P10s", OpcUa.DataTypes.Boolean));
+
+    var varNetLogicFolder = Project.Current.Get("NetLogic");
+    varNetLogicFolder.Add(InformationModel.Make<NetLogicObject>("BlinkerNetLogic"));
+
+    var varNetLogicFileUri = ResourceUri.FromProjectRelativePath("NetSolution/BlinkerNetLogic.cs");
+    // The `varBlinkersNetLogicContent` variable should contain the runtime NetLogic source text (omitted here for brevity)
+    File.WriteAllText(varNetLogicFileUri.Uri, varBlinkersNetLogicContent);
+}
+```