[NEW-FEATURE] Analogue and digital inspectors (#139)

* Create draft PR for #138

* added initial inspectors libraries

* wip on implementing AxoInspector

* added first implementation of analogue. digital inspectors, added comprehensive result, wip on data inspectors

* experiments with timers, AX sharp inheritance and interface bug

* rollback ax timers for inspectors, wip

* wip on inspector dialog

* wip on inspectors

* wip on inspectors

* experimenting with inspectors, trying to implement correct restore

* refactoring, added terminate with step

* added inspector documentation, some UI tweaks and code refactoring

* refactoring, fix some typos in doc

* remove logger

* moves process data to context

* added inspector view template and shadow views

* fix overinspection inconsistencies

---------

Co-authored-by: Specter-13 <Specter-13@users.noreply.github.com>
Co-authored-by: Specter-13 <56168909+Specter-13@users.noreply.github.com>
Co-authored-by: PTKu <61538034+PTKu@users.noreply.github.com>

build_docu.ps1

@@ -1,4 +1,4 @@
 # 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\abstractions\ctrl .\src\data\ctrl\ .\src\core\ctrl -o .\docfx\apictrl\
+dotnet ixd -x .\src\abstractions\ctrl .\src\data\ctrl\ .\src\core\ctrl .\src\inspectors\ctrl -o .\docfx\apictrl\
 dotnet docfx .\docfx\docfx.json --debug
 dotnet docfx serve .\docs\

cake/BuildContext.cs

@@ -144,6 +144,7 @@ public BuildContext(ICakeContext context, BuildParameters buildParameters)
         ("core", "axopen.core"),       
         ("data", "axopen.data"),
         ("probers", "axopen.probers"),
+        ("inspectors", "axopen.inspectors"),
         ("components.abstractions", "axopen.components.abstractions"),
         ("components.cognex.vision", "axopen.cognex.vision"),
     };

docfx/articles/inspectors/AXOANALOGUEINSPECTOR.md

@@ -0,0 +1,16 @@
+## AxoAnalogueInspector
+
+Provides evaluation of *continuous* values. The inspector checks that the input value falls within the limit of *Min* and *Max*. The inspection passes when the input value is within the required limit without interruption for the duration of stabilization time.
+
+![Analog inspector](~/images/analog-inspector.png)
+
+
+Common inspector data are extended with following analogue inspector data:
+
+```C#
+RequiredMin : LREAL; // min required value for inspection
+
+DetectedStatus : LREAL; // detected value
+
+RequiredMax: LREAL; // max required value for inspection
+```

docfx/articles/inspectors/AXODATAINSPECTOR.md

@@ -0,0 +1,16 @@
+## AxoDataInspector
+
+Provides evaluation of alphanumerical values. The input value compares against the Required value. The inspection passes when the input value matches the required value without interruption for the duration of stabilization time. In addition to exact comparison, data inspector allows for simple pattern matching where # = any number and * = any character.
+
+![Data inspector](~/images/data-inspector.png)
+
+Common inspector data are extended with following data inspector data:
+
+```C#
+RequiredStatus : STRING; //required value for inspection
+
+DetectedStatus : STRING; //detected value for inspection
+
+StarNotationEnabled: BOOL; //star notation enable/disable
+
+```

docfx/articles/inspectors/AXODIGITALINSPECTOR.md

@@ -0,0 +1,13 @@
+## AxoDigitalInspector
+
+Inspector provides evaluation of *discrete* value. The input value compares against the *Required* value. The inspection passes when the input value matches the required value without interruption for the duration of stabilization time.
+
+![Digital inspector](~/images/digital-inspector.png)
+
+Common inspector data are extended with following digital inspector data:
+
+```C#
+RequiredStatus : BOOL; //required value for inspection
+
+DetectedStatus : BOOL; //detected value for inspection
+```

docfx/articles/inspectors/README.md

