Table of Contents

Analog

Namespace
ZEquipment
Implements
FUNCTION_BLOCK ABSTRACT Analog IMPLEMENTS ZEquipment.IAnalog, ZEquipment.IDigital, ZCore.ITrigger

This function block represents a single analog IO, which can either be simulated (default) or linked to an actual IO on a terminal.

When constructing an instance of Analog (i.e. AnalogInputUdint) the resolution of the terminal that is used and its sign flag has to be specified. For converting the value that is given by the terminal into a physical unit, this function block implements a convienently SetConversionLinear.

Inputs and outputs are implemented by seperate FBs AnalogInputX or AnalogOutputX, because their behavior when using simulation and their physical link target differ. When inputs are not simulated, writing to the instance won't do anything (on purpose), because writing to an input is impossible. However, when such AnalogInputs are simulated writing is supported for the purpose of simulating the physical input.

Note

By default instances are simulated. In order to make use of a physical terminal, the method SetSimulation(on:=FALSE) has to be called.

Properties

DecimalPlaces 

PROPERTY DecimalPlaces : INT

Property Value

INT

Enabled 

PROPERTY Enabled : BOOL

see SetDigitalThreshold and Enabled.

Property Value

BOOL

PhysicalMaximum 

PROPERTY PhysicalMaximum : LREAL

This property sets the physical minimum of the analog I/O directly. See SetPhysicalLimits for details.

Property Value

LREAL

PhysicalMinimum 

PROPERTY PhysicalMinimum : LREAL

This property sets the physical minimum of the analog I/O directly. See SetPhysicalLimits for details.

Property Value

LREAL

Simulation 

PROPERTY Simulation : BOOL

This property is abstract. See documentation of an actual instance (e.g. AnalogInputUint)

Property Value

BOOL

Value 

PROPERTY Value : LREAL

Property Value

LREAL

ValueUnit 

PROPERTY ValueUnit : STRING(20)

Physical unit of the analog value (i.e. bar, degree celsius, mm)

Property Value

STRING(20)

Methods

ConvertFromTerminal 

METHOD PROTECTED ConvertFromTerminal (
 [input] value : LINT) : LREAL

Inputs

value LINT

Returns

LREAL

ConvertToTerminal 

METHOD PROTECTED ConvertToTerminal (
 [input] value : LREAL) : LINT

this method applies the linear transformation from phyiscal units to terminal values that is given by SetConversionLinear and SetTerminalResolution.

Inputs

value LREAL

Returns

LINT

Enable 

METHOD Enable (
 [input] on : BOOL)

see SetDigitalThreshold and Enable.

Inputs

on BOOL

FallingTrigger 

METHOD FallingTrigger () : BOOL

see SetDigitalThreshold and FallingTrigger.

Returns

BOOL

HasTriggered 

METHOD HasTriggered () : BOOL

Depending on the logic set with SetTriggerLogic this method internally calls RisingTrigger or FallingTrigger.

Returns

BOOL

Invert 

METHOD Invert ()

see SetDigitalThreshold and Invert.

Name 

METHOD FINAL Name () : ZCore.ZString

this method return the name that has been set with SetName

Returns

ZString

Read 

METHOD FINAL Read () : LREAL

This method read a value from the terminal and applies the physical limits set for this analog I/O. See documentation of an actual instance (e.g. AnalogInputUint) for details.

Returns

LREAL

ReadImpl 

METHOD PROTECTED ABSTRACT ReadImpl () : LREAL

Returns

LREAL

ReadNormalized 

METHOD ReadNormalized () : LREAL

This method returns the analogue value as a normalized value between 0 and 1 related to the physical limits set with SetPhysicalLimits.

Note

In the event that the physical limits are deactivated (both limit values are equal to 0) the method returns 0.

Returns

LREAL

Resolution 

METHOD Resolution () : LREAL

returns the smallest possible physical increment with a given terminal resolution and conversion function, see UpdateResolution.

Returns

LREAL

RisingTrigger 

METHOD RisingTrigger () : BOOL

see SetDigitalThreshold and RisingTrigger.

Returns

BOOL

SetConversionLinear 

METHOD SetConversionLinear (
 [input] slope : LREAL,
 [input] intercept : LREAL,
 [input] valueUnit : STRING(20))

This method is used to convert the values of an actual terminal (e.g. EL3102). to a physical unit that may be used within the context of an application. Terminals usually provide startup parameters to perform data conversion on the hardware. However, in Zeugwerk Framework we prefer to convert these values on the PLC since this is much more flexible than relying on SDO parameters.

