Table of Contents

PidController

Namespace
ZEquipment
Implements
FUNCTION_BLOCK PidController IMPLEMENTS ZCore.IObject, ZCore.IError (
 [output] Diagnostics : ZCore.DiagnosticMessage)

This controller controls the value of an analog output such that the difference between the nominal value and the feedback is minimized by using a PID controller.

There are some additional adjustments that can be taken to monitor if the PidController is working as intended.

  • The maximum settling duration can be used to automatically switch off the controller, if the nominal value does not match the feedback within a given tolerance.
  • The settling duration may be used to define the time that the feedback has to be stable (nominal value is reached within the specified tolenance over some time) before Settled return TRUE.

If the feedback (analog input) is simulated, the method PidControllerImpl.SetSimulationParameter can be used to parametrize a PT1 plant to simulate the bahavior of a physical system.

This is the managed version of this kind of object, see Objects types for details.

As an example we want to control a temperature on a surfacce with a heating element, to hold a temperature around 35 degreee celsius. The output is a AnalogOutputDint and as input we use an AnalogInputInt connected to the PT1000 thermo-sensor. In the following, the calling of this pid-controller is shown inside an automatic sequence.

CASE _step.Index OF
  (* -------------------------------------------------------- *)
  MyUnitStep.AutomaticBegin:
  (* -------------------------------------------------------- *)
    IF _step.OnEntry()
    THEN
      _timer.WaitAsync(2.0);
    END_IF

    Await(obj1:=_timer, nextStep:=MyUnitStep.AutomaticDoPidControl);

  (* -------------------------------------------------------- *)
  MyUnitStep.AutomaticDoPidControl:
  (* -------------------------------------------------------- *)
    IF _step.OnEntry()
    THEN       
      _io.PidCtrl.SetControllerParametersParallel(350, 0.6, 0);
      _io.PidCtrl.SetLogger(_logger);
      _io.PidCtrl.SetNominalValue(35.0); // command temperature 35 degree celsius
      _io.PidCtrl.SetSettling(settlingDuration:=30.0, maxSettlingDuration:=30.0, feedbackTolerance:=2.0);
      _io.PidCtrl.RunAsync(startToken:=0);
      _timer.WaitAsync(100.0); // do control for 100s
    END_IF
 
    Await(obj1:=_timer, nextStep:=MyUnitStep.AutomaticEnd);
    Assert(_io.PidCtrl);
 
  (* -------------------------------------------------------- *)
  MyUnitStep.AutomaticEnd:
  (* -------------------------------------------------------- *)
    SetBusy(FALSE);

ELSE
  Abort('sequence contains unhandled step');
END_CASE

Outputs

Diagnostics DiagnosticMessage

Constructor

FB_init 

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

This method defines the constructor of this object. In order to work properly, the PidController needs an analog 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.

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 IAnalog

Interface to the IDigital that is used for controlling

feedback IAnalog

Interface to the IAnalog that is used as the actual value signal for the controller

Returns

BOOL

Properties

AntiWindupEnabled 

PROPERTY AntiWindupEnabled : BOOL

Property Value

BOOL

Busy 

PROPERTY Busy : BOOL

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

Note that this object will never gets Busy=FALSE when it is working properly, it only finishes if an error occures or the object is stopped.

Property Value

BOOL

ControllerKd 

PROPERTY ControllerKd : LREAL

Derivative gain of the controller, see SetControllerParametersParallel for details.

Property Value

LREAL

ControllerKi 

PROPERTY ControllerKi : LREAL

Integral gain of the controller, see SetControllerParametersParallel for details.

Property Value

LREAL

ControllerKp 

PROPERTY ControllerKp : LREAL

Proportional gain of the controller, see SetControllerParametersParallel for details.

Property Value

LREAL

Done 

PROPERTY Done : BOOL

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 Value

BOOL

Error 

PROPERTY Error : BOOL

Property Value

BOOL

Feedback 

PROPERTY Feedback : IAnalog

This property provides the actual feedback value in the parameterized units of the initialized analog input. The actual feedback value this analog input can also be retrieved by using the actual analog input itself. The main use of this property is to be able to observe the actual feedback value directly in the online view of Twincat.

Property Value

IAnalog

FeedbackTolerance 

PROPERTY FeedbackTolerance : LREAL

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 PidController, see SetSettling for details.

Property Value

LREAL

InRange 

PROPERTY InRange : BOOL

This property returns TRUE if the controller has been started and the feedback value is settled between +/- feedbackTolerance set with SetSettling.

Property Value

BOOL

NominalValue 

PROPERTY NominalValue : LREAL

Nominal feedback value of the controller, see SetNominalValue for details.

Property Value

LREAL

Output 

PROPERTY Output : IAnalog

This property returns the interface to the analog output, which is controlled by the PID and passed to FB_init during initialization of this object.

Property Value

IAnalog

Settled 

PROPERTY Settled : BOOL

