Base classes design TcoCore

[PTKu]

Discussion about basic classes arising from the framework description document:
https://docs.google.com/document/d/1m0K2_1lwMMV4pcp_B2BamQrIaMImWBwfdyzMoOWHfa4/edit?disco=AAAAIXQzkYA

[PTKu]

Bringing here discussion from document https://docs.google.com/document/d/1m0K2_1lwMMV4pcp_B2BamQrIaMImWBwfdyzMoOWHfa4/edit?disco=AAAAIXQzkYA

TcoSequencer (consumer interface)

@GISED-Link wrote:

IF Step(200,
        TRUE,
        'Switch on red light') THEN
//--------------------------------------------    
    _lightR_SwitchOn := TRUE;
    IF(_lightR_IsOn) THEN
        CompleteStep();
    END_IF;
//--------------------------------------------
END_IF;

Since we use twincat, can we use enum with the {attribute to_string} decorator? This way we just don't use any number for the steps
The code will look like: Step(EnumName_e.SwitchLightRed, TRUE)

@jozefchmelar wrote:

It's faster to add new steps if they're identified by number. This way the enum class could become be way too big to read. And adding an enum for every step is cumbersome and frankly kinda annoying.

@GISED-Link wrote:

The idea of the enum is just simple. When you will afect the next step, instead of writting 'step := 200; // turn the red led on'
we simply write:
'step := Enum_e.TurnRedLedOn;'
Ok we have to manage an enum list, but the guy that read our code sees directly and without the need of a comment what our application does.

@PTKu wrote:

You can use ENUM instead of numerical literal, it will work that way. Each enumerator item must have unique value and it should be of default (INT) type.

