Add documentation for AxoMessenger

build_docu.ps1

@@ -1,4 +1,6 @@
 # dotnet run --project ..\ix\src\ix.compiler\src\ixd\Ix.ixd.csproj --framework net7.0 -x .\src\core\ctrl\ -o .\docfx\apictrl\
-dotnet ixd -x .\src\core\ctrl\ -o .\docfx\apictrl\
-dotnet docfx .\docfx\docfx.json
+dotnet ixd -x .\src\core\ctrl\ -o .\docfx\apictrl\core\
+dotnet ixd -x .\src\messaging\ctrl\ -o .\docfx\apictrl\messaging\
+dotnet ixd -x .\src\abstractions\ctrl\ -o .\docfx\apictrl\abstractions\
+dotnet docfx .\docfx\docfx.json --debug
 dotnet docfx serve .\docs\

docfx/articles/messaging/AXOMESSENGER.md

@@ -0,0 +1,55 @@
+# AxoMessenger
+
+Static `AxoMessenger` is a class that provides mechanism for delivering static message to the supervising applications (SCADA/HMI). This static messenger uses the text defined in the declaration. This text cannot be changed during runtime as the text is "transfered" just once during the compilation and it is not read during the runtime. The PLC code of the `AxoMessenger` just ensures the activation, deactivation and acknowledgement of the message. 
+
+`AxoMessenger` contains following public methods. 
+
+`Serve()` - this method must be called cyclically. It ensures the inicialization of the instance, so as the deactivation of the message.
+
+```mermaid
+  classDiagram
+    class AxoMessenger{
+        +Serve(IAxoContext _context)
+        +Serve(IAxoObject _object)        
+    }     
+```
+
+`Activate(category)` - this method immediatelly activate the message of the category where category is of the type `eAxoMessageCategory`. Deactivation is detected after one PLC cycle without calling the method `Activate`.
+
+`ActivateOnCondition(condition,category)` - this method activate the message of the category where category is of the type `eAxoMessageCategory` on the rising edge of the condition and imidiatelly deactivate the message on the falling edge of the condition. The `ActivateOnCondition` method is designed to be called cyclically. 
+
+>[!NOTE] 
+>Do not use the both activation methods on the same `AxoMessenger` instance, please use just one of them.
+
+`Acknowledge()` - acknowledge the message if required. The message could be acknowledged so as before deactivation so as after.
+
+Depending on the [eAxoMessageCategory](/apictrl/abstractions/plc.AXOpen.Messaging.eAxoMessageCategory.html) the messenger should require the acknowledgement.
+
+By default the acknowledgement is not required for the levels `Trace`,`Debug`,`Info`,`TimedOut`,`Notification` and `Warning`. 
+This could be overwritten by calling the `RequireAcknowledgement()` method. 
+Contrariwise, the acknowledgement is required for the levels `Error`,`ProgrammingError`,`Critical`,`Fatal` and `Catastrophic` by default. This could be overwritten by calling the `DoNotRequireAcknowledgement()` method. 
+
+**Attributes `MessageText` and `Help`**
+
+These attributes are used to set the values of the static texts of the messenger. These values are read out at the compilation time transfered to .NET counterpart and set as a constant strings. Therefore they can't be changed at the runtime.
+
+Example of declaration the instance and defining the attributes `MessageText` and `Help`.
+[!code-smalltalk[](../../../src/integrations/ctrl/src/Examples/AXOpen.Messaging/AxoStaticMessengerDocuExample.st?range=7-9)]
+
+**How to use `AxoMessenger`**
+
+The instance of the `AxoMessenger` must be defined inside the `AxoContext` or `AxoObject`. 
+Inside the `Main()` method of the related `AxoContext` or inside the cyclically called method of the `AxoObject` following rules must be applied. The `Serve()` method of the instance of the `AxoMessenger` must be called cyclically.
+The `Activate` method should be used called the required condition or the `AcitvateOnCondition` should be called cyclically. Avoid to mix using the both methods with the same instance.
+[!code-smalltalk[](../../../src/integrations/ctrl/src/Examples/AXOpen.Messaging/AxoStaticMessengerDocuExample.st?range=5-25,48)]
+
+If neccessary, the default behaviour of the acknowledgeable messenger should be changed as follows.
+[!code-smalltalk[](../../../src/integrations/ctrl/src/Examples/AXOpen.Messaging/AxoStaticMessengerDocuExample.st?name=DoNotRequireAcknowledgement)]
+Contrariwise, the default behaviour of the unacknowledgeable messenger should be changed as follows.
+[!code-smalltalk[](../../../src/integrations/ctrl/src/Examples/AXOpen.Messaging/AxoStaticMessengerDocuExample.st?name=RequireAcknowledgement)]
+
+**How to visualize `AxoMessenger`**
+
+On the UI side use the `RenderableContentControl` and set its Context according the placement of the instance of the `AxoMessenger`.
+[!code-csharp[](../../../src/integrations/src/AXOpen.Integrations.Blazor/Pages/DocuExamples/AxoMessagingStaticDocu.razor?name=RenderedView)]
+

