Table of Contents

EthercatMasterImpl

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

The function block implements the most common commands that are needed by a developer when communicating with an EtherCAT master.

  • The object contains variables that have to be linked to Process Data Objects (PDO) and will fail if PDOs are not linked correctly
  • When starting, this function block is in its Booting state. Here, the object tries to gather information about the slave devices that are connected to the master. It scans the available slave devices and also gathers information about the slave devices that have been configured during engineering. If this is not possible or fails for any reason (e.g. incorrect linking, the device is not connected, ...) the object transitions into BootingError. If everything is ok, the object transitions into its Idle state.
  • While the object is idle, it continously monitors the DevState (EthercatMasterStateFlags) and checks if an error is reported by the Ethercat master device. If the device is in a state that is not masked out the objects transitions to the Error state for at least 1 cycle. The error state can be polled with Error externally.
  • In the Idle state the object performs several synchronization calls. The period of this sychronization can be adjusted or the feature be disabled with SetSynchronizationPeriod. Synchronization includes
    • Fetching the master statistic that contains information about missed frames, etc.
    • Fetch the state of all slaves that are connected to the busmaster. Information about connected slaves can be obtained with SlaveDescription and SlaveCount.
  • While in idle state, the object accepts external state requests by calls to RequestStateAsync.

This implementation is a wrapper around the following TwinCAT function blocks.

By extending from PlatformAdapterObject error codes that are returned by the beckhoffs function blocks are returned nicely as strings and follow Beckhoff's specification in regard to error codes.

Note that this object comes with an initial booting phase that requires some cycles to execute. So initially this object is busy and to be more specific the object is in its Booting state when creating this object.

Constructor

FB_init 

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

At construction time the EthercatMaster needs an Object manager in order to function properly. This object is given by setting a proper parent when instantiating this object.

The default settings of an Ethercat Master are:

  • setting the object to booting
  • setting the error mask in a way that the ethercat master does not transition into error if a slave is in preop, init or safeop
  • setting the timeout to the ParameterList.DefaultEthercatMasterTimeout

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

Returns

BOOL

Properties

BootingHints 

PROPERTY BootingHints : ZCore.ManagedObjectBootingHintFlags

Property Value

ManagedObjectBootingHintFlags

Simulation 

PROPERTY Simulation : BOOL

This property can be used at any time to switch the ethercat master from simulated mode to physical mode. Whenever the nominal flag changes, the instance will get busy and run its Booting sequence. This even works if this object is in BootingError.

Property Value

BOOL

Methods

Cyclic 

METHOD Cyclic ()

This method should be called every cycle to enable this class to operate. For details see EthercatMasterImpl.

EthercatStateDecoded 

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

