Table of Contents

PwmController

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

This controller pulses a digital output with a duty cycle such that the difference between the nominal value and the feedback is minimized. Internally, a PID is modulating the [duty cycle](xref:ZEquipment.PwmController#DutyCycle (returned in % by property but internally the time on which the output is active) within an interval.

There are some additional adjustments that can be taken to monitor if the PwmController 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, this function block will automatically write random values in the range of [nominalValue-feedbackTolerance/2, nominalValue+feedbackTolerance/2) to the analog input.

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 DigitalOutput and as input we use an AnalogInputInt connected to the PT1000 thermo-sensor. In the following, the calling of this pwm-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.AutomaticDoPwmControl);

  (* -------------------------------------------------------- *)
  MyUnitStep.AutomaticDoPwmControl:
  (* -------------------------------------------------------- *)
    IF _step.OnEntry()
    THEN       
      _io.PwmCtrl.SetControllerParametersParallel(350, 0.6, 0);
      _io.PwmCtrl.SetInterval(100); // max pulse width 100ms
      _io.PwmCtrl.SetLogger(_logger);
      _io.PwmCtrl.SetNominalValue(35.0); // command temperature 35 degree celsius
      _io.PwmCtrl.SetSettling(settlingDuration:=30.0, maxSettlingDuration:=30.0, feedbackTolerance:=2.0);
      _io.PwmCtrl.RunAsync(startToken:=0);
      _timer.WaitAsync(100.0); // do control for 100s
    END_IF
 
    Await(obj1:=_timer, nextStep:=MyUnitStep.AutomaticEnd);
    Assert(_io.PwmCtrl);
 
  (* -------------------------------------------------------- *)
  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 : IDigital,
 [input] feedback : IAnalog) : BOOL

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

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 pulsed by this controller

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

DutyCycle 

PROPERTY DutyCycle : LREAL

This property returns the actual duty cycle in % with regard to the set interval in seconds (PWM-on-phase). The PID controller constantly changes this value in order to keep the system deviation at a minimum. The maximum duty cycle can be the initialized interval set by SetInterval

Property Value

LREAL

Enabled 

PROPERTY Enabled : BOOL

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 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 PwmController, 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

Interval 

PROPERTY Interval : LREAL

This property returns the actual parametrized interval duration in seconds (sometimes called PWM period), see SetInterval for details.

Property Value

LREAL

MaxDutyCycle 

PROPERTY MaxDutyCycle : LREAL

Returns the last set MaxDutyCycle Value set with EnableAntiWindup method. To check if AntiWindup is enabled test AntiWindupEnabled property.

Property Value

LREAL

MinDutyCycle 

PROPERTY MinDutyCycle : LREAL

Returns the last set MinDutyCycle Value set with EnableAntiWindup method. To check if AntiWindup is enabled test AntiWindupEnabled property.

Property Value

LREAL

NominalValue 

PROPERTY NominalValue : LREAL

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

Property Value

LREAL

PhaseShift 

PROPERTY PhaseShift : LREAL

Usually the duty-cycle is right at the beginning of the PWMs interval. This means that after the RunAsync method is called and the controller is not settled, it will start to output a digital signal. The PhaseShift property can be used to delay the output in the interval. For instance, if Interval=0.1s and PhaseShift=50%, the PWM will only start to output a signal after 0.050s. After the initial delay the controller behaves as it would without the PhaseShift. The property is useful to distribute the peak load more evenly over time if multiply PWMs are operated simultaniously. This can help to prevent overloading of a power supply and improve overall system performance. Note that a similar effect can be achieved by starting the PWMs with a delay to each other, however the property may be changed at any time while the controller is active to adjust the timing. The default phase shift is 0 and the unit of this property is percent, which decouples the property from the actual interval.

Property Value

LREAL

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

Property Value

LREAL

Simulation 

PROPERTY Simulation : BOOL

With this property the simulation behavior of the PwmController 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 axis object. This exposes if an object is still in its booting phase, had an error, or is busy executing an async action.

Property Value

ObjectState

Methods

EnableAntiWindup 

METHOD EnableAntiWindup (
 [input] on : BOOL,
 [input] minDutyCycle : LREAL,
 [input] maxDutyCycle : 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

minDutyCycle LREAL

minimum value for anti-windup in %

maxDutyCycle LREAL

maximum value for anti-windup in % - max value is 100%

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 PwmController. Beforehand the controller has to parametrized by SetSettling, SetInterval, 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](xref:ZCore.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)

SetInterval 

METHOD SetInterval (
 [input] val : LREAL)

This method is used to specify the maximum duty cycle in 'seconds' of this controller, where duty cycle = 100% means that output is activated for the full interval time. The slower the system reacts to changes, the longer the interval time may be. For 'normal' applications, the interval time may range from several milliseconds to several seconds. If Antiwindup was not configured before calling this method, it also activates anti windup with the lower limit = 0% and to upper limit = 100%.

The default value for the interval setting is '1.0 seconds'

Inputs

val LREAL

in seconds

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 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 conrtoller 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 explictly stops the PwmController such that no PWM signal is sent 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