Update to SDK 2311.0.1

.github/workflows/build-library.yml

@@ -1,10 +1,10 @@
 on: push
 
 jobs:
-  build-and-test-lib:
+  test-apax-lib:
     uses: simatic-ax/actions/.github/workflows/apax-build-test.yml@stable
     secrets:
       APAX_TOKEN: ${{ secrets.APAX_TOKEN }}
-      SIMATIC_AX_TOKEN: ${{ secrets.DEPLOY_KEY}}
+      SIMATIC_AX_TOKEN: ${{ secrets.DEPLOY_KEY }}
     with:
-      LOGIN_SIMATIC_AX: true
+      LOGIN_SIMATIC_AX: true

.github/workflows/release-library.yml

@@ -11,5 +11,6 @@ jobs:
       APAX_TOKEN: ${{ secrets.APAX_TOKEN }}
       DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
       APAX_SIGNKEY: ${{ secrets.APAX_SIGNKEY }}
+
     with:
       VERSION: ${{ github.ref_name }}

.gitignore

@@ -2,5 +2,6 @@
 .env
 bin
 obj
-testresult
-./apax-lock.json
+TestResult
+*.tgz
+assets

.markdownlint.yml

@@ -8,4 +8,7 @@ default: true
 line-length: false
 no-inline-html: false
 first-line-h1: false
-no-emphasis-as-header: false
+no-emphasis-as-header: false
+MD024:
+  allow_different_nesting: true
+  siblings_only: true

README.md

@@ -3,11 +3,17 @@
 
 ## Description
 
-This library was created for the “Fischertechnik Factorysimulation 24V”. It contains classes for the basic elements of this Model.
-In the current state only the “Sortingline” is finished and can be fully implemented using this library.
+This library was created for the `Fischertechnik Factorysimulation 24V`. It contains classes for the basic elements of this Model.
+In the current state only the `SortingLine` is finished and can be fully implemented using this library.
 This library includes the following classes:
-Cylinder, Compressor, Color sensor and Axis + Motor + Encoder.
-*Note: Since the Encoder included with the model could not be accessed due to hardware limitations, the library includes TimebasedEncoder as well as Timeprovider to substitute this.
+
+- Cylinder
+- Compressor
+- ColorSensor
+- Axis
+- Encoder
+- Motor
+
 Those classes can be used for the calculation of the position based on the time.
 
 ## Install this package
