Table of Contents

ActuatorDigital

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

The are many implementions for actuators that can be described with the IActuatorDigital interface. This implementation focuses on actuators whose movement can be started by enabling digital output(s) and can be monitored by digital input(s).

In the industry such actuators can be most commonly found in the form of pneumatic actuators that use compressed air acting on a piston inside a cylinder to move a load along a linear path from point A (minus) to point B (plus). This function block supports several configurations of such actuators. The name scheme for the most commonly used actuators in the Zeugwerk Framework is ActuatorDigitalActing TypeLsLimitswitch Type.

Acting Type:

The acting type describes how digital outputs are used.

  • Single-acting cylinders (indicated by the suffix Mono): use one air port to let compressed air enter the cylinder to move the piston to the desired position, as well as an internal spring to return the piston to the home position when the air pressure is removed. This type of actuator only requires digital interface, e.g. either a plus output or a minus output. While on the software side it isn't really needed to give this output a name, it is still relevant for pneumatics engineers if the are using a norm to differentiate between plus and minus. Most commonly such actuators are needed for safety features, where 1 position of the actuator should be activated automatically in the case of an emergency shutdown.

  • Double-acting cylinders (indicated by the suffix Bi) have an air port at each end and move the piston forward and back by alternating the port that receives the high pressure air. This type of actuator require two digital interfaces to move the actuator around. Most commonly such actuators are found in grippers that need to have 2 stable positions.

Limitswitch Type:

The limitswitch type describes on which side(s) of the actuator a digital interface is used to monitor the actuators position.

  • No: No digital interface is used at all. The actuator operates "blindly".
  • Plus: Only 1 digital interface is used at the plus position of the actuator.
  • Minus: Only 1 digital interface is used at the minus position of the actuator.
  • PlusMinus: Both sides of the actuator are monitored by digital interface.

While it is most desirable to use the PlusMinus limitswitch type for practically all applications, it is not always feasible to implement two digital interfaces for monitoring the actuator's position. There might be cost reasons, hardware reasons (...) to only use one or even no limit switch at all for some specific applications.

Outputs

Diagnostics DiagnosticMessage

Properties

Busy 

PROPERTY Busy : BOOL

Property Value

BOOL

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

PositionAsString 

PROPERTY PositionAsString : ZCore.ZString

