Table of Contents

Analog

Namespace
ZEquipment
Implements

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.

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

Properties

DecimalPlaces 

PROPERTY DecimalPlaces : INT

Property Value

INT

Enabled

see SetDigitalThreshold and Enabled.

PROPERTY Enabled : BOOL

Property Value

BOOL

PhysicalMaximum

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

PROPERTY PhysicalMaximum : LREAL

Property Value

LREAL

PhysicalMinimum

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

PROPERTY PhysicalMinimum : LREAL

Property Value

LREAL

Simulation

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

PROPERTY Simulation : BOOL

Property Value

BOOL

Value 

PROPERTY Value : LREAL

Property Value

LREAL

ValueUnit

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

PROPERTY ValueUnit : STRING(20)

Property Value

STRING(20)

Methods

ConvertFromTerminal

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

METHOD PROTECTED ConvertFromTerminal (
 value : LINT) : LREAL

Inputs

value LINT

Returns

LREAL

ConvertToTerminal

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

METHOD PROTECTED ConvertToTerminal (
 value : LREAL) : LINT

Inputs

value LREAL

Returns

LINT

Enable

see SetDigitalThreshold and Enable.

METHOD Enable (
 on : BOOL)

Inputs

on BOOL

FallingTrigger

see SetDigitalThreshold and FallingTrigger.

METHOD FallingTrigger () : BOOL

Returns

BOOL

HasTriggered

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

METHOD HasTriggered () : BOOL

Returns

BOOL

Invert

see SetDigitalThreshold and Invert.

METHOD Invert ()

Name

this method return the name that has been set with SetName

METHOD FINAL Name () : ZCore.ZString

Returns

ZString

Read

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.

METHOD FINAL Read () : LREAL

Returns

LREAL

ReadImpl 

METHOD PROTECTED ABSTRACT ReadImpl () : LREAL

Returns

LREAL

ReadNormalized

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.

METHOD ReadNormalized () : LREAL

Returns

LREAL

Resolution

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

METHOD Resolution () : LREAL

Returns

LREAL

RisingTrigger

see SetDigitalThreshold and RisingTrigger.

METHOD RisingTrigger () : BOOL

Returns

BOOL

SetConversionLinear

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.

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

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

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.

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

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

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.

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

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

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.

METHOD SetDigitalThreshold (
 threshold : LREAL)

Inputs

threshold LREAL

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

SetLogger

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

METHOD SetLogger (
 logger : ZCore.ILogger)

Inputs

logger ILogger

interface of a logger instance or a logger decorator instance

SetLogic

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.

METHOD SetLogic (
 logic : DigitalLogic)

Inputs

logic DigitalLogic

SetName

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.

METHOD SetName (
 name : ZCore.ZString)

Inputs

name ZString

SetPhysicalLimits

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

METHOD SetPhysicalLimits (
 physMin : LREAL,
 physMax : LREAL)

Inputs

physMin LREAL

physMax LREAL

SetSimulation

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

METHOD SetSimulation (
 on : BOOL)

Inputs

on BOOL

SetTerminalResolution

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

METHOD FINAL SetTerminalResolution (
 resolution : BYTE)

Inputs

resolution BYTE := 16

sampling resolution of the actual analog input or output

SetTriggerLogic

This method controls the logic of the HasTriggered method

METHOD SetTriggerLogic (
 logic : DigitalLogic)

Inputs

logic DigitalLogic

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

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.

METHOD PRIVATE UpdateResolution ()

Write

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.

METHOD FINAL Write (
 value : LREAL)

Inputs

value LREAL

WriteImpl 

METHOD PROTECTED ABSTRACT WriteImpl (
 value : LREAL)

Inputs

value LREAL

WriteNormalized

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.

METHOD WriteNormalized (
 value : LREAL)

Inputs

value LREAL