Values that are read and written to a terminal are internally normalized before applying any conversions on them. Terminals that use unsigned datatypes are normalized between [0,1] and terminals with signed datatypes are normalized between [-1,1] before applying the linear transformation that is set with this method to it. This makes it rather easy to specify linear conversion functions that are independent of the terminal resolution and the internal datatype that is used by a terminal.

For instance, a terminal that can measure 0V..10V with 16bit resolution, uses INT as datatype, such that the terminals values are in the interval [0, 65535].

If the I/O is simulated, this method initializes the physical value to 0. Call Write manually after this method to initialize the I/O with a value, which suites your application best in a simulated environment.

Note

This method automatically resets the physical limits However, it is possible to overwrite the limits later on if needed.

Inputs

slope LREAL

represents the slope k of the linear function $y=k*x+d$

intercept LREAL

represents the intercept d of the linear function $y=k*x+d$

valueUnit STRING(20)

physical unit of the analog value - used for logging and in [IoBridge](xref:ZApplication.IoBridge]

SetConversionParameters 

METHOD SetConversionParameters (
 [input] terminalMin : LREAL,
 [input] terminalMax : LREAL,
 [input] elecMin : LREAL,
 [input] elecMax : LREAL,
 [input] physMin : LREAL,
 [input] physMax : LREAL,
 [input] physicalUnit : STRING(20))

This method is used to convert the values of an actual terminal (e.g. EL3102). to a phyiscal unit that may be used within the context of an application. Terminals usually provide startup parameters to perform data conversion on the hardware. However, in Zeugwerk Framework we prefer to convert these values on the PLC since this is much more flexible than relying on SDO parameters.

The value ranges for the physical, the electrical and the terminal value are required for this. If you want to use a simple scaling conversion instead, which is typically used for temperature inputs, use SetConversionScaling instead.

If the I/O is simulated, this method initializes the physical value to physMin. Call Write manually after this method to initialize the I/O with a value, which suites your application best in a simulated environment.

Note

This method automatically initializes the physical limits to physMin and physMax. However, it is possible to overwrite the limits later on if needed.

Warning

This conversion expect the terminal resolution to be set correctly. When constructing an Analog I/O this is automatically done in the constructor. However, if SetConversionScaling is called at some point this value is overwritten and has to be set up again, by calling SetTerminalResolution.

Inputs

terminalMin LREAL

minimum terminal value, e.g. 0mA, 4mA, 0V, -10V

terminalMax LREAL

maximum terminal value, e.g. 20mA, 10V, 5V

elecMin LREAL

minimum electrical value of the sensor/actuator, e.g. 1V, 0V, 4mA

elecMax LREAL

maximum electrical value of the sensor/actuator, e.g. 5V, 10V, 20V

physMin LREAL

minimum physical value, e.g. 0bar, -30°C, 0mm

physMax LREAL

maximum physical value, e.g. 10bar, 100°C, 10mm

physicalUnit STRING(20)

physical Unit, e.g. 'bar', 'mm', '°C'

SetConversionScaling 

METHOD SetConversionScaling (
 [input] scale : LREAL,
 [input] offset : LREAL,
 [input] physicalUnit : STRING(20))

This method is used to convert the values of an actual terminal (e.g. EL3102). to a phyiscal unit that may be used within the context of an application. Terminals usually provide startup parameters to perform data conversion on the hardware. However, in Zeugwerk Framework we prefer to convert these values on the PLC since this is much more flexible than relying on SDO parameters.

This method adjusts the conversion from the terminal to a physical value in a way that the value provided by the terminal is simply scaled. For advanced sensor-data conversion consider using SetConversionParameters instead.

An example could be a temperature value from a Beckhoff EL3312 EtherCAT Terminal, 2-channel analog input, temperature, thermocouple, 16bit. This terminal has a INT datatype and delivers a temperature for thermocouples with type J as 0.1 degree celsius. The rest of the scaling (resolution in bits and so on) is done by the terminal itself, here a simple decimal place scaling has to be done. This can be done by setting the scale value to 0.1

In most cases the offset can be set to zero, but sometimes it is necessary to start with a desired value. One example could be an ultra-sound sensor which has a dead-range and this value should be set as offset.

If the I/O is simulated, this method initializes the physical value to 0. Call Write manually after this method to initialize the I/O with a value, which suites your application best in a simulated environment.

Note

This method automatically resets the physical limits However, it is possible to overwrite the limits later on if needed.

Warning

Calling this method resets the terminal resolution, which is otherwise automatically set during construction of the object. Hence, if SetConversionParameters is called after this method for any reason, make sure to reset the terminal resolution first.

