Table of Contents

ParameterChannelScpUM

Namespace
ZAux
Implements
FUNCTION_BLOCK ParameterChannelScpUM IMPLEMENTS ZCore.IParameterChannel, ZCore.IUnmanagedObject, ZCore.IObject, ZCore.IError

This ParameterChannel implementation allows to read and write parameters of EtherCAT devices that use the Servodrive over Ethercat (short SoE) protocol.

SoE distinguishes two types of parameters, which are enumerated in ParameterChannelScparameterElement

  1. S parameters which are defined and standardized for all manufacturers.
  2. P parameters which are not standardized, but are defined by the vendor of a SoE device. A SoE parameter is often referred to as IDN (identification number). However, the IDN is only one of multiple data block elements (DBE) constituting a SoE parameter, which is in total made up of the following elements.
  • The IDN contains information such as structure instance (SI), structure element (SE), P, OR S parameter.
  • Name (up TO 240 bytes)
  • The attribute contains information on write protection, decimal places, data TYPE, AND display format, procedure command, data length.
  • Unit
  • Minimum value
  • Maximum value
  • Operation data: This can contain a value or also, a list with IDNs for a procedure command.

Even though a single SoE parameter has multiple elements, in the Zeugwerk Framework every single one of those elements is regarded as a distinctive parameter. This, for instance, means that reading the operation data with a specific IDN is 1 request and reading the Minimum Value is also 1 separate request.

Use this function block to request Read and Write on certain parameters by using the RequestAsync. Such a request causes this function block to transition into its Busy in which it will stay until the operation is successful or failed, respectively. In constrast to most other implementations of the Object interface, parameter requests are not blocking. This means that calls to RequestAsync can be called consecutively - most other objects in the framework would not allow two consecutive calls to an "Async" method.

Constructor

FB_init 

METHOD FB_init (
 [input] bInitRetains : BOOL,
 [input] bInCopyCode : BOOL,
 [input] ethercatSlave : ZCore.IEthercatSlave) : BOOL

When constructing this object an EthercatSlave interface can be supplied, which parameter requests of this object are performed with. It is ok, and sometime useful, to initialize the object without an ethercat-slave interface. In this case, the interface may be set by using SetEthercatSlave.

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)

ethercatSlave IEthercatSlave

optional, this can also be set at a later point via SetEthercatSlave

Returns

BOOL

Properties

Busy 

PROPERTY Busy : BOOL

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

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 Value

BOOL

Methods

Cyclic 

METHOD Cyclic ()

This method should be called every cycle to enable this class to operate. The method returns immediately if no task of the function block has been started (i.g. RequestAsync.

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

RequestAsync 

METHOD RequestAsync (
 [input] taskToken : ZCore.ITaskToken,
 [input] actionFlags : ZCore.ParameterChannelActionFlag,
 [input] parameter1 : DWORD,
 [input] parameter2 : DWORD,
 [input] parameterType : INT,
 [input] bufferPtr : ZCore.ZPointer,
 [input] bufferSize : UDINT)

Depending on the chosen actionFlag this method starts a Read or Write request on a SoE parameter. The parameter should be the IDN of this specific Ethercat Device. The parameter for S-Parameters should be in the range (0-32767, 16#0000 - 16#7FFF) and P-Parameters are considered in the range (32768-65535, 16#8000 - 16#FFFF). This means that P-0-0001 corresponds to parameter:=16#8001

// Example on how to read S-0-0138 (16#008A) - 4Byte - bipolar acceleration limit value from a drive in use
_parameterChannel.RequestAsync(taskToken:=tasktoken,
                               actionFlags:=ZCore.ParameterChannelActionFlag.Read,
                               parameter1:=16#008A, parameterType:=ZCore.ParameterChannelScpParameterType.Long, parameter2:=ZCore.ParameterChannelScpParameterElement.Value,
                               bufferPtr:=ADR(value), buffersize:=SIZEOF(value));
// Example on how to read P-0-0118 (16#8076) - 2Byte - power supply, configuration value from a drive in use
_parameterChannel.RequestAsync(taskToken:=tasktoken,
                               actionFlags:=ZCore.ParameterChannelActionFlag.Read,
                               parameter1:=16#8076, parameterType:=ZCore.ParameterChannelScpParameterType.Word16, parameter2:=ZCore.ParameterChannelScpParameterElement.Value,
                               bufferPtr:=ADR(value), buffersize:=SIZEOF(value));

Since requests are buffered internally when using this method, calls to the method can be directly chained. However, when there are too many open requests (more than ParameterList.ParameterChannelBuffersize) the instance will abort with an error.

Warning

If any request fails, all remaining requests are cleared from the internal buffer as well.

Inputs

taskToken ITaskToken
actionFlags ParameterChannelActionFlag

actions to be performed for the following parameter. This is a flag parameter (several actions are possible)

parameter1 DWORD

S-Parameter [0-32767, 16#0000 - 16#7FFF] or P-Parameter [32768-65535, 16#8000 - 16#FFFF]

parameter2 DWORD

see ParameterChannelScpParameterElement

parameterType INT

see ParameterChannelScpParameterType

bufferPtr ZPointer

POINTER to the location this method writes to or reads from

bufferSize UDINT

Size of the location buffer is pointing to

SetEthercatSlave 

METHOD FINAL SetEthercatSlave (
 [input] ethercatSlave : ZCore.IEthercatSlave)

This method allows to overwrite the EtherCAT device (i.e. EtherCAT Slave) that this ParameterChannel is communicating with when reading or writing parameters.

Calling this method while this object is Busy (e.g. due to calling RequestAsync) the pending requests are aborted with an Error.

Inputs

ethercatSlave IEthercatSlave

Interface to an externally instantiated EthercatSlave Instance

SetLogger 

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

Use this function to enable logging for this parameter channel instance. If logging is enabled, every parameter request (Read and Write) is written to the logger.

If no Logging Instance is given here (logger=0), logging is generally deactivated.

Inputs

logger ILogger

SetName 

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

This method can be used to give a name to the parameter channel instance, which is useful if logging is used.

Inputs

name ZString

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

SetTimeout 

METHOD SetTimeout (
 [input] timeout : LREAL)

Sets the timeout values for communicating with the EtherCAT slave controller. If reading or writing takes longer than this timeout, 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. Especially for fieldbus configurations with many Ethercat slave controllers this timeout should be increased to avoid running into it.

Inputs

timeout LREAL

Timeout as LREAL variable in seconds

TraceErrorStack 

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

This method is used internally when recording an error trace.

Inputs

trace IErrorTrace