Table of Contents

EthercatSlave

Namespace
ZEquipment
Implements
FUNCTION_BLOCK EthercatSlave IMPLEMENTS ZCore.IEthercatSlave, ZCore.IObject, ZCore.IBootable, ZCore.IError (
 [output] Diagnostics : ZCore.DiagnosticMessage)

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.

Outputs

Diagnostics DiagnosticMessage

Constructor

FB_init 

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

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.

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 

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

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

Returns

EthercatSlaveStateFlags
METHOD Link () : ZCore.ZPointer

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

Returns

ZPointer

Name 

METHOD FINAL Name () : ZCore.ZString

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.

Returns

ZString

RequestStateAsync 

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

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.

Inputs

startToken IStartToken

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

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

Inputs

logger ILogger

interface to a Zeugwerk Framework compatible logger instance

SetName 

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

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

Inputs

name ZString

SetSimulation 

METHOD SetSimulation (
 [input] on : BOOL)

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.

Inputs

on BOOL

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

TraceErrorStack 

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

This method is used internally when recording an error trace.

Inputs

trace IErrorTrace

WcState 

METHOD WcState () : BOOL

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.

Returns

BOOL