Table of Contents

EthercatSyncUnit

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

The EthercatSyncUnit function block is mainly used to observe a group of ethercat slaves on the fieldbus which are grouped together in a syncunit. There are several usecases why one wants to group ethercat slaves

  • some slaves have to be independently from others and there is a need to turn off the power while others are running
  • maybe some devices have to run at a slower framerate/cycle time on the fieldbus
  • if there is an error on the fieldbus for example on cables which are guided through cable carriers this should not affect other ethercat slaves which are placed in the control cabinet

This function block gives access to the syncunits WcState, SlaveCount and even counts how often a fault happened. It also provides a trigger on a frame fault or frame recovered event. Last but not least it is also possible to fetch errors on the frame which are encoded in the syncunits State variable.

In booting phase of the application, this function block also observes (if parameterized), if the syncunit reaches its expected state (OP, SAFEOP,...) in a given timeout otherwise booting will result in an error BootingError.

Outputs

Diagnostics DiagnosticMessage

Constructor

FB_init 

METHOD FB_init (
 [input] bInitRetains : BOOL,
 [input] bInCopyCode : BOOL,
 [input] parent : ZCore.IManagedObject,
 [input] expectedState : ZCore.EthercatSyncUnitState) : BOOL

Inputs

bInitRetains BOOL
bInCopyCode BOOL
parent IManagedObject

Interface to the ManagedObject that is the parent of this object

expectedState EthercatSyncUnitState

Finish booting after Ethercat syncunit reaches expected state within a given timeout, if set to 0 the object doesn't wait for a specific state

Returns

BOOL

Properties

Booted 

PROPERTY Booted : BOOL

Property Value

BOOL

Busy 

PROPERTY Busy : BOOL

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

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 Value

BOOL

Simulation 

PROPERTY Simulation : BOOL

This property should be used in initialization phase to switch the ethercat syncunit from simulation mode to physical mode.

Property Value

BOOL

Methods

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

EthercatStateFlags 

METHOD EthercatStateFlags () : ZCore.EthercatSyncUnitStateFlags

The state variable in the InfoData item of an ethercat sync unit indicates the EtherCAT status of itself. In addition, the variable provides general information about the sync unit, for example it shows whether one of the configured slaves in this particular sync unit is not present or no communication is running. For more information on those error flags read the documentation here.

Returns

EthercatSyncUnitStateFlags

FrameFaultRecovered 

METHOD FrameFaultRecovered () : ZCore.ITrigger

This method returns an interface to an internally held Trigger function block. If the frame has recovered (WcState = 0) from a previously occured fault (WcState = 1) the returned HasTriggered() method of this interface, will return TRUE for exactly one cycle. This can be used to react in your application

IF _mySyncUnit.FrameFaultRecovered().HasTriggered() THEN
THEN
  _logger.Info('WcState = 0');
  // do something else if WcState change to 0 gets triggered
END_IF

Returns

ITrigger

FrameFaultTrigger 

METHOD FrameFaultTrigger () : ZCore.ITrigger

This method returns an interface to an internally held Trigger function block. If the frame is invalid (WcState = 1) and was previously valid (WcState = 0) the returned HasTriggered() method of this interface, will return TRUE for exactly one cycle. This can be used to react in your application

IF _mySyncUnit.FrameFaultTriggered().HasTriggered() THEN
THEN
  _logger.Info('WcState = 1');
  // do something else if WcState change to 1 gets triggered
END_IF

Returns

ITrigger

IsFrameOk 

METHOD IsFrameOk () : BOOL

This method returns TRUE if WcState is 0 otherwise FALSE

Returns

BOOL

Name 

METHOD FINAL Name () : ZCore.ZString

This method returns the name that has been passed with the SetName method concatenated with the string '| EthercatSyncUnit' and the identifier of the object. If simulated, the identifier 'Simulated' is used.

ethercatSyncUnit.SetSimulated(FALSE);
ethercatSyncUnit.SetName('SyncUnit1');
ethercatSyncUnit.Name(); // returns 'SyncUnit1 | EthercatSyncUnit (Simulated) '

The name that is passed here is considered when logging is activated.

Returns

ZString

SetErrorMask 

METHOD FINAL SetErrorMask (
 [input] mask : WORD)

When this object is in its Idle state, the Error bits of the sync units State variable is continously polled. If any bit is active, the object transitions into its error state for at least 1 cycle and stays there until the error is resolved. The mask that is passed with this method can be used to mask out some of the error bits. While booting, it is common to set individual states to PREOP, perform parametrization and then set the state to OP again. This is the reason why the default mask is set in a way to not trigger errors for this cases. The actual mask that should be used to detect "actual" errors are application specific and sometime even sequence specific.

Inputs

mask WORD

default is (NOT (ZCore.EthercatSyncUnitStateFlags.Init OR ZCore.EthercatSyncUnitStateFlags.PreOp OR ZCore.EthercatSyncUnitStateFlags.SafeOp OR ZCore.EthercatSyncUnitStateFlags.Op)

SetLogger 

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

This method sets or removes (logger=0) a logger for the EthercatSyncUnit.

Inputs

logger ILogger

interface to a Zeugwerk Framework compatible logger instance

SetName 

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

This method can be used to give a name to the EthercatSyncUnit instance, which is useful if logging is used. Note that the name that is passed is prefixed with ' | EthercatSyncUnit'. Also the getter Name appends more details to this instance (i.e. the ethercat syncunit device's identifier).

Inputs

name ZString

Name of the EthercatSyncUnit Instance, usually the name of the syncunit itself

SetSimulation 

METHOD SetSimulation (
 [input] on : BOOL)

This method should be used in initialization phase to switch the ethercat syncunit from simulation mode to physical mode.

Inputs

on BOOL

Set to TRUE to turn on Simulation for Ethercat SyncUnit, FALSE to work in physical mode

SetTimeout 

METHOD FINAL SetTimeout (
 [input] timeout : LREAL)

Sets the timeout which triggers an error if the sync unit state does not transition into its expected state, the timeout is used in the Booting phase of this object. If the expected state is not reaching within the timeout, the object transitions into BootingError. Use timeout=0 to disable the timeout and keep the object waiting forever. Timeout defaults to ParameterList.DefaultEthercatMasterTimeout.

Inputs

timeout LREAL

timeout in seconds to transition into final state (e.g. OP, PREOP, SAFEOP,...)

SlaveCount 

METHOD SlaveCount () : UINT

Returns how many slaves are connected to the master and further on configured to this syncunit

Returns

UINT

SyncUnitStatistic 

METHOD SyncUnitStatistic (
 [inout] statistic : ZCore.EthercatSyncUnitStatistic)

Returns the actual statistics of this SyncUnit which includes WcState toggle counting, the time until wcstate recovered again to 0 and the time until an error bit recovered from an indicated error

InOuts

statistic EthercatSyncUnitStatistic

TraceErrorStack 

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

This method is used internally when recording an error trace.

Inputs

trace IErrorTrace

WcState 

METHOD WcState () : BOOL

Returns the actual state of cyclically updated WcState if it is linked to a SyncUnit on the Ethercat fieldbus If it returns FALSE the ethercat communication was valid in the last cycle If it returns TRUE the ethercat communication was invalid A WcState with value 1 will not lead to a transition into BootingError of the EthercatSyncUnit function block because this could also be expected behaviour.

Returns

BOOL