This method converts the dev state (ZCore.EthercatMasterStateFlags) of an EtherCAT master device to a human readable text.

 EthercatStateDecoded(16#0101); // returns 'Link error; Out of send resources (I/O reset required); '
 EthercatStateDecoded(ZCore.EthercatSlaveStateFlags.AtLeastOneDeviceInPreopState); // returns 'At least one device in PREOP state; '

Inputs

state WORD

dev state of the instantiated ethercat master

Returns

ZString

EthercatStateFlags 

METHOD EthercatStateFlags () : ZCore.EthercatMasterStateFlags

This method returns the EthercatMasterStateFlags which is present as cyclic data in the variable DevState. These error flags can also be decoded to human readable flags bei providing the output of this method EthercatStateDecoded.

Returns

EthercatMasterStateFlags

MasterStatistic 

METHOD MasterStatistic (
 [inout] statistic : ZCore.EthercatMasterStatistic)

This method returns some statistical data about the ethercat master device that is linked to this object. The information is polled automatically when the object is in its Idle state with the period that can be set with SetSynchronizationPeriod.

InOuts

statistic EthercatMasterStatistic

reference to the statistic information stored inside this instantiated ethercat master

Name 

METHOD Name () : ZCore.ZString

This method returns the name that has been passed with the SetName method. The name is added to every logmessage which is communicated by this object and is usefull if a PLC has more than one Ethercat Master instantiated and running.

Returns

ZString

RequestStateAsync 

METHOD RequestStateAsync (
 [input] startToken : ZCore.IStartToken,
 [input] state : ZCore.EthercatMasterState)

Use this method to switch the ethercat master device into any possible state. If the object is busy while the method is called, the startToken that is passed will inform about this and the actual request will not be performed. EthercatMasterImpl can only perform 1 task at a given time, this includes booting.

Inputs

startToken IStartToken

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

state EthercatMasterState

provided ethercat master state to which the transition has to be done

SetErrorMask 

METHOD FINAL SetErrorMask (
 [input] mask : WORD)

When this object is in its Idle state, the DevState of the Ethercat master device is continously polled for error bits. If any bit is active, the object transitions into its error state of 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 devstate's bit. 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 set to 16#F8FF = NOT (ZCore.EthercatMasterStateFlags.AtLeastOneDeviceInInitState OR ZCore.EthercatMasterStateFlags.AtLeastOneDeviceInPreopState OR ZCore.EthercatMasterStateFlags.AtLeastOneDeviceInSafeOpState)

METHOD SetLink (
 [input] linkPtr : ZCore.ZPointer)

Calling this method in TwinCAT has no effect, in- and output variables of the object is directly linked in the IDE.

Inputs

linkPtr ZPointer

Pointer to an external link variable -> not used on Twincat systems

SetLogger 

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

Use this function to enable logging for this EthercatMasterImpl instance. If no Logging instance is given here (logger=0), logging is automatically deactivated.

Inputs

logger ILogger

interface to a Zeugwerk compatible logger instance

SetSimulation 

METHOD SetSimulation (
 [input] on : BOOL)

This method can be used at any time to switch the ethercat master from simulated mode to physical mode. Whenever the nominal flag changes, the instance will get busy and run its Booting sequence. This even works if this object is in BootingError.

Inputs

on BOOL

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

SetSynchronizationPeriod 

METHOD SetSynchronizationPeriod (
 [input] timeout : LREAL)

Set the timeout when the ethercat master should start polling

  • Statistical data that is cached internally and can be retrieved by the MasterStatistic method.
  • Slave information that is cached internally and and can be retrieved by the SlaveDescription method. Use timeout = 0 to disable synchronization. It is recommended to set the synchronization timeout in the range of several seconds and it defaults to 10 seconds.

Inputs

timeout LREAL

timeout for internal manufacturers function block actions in seconds

SetTimeout 

METHOD FINAL SetTimeout (
 [input] timeout : LREAL)

Sets the timeout values for communicating with the EtherCAT master device that is linked to this object. If any command takes longer than this timeout to execute, an error will be thrown and can be signaled with Error. If no user specific timeout is set, the default timeout set in DefaultTimeout is used.

Inputs

timeout LREAL

in seconds, default is ParameterList.DefaultEthercatMasterTimeout

SlaveCount 

METHOD SlaveCount () : INT

This method returns the count of slaves that have been configured on the ethercat master device that is linked to this object. The value that is returned here can be used together with SlaveDescription to externally poll informations about ethercat slave devices that are connected to the busmaster.

The information is polled automatically when the object is in its Idle state with the period that can be set with SetSynchronizationPeriod.

Returns

INT

SlaveDescription 

METHOD SlaveDescription (
 [input] slaveNo : INT,
 [inout] slaveDescription : ZCore.EthercatSlaveDesc)

This method returns information about slaves that have been configured to the ethercat master device that is linked to this object. The method should be used together with SlaveCount to externally poll informations about ethercat slave devices that are connected to the busmaster.

The information is polled automatically when the object is in its Idle state with the period that can be set with SetSynchronizationPeriod.

Inputs

slaveNo INT

slave number of the ethercat slave of which the description should be provided starting bei 0 and going to SlaveCount

InOuts

slaveDescription EthercatSlaveDesc

reference to the according slave description of the slave number provided on var_input