Returns the current position of the actuator. The property uses the names of the digital inputs, which can be set with [SetName](xref:ZEquipment.ActuatorDigital#SetName].

Property Value

ZString

Simulation 

PROPERTY Simulation : ActuatorDigitalSimulation

Enable or disable simulation for this actuator. This can be done on the fly also during execution of the PLC

Property Value

ActuatorDigitalSimulation

State 

PROPERTY State : ZCore.ObjectState

Property Value

ObjectState

Methods

Duration 

METHOD Duration () : LREAL

Returns the duration of the actuator's last (successful and actually performed) movement in seconds The method may return very small values if the actuator already was in the correct position and larger numbers if it actually had to move. If no movement has been performed yet, the method returns the maximum of the expected movement duration.

Returns

LREAL

EnableForcedMovement 

METHOD EnableForcedMovement (
 [input] on : BOOL)

If forcedMovement = TRUE (default behavior) an actuator always performs this a complete movement cycle, which is as follows.

  • wait for start delay (if configured)
  • call all listeners with PreMoveMinus and PreMovePlus , respectively.
  • perform the actual movement with the configured timeouts, switch the output for the desired time
  • check if movement successed if the actuators has input (limit switches) available
  • call all listeners with PpostMoveMinus and PostMovePlus , respectively.
  • wait for end delay (if configured)

For actuators that do not have limit switches on both sides it is ofter desireable to switch to a less time consuming behavior once the machine has been brought to a defined state, e.g. after homing. By setting forced movement to FALSE most of the movement phases are skipped if the actuator is already in the right position (according to limit switches if available and a software status that ActuatorDigital keep track of interally. If forcedMovement = FALSE AND nominal position = actual position the movement phases are skipped.

Inputs

on BOOL

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

IsAtMinus 

METHOD IsAtMinus () : BOOL

Returns if the actuator is on its minus position. For checking the position the software status (stored at every movement) and (if available*) the hardware status (e.g. limit switches) are used.

Returns

BOOL

IsAtPlus 

METHOD IsAtPlus () : BOOL

Returns if the actuator is on its plus position. For checking the position the software status (stored at every movement) and (if available*) the hardware status (e.g. limit switches) are used.

Returns

BOOL

MoveMinusAsync 

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

Starts a movement of the actuator to its minus position. The startToken that can be optionally returned from the method is used to give an indication if the move command started or if any error occured. The Async suffix suggests that after initiating the call, the object will get busy and it should be waited for. In a sequence function block, the typical usecase is as follows.

IF step.OnEntry()
THEN
  actuators_.Cylinder1.MoveMinusAsync(THIS^);
END_IF

Await(actuators_.Cylinder1, <next step>);

It is possible to "override" an ongoing movement to direct the actuator into its opposite movement direction. Keep in mind that in this case the Post-Listener call for the current movement will not be exectued, while the Pre-Listener call for the new movement will be done.

Inputs

startToken IStartToken

(optional) object to check if the method was executed successfully - may be 0

MovePlusAsync 

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

Starts a movement of the actuator to its plus position. The startToken that can be optionally returned from the method is used to give an indication if the move command started or if any error occured. The Async suffix suggests that after initiating the call, the object will get busy and it should be waited for. In a sequence function block, the typical usecase is as follows.

IF step.OnEntry()
THEN
  actuators_.Cylinder1.MoveMinusAsync(THIS^);
END_IF

Await(actuators_.Cylinder1, <next step>);

It is possible to "override" an ongoing movement to direct the actuator into its opposite movement direction. Keep in mind that in this case the Post-Listener call for the current movement will not be exectued, while the Pre-Listener call for the new movement will be done.

Inputs

startToken IStartToken

(optional) object to check if the method was executed successfully - may be 0

Name 

METHOD Name (
 [output] movePlusName : ZCore.ZString,
 [output] moveMinusName : ZCore.ZString,
 [output] plusName : ZCore.ZString,
 [output] minusName : ZCore.ZString) : ZCore.ZString

Returns the names of all object that are used within this actuator and were set by calling [SetName](xref:ZEquipment.ActuatorDigital#SetName]. The names that are returned independently from the fact if an actuator actually has the appropriate digital I/Os or not.

This method should be used with care. It copies several strings and should be called rarely and that means of course not every cycle, but only at initialization phases.

Outputs

movePlusName ZString

Name of the digital output, which makes the actuator move into the plus direction

moveMinusName ZString

Name of the digital output, which makes the actuator move into the minus direction

plusName ZString

Name of the limit switch for the plus direction

minusName ZString

Name of the limit switch for the minus direction

Returns

ZString

SetDelay 

METHOD SetDelay (
 [input] plusStartDuration : LREAL,
 [input] plusEndDuration : LREAL,
 [input] minusStartDuration : LREAL,
 [input] minusEndDuration : LREAL,
 [input] stop : LREAL)

This method is used to configure delays (periods of waiting) for all movements that can be performed by the actuator. Delays are performed before performing any action (start delays) on DigitalOutputs, after performing checks (end delay) on DigitalInput and after stopping an action (stop delay).

Please note that for end delays no additional check after the delay are performed, e.g. if the DigitalInput(s) are still valid for the desired position.

Possible applications for delays may be, but not exclusively

  • start delay can be used in combination with another actuator to perform coupled movements
  • end delay can be used to let an actuator exceed a limit switch

Inputs

plusStartDuration LREAL

in seconds, defaults to 0s

plusEndDuration LREAL

in seconds, defaults to 0s

minusStartDuration LREAL

in seconds, defaults to 0s

minusEndDuration LREAL

in seconds, defaults to 0s

stop LREAL

in seconds, defaults to 1s

SetLogger 

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

Sets or removed (logger=0) a logger for the actuator and all Digital interfaces

Inputs

logger ILogger

interface of a logger instance or a logger decorator instance

SetMovementDuration 

METHOD SetMovementDuration (
 [input] plusDuration : LREAL,
 [input] minusDuration : LREAL)

Here the Duration which it takes the actuator to move from one side to another side can be defined. The durations that can be set with this method are only relevant if an actuator doesn't have limit switches on either side to wait for the actuator to finish its movement. If the software status shows that an actuator is already the correct position when starting a move command the duration is ignored. The later behavior can be overwritten by Enabling forced movement.

Note

If the actuator uses feedback inputs, the durations that are specified here, do not apply and are only used for simulation purposes. In the latter case, the actuator needs plusDuration and minusDuration +/- uncertainty duration until it gets Busy=FALSE

Inputs

plusDuration LREAL
minusDuration LREAL

SetName 

METHOD SetName (
 [input] name : ZCore.ZString,
 [input] movePlusName : ZCore.ZString,
 [input] moveMinusName : ZCore.ZString,
 [input] plusName : ZCore.ZString,
 [input] minusName : ZCore.ZString)

This method sets the name for the actuator and, if set, the IDigitals that are used by the actuator. The digital-input names, which are passed with this method, are used in the PositionAsString property, which can be used for online monitoring of the actuator.

Inputs

name ZString

Name of the actuator

movePlusName ZString

Name of the digital output, which makes the actuator move into the plus direction

moveMinusName ZString

Name of the digital output, which makes the actuator move into the minus direction

plusName ZString

Name of the limit switch for the plus direction

minusName ZString

Name of the limit switch for the minus direction

SetSimulation 

METHOD SetSimulation (
 [input] mode : ActuatorDigitalSimulation)

Enable or disable simulation for this actuator. This can be done on the fly also during execution of the PLC

Inputs

mode ActuatorDigitalSimulation

SetSimulationUncertainty 

METHOD SetSimulationUncertainty (
 [input] uncertainty : LREAL)

This simulation uncertainy parameter is used to introduce a bit more realism to movement durations if an actuators input is simulated.

Inputs

uncertainty LREAL

In percent (0-100) to control the jitter of the movement duration (1% means that that the simulated time is in the interval [MovementDuration*0.99, MovementDuration*1.01]

SetSwitchDuration 

METHOD SetSwitchDuration (
 [input] plusDuration : LREAL,
 [input] minusDuration : LREAL)

This method is used for actuators that only need a rising edge on a digital output to start a movement, rather than required to permanently enable the output. Most commonly this feature is used by pulse valves. For such valves it is recommended to parametrize the switch duration. The minimum duration that should be used is the cycle time of the PLC, however, most of the times the valves required longer periods in the order of 0.1s to register a rising edge.

Inputs

plusDuration LREAL

in seconds, usually ~0.1s

minusDuration LREAL

in seconds, usually ~0.1s

SetTimeout 

METHOD SetTimeout (
 [input] plusDuration : LREAL,
 [input] minusDuration : LREAL)

This method is used to specify to expected maximum duration it takes to move the actuator from minus to plus (plusDuration) and from plus to minus (minusDuration), respectively. If this time is exceed after starting a move command, the actuator switch into its fault state and [Error = TRUE)[xref:ZEquipment.ActuatorDigital#Error].

The main purpose of this method is to find out if the actuator is physically blocked and/or to find any infrastructure issue (e.g. no pressure to move the actuator due to a leak, ...).

For commissioning it is recommended to parametrize high values for the timeouts and then use the duration method together with the requirements of our application to specify a timeout that makes sense. If the durations are set to 0s, monitoring is deactivated.

Inputs

plusDuration LREAL

in seconds, defaults to 0s (deactivated)

minusDuration LREAL

in seconds, defaults to 0s (deactivated)

StopAsync 

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

Calling this method stops any kind of movement from the actuator as soon as possible The command overwrites ongoing position commands and disables the digital output(s) of the actuator. After disabling the digital outputs, the actuator will wait for the stop delay (see SetDelay) before the actuators transitions from the state Busy into Idle.

Note

If an ongoing task was started with an ExecutionToken as the token parameter (e.g. _actuator.ActuatorName.MoveMinusAsync(THIS^) in a Sequence), it gets informed (aborted), if not the same ExecutionToken is used here with this call.

Inputs

startToken IStartToken

(optional) object to check if the method was executed successfully - may be 0

TraceErrorStack 

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

This method is used internally when recording an error trace.

Inputs

trace IErrorTrace