Jouke (don't know GH name) wrote :

I agree with Roger here. It's a great feature provided by Twincat. So technically it could still be an INT value, but maybe for the example it's nicer to use the ENUM way.

[GISED-Link]

After some discussions with my colleagues and friends, it seems that using magic numbers to define steps is definitely a huge habit (in the PLC programming field). After some thought and acceptance by myself, I agree that it's a good idea to keep 2 different fields for the step and the associated name because enum names are not really pretty for a HMI or a debugging console.

I'll definitely take a closer look at the more general look of the whole project. That definitely seems more important than spending time on the details.

[HAHermsen]

because enum names are not really pretty for a HMI or a debugging console.

I strongly disagree on this, but everybody is entitled to their own opinion.
I use enums without hesitation in my ST based SFC's

The given example

Step(200,
        TRUE,
        'Switch on red light') 

I think an Enum in place of the first parameter and second will give more context and automagically drops the descriptive String. The following code is less prone to errors in writing and, even more important, reading by others to improve maintainability which in frameworks like this imho 'mandatory'.

My suggestion is that both enums can be printed to screen or with pragma strict removed, and this code needs no extra comment as it is written fluently, selbdescribing and leaves no place for 'guessing'

Step( Name := eStepName.RedLight,
         Action := eStepAction.On ); // this call could print "RedLight is On" easily without effort

Thus avoid this kind of syntax;

IF(_state = 20) THEN  // Where are we?
    _state := 0; // where do we go?
END_IF;

[GISED-Link]

I don't know if we can use some sort of typedef in TwinCAT. The way that StepFoo(Name: eStepName, ...) is used sounds a bit weird at the first look. Maybe eName: eStepName would help. It would be greate to tell the user he can feed those functions with any kind of enum he has to create for its application.

I think there will be need for predefined step.entry(), step.continous() and step.exit()

after a quick reading here:
https://infosys.beckhoff.com/english.php?content=../content/1033/tcplccontrol/html/TcPlcCtrl_Languages%20SFC.htm&id=
it seems that .Entry() and .Exit() method names are appropriate. For the .Continous(), I cannot find something consistant... B&R uses the term .Cyclic(), Infosys uses "Action"...

In the FreeRTOS doc, I can read: [task] ... are typically implemented as a continuous loop
https://www.freertos.org/implementing-a-FreeRTOS-task.html

I prefer Continuous as Cyclic

[HAHermsen]

"Continous" is common naming convention for such actions.

PS I am not a fan of the Hungarian notation, as tooltips etc provide good context/info on the variable / parameter so I personally prefer Name: eStepName over eName: eStepName.

Ultimatly these things are both a matter of taste, but being constistant is key.

Typedefs in CODESYS == TwinCAT == DUT's == Types / Enums / Structs

[PTKu]

I'd say the former, i.e. Step(Name: eStepName, Action : eStepAction); as
Name : INT doesn't make sense in a human readable manner.

Thanks, @HAHermsen! Yes, we can take that approach, but we will need to think about another form of coordination primitive or about an extension of the one in question. The current implementation targets the most generic design (agnostic of concrete type of particular application), this is a lightweight version of the sequencing primitive.

The devil is in the details.

One of the problems is that there is no support for method overload at this time, and although you can pass different types of enums as a parameter to the method there is no warranty of consistency between the two types of enums:

At current implementation, we have a protected method Step (we want to hide it to prevent the call from other parts of the application) this method has a signature that cannot be overridden.

let's have a step method with the following signature:

METHOD Step : BOOL
VAR_INPUT
	Name : eStepNameA;
	Act : eActionA; // ACTION would not work as it is a keyword
END_VAR

where enums are:

{attribute 'qualified_only'}
{attribute 'strict'}
TYPE eStepNameA :
(
	step1 := 100,
	step2 := 200
);
END_TYPE
//----------------------------------------
{attribute 'qualified_only'}
{attribute 'strict'}
TYPE eActionB :
(
	On := 10,
	Off := 20
);
END_TYPE

Let have another set of enums:

{attribute 'qualified_only'}
{attribute 'strict'}
TYPE eStepNameB :
(
	step1 := 200,
	step2 := 100
);
END_TYPE
//-----------------------------------
{attribute 'qualified_only'}
{attribute 'strict'}
TYPE eActionB :
(
	On := 20,
	Off := 10
);
END_TYPE

This would be the correct call that will work fine

_seq.Step(eStepNameA.step1, eActionA.On);

now imagine we have another instance of sequencer and we call Step method like this:

_seq.Step(eStepNameB.step1, eActionB.On);

what would we get as the step description?

There are all sorts of other types of issues we would need to face. I cannot go into details now.

I am sure that the description from the enums is fine for us, not so sure about the customers using the HMI (just relaying my experience).

[TomKovac]

I have already made some tries with OnEntry and OnExit, but for the moment we did not implement this mechanism. It's a point for discussion. From my perspective, it could be useful, mostly for the people with previous experiences with SFC ( I am not pretty sure how this sequential graphic language inside Twincat is called).

[PTKu]

@TomKovac I will create an issue for that... did not know this would pop up so early in the discussion 😄.
#22

[PTKu]

This is maybe off-topic here but anyways @GISED-Link @HAHermsen there is this comment from Gerhard #13 (comment), I'd like to know your opinion on that; we will need to address this question before we continue.

[HAHermsen]

Short and quick anwsers

The devil is in the details.

TRUE, no doubts here.

Let have another set of enums:

DUT's can be extended, so a base type can be extended with user defined additions so in theory the agnostic/generic usability is maintained;

https://help.codesys.com/api-content/2/codesys/3.5.14.0/en/_cds_obj_dut/
or
https://infosys.beckhoff.com/english.php?content=../content/1033/tc3_plc_intro/2530071691.html&id=

Allthough it seems valid to me? (I think that the liskov principle applies here too?), I never applied this trick on DUT's (!)
I just never had any need to, so it will be interesting.

[PTKu]

DUT can be extended however:

looks like ENUMs can't 😢 ... but yeah it would be great if they could...

[HAHermsen]

Ah.... too bad, again the details! Agreed on the extension of ENUM, it could be a wonderful addition.

[HAHermsen]

From our own work: a CFC application example in "easy" classic style, while the library underneath is OOP all the way.
Basicly the JanzTec library utilises this trick also. Offcourse the application can be written in ST but CFC is popular as it is easy to follow for beginners.

OFFLINE

ONLINE

[PTKu]

OK then. Let's design a pattern to write wrapping FBs to hide OOP implementation, then. The way I think about it now is to have separate libraries for traditional interface where dedicated contributors will take care of wrapping OOP blocks (in a separate library and namespace).

We are aiming here to create several dozens (maybe hundreds) of components. In order to develop, document, test, maintain and support both interfaces, it will require extra work from the community, so we need to think about how do we organize the work around this.

I am creating an issue for that #28