docfx/articles/messaging/README.md

@@ -0,0 +1,7 @@
+# **AXOpen.Messaging**
+
+**AXOpen.Messaging** provides basic blocks for providing messaging.
+
+# Basic concepts
+
+[!INCLUDE [AxoMessenger](AXOMESSENGER.md)]

docfx/articles/toc.yml

@@ -24,4 +24,9 @@
   - name: AxoComponent
     href: ~/articles/core/AXOCOMPONENT.md  
 - name: AXOpen.Data
-  href: ~/articles/data/README.md
+  href: ~/articles/data/README.md
+- name: AXOpen.Messaging
+  href: ~/articles/messaging/README.md
+  items:
+  - name: AxoMessenger
+    href: ~/articles/messaging/AXOMESSENGER.md

docfx/docfx.json

@@ -2,10 +2,12 @@
   "metadata": [
     {
       "src":  [
-        {        
+        {
           "files": [
+            "abstractions/src/**.csproj",
             "core/src/**.csproj",
-            "data/src/**.csproj"           
+            "data/src/**.csproj",
+            "messaging/src/**.csproj"
           ],
           "exclude": [
             "**Test*.csproj",

src/abstractions/ctrl/apax.yml

@@ -1,5 +1,5 @@
 name: "@ix-ax/axopen.abstractions"
-version                                                                                                                                                                                                     : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
+version                                                                                                                                                                                                      : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
 type: lib
 targets:
   - "1500"

src/core/ctrl/apax.yml

@@ -1,5 +1,5 @@
 name: "@ix-ax/axopen.core"
-version                                                                                                                                                                                : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
+version                                                                                                                                                                                 : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
 type: lib
 targets:
   #  - "1500"
@@ -15,6 +15,6 @@ scripts:
     - dotnet ixc
 dependencies:
   "@ax/system-timer": 3.0.9
-  "@ix-ax/axopen.abstractions"        : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
+  "@ix-ax/axopen.abstractions"         : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
   "@ax/axunit-library": ^4.0.6
 

src/data/ctrl/apax.yml

@@ -1,5 +1,5 @@
 name: "@ix-ax/axopen.data"
-version                                                                                                                                                                                                                                  : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
+version                                                                                                                                                                                                                                   : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
 type: lib
 targets:
 #  - "1500"
@@ -8,7 +8,7 @@ targets:
 files:
   - src
 dependencies:
-  "@ix-ax/axopen.core"                                                                                                                                                                                              : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
+  "@ix-ax/axopen.core"                                                                                                                                                                                               : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
   "@ax/axunit-library": ^4.0.6
 devDependencies:
   "@ax/sdk": 3.0.18

src/integrations/ctrl/apax.yml

@@ -1,5 +1,5 @@
 name: "axopen.integrations"
-version                                                                                                                                                                                   : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
+version                                                                                                                                                                                    : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
 type: app
 targets:
 #  - "1500"
@@ -11,11 +11,11 @@ devDependencies:
   "@ax/sld": ^0.14.2
 
 dependencies:
-  "@ix-ax/axopen.core"           : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
-  "@ix-ax/axopen.data"           : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
-  "@ix-ax/axopen.probers"        : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
-  "@ix-ax/axopen.messaging"      : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
-  "@ix-ax/axopen.simatic1500"    : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
+  "@ix-ax/axopen.core"            : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
+  "@ix-ax/axopen.data"            : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
+  "@ix-ax/axopen.probers"         : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
+  "@ix-ax/axopen.messaging"       : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
+  "@ix-ax/axopen.simatic1500"     : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
   "@ax/axunit-library"          : ^4.0.6
 
 variables:

src/integrations/ctrl/src/Examples/AXOpen.Messaging/AxoStaticMessengerDocuExample.st

@@ -0,0 +1,49 @@
+USING AXOpen.Messaging;
+USING AXOpen.Messaging.Static;
+
+NAMESPACE AxoStaticMessengerDocuExample
+    CLASS Messengers EXTENDS AXOpen.Core.AxoContext
+        VAR PUBLIC
+            {#ix-set:MessageText = "<#Message text for messenger 1#>"}
+            {#ix-set:Help = "<#Help text for messenger 1#>"}
+            _messenger1 : AxoMessenger;
+            _messenger1condition : BOOL;
+            {#ix-set:MessageText = "<#Message text for messenger 2#>"}
+            {#ix-set:MessageText = "<#Message text for messenger 2#>"}
+            _messenger2 : AxoMessenger;
+            _messenger2condition : BOOL;
+       END_VAR    
+
+       METHOD PROTECTED OVERRIDE Main
+            _messenger1.Serve(THIS);    
+            IF _messenger1condition THEN
+                _messenger1.Activate(eAxoMessageCategory#Error);
+            END_IF;
+
+            _messenger2.Serve(THIS);    
+            _messenger2.ActivateOnCondition(_messenger2condition,eAxoMessageCategory#Warning);
+        END_METHOD
+
+        METHOD Examples
+            //<Activate>
+            _messenger1.Serve(THIS);    
+            IF _messenger1condition THEN
+                _messenger1.Activate(eAxoMessageCategory#Error);
+            END_IF;
+            //</Activate>
+
+            //<ActivateOnCondition>
+            _messenger2.Serve(THIS);    
+            _messenger2.ActivateOnCondition(_messenger2condition,eAxoMessageCategory#Warning);
+            //</ActivateOnCondition>
+
+            //<RequireAcknowledgement>
+            _messenger2.ActivateOnCondition(_messenger2condition,eAxoMessageCategory#Warning).RequireAcknowledgement();
+            //</RequireAcknowledgement>
+
+            //<DoNotRequireAcknowledgement>
+            _messenger2.ActivateOnCondition(_messenger2condition,eAxoMessageCategory#Error).DoNotRequireAcknowledgement();
+            //</DoNotRequireAcknowledgement>
+        END_METHOD
+    END_CLASS    
+END_NAMESPACE

src/integrations/ctrl/src/configuration.st

@@ -22,6 +22,7 @@ CONFIGURATION MyConfiguration
         AxoMomentaryTaskDocu : AxoMomentaryTaskExamples.AxoMomentaryTaskDocuExample;
         AxoDataExamplesDocu : AxoDataExamplesDocu.Context;
         AxoMessengers : AxoStaticMessengerExample.Messengers;
+        AxoMessengersDocu : AxoStaticMessengerDocuExample.Messengers;
         AxoRtc : AxoRtc.AxoS71500Rtc;
 
         process_data_manager: AxoDataExamples.AxoProcessDataManager;

src/integrations/ctrl/src/program.st

@@ -19,6 +19,7 @@ PROGRAM MyProgram
         AxoDataExamplesDocu : AxoDataExamplesDocu.Context;
 
         AxoMessengers : AxoStaticMessengerExample.Messengers;
+        AxoMessengersDocu : AxoStaticMessengerDocuExample.Messengers;
 
         // Integration test
         Integrations : IntegrationTests.Integrations;
@@ -42,7 +43,8 @@ PROGRAM MyProgram
     AxoDataExamplesDocu.Run();
     AxoMessengers.Run();
     AxoMessengers.InjectRtc(AxoRtc);
-
+    AxoMessengersDocu.Run();
+    AxoMessengersDocu.InjectRtc(AxoRtc);
 
 
     // Integration tests

src/integrations/src/AXOpen.Integrations.Blazor/Pages/DocuExamples/AxoMessagingStaticDocu.razor

@@ -0,0 +1,35 @@
+@page "/AxoMessagingStaticDocu"
+@using axopen_integrations
+@using AXOpen.Core;
+<h3>AxoMessagingStaticDocu</h3>
+
+<div class="container">
+    <div class="card">
+        <div class="card-header d-flex">
+            <div class="h4 p-0 w-100 mb-4 text-primary border-bottom border-primary">Simple static messages examples.</div>
+        </div>
+        <div class="card card-body">
+            <div class="container text-left">
+                <div class="row">
+                    <div class="col">
+                        <div class="card ps-2">
+                            //<RenderedView>
+                                <RenderableContentControl Context="@Entry.Plc.AxoMessengersDocu._messenger1" Presentation="Command-Control" Class="ps-2"/>
+                            //</RenderedView>
+                        </div>
+                        <div class="card ps-2">
+                            <RenderableContentControl Context="@Entry.Plc.AxoMessengersDocu._messenger1condition" Presentation="Command-Control" Class="ps-2" />
+                        </div>
+                        <div class="card ps-2">
+                            <RenderableContentControl Context="@Entry.Plc.AxoMessengersDocu._messenger2" Presentation="Command-Control" Class="ps-2" />
+                        </div>
+                        <div class="card ps-2">
+                            <RenderableContentControl Context="@Entry.Plc.AxoMessengersDocu._messenger2condition" Presentation="Command-Control" Class="ps-2" />
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+     </div>
+</div>
+

src/integrations/src/AXOpen.Integrations.Blazor/Pages/DocuExamples/DocuExamples.razor

@@ -24,5 +24,10 @@
                 <span class="oi oi-plus" aria-hidden="true"></span> AxoDataExamplesDocu
             </NavLink>
         </div>
+        <div class="nav-item px-3">
+            <NavLink class="nav-link" href="AxoMessagingStaticDocu">
+                <span class="oi oi-plus" aria-hidden="true"></span> AxoMessagingStaticDocu
+            </NavLink>
+        </div>
     </nav>
 </div>

src/messaging/ctrl/apax.yml

@@ -1,5 +1,5 @@
 name: "@ix-ax/axopen.messaging"
-version : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
+version  : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
 type: lib
 targets:
   # - "1500"
@@ -14,7 +14,7 @@ scripts:
   postbuild:
     - dotnet ixc
 dependencies:
-  "@ix-ax/axopen.core" : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
-  "@ix-ax/axopen.utils" : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
-  "@ix-ax/axopen.abstractions" : '0.1.4-55-Create-unit-tests-for-messaging-tranfered-from-tco.72'
+  "@ix-ax/axopen.core"  : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
+  "@ix-ax/axopen.utils"  : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
+  "@ix-ax/axopen.abstractions"  : '0.1.4-83-Add-documentation-for-AxoMessenger.65'
   "@ax/axunit-library": ^4.0.6