Table of Contents

ParameterChannelCanUM

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

This ParameterChannel implementation allows to read and write parameters of EtherCAT devices that use the CANopen protocol over Ethercat.

CANopen devices have several application profiles like (CiA402, Cia406, ...) and the parameters are defined in an object dictionary, which is used for configuration and communication with the device. These objects are refered to as "Parameters" in the Zeugwerk Framework, because similar protocols use different names for these type of objects, but in all protocols they are used for parametrization of the different functions and features.

An entry in the object dictionary (i.e. parameters) in CANopen is defined by:

  • Index: the 16-bit address of the object in the dictionary
  • Object name (Object TYPE/Size): a symbolic TYPE OF the object in the entry, such as an ARRAY, record, OR simple variable
  • Name: a string describing the entry
  • Type: gives the datatype of the variable (or the datatype of all variables of an array)
  • Attribute: gives information on the access rights for this entry, this can be read/write, read-only or write-only and also if they can be accessed in PDOs (cyclically) or just over SDO Channel
  • The Mandatory/Optional field (M/O) defines whether a device conforming to the device specification has to implement this object or not
  • The basic datatypes for object dictionary values such as booleans, integers and floats are defined in the standard (their size in bits is optionally stored in the related type definition, index range 0x0001–0x001F), as well as composite datatypes such as strings, arrays and records (defined in index range 0x0040–0x025F). The composite datatypes can be subindexed with an 8-bit index; the value in subindex 0 of an array or record indicates the number of elements in the data structure, and is of type UNSIGNED8.

Use this function block to request Read and Write on certain parameters by using the RequestAsync method. Such a request causes this function block to transition into its Busy in which it will stay until the operation is successful or has 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

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

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 (e.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 CANopen object. According to the CANopen protocol, individual parameters are identified by an index and a subindex. The ParameterChannel interface specifies only a single identifier for parameter and so, this particular implementation chains index and subindex together in parameter. Please note, that subindex in the TwinCAT context are decimal values while the index is usually given in Hex. Since parameter1 is only 1 value, index and subindex are encoded in the same way. (e.g. for the object with index=6089 and subindex=10, the value should be parameter1=16#60890A).

// Example on how to read standard parameter 6073h (16#00607300) max current of a drive in use
_parameterChannel.RequestAsync(taskToken:=tasktoken,
                               actionFlags:=ZCore.ParameterChannelActionFlag.Read,
                               parameter1:=16#607300, parameterType:=ZCore.ParameterChannelCanParameterType.Uint16, parameter2:=0,
                               bufferPtr:=ADR(value), buffersize:=SIZEOF(value));
// Example on how to read standard parameter 607Bh (16#00607B01) Position Range Limit with Subindex 1 - Min Position Range Limit
_parameterChannel.RequestAsync(taskToken:=tasktoken,
                               actionFlags:=ZCore.ParameterChannelActionFlag.Read,
                               parameter1:=16#607B01, parameterType:=ZCore.ParameterChannelCanParameterType.Int32, parameter2:=0,
                               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 flags parameter (several actions are possible)

parameter1 DWORD

index:=16#6088, subindex:=01 -> 16#608801; index:=16#607F, subindex:=12 -> 16#607F0B; index:=16#8001 subindex:=0 -> 16#800100

parameter2 DWORD

unused for CANopen objects

parameterType INT

see ZCore.ParameterChannelCanParameterType

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