@@ -24,11 +30,229 @@ apax add @simatic-ax/axftcmlib
 Simatic.Ax.axftcmlib
 ```
 
-## Objects
+## Classes
+
+### Class PneumaticCylinder
+
+PneumaticCylinder (*Note: Needs an active compressor to function with the model)
+
+|Method|Description|
+|-|-|
+|PneumaticCylinderPush()|Cylinder pushes|
+|PneumaticCylinderRetract()|Cylinder retracts|
+|Start()| Activates StateMachine and executes it once|
+
+<details><summary>Example for the class Cylinder ... </summary>
+
+```iec-st
+  VAR_GLOBAL
+      SortingLineValveEjector : BOOL; //Actual PLC-variable
+      CylinderOutputWriter : BinOutput; //Used to write on the PLC-variable
+      CylinderClassInstance : PneumaticCylinder := (CoilPushing := CylinderOutputWriter); //Class instance initialized with the needed OutputWriter
+      EnableCylinder : BOOL;
+  END_VAR
+
+  PROGRAM
+    CylinderClassInstance.RunCyclic(); //Class Setup-> needs to be called in every cycle
+    IF (EnableCylinder) THEN
+      CylinderClassInstance.Start(); // start pushing the cylinder for a configured time
+    END_IF;
+    CylinderOutputWriter.WriteCyclic(Q => SortingLineValveEjector); //Writing on the Actual PLC-variable ->needs to be called in every cycle
+  END_PROGRAM
+
+```
+
+</details>
+
+### Class PneumaticCompressor
+
+|Method|Description|
+|-|-|
+|PneumaticCompressorOn()|Turns the compressor on|
+|PneumaticCompressorOff()|Turns the compressor off|
+
+<details><summary>Example for the class Compressor ... </summary>
+
+```iec-st
+
+  VAR_GLOBAL
+    SortingLineCompressor : BOOL; //Actual PLC-variable
+    CompressorOutputWriter : BinOutput; //Used to write on the PLC-variable
+    CompressorClassInstance : PneumaticCompressor := (ActiveCompressor := CompressorOutputWriter); // Class instance initialized with the needed OutputWriter
+    EnableCCompressor : BOOL;
+  END_VAR
+
+  PROGRAM
+    IF (EnableCCompressor) THEN
+      CompressorClassInstance.PneumaticCompressorOn(); //Turning on the compressor -> Call only when needed (Off works the same way)
+    END_IF;
+    CompressorOutputWriter.WriteCyclic(Q => SortingLineCompressor);//Writing on the Actual PLC-variable ->needs to be called in every cycle
+  END_PROGRAM
+```
+
+</details>
+
+### Class ColorSensor
+
+|Method|Description|
+|-|-|
+|DetectColor(DetectedColor : INT, ColorArray : ARRAY[*] OF ColorRange) : INT |Takes INT-value from sensor and compares it to a Array to find the correct color. ColorArray is a Array of ColorRanges which contains the thresholds for the corresponding color |
+
+<details><summary>Example for the class ColorSensor ... </summary>
+
+```iec-st
+
+  VAR_GLOBAL
+    SortingLineColorSensorValue : INT; //Actual Value provided from the sensor
+    ColorSensorClassInstance : ColorSensor; //Instance of the class
+    ColorValueArray[0..1] OF ColorRange := [(StartValue := 19801, EndValue := 30000, color := Colors#UNKNOWN), (StartValue := 6000, EndValue := 9999, color := Colors#WHITE)];
+      //Gives the area in which each color is set
+      ResultColor : INT;
+  END_VAR
+
+
+  PROGRAM
+    ResultColor :=  ColorSensorClassInstance.detectColor(DetectedColor := SortingLineColorSensorValue, ColorArray := ColorValueArray);
+    //outputs the detected color as an INT/ TYPE Colors (from Lib)
+  END_PROGRAM
+```
+
+</details>
+
+<details><summary>Colors and ColorRange ... </summary>
+
+```iec-st
+
+  ///Contains all Colors that the Sensor should know -> Can be expanded
+  TYPE
+      Colors : INT (UNKNOWN := 10, WHITE := 1, RED := 2,  BLUE := 3); // default value = UNKNOWN
+  END_TYPE
+
+  ///Defines the area in which the values equals a certain color
+  TYPE
+      ColorRange : STRUCT
+          StartValue : INT;
+          EndValue : INT;
+          Color : colors;
+      END_STRUCT;
+  END_TYPE
+```
+
+</details>
 
-## Example
+### Class Axis
+
+The Axis consists of a motor and an Encoder
+
+<details><summary>Motor ... </summary>
+
+|Method|Description|
+|-|-|
+|Move(Velocity : LREAL, direction := Direction) | starts movement depending on the direction|
+|Halt()| Stops any current movement|
+
+The motor is usually completely controlled through the Axis but needs to manually write on the output.
+
+```iec-st
+
+  VAR_GLOBAL
+    SortingLineMotor : BOOL; //Actual PLC-variable
+    MotorOutputWriterForward : BinOutput; //Used to write on the PLC-variable
+    MotorOutputWriterReverse : BinOutput; //Used to write on the PLC-variable
+    MotorClassInstance : MotorFT := (Forward := MotorOutputWriterForward, Reverse := MotorOutputWriterReverse ); //Class instance initialized with the needed OutputWriter
+  END_VAR
+
+  PROGRAM
+  //The methods of the motor are all called by the axis but could be added here.
+   MotorClassInstance.MoveVelocity(Velocity := 1.0, direction := Direction#Forward);
+   MotorOutputWriterForward.WriteCyclic(Q =>SortingLineMotor);//Writing on the Actual PLC-variable ->needs to be called in every cycle
+  END_PROGRAM
+
+```
+
+</details>
+
+<details><summary>Encoder + TimeProvider ... </summary>
+
+If you haven't a hardware encoder for the Axis, then you can simulate this hardware encoder by the `TimeBasedEncoder` which calculates the position based on time. The time will be provided by a TimeProvider. This `TimeProvider` is based on the PLC cycle time
+
+### Class TimeBasedEncoder
+
+|Method|Description|
+|-|-|
+|Reset()|Sets current Position to 0|
+|SetValue(value : LINT)|Sets position to a certain value|
+|GetValue() : LINT|Outputs current value as LINT in mm|
+|Evaluate()|Measures change in position based on the velocity and cycle time (from the encoder)|
+
+### Class TimeProvider
+
+|Method|Description|
+|-|-|
+|Evaluate()| Measures the time needed for one cycle of the CPU|
+|GetElapsedSeconds()| Outputs the measured time|
+
+```iec-st
+
+  VAR_GLOBAL
+     TimeProviderForAxis : TimeProvider; //Class instance
+     TimebasedEncoderForAxis         : TimeBasedEncoder  := (TimeProvider := TimeProviderForAxis, EncoderAxis := ConveyorbeltForSortingLine, Velocity := 1.0); //Class instance
+      //Encoder needs access to the axis to check, if it is running
+  END_VAR
+
+  PROGRAM
+    TimebasedEncoderForAxis.Evaluate(); //Checking the position every cycle -> must be called every cycle
+    TimeProviderForAxis.Evaluate();    //Checking the cycle time -> must be called every cycle
+   //Axis uses this information for the monitoring of the current position
+  END_PROGRAM
+
+```
+
+</details>
+
+|Method|Description|
+|-|-|
+|RunCyclic()| Execute the cyclic evaluation of the axis|
+|MoveVelocity(Velocity : LREAL, direction : Direction)| moves the axis with given speed into certain direction until Halt() is called|
+|MoveRelative(velocity : LREAL, distance : LINT) : BOOL|moves the axis for a distance based on the current position|
+|MoveAbsolute(velocity : LREAL, position : LINT) : BOOL|moves the axis based on a default point -> Axis needs to be homed|
+|Homing(velocity : LREAL, direction : Direction) : BOOL|moves the axis into its homing position|
+|Homing(Position : LINT) : BOOL| homes the axes without movement -> position is set to given value|
+|Halt()|Stops all movement|
+|GetPlcOpenState() : PlcOpenState | Returns current status of axis: Ready, busy, done, error|
+|IsRUnning() : BOOL| Checks, if the  axis is currently moving|
+
+<details><summary>Example for the class Axis ... </summary>
+
+```iec-st
+
+  VAR_GLOBAL
+    SortingLineMotor : BOOL; //Actual PLC-variable
+    MotorOutputWriterForward : BinOutput; //Used to write on the PLC-variable
+    MotorOutputWriterReverse : BinOutput; //Used to write on the PLC-variable
+    MotorClassInstance : MotorFT := (Forward := MotorOutputWriterForward, Reverse := MotorOutputWriterReverse ); //Class instance initialized with the needed OutputWriter
+
+    TimeProviderForAxis : TimeProvider; //Class instance
+    TimebasedEncoderForAxis         : TimeBasedEncoder  := (TimeProvider := TimeProviderForAxis, EncoderAxis := ConveyorbeltForSortingLine, Velocity := 1.0); //Class instance
+
+    AxisReferenceSwitch  : BinSignal;
+    ConveyorbeltForSortingLine : Axis := (Motor :=  MotorForAxis, Encoder := TimebasedEncoderForAxis, ReferenceSwitch := AxisReferenceswitch);
+  END_VAR
+
+  PROGRAM
+    TimebasedEncoderForAxis.Evaluate(); //Checking the position every cycle -> must be called every cycle
+    TimeProviderForAxis.Evaluate();    //Checking the cycle time -> must be called every cycle
+
+    ConveyorbeltForSortingLine.RunCyclic(); //Must be called every cycle
+    ConveyorbeltForSortingLine.Homing(Position := 0);
+    ConveyorbeltForSortingLine.MoveAbsolute(Velocity := 1.0, Position := 4000); 
+
+     MotorForwardOutputWriter.WriteCyclic(Q => SortingLineMotorForConveyor); // Write output signals 
+  END_PROGRAM
+
+```
 
-<please provide a working example>
+</details>
 
 ## Markdownlint-cli