Table of Contents

DebouncedInput

Namespace
ZEquipment
Implements

When a button is pressed/released or when a switch is toggled in practice it is not exactly a clean transition from FALSE to TRUE or vice versa. Instead, because of mechanical or physical characteristics, the actual state may toggle several times between these states. This phenomenon is called chattering and can be handled by using the DebouncedInput function block. It represents a single digital input with the same functionality as DigitalInput, but an additional method (xref:ZEquipment.DebouncedInput#SetDebouncingDuration) is used to deal with chattering phenomenons. In contrast to DigitalInput, it will only report a change of state if that change has been continuous for the set debounce time (xref:ZEquipment.DebouncedInput#SetDebouncingDuration).

Debouncing times can be set dynamically at any time in the application with SetDebouncingDuration.

Note

By default instances are simulated. In order to make use of a physical terminal, the method SetSimulation should be used.

FUNCTION_BLOCK DebouncedInput IMPLEMENTS ZEquipment.IDebouncedInput, ZEquipment.IDigital, ZCore.ITrigger

Outputs

Diagnostics DiagnosticMessage

Constructor

FB_init 

METHOD FB_init (
 bInitRetains : BOOL,
 bInCopyCode : BOOL,
 parent : ZCore.IManagedObject,
 debouncingTime : LREAL) : BOOL

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

debouncingTime LREAL

symmetric debouncing time in seconds, use SetDebouncingDuration for more options

Returns

BOOL

Properties

DebouncingDurationDisabled 

PROPERTY DebouncingDurationDisabled : LREAL

Property Value

LREAL

DebouncingDurationEnabled 

PROPERTY DebouncingDurationEnabled : LREAL

Property Value

LREAL

Enabled

This property returns the actual state of the debounced input as boolean. It respects the configured logic and debounced times.

The fieldbus state is the actual value that is represented by your terminal. The software logic of this input can be changed at any time in an application and defaults to Normal. The logic table that links the terminal state to the software state is as follows. See DigitalLogic for details.

PROPERTY Enabled : BOOL

Property Value

BOOL

Simulation

Every input is able to simulate its behaviour. With activated simulation the function block internally uses a software state-variable and ignores the terminal that has been linked to the function block. With this property the simulation state of the DebouncedInput can be set or retrieved if it is simulated or not.

PROPERTY Simulation : BOOL

Property Value

BOOL

State 

PROPERTY State : ZCore.ObjectState

Property Value

ObjectState

Methods

Enable

This method enables the actual input or output which means different states depending on the initialised logic The method is only relevant if the hardward is simulated. It immediately changes the state of the debounced input, ignoring the debouncing durations that have been configured for this instance. For physical inputs no state is changed.

METHOD Enable (
 on : BOOL)

Inputs

on BOOL

on=TRUE ... enables the input, on=FALSE ... disables the input

FallingTrigger

Consecutive calls to this method returns TRUE whenever the state of the digital interface switched from IsEnabled to NOT IsEnabled. It is the same as using a FallingTrigger instance or using an F_TRIG instance on Enabled. Since Enabled respects the debouncing times, so does this method.

IF debouncedInput.FallingTrigger()
THEN
  // ...
END_IF

METHOD FallingTrigger () : BOOL

Returns

BOOL

HasTriggered

Depending on the logic set with SetTriggerLogic this method internally calls RisingTrigger or FallingTrigger and returns its output.

By default this method is the same as calling FallingTrigger.

METHOD HasTriggered () : BOOL

Returns

BOOL

Invert

This method inverts the input and should only be used for simulation purposes. The method is only relevant if the hardward is simulated. It immediately changes the state of the debounced input, ignoring the debouncing durations that have been configured for this instance. For physical inputs no state is changed.

It is the equivalent to

debouncedInput.Enable(NOT debouncedInput.IsEnabled);

METHOD Invert ()

IsInputEnabled

This method returns the actual state of the terminal as boolean. Here debouncing times are by-passed considered. While debouncing times are ignored by this method, the configured logic is respected. For details refer to Enabled or DigitalLogic.

METHOD IsInputEnabled () : BOOL

Returns

BOOL

Name

This method return the name that has been set with SetName. The name is considered when writing messages to the log.

METHOD FINAL Name () : ZCore.ZString

Returns

ZString

RisingTrigger

Consecutive calls to this method returns TRUE whenever the state of the digital interface switched from IsEnabled to NOT IsEnabled. It is the same as using a RisingTrigger instance or using an F_TRIG instance on Enabled.

IF digitalInput.RisingTrigger()
THEN
  // ...
END_IF

METHOD RisingTrigger () : BOOL

Returns

BOOL

SetDebouncingDuration

This method sets the debouncing times for each state change. Calling Enabled will only return TRUE, if the actual input from the terminal is "stable", which means that the state did not change for enabled seconds or disabled seconds, repectively. Note that the latter states refer to the logic of the software-state, which is configured by calling SetLogic.

Note

Setting a duration to 0 is not completely the same than simply using a DigitalInput. Since this function blocks updates its internal state through calls to its cyclic method. The shortest duration is the cycle time of the PLC. Thus, when using this function block with duration=0 maybe consider to use the simpler DigitalInput function block instead.

METHOD SetDebouncingDuration (
 enabled : LREAL,
 disabled : LREAL)

Inputs

enabled LREAL

time in seconds for the stable enabled state (TRUE)

disabled LREAL

time in seconds for the stable disabled state (FALSE)

SetLogger

Setting a Logger with this method enables the logging functionality of the DebouncedInput function block.

Leaving the IO without logger will not create any log entry and is sometimes, depending on your performance requirements useful. However, the behaviour can also be changed during running of the PLC by changing the LogLevel.

Note

To change the logging behaviour it is sometimes useful to inject a LoggerNameDecorator here.

METHOD SetLogger (
 logger : ZCore.ILogger)

Inputs

logger ILogger

interface of a logger instance or a logger decorator instance

SetLogic

According to the process or the used hardware some signals on the fieldbus are high or low active, but in the PLC it is benefical to have these states inverted. This method allows to switch the logic that this class is operating with. Note that almost all methods of the digital make use of the logic that can be set here. (i.e. RisingTrigger, FallingTrigger, Enable, ...).

METHOD SetLogic (
 logic : DigitalLogic)

Inputs

logic DigitalLogic

logic of the input, available types normal and inverted

SetName

Sets the name of this object as it will show up in any log messages that is created by this object. The name set with this method should be relatable to the name of the input in the electrical plan of your automation project to identify the corresponding input properly. However, please note that logging should not be used for inputs because some of them are switched very often, which leads to a high logging load.

METHOD SetName (
 name : ZCore.ZString)

Inputs

name ZString

name of the input

SetSimulation

By default all digital interfaces that extend from this function block are simulated, to disable simulation mode this can be done by this method. Usually, the decision if simulation is used, takes places during initialization phase. However, some applications require to switch between these modes on-the-fly. In the latter case simply call this method at any time.

METHOD SetSimulation (
 on : BOOL)

Inputs

on BOOL

SetTriggerLogic

This method controls the logic of the HasTriggered method. By default, the trigger logic is set to Normal.

METHOD SetTriggerLogic (
 logic : DigitalLogic)

Inputs

logic DigitalLogic

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