Table of Contents

EthercatSyncUnitImpl

Namespace
ZPlatform
Extends
Inherited Properties
Inherited Methods
Implements
FUNCTION_BLOCK EthercatSyncUnitImpl EXTENDS ZPlatform.PlatformAdapterManagedObject IMPLEMENTS ZCore.IManagedObject, ZCore.IBootable, ZCore.IObject, ZCore.IError (
 [output] State : ObjectState)

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.

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

BootingHints 

PROPERTY BootingHints : ZCore.ManagedObjectBootingHintFlags

Suggests when the Cyclic method should be called during the booting phase of the application

It is best to call the cyclic method of this object in every PLC cycle so monitoring works even during booting

Property Value

ManagedObjectBootingHintFlags

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

Cyclic 

METHOD Cyclic ()

Cyclic behavior of this function block is only given to check if the WcState variable gets one which indicates that there was an invalid frame received or transmitted and vice versa.

EthercatStateDecoded 

METHOD EthercatStateDecoded (
 [input] state : WORD) : ZCore.ZString

This method converts the link state of an EtherCAT sync unit to human readable text. The Ethercat State Flags can be retrieved by calling the EthercatSateFlags method.

 EthercatStateDecoded(16#0101); // return 'INIT; Slave not present;'
 EthercatStateDecoded(ZCore.EthercatSyncUnitStateFlags.PreOp OR ZCore.EthercatSyncUnitStateFlags.InitializationCommandsError); // return 'PREOP; Initialization error occurred; '

Inputs

state WORD

ethercat state of the ethercat sync unit represented by this function block

Returns

ZString

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

ObserveFieldbus 

METHOD PROTECTED ObserveFieldbus ()

observe routines for WcState of sync unit.

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

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