Table of Contents

EthercatMaster

Namespace
ZEquipment
Implements

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

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

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.

FUNCTION_BLOCK EthercatMaster IMPLEMENTS ZCore.IEthercatMaster, ZCore.IObject, ZCore.IBootable, ZCore.IError

Outputs

Diagnostics DiagnosticMessage

Constructor

FB_init

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
METHOD FB_init (
 bInitRetains : BOOL,
 bInCopyCode : BOOL,
 parent : ZCore.IManagedObject) : BOOL

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

Booted 

PROPERTY Booted : BOOL

Property Value

BOOL

Busy

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 Busy : BOOL

Property Value

BOOL

Done

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 Done : BOOL

Property Value

BOOL

Error

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 Error : BOOL

Property Value

BOOL

Simulation

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 Simulation : BOOL

Property Value

BOOL

Methods

ErrorId

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.

METHOD ErrorId () : UDINT

Returns

UDINT

ErrorMessage

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.

METHOD ErrorMessage () : ZCore.ZString

Returns

ZString

ErrorSource

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.

METHOD ErrorSource () : ZCore.IError

Returns

IError

EthercatStateFlags

This method returns the EthercatMasterStateFlags which is present as cyclic data in the variable DevState.

METHOD EthercatStateFlags () : ZCore.EthercatMasterStateFlags

Returns

EthercatMasterStateFlags

MasterStatistic

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.

METHOD MasterStatistic (
 statistic : ZCore.EthercatMasterStatistic)

Inouts

statistic EthercatMasterStatistic

Name

This method returns the name that has been set with SetName

METHOD FINAL Name () : ZCore.ZString

Returns

ZString

RequestStateAsync

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.

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

Inputs

startToken IStartToken

state EthercatMasterState

SetErrorMask

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.

METHOD FINAL SetErrorMask (
 mask : WORD)

Inputs

mask WORD

defaults to 16#F8FF

Set the platform specific data pointer to ethercat slave communication. This method is highly platform dependent, refer to the platform implementation.

METHOD SetLink (
 linkPtr : ZCore.ZPointer)

Inputs

linkPtr ZPointer

SetLogger

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

METHOD SetLogger (
 logger : ZCore.ILogger)

Inputs

logger ILogger

interface to a Zeugwerk Framework compatible logger instance

SetName

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

METHOD SetName (
 name : ZCore.ZString)

Inputs

name ZString

SetSimulation

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.

METHOD SetSimulation (
 on : BOOL)

Inputs

on BOOL

SetSynchronizationPeriod

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.
METHOD SetSynchronizationPeriod (
 timeout : LREAL)

Inputs

timeout LREAL

in seconds

SetTimeout

Controls the timeout when communicating asynchronously with ethercat slave devices. This method is highly platform dependent, refer to the platform implementation.

METHOD SetTimeout (
 timeout : LREAL)

Inputs

timeout LREAL

in seconds

SlaveCount

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.

METHOD SlaveCount () : INT

Returns

INT

SlaveDescription

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.

METHOD SlaveDescription (
 slaveNo : INT,
 slaveDescription : ZCore.EthercatSlaveDesc)

Inputs

slaveNo INT

Inouts

slaveDescription EthercatSlaveDesc

TraceErrorStack

This method is used internally when recording an error trace.

METHOD TraceErrorStack (
 trace : ZCore.IErrorTrace)

Inputs

trace IErrorTrace