@@ -0,0 +1,114 @@
+# **AXOpen.Inspectors**
+
+**AXOpen.Inspectors** provides mechanism of inspection of different types of data. The input value is compared to required value. If input value is the same as required value for a *stabilization* time period, the inspection will succeed. If values are different, *timeout* will occur and inspection will fail.
+
+Inspectors can integrate with coordination primitives like [AxoSequencer](../core/AXOSEQUENCER.md). In consequence, inspectors offer extended capabilities in decision flow for failed checks.
+
+Each inspector contains:
+
+1. `Inspect` method, which input is current parent and inspection variable
+2. `OnFail` method, which provides methods for making a decision after a failed inspection (see Handling failure section)
+3. `UpdateComprehensiveResult` method, which input is object of type `AxoComprehesiveResult`, which can be used to gather results of all inspections.
+
+4. `Common data` about inspection inputs and result. See below.
+
+## Example inspection
+Example of inspection within a sequencer in PLC:
+```
+ _presenceInspector.WithCoordinator(THIS).Inspect(THIS,_inspectionResult)
+        .UpdateComprehensiveResult(_comprehensiveResult)
+        .OnFail().CarryOn();
+```
+
+1. A _presenceInspector is created instance of `AxoDigitalInspector`
+
+2. A coordinator is passed to this inspector with `WithCoordinator(THIS)` method, in this case it is a sequencer, a parent object.
+3. `Inspect` methods takes parent and inspection variable, on which inspection is performing.
+4. If inspection fails, the result is updated to `_comprehensiveResult` object with `UpdateComprehensiveResult` method.
+5. If inspection fails, `OnFail` method provides `CarryOn` method, which tells the coordinator to continue in execution.
+
+## Common inspector data
+
+Inspectors contain common data, which are used to store data about inspection. Each inspector contain following data:
+
+```C#
+Timestamp: LDATE_AND_TIME; // timestamp of inspection
+
+PassTime : TIME; // stabilization time, inspection must be success for this period of time
+
+FailTime : TIME; // timeout, after which inspection fails
+
+Result : eInspectorResult; // result of inspection
+
+IsExcluded: BOOL; // inspection will be performed, however result will be omitted in overall result
+
+IsByPassed : BOOL; // inspection will be skipped
+
+NumberOfAllowedRetries : UINT; // maximum number of retries of inspection, from which overinspection will occur
+
+RetryAttemptsCount : UINT; // actual number of retries, if RetryAttemptsCount > NumberOfAllowedRetries, overinspection occurs
+
+```
+
+
+
+[!INCLUDE [AxoDigitalInspector](AXODIGITALINSPECTOR.md)]
+
+[!INCLUDE [AxoAnalogueInspector](AXOANALOGUEINSPECTOR.md)]
+
+[!INCLUDE [AxoDataInspector](AXODATAINSPECTOR.md)]
+
+
+
+## Handling failure
+
+When an inspector fails, OnFail() provides a series of methods for making decisions about the process. In order for this is feature to work the inspector needs to be aware of the coordinator of `IAxoCoordinator`. The coordinator must be passed to the inspector by `WithCoordinator(coordinator)` method.
+
+
+| Syntax                                | Description |
+| -----------                           | ----------- |
+| Dialog(inRetryStep, inTerminateStep)  | Opens dialog for the user to take a decision. Parameter `inRetryStep` represent state from which the inspection should start again. Parameter `inTerminateStep` represent terminate state of coordinator.                                       |
+| Retry(inRetryStep)                    | Retries the inspector. Retry state parameter tells from which state the inspection should start again.                        |
+| Override()                            | Marks the inspection as failed but continues with the following states of the coordinator.                                      |
+| Terminate(inTerminateStep)            | Marks the inspection as failed and aborts the execution of the coordinator.                                          |
+
+The following example specify, that when inspection fails, dialog is shown and is requesting user decision.
+
+```
+ _valueInspector.WithCoordinator(THIS).Inspect(THIS,_inspectionValue).OnFail().Dialog(Steps[20], Steps[145]);
+```
+
+![Inspection failure](~/images/inspection-failure-dialog.png)   
+
+## Over-inspection
+When `RetryAttemptsCount` is same as `NumberOfAllowedRetries`, no more inspection are allowed, as data are overinspected.
+
+![Overinspected](~/images/overinspected.png)
+
+
+## Preserving overall result
+
+Overall result of a series of inspections can be preserved in `AxoComprehensiveResult`. Each inspector has `UpdateComprehensiveResult` method that provides the update function. Once the `UpdateComprehensiveResult` marks the overall result as Failed, successive inspection will not overwrite the result. 
+
+```
+
+IF (Steps[30].Execute(THIS, TRUE, 'Example Digital inspection')) THEN
+
+    _presenceInspector.WithCoordinator(THIS).Inspect(THIS,_inspectionResult)
+        .UpdateComprehensiveResult(_comprehensiveResult)
+        .OnFail().CarryOn();
+
+    END_IF;
+
+    IF (Steps[40].Execute(THIS, TRUE, 'Example Analog inspection')) THEN
+
+    _valueInspector.WithCoordinator(THIS).Inspect(THIS,_inspectionValue)
+        .UpdateComprehensiveResult(_comprehensiveResult)
+        .OnFail().CarryOn();
+
+    END_IF;
+
+
+END_IF;
+```
+