Inputs

scale LREAL

scale as multiplier to the delivered value; e.g. a temperature terminal returns 10 which is 1 degree Celsius so we need to set 0.1 as multiplier to get Celsius

offset LREAL

offset which defines the value when the terminal transmits zero

physicalUnit STRING(20)

physical Unit, e.g. 'bar', 'mm', '°C'

SetDigitalThreshold 

METHOD SetDigitalThreshold (
 [input] threshold : LREAL)

An analog I/O can be treated as a digital I/O by defining a threshold for on/off. For values above and below this threshold the Enabled and Enabled (and other methods coming from IDigital will behave the same as a Digital I/O, including Logic.

The parameter of this method is given in physical value of the terminal (see SetConversionLinear). Per default digital threshold is set to 0 in physical units and the Logic is set to (DigitalLogic.Normal)[xref:ZEquipment.DigitalLogic#Normal], where values above the threshold mean on and values below or equal mean off.

Inputs

threshold LREAL

threshold for on/off in physical units, defaults to 0

SetLogger 

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

Using this method a logger may be supplied to the object in order to log read and write access to the terminal. Logging can be disabled by passing a 0 pointer to the method. TODO: parameter for logging threshold???

Inputs

logger ILogger

interface of a logger instance or a logger decorator instance

SetLogic 

METHOD SetLogic (
 [input] logic : DigitalLogic)

This method is used to set the logic of the analog I/O in case the IDigital is utilized via SetDigitalThreshold. By default, the analog I/O is using normal logic, which means that values about the digital threshold are treated as on, while values below or equal this threshold are treated as off.

Inputs

logic DigitalLogic

SetName 

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

This method can be used to give a name to this object. This is automatically used for logging (if enabled, see SetLogger). Also, this name is used with using this instance together with an IoBridge to make it available on a HMI.

Inputs

name ZString

SetPhysicalLimits 

METHOD SetPhysicalLimits (
 [input] physMin : LREAL,
 [input] physMax : LREAL)

By default the physical limits are switched off and any value can be read from or written to a terminal, even values which make no sense in a physical way. This method allows to set boundaries for Read and Write calls such that only values can be used that make sense for your application. When calling SetConversionParameters and no other physical limit has been set the former method will automatically set the limits accordingly to its parameter.

To disable previously activated physical limits, call this method with physMin=0 and physMax=0

Inputs

physMin LREAL
physMax LREAL

SetSimulation 

METHOD SetSimulation (
 [input] on : BOOL)

This method is used to enable or disable the simulation mode for the analog input and output function blocks. Internally the pointer to the variable that is written to or read from, respectively, is swapped by toggling this method. Simulated inputs behave different with respect to actual terminals with regard to the Write method. Phyisical terminals can not be written to, for simulated terminal this is totally fine though (and even needed most of the times).

Inputs

on BOOL

SetTerminalResolution 

METHOD FINAL SetTerminalResolution (
 [input] resolution : BYTE)

Sets die sampling resolution of the terminal. This is needed to convert the actual number which is written from the terminal in a correct way to the physical value. By default distinct analog I/Os inititialize the terminal resolution by the maximum resolution for the respective datatype.

Important

This method is used in FB_init and may not be overwritten by any function block extending from this Analog class

Inputs

resolution BYTE := 16

sampling resolution of the actual analog input or output

SetTriggerLogic 

METHOD SetTriggerLogic (
 [input] logic : DigitalLogic)

This method controls the logic of the HasTriggered method

Inputs

logic DigitalLogic

logic of the input or output, available types normal and inverted

UpdateResolution 

METHOD PRIVATE UpdateResolution ()

Calculates the smallest possible increment of the terminal with the given linear conversion and updates the significant digit variable according to this value. For instance, if the resolution of the terminal (including conversion) is 0.0004, the significant digit is in the fourth decimal.

Write 

METHOD FINAL Write (
 [input] value : LREAL)

This method applies the physical limits to value and then writes the value from the terminal and set for this analog I/O. See documentation of an actual instance (e.g. AnalogInputUint) for details.

Inputs

value LREAL

WriteImpl 

METHOD PROTECTED ABSTRACT WriteImpl (
 [input] value : LREAL)

Inputs

value LREAL

WriteNormalized 

METHOD WriteNormalized (
 [input] value : LREAL)

This method outputs the analog value normalized, based on the physical limits set with SetPhysicalLimits. Permitted values for the input 'value' are between 0 and 1.

Note

In the event that the physical limits are disabled (both limit values are equal to 0), there will be no change in the current analog output value.

Inputs

value LREAL