Table of Contents

OnOffController

Namespace
ZEquipment
Implements

In control theory a on off controller is a controller with a feedback and a digital output to switch abruptly between two states. Usually this type of system is used to control hydraulic levels, pressure or also heat in a water heating system. In general these processes do not have high dynamic requirements..

This function block has to be provided with a digital output which controls the actor of the control system and an analog input which measures the actual value of the controlled system. E.g. a pressurized system with the digital output it is possible to switch on and off a compressor. The analog input measures the actual pressure in the system.

In order to function as supposed one has to provide an upper limit, a lower limit as on and off thresholds and a feedback tolerance to detect runaway events like a wire break for the digital output or a stuck relais. There is also a timeout and a duration parameter which is necessary to observe the settling of the controlled system.

If the feedback (analog input) is simulated, this function block will automatically write random values in the range of (switchOnAt, switchOffAt) to the analog input in order to simulate a working behavior of the controller

The controller triggers an error if the settling is not ok within the parameterized settling timeout or if the feedback value gets outside its on and off limits always taking the feedback tolerance into account.

See the following diagram for more information on how the OnOffController switches the digital output: OnOffController switching behavior

  1. FeedbackTolerance: Defines the threshold value for the Settled property in physical units of the feedback analogue input
  2. Hysteresis: When parametrizing the controller with SetReference this value is defined by 2*hysteresis around reference value
  3. Settled=TRUE range: This range is defined by 2*hysteresis + feedbackTolerance
Note

The simulation behavior of the OnOffController depends on the feedback input only. If this object is set to Simulation:=TRUE then the OnOffController will also calculate a simulated trajectory of the feedback input and therefore simulate its behavior. It is also possible to set the OnOffController to Simulation:=TRUE which will propagate this setting to the input and output automatically.

Note

It is important to note, that if one sets the direct used feedback input of the OnOffController to Simulation:=FALSE, after initialization of OnOffController itself with Simulation:=TRUE, this last call will set the final Simulation config, which is in this case Simulation:=FALSE.

FUNCTION_BLOCK OnOffController IMPLEMENTS ZCore.IObject, ZCore.IError

Outputs

Diagnostics DiagnosticMessage

Constructor

FB_init

This method defines the constructor of this object. In order work properly the OnOffController needs a parent which is in charge of calling the Cyclic method, a digital output which controls the actor of the controlled system and an analog input which provides the feedback signal for the control loop. These objects have to be present in construction phase of this object.

METHOD FB_init (
 bInitRetains : BOOL,
 bInCopyCode : BOOL,
 parent : ZCore.IManagedObject,
 output : IDigital,
 feedback : IAnalog) : BOOL

Inputs

bInitRetains BOOL

if TRUE, the retain variables are initialized (warm start / cold start)

bInCopyCode BOOL

if TRUE, the instance afterwards gets moved into the copy code (online change)

parent IManagedObject

Interface to the ManagedObject that is the parent of this object

output IDigital

Interface to the IDigital that should be used to control the actor of the controlled system

feedback IAnalog

Interface to the IAnalog that is used as the actual feedback input for the controller

Returns

BOOL

Properties

Busy

This property returns TRUE if the object is Busy executing a sequence or still in its initialization phase (if applicable). It returns FALSE if the object is Idle or in an Error state.

Use State to find out if the object is busy executing its initialization phase, or it is busy performing an actual sequence.

PROPERTY Busy : BOOL

Property Value

BOOL

Done

If the object is in idle state (often mentioned as "the object is not busy and not on error"), this is indicated by this property returning TRUE.

PROPERTY Done : BOOL

Property Value

BOOL

Enabled

This property returns the actual state of the internal initialized digital output. If the controller is working and the controlled output is set, this property will return TRUE, otherwise FALSE. The output state of this digital output can also be retrieved by using the actual digital output

PROPERTY Enabled : BOOL

Property Value

BOOL

Error

If the object aborts its execution with an error, this is indicated by this property returning TRUE. Information about the error may be retrieved by utilizing the methods that are implemented from the IError.

Returns TRUE if a fault occured within a sequence or the initialization phase of an object, respectively. If this property returns TRUE, use

to get insights about the origin of the fault.

PROPERTY Error : BOOL

Property Value

BOOL

Feedback

This property provides the interface of the feedback of the controllers as it has be initialized with the constructor.

PROPERTY Feedback : IAnalog

Property Value

IAnalog

FeedbackTolerance

