Table of Contents

EthercatSlave

Namespace
ZEquipment
Implements

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

  • 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 identity and (optional) set an initial state for the slave device. 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 if the requested state (FB_init (optional) or RequestStateAsync) differs from the actual state of the device. If it differs, it transitions for at least 1 cycle to an Error state that can be polled externally. Also, the object automatically reads the mailbox of the Ethercat Slave device and append its content to its ErrorMessage.
  • 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 EthercatSlave IMPLEMENTS ZCore.IEthercatSlave, ZCore.IObject, ZCore.IBootable, ZCore.IError

Outputs

Diagnostics DiagnosticMessage

Constructor

FB_init

When constructing this object an optional initial state of the EtherCAT slave device can be provided. If initialState <> 0, the object tries to set the appropriate state during the Booting phase of the object.

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

initialState EthercatSlaveState

(optional) State that is set during boot, set to 0 if the default settings should be used

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 slave 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 the slave 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 state of the EtherCAT slave device in a flags enum. This means that several bits of the returned value can be on or off at once. If simulated, the returned value is always the requested state that is set either in FB_init or with RequestStateAsync).

METHOD EthercatStateFlags () : ZCore.EthercatSlaveStateFlags

Returns

EthercatSlaveStateFlags

Retrieves the platform specific data pointer to ethercat slave communication. This method is highly platform dependent, refer to ZPlatform.EthercatSlaveImpl.

METHOD Link () : ZCore.ZPointer

Returns

ZPointer

Name

This method returns the name that has been passed with the SetName method concatenated with the string '| EthercatSlave' and the identifier of the object. The later is obtained in the booting sequence when reading the EtherCAT slave device's identity. If simulated, the identifier 'Simulated' is used.

ethercatSlave.SetSimulated(FALSE);
ethercatSlave.SetName('Slave1');
ethercatSlave.Name(); // returns 'Slave1 | EthercatSlave (Simulated) '

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

METHOD FINAL Name () : ZCore.ZString

Returns

ZString

RequestStateAsync

Use this method to switch the ethercat slave device into any 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. EthercatSlaveImpl can only perform 1 task at a given time, this includes booting. If a special state should be set during booting, please use the parameter in FB_init.

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

Inputs

startToken IStartToken

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

state EthercatSlaveState

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

METHOD SetLogger (
 logger : ZCore.ILogger)

Inputs

logger ILogger

interface to a Zeugwerk Framework compatible logger instance

SetName

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

METHOD SetName (
 name : ZCore.ZString)

Inputs

name ZString

SetSimulation

This method can be used at any time to switch the ethercat slave 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 the slave is in BootingError.

METHOD SetSimulation (
 on : BOOL)

Inputs

on BOOL

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

TraceErrorStack

This method is used internally when recording an error trace.

METHOD TraceErrorStack (
 trace : ZCore.IErrorTrace)

Inputs

trace IErrorTrace

WcState

The method returns the state of the working counter for the ethercat slave device whose Process Data Objects are mapped to this instance. It is an easy way to find out if data is sent and received correctly to the device. If any error occurs, this objects additionally transitions into its error state (for at least 1 cycle) and ErrorMessage can be used to retrieve informations about the error.

METHOD WcState () : BOOL

Returns

BOOL