docfx/articles/toc.yml

@@ -36,6 +36,16 @@
         href: ~/articles/data/AxoDataExchange.md
       - name: Data fragmets exchange
         href: ~/articles/data/AxoDataFragmentExchange.md
+
+- name: AXOpen.Inspectors
+  href: ~/articles/inspectors/README.md
+  items:
+      - name: AxoDigitalInspector
+        href: ~/articles/inspectors/AXODIGITALINSPECTOR.md
+      - name: AxoAnalogueInspector
+        href: ~/articles/inspectors/AXOANALOGUEINSPECTOR.md
+      - name: AxoDataInspector
+        href: ~/articles/inspectors/AXODATAINSPECTOR.md
 - name: AXOpen.Messaging
   href: ~/articles/messaging/README.md
   items:

docs/articles/timers/OFFDELAYTIMER.html

@@ -0,0 +1,165 @@
+<!DOCTYPE html>
+<!--[if IE]><![endif]-->
+<html>
+
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+    <title>AxOpen.Timers.OffDelayTimer | System.Dynamic.ExpandoObject </title>
+    <meta name="viewport" content="width=device-width">
+    <meta name="title" content="AxOpen.Timers.OffDelayTimer | System.Dynamic.ExpandoObject ">
+    <meta name="generator" content="docfx ">
+
+    <link rel="shortcut icon" href="../../images/favicon.ico">
+    <link rel="stylesheet" href="../../styles/docfx.vendor.css">
+    <link rel="stylesheet" href="../../styles/docfx.css">
+    <link rel="stylesheet" href="../../styles/main.css">
+    <link rel="stylesheet" href="../../styles/custom.css">
+    <link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">  
+    <meta property="docfx:navrel" content="../../toc.html">
+    <meta property="docfx:tocrel" content="../toc.html">
+
+  <meta property="docfx:rel" content="../../">
+
+  </head>  <body data-spy="scroll" data-target="#affix" data-offset="120">
+    <div id="wrapper">
+      <header>
+
+        <nav id="autocollapse" class="navbar navbar-inverse ng-scope" role="navigation">
+          <div class="container">
+            <div class="navbar-header">
+              <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
+                <span class="sr-only">Toggle navigation</span>
+                <span class="icon-bar"></span>
+                <span class="icon-bar"></span>
+                <span class="icon-bar"></span>
+              </button>
+
+              <a class="navbar-brand" href="../../index.html">
+                <p class="text-logo">AXOpen</p>
+              </a>            </div>
+            <div class="collapse navbar-collapse" id="navbar">
+              <form class="navbar-form navbar-right" role="search" id="search">
+                <div class="form-group">
+                  <input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
+                </div>
+              </form>
+            </div>
+          </div>
+        </nav>
+
+        <div class="subnav navbar navbar-default">
+          <div class="container hide-when-search" id="breadcrumb">
+            <ul class="breadcrumb">
+              <li></li>
+            </ul>
+          </div>
+        </div>
+      </header>
+      <div class="container body-content">
+
+        <div id="search-results">
+          <div class="search-list">Search Results for <span></span></div>
+          <div class="sr-items">
+            <p><i class="glyphicon glyphicon-refresh index-loading"></i></p>
+          </div>
+          <ul id="pagination" data-first="First" data-prev="Previous" data-next="Next" data-last="Last"></ul>
+        </div>
+      </div>
+      <div role="main" class="container body-content hide-when-search">
+
+        <div class="sidenav hide-when-search">
+          <a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
+          <div class="sidetoggle collapse" id="sidetoggle">
+            <div id="sidetoc"></div>
+          </div>
+        </div>
+        <div class="article row grid-right">
+          <div class="col-md-10">
+            <article class="content wrap" id="_content" data-uid="">
+<h1 id="axopentimersoffdelaytimer">AxOpen.Timers.OffDelayTimer</h1>
+
+<p><code>OffDelayTimer</code> class contains <code>OffDelay</code> method, where logic of OffDelayTimer is implemented. <code>OffDelay</code> method has following input:</p>
+<pre><code class="lang-C#">VAR_INPUT 
+    Parent : IAxoObject; // or IAxoContext, parent provides RTC implementation              
+    inSignal : BOOL; // starts timer with falling edge, resets timer with rising edge
+    TimeDelay : LTIME; // time to pass, before output is set
+END_VAR 
+</code></pre>
+<p>The OffDelay method returns <code>output</code>, which <em>is FALSE, <code>TimeDelay</code> seconds after falling edge of <code>inSignal</code> is detected</em>.</p>
+<p>The <code>OffDelayTimer</code> have also public variables which can be used to access timer results:</p>
+<pre><code class="lang-C#">VAR PUBLIC
+    output : BOOL; // is FALSE, TimeDelay seconds after falling edge of inSignal is detected
+    elapsedTime : LTIME; // elapsed time 
+END_VAR 
+</code></pre>
+<p>The LOGIC of <code>OffDelayTimer</code> is following:</p>
+<p>When <code>inSignal</code> is TRUE, <code>output</code> is TRUE and <code>elapsedTime</code> is 0. As soon as <code>inSignal</code> becomes FALSE, the time will begin to be counted in <code>elapsedTime</code> until its value is equal to that of <code>TimeDelay</code>. It will then remain constant. The <code>output</code> is FALSE when <code>inSignal</code> is FALSE and <code>elapsedTime</code> is equal to <code>TimeDelay</code>. Otherwise it is TRUE. Thus, <code>output</code> has a falling edge when the time indicated in <code>TimeDelay</code> has run out.</p>
+<p>Example usage of <code>OffDelay</code> timer:</p>
+<pre><code>USING AXOpen.Timers;
+
+
+VAR 
+    _signal : BOOL; // input signal, which is set somewhere in application
+    _testTimerOffDelay: AXOpen.Timers.OffDelayTimer; // timer instance
+    _testTimeDelay: LTIME := LTIME#5s; // time delay
+END_VAR  
+
+// call OffDelay method somewhere in application
+// THIS must type of IAxoObject
+_testTimerOffDelay.OffDelay(THIS, _signal, _testTimeDelay);
+
+// check for output
+IF(_testTimerOffDelay.output) THEN
+
+    // handle result
+
+ENDIF;
+</code></pre>
+</article>
+          </div>
+
+          <div class="hidden-sm col-md-2" role="complementary">
+            <div class="sideaffix">
+              <div class="contribution">
+                <ul class="nav">
+                  <li>
+                    <a href="https://github.com/ix-ax/AXOpen/blob/150-_NEW-FEATURE_Create_library_for_timers_that_will_be_platform_independent_using_injected_RTC/docfx/articles/timers/OFFDELAYTIMER.md/#L1" class="contribution-link">Improve this Doc</a>
+                  </li>
+                </ul>
+              </div>
+              <nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
+                <h5>In This Article</h5>
+                <div></div>
+              </nav>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <footer>
+        <div class="grad-bottom"></div>
+        <div class="footer">
+          <div class="container">
+            <span class="pull-right">
+              <a href="#top">Back to top</a>
+            </span>
+       Generated by DocFx. © Peter Kurhajec, MTS spol. s r.o., and awesome contributors
+
+          </div>
+        </div>
+      </footer>
+    </div>
+    <script type="text/javascript" src="../../styles/docfx.vendor.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.0.1/highlight.min.js"></script>
+    <script src="https://unpkg.com/highlightjs-dotnetconfig@0.9.3/dist/dotnetconfig.min.js"></script>
+    <script type="text/javascript" src="../../styles/docfx.js"></script>
+    <script type="text/javascript" src="../../styles/main.js"></script>
+    <script type="text/javascript" src="https://unpkg.com/mermaid@8.10.2/dist/mermaid.min.js" integrity="sha384-nzpOk138h0/O14Ig1PAUlf1XSo5T+XvpBUVkpLaU40QBvMgrNkSKusdNAomDLEd2" crossorigin="anonymous"></script>
+    <script>
+    mermaid.initialize({
+    startOnLoad: false
+    });
+    mermaid.init(undefined, ".lang-mermaid");
+    </script>  </body>
+</html>