Maximum and minimum value of the feedback input given in %. If the feedback gets outside these values the controller will trigger an error. Use 0 to disable this feature. This property is used for the settling feature of the OnOffController, see SetSettling for details.

PROPERTY FeedbackTolerance : LREAL

Property Value

LREAL

InRange

This property returns TRUE if the controller has been started and the feedback value is in between the provided on and off limits set by SetOnOffThreshold also taking the feedbackTolerance into account.

See the following diagram for more information on when this property returns TRUE: OnOffController.InRange behavior

PROPERTY InRange : BOOL

Property Value

BOOL

Settled

This property returns TRUE if the controller has been started and the feedback value is in between the given on and off threshold also tolerating the parameterized tolerance with SetSettling

PROPERTY Settled : BOOL

Property Value

BOOL

SettlingDuration

Minimum duration in seconds which the feedback has to be inside the on and off range (including feedback tolerance). Use 0 to disable this feature. This property is used for the settling feature of the OnOffController, see SetSettling for details.

PROPERTY SettlingDuration : LREAL

Property Value

LREAL

SettlingTimeout

Maximum time in seconds which it can take the controller to get the feedback value into the given range of on and off value. Use 0 to disable this feature. This property is used for the settling feature of the OnOffController, see SetSettling for details.

PROPERTY SettlingTimeout : LREAL

Property Value

LREAL

Simulation

With this property the simulation behavior of the OnOffController can be set. If set to TRUE the Feedback and control output is also set to simulation on, if FALSE then the simulation will be turned off.

PROPERTY Simulation : BOOL

Property Value

BOOL

State

Returns the object state of the axis object. This exposes if an object is still in its booting phase, had an error, or is busy executing an async action.

PROPERTY State : ZCore.ObjectState

Property Value

ObjectState

SwitchOffThreshold

Feedback value at which the controller switches off its output. Provide here the same units as initialized at the analog input. This property is a shortcut to set this threshold directly, see SetOnOffThreshold for details.

PROPERTY SwitchOffThreshold : LREAL

Property Value

LREAL

SwitchOnThreshold

Feedback value at which the controller switches on its output. Provide here the same units as initialized at the analog input. This property is a shortcut to set this threshold directly, see SetOnOffThreshold for details.

PROPERTY SwitchOnThreshold : LREAL

Property Value

LREAL

Methods

ErrorId

Returns the error code of the first error source for this object. The method recursively goes down the error stack until the initial source of error of this object can be found. For performance reasons, the error stack is not cleared when the error state is reset. So this method should always used in conjunction with Error.

METHOD ErrorId () : UDINT

Returns

UDINT

ErrorMessage

Returns the error description of the first error source for this object. The method recursively goes down the error stack until the initial source of error of this object can be found. For performance reasons, the error stack is not cleared when the error state is reset. So this method should always used in conjunction with Error.

METHOD ErrorMessage () : ZCore.ZString

Returns

ZString

ErrorSource

This method returns the direct error source of this object. This method can then be used to retrieve the actual error source by using the method of the returned IError.

METHOD ErrorSource () : ZCore.IError

Returns

IError

Name

This method returns the name that has been set with SetName during initialization phase.

METHOD FINAL Name () : ZCore.ZString

Returns

ZString

RunAsync

This method starts the opreation of the OnOffController. After calling and the feddback value is outside its initialized on and off boundaries it sets the output and tries to hold the feedback in between the parameterized values. It only stops doing this if an error occurs like exceeding the on or off boundaries (always taking the feedbackTolerance into account) or if you stop it by calling the stop method

Before starting the OnOffController, one has to set the On- & Off- Thresholds with SetOnOffThreshold or it is also possible to set a reference value and a specific hysteresis for symetric on and off thresholds with SetReference. It is also important to provide a digital output for controlling the actuator of the system and an analog input for the feedback value of the control loop.

METHOD RunAsync (
 startToken : ZCore.IStartToken)

Inputs

startToken IStartToken

SetLogger

With this method an optional logger may be passed to this object. The object then informs about errors, starting, stopping actions and so on. The logger of the IDigital and IAnalog that is passed when constructing this object is not influenced by this method and have to be set in the according initialization phases.

METHOD SetLogger (
 logger : ZCore.ILogger)

Inputs

logger ILogger

SetName

The name of this object is used for identification to simplify debugging, especially when generating log messages in an application. It can be set during initialization while constructing the function block or anywhere, at any time in the application

METHOD SetName (
 name : ZCore.ZString)

Inputs

name ZString

