Behaviour Model and Interface Design¶

Note

With CODESYS 3.5.11.0 a new library was introduced. The Common Behaviour Model replaces the CAA_Bahaviour.library. Please take a look to the documentation inside the new library for more detailed information.

Actions whose execution time depends on external devices (e.g. reading from a network interface) or is strongly influenced by the size of parameters (e.g. writing the data of a huge portion of memory to a file), should be defined as function blocks (FB) with asynchronous processing, i.e. for distributing the work load over several plc cycles (invocations).

We distinguish two models according their processing behaviour:

Edge triggered (xExecute)
Level controlled (xEnable)

Note

Please take a look to an article about the special handling of VAR_INPUT CONSTANT.

The VAR_INPUT CONSTANT construct is part of a convention for declarative parameterization of function blocks.

Edge Triggered Function Blocks¶

The input variable xExecute is the defining feature for this type of function block.
A rising edge detected at the input variable xExecute (start condition) starts the operation defined by this particular edge triggered function block.
All inputs other than xExecute and the eventually present variable xAbort are sampled with this rising edge. Their values will be stored locally. Thus, later changes of these inputs can not influence the defined operation while it is running [1].
The input variable xExecute can be set to FALSE after the status TRUE was seen on the output variable xBusy.
A falling edge detected at the input variable xExecute will not abort the defined operation. The defined operation is running normally to its ready condition, abort condition or error condition.
Only the status TRUE detected on the eventually present input variable xAbort cancels the defined operation (abort condition).
If the eventually present input variable xAbort and the input variable xExecute have the same value TRUE the abort condition is reached immediately.
Only one of the output variables xDone, xBusy, xError or the eventually present output variable xAborted can have the status TRUE at the same time.
If a abort condition was detected, the output variable xAborted is set to TRUE after setting the output variable xBusy to FALSE.
With the falling edge of xBusy the input variable xExecute is sampled and its inverted value is stored as a reset request.
The state of the output variables will be valid for a minimum of one invocation even though the state of the xExecute input variable is already set to FALSE. In this case (reset request is TRUE) the internal state of the function block is automatically reinitialized. In the other case (xExecute is still TRUE) the function block is waiting for a falling edge of the input variable xExecute before reinitializing the function block (standard handshake).
The status of the output variables other than xDone, xBusy, xError, xAborted or eErrorID are valid only while xDone has the status TRUE [2][3].
With an active reset request and after the status TRUE of one of the output variables xDone, xError or xAborted was seen, the input variable xExecute can be set to TRUE again and the function block will restart its defined operation (quick handshake).

See the description of the output behaviour, the description of the possible timing constraints and the description of the possible error handling.

Level Controlled Function Blocks¶

The input variable xEnable is the defining feature for this type of function block.
The status TRUE detected on the input variable xEnable (start condition) starts the operation defined by this particular level controlled function block. The defined operation is running to its ready condition or error condition while the input variable xEnable is TRUE. The status FALSE detected on the input variable xEnable is interpreted as an abort (abort condition). This means the internal state of the function block and all output variables will be reinitialized and it is then ready for a new start (standard handshake).
The input variables will not be stored locally and can so influence the current work flow of the defined operation.
Only one of the output variables xDone, xBusy or xError can have the status TRUE at the same time.
The status of all output variables are valid as long as the status of the output variables xBusy or xDone is TRUE [3].
With the falling edge of xBusy the input variable xEnable is sampled and its inverted value is stored as a reset request.
The state of the output variables will be valid for a minimum of one invocation even though the state of the xEnable input variable is already set to FALSE. In this case (reset request is TRUE) the internal state of the function block is automatically reinitialized. This can especially be happen after an error condition while aborting the defined operation.
The status of the output variables other than xDone, xBusy, xError or eErrorID are valid only while xDone has the status TRUE [2][3].
With an active reset request and after the status TRUE of one of the output variables xDone or xError was seen, the input variable xEnable can be set to TRUE again and the function block will restart its defined operation (quick handshake).

Sometimes it is necessary to have a behaviour model which never reaches its ready condition. Such a function block has no xDone output variable and no Done state. This behaviour is defined as a Continuous Behaviour. In the context of this document we refer to this kind of behavior models as LConC and LConTlC.

See the description of the output behaviour, the description of the possible timing constraints and the description of the possible error handling.

Common properties¶

If a specific invocation of a function block detects a start condition, the output variable xBusy is set immediately to the status TRUE.
As long as the defined operation of a function block is running the output variable xBusy has the status TRUE.
If a error condition was detected, the output variable xError is set to TRUE and the output variable xBusy is set to FALSE. In addition, one of the defined error codes (one value out of the local enumeration type ERROR) will be assigned to the output variable eErrorID.
If the ready condition is reached, the output variable xDone is set to TRUE and the output variable xBusy is set to FALSE.
If the defined operation can be fully processed in one invocation, the ready condition or the error condition is reached immediately and the TRUE status of the output variable xBusy is never be seen.
With the rising edge of xDone, the status of all output variables will be frozen.
As long as one of the output variables xDone, xBusy, xAborted (eventually present) or xError has the status TRUE the defined operation of this function block is not yet completed, so further invocations are necessary to complete the Resetting state.

Timing constraints¶

udiTimeLimit ([µs], 0 ⇒ no operating time limit):

