Table of Contents

EthercatSlaveImpl

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

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.

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

By extending from PlatformAdapterObject error codes that are returned by these 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,
 [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

BootingHints 

PROPERTY BootingHints : ZCore.ManagedObjectBootingHintFlags

Suggests when the Cyclic method should be called during the booting phase of the application

It is best to call the cyclic method of this object in every PLC cycle so monitoring works even during booting

Property Value

ManagedObjectBootingHintFlags

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

Cyclic 

METHOD Cyclic ()

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

EthercatStateDecoded 

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

This method converts the dev and link state of an EtherCAT slave device to human readable text. The Ethercat State Flags can be retrieved by calling the EthercatSateFlags method.

 EthercatStateDecoded(16#0101); // return 'INIT; Slave not present;'
 EthercatStateDecoded(ZCore.EthercatSlaveStateFlags.PreOp OR ZCore.EthercatSlaveStateFlags.InitializationCommandsError); // return 'PREOP; Initialization error occurred; '

Inputs

state WORD

ethercat state of the ehtercat slave represented by this function block

Returns

ZString

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

This method returns a pointer to the internal EthercatSlaveInput datatype that is linked to Process Data Objects (PDOs). The method returns a pointer that requires implicit knowledge of the underlying data structure! This is required for providing a platform-independent solution. For instance, TwinCAT and Codesys, while similar, do not share the same workflow when linking to PDOs.

Returns

ZPointer

Name 

METHOD 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

requested ethercat state in which this function block should switch to

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 EthercatSlaveImpl instance. If no Logging Instance is given here (logger=0), logging is deactivated.

Inputs

logger ILogger

interface to a Zeugwerk 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

Name of the EthercatSlave Instance, usually the name of the device which is connected on the Ethercat fieldbus

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

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

SetTimeout 

METHOD FINAL SetTimeout (
 [input] timeout : LREAL)

Sets the timeout values for communicating with the EtherCAT slave device. 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.DefaultEthercatSlaveTimeout

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