EthercatMaster

Namespace

ZEquipment

Implements

IEthercatMaster

IObject

IBootable

IError

FUNCTION_BLOCK EthercatMaster IMPLEMENTS ZCore.IEthercatMaster, ZCore.IObject, ZCore.IBootable, ZCore.IError (
 [output] Diagnostics : ZCore.DiagnosticMessage)

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.

Outputs

Diagnostics DiagnosticMessage

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

Booted

PROPERTY Booted : BOOL

Property Value

BOOL

Busy

PROPERTY Busy : BOOL

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

Property Value

BOOL

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

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

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

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

Name

METHOD FINAL Name () : ZCore.ZString

This method returns the name that has been set with SetName

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

state EthercatMasterState

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

defaults to 16#F8FF

SetLink

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

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

Inputs

linkPtr ZPointer

SetLogger

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

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

Inputs

logger ILogger

interface to a Zeugwerk Framework compatible logger instance

SetName

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

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

Inputs

name ZString

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

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

in seconds

SetTimeout

METHOD SetTimeout (
 [input] timeout : LREAL)

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

Inputs

timeout LREAL

in seconds

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

InOuts

slaveDescription EthercatSlaveDesc

TraceErrorStack

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

This method is used internally when recording an error trace.

Inputs

trace IErrorTrace