A function block could, for example, complete a complex task in a loop. The larger the task is, the more time that is consumed in the current invocation of this function block. The udiTimeLimit parameter can define how much time per invocation is permitted for consumption in the respective function block. Function blocks with a udiTimeLimit input variable are implement in such a way that the current invocation is exited when the task is complete (Ready Condition), or when the consumed time for this invocation has exceeded the settings from udiTimeLimit.
udiTimeOut ([µs], 0 ⇒ no operating time limit):

When processing its defined operation, a function block could be forced for example to wait for an external event. It can do this in an internal loop (Busy Wait) or it can check in each invocation whether its task can be completed in full. The udiTimeOut parameter can define then how much time is permitted for consumption for the defined operation. Function blocks with the udiTimeOut input variable are implemented in such a way that the current invocation is exited towards a error condition (xError ⇒ TRUE and eErrorID ⇒ ERROR.TIME_OUT) when the time interval as defined by udiTimeOut has been exceeded.

Error Handling¶

Every Function Block in this document has a Boolean output xError to indicate that there is an error condition reached. In that case the related information will be signaled with the value of the output eErrorID. The eErrorID represents an Integer, indicating the reason of the error. In many cases this integer value is used as input for an additional FB which converts the number to a related localized string in an applicable language. The set of values for a specific eErrorID are application dependent. In case several libraries are combined (several domains), there can be an overlap in the numbers of the eErrorID, meaning that the same number identifies a different error in a different domain. For this reason an value range definition for eErrorID per library must be done.

The error handling of a function block should be designed in a way that only error codes are returned, which are documented in the affected library. It is very convenient but not recommended simply to return untreated error codes from sub libraries. This would result in a bad user experience. It is recommended to map foreign error codes to the error range of the affected library.

Note

Please take a look to the Rules for Error Handling

Sorting Inputs and Outputs¶

If default inputs (xExecute or xEnable, xAbort, udiTimeLimit, udiTimeOut) are used, these must be positioned at top of the list of inputs, followed by specific inputs and the section VAR_IN_OUT. Further on the default outputs are to be declared in the following sequence: xDone, xBusy, xError, eErrorID. Subsequently the specific outputs are to be defined.

Cooperation¶

If the design of function block interfaces consistently takes into account the described behaviour models then complex relationships between instances of them can easily be expressed and understood, in particular in graphical languages. The following example demonstrates the opportunities which are resulting from the use of the CODESYS Common Behaviour Model:

TCP Reader Example¶

A TCP Server (LConC) listens at a specific endpoint. This endpoint is defined with an tuple consisting of an IP address and a related port number. After a connection to a TCP client has been established, the related Connection (LConC) will be activated. With the help of an Reader (LConTlC), a message structure is allocated out of a MessagePool. This structure is then used to store the information received from the client. For further processing, the message is then handed over to function block QWrite (LCon) that interfaces a queue.

Extending the Example to a Complete EchoServer¶

A Writer (ETrigTlTo) is working now at the end of the original Queue and is requesting (dequeuing) the stored messages. This message is sent back over the original Connection to the client. So every received message will be sent back to the original sender, the client. With this small modification, a complete Echo Server is created.

Note

Why is it sometimes important to choose a level-controlled model rather than an edge-triggered model?

For the detection of a rising edge in a function block, two PLC cycles are necessary. Thus, if the requirement is to be able to process a new value in each cycle, an edge-triggered model cannot serve as a solution. In this case, a level-controlled function block model is the preferred way to implement the required functionality.

The Reader function block in the example above must have the possibility to provide a new message in each cycle. If there is no new message available in the current cycle, the output variable is set to null. So in this case, a level-control model was chosen.

Sending a message with the help of the Writer function block in the example above can last more then one cycle. So it is important to choose an edge-triggered model.

In order to combine these two function blocks into an efficient working team, a queue mechanism is necessary.

Please spend a look to the connection between the xBusy output variable of the Writer and the negated xExecute input variable of the QRead. In this way the handshake between these two function block generated the most efficient output.

Transformation to a Multithreaded EchoServer¶

Step 1: Encapsulate the “Reader – Queue – Writer” logic into a function block called EchoHandler

Content of the new EchoHandler function block:

Step 2: Declare a numer of EchoHandler instances and assign these instances to different tasks.

Now we have a full-fledged multi threaded EchoServer.

Library Support¶

For CODESYS V3 there is the library CommonBehaviourModel.library, it implements the behavior model described earlier at a central location. Also there are library project templates, extending the behaviour model for the particular usage. The Library and the templates are available with the CODESYS V3 setup.

How to set up a user specific implementation of a Behaviour Model FB in a new library:

Create a new library in CODESYS (New Project -> Category “Library”) and for this for example choose the template “CODESYS library”. In the Template folder in the POUs view of your new library project you will find an example for each of the function blocks of the CommonBehaviourModel.library. To create an implementation e.g. of the FB ETrigA copy ETrigA_Temp from the Templates folder to the function block folder and rename it to myETrigA. Activate code generation for myEtrigA as follows: Open the “Properties” of the POU and in category “Build” deactivate option “Exclude from build”. In the comments of myETrigA and its methods you will find hints on how to do the implementation. For being able to acquire some experience with the behaviour of the FB (when and at which state change of the inputs which of the related method gets called), we recommend to implement a counter in each method before starting to test the implementation. For further information please take a look to the source code of Common Behaviour Model.

State Chart of the abortable, timing constrained and edge triggered Common Behaviour Model (ETrigATlTo)