This property returns TRUE if the controller has been started and the feedback has been stable for > settling duration > 0). Stable is defined as holding the feedback value at the nominal value set by SetNominalValue within the feedbackTolerance/2 as lower and upper border.

Property Value

BOOL

SettlingDuration 

PROPERTY SettlingDuration : LREAL

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 PidController, see SetSettling for details.

Property Value

LREAL

SettlingTimeout 

PROPERTY SettlingTimeout : LREAL

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 PidController, see SetSettling for details.

Property Value

LREAL

Simulation 

PROPERTY Simulation : BOOL

With this property the simulation behavior of the PidController 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 Value

BOOL

State 

PROPERTY State : ZCore.ObjectState

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

Property Value

ObjectState

Methods

EnableAntiWindup 

METHOD EnableAntiWindup (
 [input] on : BOOL,
 [input] minOutput : LREAL,
 [input] maxOutput : LREAL)

This method should be used to limit the PIDs output to physical relevant values. For instance, of a temperature should be controlled within some given window, the user should supply the PID with this values. For instance, a heating device can not cool. Here a negative output should be cut off by setting minOutput to zero.

If anti windup is enabled, the integral part as well as the controllers output is limited to the windup parameters. The integral part is limited in the cyclic method and the controllers output is limited in the output method, respectively.

Inputs

on BOOL

TRUE if anti windup should be generally enabled and FALSE if not

minOutput LREAL

minimum value for anti-windup in units of the analog output, which the PID controlles

maxOutput LREAL

maximum value for anti-windup in units of the analog output, which the PID controlles

ErrorId 

METHOD ErrorId () : UDINT

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.

Returns

UDINT

ErrorMessage 

METHOD ErrorMessage () : ZCore.ZString

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.

Returns

ZString

ErrorSource 

METHOD ErrorSource () : ZCore.IError

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.

Returns

IError

Name 

METHOD FINAL Name () : ZCore.ZString

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

Returns

ZString

RunAsync 

METHOD RunAsync (
 [input] startToken : ZCore.IStartToken)

This method is used to start the PidController. Beforehand the controller has to be parametrized by SetSettling, SetSettling, SetControllerParametersParallel and of course one has to provide a nominal value by SetNominalValue.

Inputs

startToken IStartToken

returns error information if the controller could not be started

SetControllerParametersParallel 

METHOD SetControllerParametersParallel (
 [input] kp : LREAL,
 [input] ki : LREAL,
 [input] kd : LREAL)

This method is directly passed to the internally used Pid to adjust the parameters of this controller. See PID for details.

Inputs

kp LREAL

proportional gain

ki LREAL

integral part (in s)

kd LREAL

derivative part (in s)

SetDefaultOutput 

METHOD SetDefaultOutput (
 [input] enable : BOOL,
 [input] value : LREAL)

If the PID-Controller gets stopped or aborts due to an error (e.g. not settled) a default output value can be set by this method. This value will be written directly to the output if Stop gets called or the PID-controller is aborted. Via enable input, this feature can be switched on or off

Inputs

enable BOOL

set this to TRUE to use the default output value after stop is called or an error occurs

value LREAL

default value which will be written to the output after a stop or when an error occurs

SetLogger 

METHOD SetLogger (
 [input] logger : ZCore.ILogger)

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.

Inputs

logger ILogger

Zeugwerk framework compatible Logger instance implementing ILogger

SetName 

METHOD SetName (
 [input] name : ZCore.ZString)

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

Inputs

name ZString

name of the controller usually set with context to the process

SetNominalValue 

METHOD SetNominalValue (
 [input] val : LREAL)

This method is used to set the nominal value of the system which the controller has to get the feedback into. An additional tolerance may be passed with the SetSettling feature for monitoring if the feedback is 'stable'. If a new nominal value is set, the settling timeout is reset.

Inputs

val LREAL

nominal value to which the feedback gets controlled to by the system output within settling duration time

SetSettling 

METHOD SetSettling (
 [input] settlingDuration : LREAL,
 [input] settlingTimeout : LREAL,
 [input] feedbackTolerance : LREAL)

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;

Inputs

settlingDuration LREAL

duration which starts counting after system gets in range for the first time

settlingTimeout LREAL

duration which starts counting when controller starts its operation, after duration the system has to be at least once inside range

feedbackTolerance LREAL

defines the tolerance around the nominal value (+/- feedbackTolerance)

SetSimulation 

METHOD SetSimulation (
 [input] on : BOOL)

With this method the simulation behavior of the controller 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.

Inputs

on BOOL

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

Stop 

METHOD Stop ()

This method explicitly stops the PidController such that no PWM signal is send to the output, also the output will be deactivated. If everything goes well with your system this is the way to stop the controller after a successfull operation

TraceErrorStack 

METHOD TraceErrorStack (
 [input] trace : ZCore.IErrorTrace)

This method is used internally when recording an error trace.

Inputs

trace IErrorTrace