name of the controller usually set with context to the process

SetOnOffThreshold

This method is used to set the desired feedback boundaries for on and off of this controller. The output is switched off, if the feedback value is greater than switchOffAt and it gets switched on, if the feedback value is smaller than switchOnAt. In order to function properly these parameters have to be provided in correct units which are also parametrized by the initialzed analog input. When changing the values while the controller is already busy, the settling timeout is reset.

METHOD SetOnOffThreshold (
 switchOnAt : LREAL,
 switchOffAt : LREAL)

Inputs

switchOnAt LREAL

feedback value at which the controller switches on its output. Provide here the same units as initialized at the analog input

switchOffAt LREAL

feedback value at which the controller switches off its output. Provide here the same units as initialized at the analog input

SetReference

This method is used to set the desired feedback boundaries for on and off of this controller by providing the reference value as mean value surrounded by a hysteresis for on and off. The output is switched off, if the feedback value is greater than switchOffAt and it gets switched on, if the feedback value is smaller than switchOnAt. In order to function properly these parameters have to be provided in correct units which are also parametrized by the initialzed analog input.

Internally the OnOffController calls SetOnOffThreshold with switchOnAt as referenceValue - hysteresis and referenceValue + hysteresis for the parameter switchOffAt.

SetOnOffThreshold(referenceValue - hysteresis, referenceValue + hysteresis);

METHOD SetReference (
 referenceValue : LREAL,
 hysteresis : LREAL)

Inputs

referenceValue LREAL

desired process value to which the on off controller should get the feedback value by controlling the process

hysteresis LREAL

hysteresis around the reference value which defines the on and off value

SetSettling

This method can be used to parameterize a duration that the feedback has to be stable (actual value matched the nominal value within its tolerance) in order for the Settled property to return TRUE. The actual tolerance is taken into account in the form switchOnAt - feedbackTolerance, switchOffAt + feedbackTolerance such that it closely resembles the behavior of OnOffController.

METHOD SetSettling (
 settlingDuration : LREAL,
 settlingTimeout : LREAL,
 feedbackTolerance : LREAL)

Inputs

settlingDuration LREAL

The feedback value has to be at least for settlingDuration seconds between On-tolerance and Off+tolerance, use 0 to disable this feature.

settlingTimeout LREAL

After settlingTimeout seconds the feedback has to reach at least the onValue otherwise the OnOffController will signal an error, use 0 to disable this feature.

feedbackTolerance LREAL

Defines the threshold value for the Settled property in physical units of the feedback analogue input for on and off value, use 0 to disable this feature.

SetSimulation

With this method the simulation behavior of the OnOffController can be set. If set to TRUE the Feedback and control output is also set to simulation on, if FALSE then the simulation will be turned off. Also when simulation is on, the OnOffController simulates the process by writing simulated values to the feedback and therefore the OnOffController can function properly.

METHOD SetSimulation (
 on : BOOL)

Inputs

on BOOL

Provide TRUE to switch on simulation and FALSE to run with the actual linked variables

SetSimulationParameter

If Simulation is activated for the OnOffController, this method can be used to adjust some parameters that are used to simulate the feedback of the controller. The parameters of this method are based on the parameters that are set with SetSettling.

  • feedbackNoise, feedback noise in percent (0-100) relative to the feedback-tolerance range which is added to the (simulated) feedback, defaults to 1 percent
METHOD SetSimulationParameter (
 feedbackNoise : LREAL,
 disabledGain : LREAL,
 enabledGain : LREAL)

Inputs

feedbackNoise LREAL

In percent, based on feedbackTolerance, defaults to 1

disabledGain LREAL

Controls how much the feedback changes in every cycle relative to (switchOffThreshold-switchOnThreshold) / settlingDuration times the deviation from the nominal value, if the controller is disabled, defaults to 0.4

enabledGain LREAL

Controls how much the feedback changes in every cycle relative to (switchOffThreshold-switchOnThreshold) / settlingDuration time sthe deviation from the nominal value, if the controller is enabled, defaults to 1

Stop

This method explictly stops the OnOffController and resets the output. After that all observing mechanisms are switched off and are only turned on by calling RunAsync again. If the OnOffController is on error, it can simply be started by calling RunAsync again, there is no need for calling Stop beforehand.

METHOD Stop ()

TraceErrorStack

This method is used internally when recording an error trace.

METHOD TraceErrorStack (
 trace : ZCore.IErrorTrace)

Inputs

trace IErrorTrace