edouard@3929: Standard library edouard@3929: ================ edouard@3929: edouard@3929: .. edouard@3929: Documentation originally part of Smarteh's user Manual, and donated to Beremiz project. edouard@3929: edouard@3929: edouard@3929: .. list-table:: edouard@3929: edouard@3929: * - .. figure:: library_panel.png edouard@3929: edouard@3929: Library browser edouard@3929: edouard@3929: - Library contains various groups of standard edouard@3929: and user defined functions. They support the edouard@3929: usage in different programmable controller edouard@3929: programming languages inside POUs. edouard@3929: edouard@3929: edouard@3929: * - .. figure:: block_properties.png edouard@3929: edouard@3929: Block Properties edouard@3929: edouard@3929: - Block Properties pop-up window can be edouard@3929: opened by double-click on function block. edouard@3929: Some of the blocks can have more inputs than edouard@3929: default. This is selectable in the Inputs field edouard@3929: (e.g. ADD block). Also an Execution Order of edouard@3929: the blocks can be programmer-defined. All edouard@3929: blocks have an additional Execution Control edouard@3929: check-box. If it is checked than two new pins edouard@3929: are added (EN – input and ENO – output) to edouard@3929: control dynamically their execution. edouard@3929: edouard@3929: edouard@3929: Standard function blocks edouard@3929: ------------------------ edouard@3929: edouard@3929: .. highlight:: text edouard@3929: edouard@3929: .. list-table:: edouard@3929: edouard@3929: * - .. figure:: std_block-012.png edouard@3929: edouard@3929: SR bistable edouard@3929: edouard@3929: - The SR bistable is a latch where the Set dominates.:: edouard@3929: edouard@3929: ( BOOL:S1, BOOL:R ) => ( BOOL:Q1 ) edouard@3929: edouard@3929: This function represents a standard set-dominant set/reset flip edouard@3929: flop. The Q1 output become TRUE when the input S1 is TRUE and edouard@3929: the R input is FALSE. In the same way, the Q1 output become edouard@3929: FALSE when the input S1 is FALSE and the R input is TRUE. After edouard@3929: one of these transitions, when both the S1 and R signals return to edouard@3929: FALSE, the Q1 output keeps the previous state until a new edouard@3929: condition occurs. If you apply a TRUE condition for both the edouard@3929: signals, the Q1 output is forced to TRUE (set-dominant). edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-010.png edouard@3929: edouard@3929: RS bistable edouard@3929: edouard@3929: - The RS bistable is a latch where the Reset dominates.:: edouard@3929: edouard@3929: ( BOOL:S, BOOL:R1 ) => ( BOOL:Q1 ) edouard@3929: edouard@3929: This function represents a standard reset-dominant set/reset flip edouard@3929: flop. The Q1 output become TRUE when the input S is TRUE and edouard@3929: the R1 input is FALSE. In the same way, the Q1 output become edouard@3929: FALSE when the input S is FALSE and the R1 input is TRUE. After edouard@3929: one of these transitions, when both the S and R1 signals return to edouard@3929: FALSE, the Q1 output keeps the previous state until a new edouard@3929: condition occurs. If you apply a TRUE condition for both the edouard@3929: signals, the Q1 output is forced to FALSE (reset-dominant). edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-019.png edouard@3929: edouard@3929: SEMA Semaphore edouard@3929: edouard@3929: - The semaphore provides a mechanism to allow software elements edouard@3929: mutually exclusive access to certain resources.:: edouard@3929: edouard@3929: ( BOOL:CLAIM, BOOL:RELEASE ) => ( BOOL:BUSY ) edouard@3929: edouard@3929: This function block implements a semaphore function. Normally edouard@3929: this function is used to synchronize events. The BUSY output is edouard@3929: activated by a TRUE condition on the CLAIM input and it is de- edouard@3929: activated by a TRUE condition on the RELEASE input. edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-021.png edouard@3929: edouard@3929: R_TRIG Rising edge detector edouard@3929: edouard@3929: - The output produces a single pulse when a rising edge is detected.:: edouard@3929: edouard@3929: ( BOOL:CLK ) => ( BOOL:Q ) edouard@3929: edouard@3929: This function is a rising-edge detector. The Q output becomes edouard@3929: TRUE when a 0 to 1 (or FALSE to TRUE or OFF to ON) condition is edouard@3929: detected on the CLK input and it sustains this state for a complete edouard@3929: scan cycle. edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-023.png edouard@3929: edouard@3929: F TRIG edouard@3929: edouard@3929: - Falling edge detector edouard@3929: The output Q produces a single pulse when a falling edge is edouard@3929: detected.:: edouard@3929: edouard@3929: ( BOOL:CLK ) => ( BOOL:Q ) edouard@3929: edouard@3929: This function is a falling-edge detector. The Q output becomes edouard@3929: TRUE when a 1 to 0 (or TRUE to FALSE or ON to OFF) condition is edouard@3929: detected on the CLK input and it sustains this state for a complete edouard@3929: scan cycle. edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-030.png edouard@3929: edouard@3929: CTU edouard@3929: CTU_DINT, edouard@3929: CTU_LINT, edouard@3929: CTU_UDINT, CTU_ULINT edouard@3929: Up-counter edouard@3929: edouard@3929: - The up-counter can be used to signal when a count has reached a edouard@3929: maximum value.:: edouard@3929: edouard@3929: CTU: ( BOOL:CU, BOOL:R, INT:PV ) => ( BOOL:Q, INT:CV ) edouard@3929: CTU_DINT: ( BOOL:CU, BOOL:R, DINT:PV ) => ( BOOL:Q, DINT:CV ) edouard@3929: CTU_LINT: edouard@3929: ( BOOL:CU, BOOL:R, LINT:PV ) => ( BOOL:Q, LINT:CV ) edouard@3929: CTU_UDINT: ( BOOL:CU, BOOL:R, UDINT:PV ) => ( BOOL:Q, UDINT:CV ) edouard@3929: CTU_ULINT: ( BOOL:CU, BOOL:R, ULINT:PV ) => ( BOOL:Q, ULINT:CV ) edouard@3929: edouard@3929: The CTU function represents an up-counter. A rising-edge on CU edouard@3929: input will increment the counter by one. When the programmed edouard@3929: value, applied to the input PV, is reached, the Q output becomes edouard@3929: TRUE. Applying a TRUE signal on R input will reset the counter to edouard@3929: zero (Asynchronous reset). The CV output reports the current edouard@3929: counting value. edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-028.png edouard@3929: edouard@3929: CTD edouard@3929: CTD_DINT, CTD_LINT, edouard@3929: CTD_UDINT, CTD_ULINT edouard@3929: Down-counter edouard@3929: edouard@3929: - The down-counter can be used to signal when a count has reached edouard@3929: zero, on counting down from a pre-set value.:: edouard@3929: edouard@3929: CTD: ( BOOL:CD, BOOL:LD, INT:PV ) => ( BOOL:Q, INT:CV ) edouard@3929: CTD_DINT: ( BOOL:CD, BOOL:LD, DINT:PV ) => ( BOOL:Q, DINT:CV ) edouard@3929: CTD_LINT: ( BOOL:CD, BOOL:LD, LINT:PV ) => ( BOOL:Q, LINT:CV ) edouard@3929: CTD_UDINT: ( BOOL:CD, BOOL:LD, UDINT:PV ) => ( BOOL:Q, UDINT:CV ) edouard@3929: CTD_ULINT: ( BOOL:CD, BOOL:LD, ULINT:PV ) => ( BOOL:Q, ULINT:CV ) edouard@3929: edouard@3929: The CTD function represents a down-counter. A rising-edge on CD edouard@3929: input will decrement the counter by one. The Q output becomes edouard@3929: TRUE when the current counting value is equal or less than zero. edouard@3929: Applying a TRUE signal on LD (LOAD) input will load the counter edouard@3929: with the value present at input PV (Asynchronous load). The CV edouard@3929: output reports the current counting value. edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-035.png edouard@3929: edouard@3929: CTUD edouard@3929: CTUD_DINT, edouard@3929: CTUD_LINT, edouard@3929: CTUD_UDINT, edouard@3929: CTUD_ULINT edouard@3929: Up-down counter edouard@3929: edouard@3929: - The up-down counter has two inputs CU and CD. It can be used to edouard@3929: both count up on one input and down on the other.:: edouard@3929: edouard@3929: CTUD: ( BOOL:CU, BOOL:CD, BOOL:R, BOOL:LD, INT:PV ) => ( BOOL:QU, BOOL:QD, INT:CV ) edouard@3929: CTUD_DINT: ( BOOL:CU, BOOL:CD, BOOL:R, BOOL:LD, DINT:PV ) => ( BOOL:QU, BOOL:QD, DINT:CV ) edouard@3929: CTUD_LINT: ( BOOL:CU, BOOL:CD, BOOL:R, BOOL:LD, LINT:PV ) => ( BOOL:QU, BOOL:QD, LINT:CV ) edouard@3929: CTUD_UDINT: ( BOOL:CU, BOOL:CD, BOOL:R, BOOL:LD, UDINT:PV ) => ( BOOL:QU, BOOL:QD, UDINT:CV ) edouard@3929: CTUD_ULINT: ( BOOL:CU, BOOL:CD, BOOL:R, BOOL:LD, ULINT:PV ) => ( BOOL:QU, BOOL:QD, ULINT:CV ) edouard@3929: edouard@3929: This function represents an up-down programmable counter. A edouard@3929: rising-edge on the CU (COUNT-UP) input increments the counter edouard@3929: by one while a rising-edge on the CD (COUNT-DOWN) decreases edouard@3929: the current value. Applying a TRUE signal on R input will reset the edouard@3929: counter to zero. A TRUE condition on the LD signal will load the edouard@3929: counter with the value applied to the input PV (PROGRAMMED edouard@3929: VALUE). QU output becomes active when the current counting edouard@3929: value is greater or equal to the programmed value. The QD output edouard@3929: becomes active when the current value is less or equal to zero. edouard@3929: The CV output reports the current counter value. edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-037.png edouard@3929: edouard@3929: TP edouard@3929: Pulse timer edouard@3929: edouard@3929: - The pulse timer can be used to generate output pulses of a given edouard@3929: time duration.:: edouard@3929: edouard@3929: ( BOOL:IN, TIME:PT ) => ( BOOL:Q, TIME:ET ) edouard@3929: edouard@3929: This kind of timer has the same behaviour of a single-shot timer or edouard@3929: a monostable timer. edouard@3929: When a rising-edge transition is detected on the IN input, the Q edouard@3929: output becomes TRUE immediately. This condition continues until edouard@3929: the programmed time PT, applied to the relative pin, is elapsed. edouard@3929: After that the PT is elapsed, the Q output keeps the ON state if edouard@3929: the input IN is still asserted else the Q output returns to the OFF edouard@3929: state. This timer is not re-triggerable. This means that after that edouard@3929: the timer has started it can't be stopped until the complete edouard@3929: session ends. The ET output reports the current elapsed time. edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-042.png edouard@3929: edouard@3929: TON edouard@3929: On-delay timer edouard@3929: edouard@3929: - The on-delay timer can be used to delay setting an output true, edouard@3929: for fixed period after an input becomes true.:: edouard@3929: edouard@3929: ( BOOL:IN, TIME:PT ) => ( BOOL:Q, TIME:ET ) edouard@3929: edouard@3929: Asserting the input signal IN of this function starts the timer. edouard@3929: When the programmed time, applied to the input PT, is elapsed edouard@3929: and the input IN is still asserted, the Q output becomes TRUE. This edouard@3929: condition will continue until the input IN is released. If the IN edouard@3929: input is released before time elapsing, the timer will be cleared. edouard@3929: The ET output reports the current elapsed time. edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-044.png edouard@3929: edouard@3929: TOF edouard@3929: Off-delay timer edouard@3929: edouard@3929: - The off-delay timer can be used to delay setting an output false, edouard@3929: for fixed period after input goes false.:: edouard@3929: edouard@3929: ( BOOL:IN, TIME:PT ) => ( BOOL:Q, TIME:ET ) edouard@3929: edouard@3929: Asserting the input signal IN of this function immediately activates edouard@3929: the Q output. At this point, releasing the input IN will start the edouard@3929: time elapsing. When the programmed time, applied to the input edouard@3929: PT, is elapsed and the input IN is still released, the Q output edouard@3929: becomes FALSE. This condition will be kept until the input IN is edouard@3929: released. If the IN input is asserted again before time elapses, the edouard@3929: timer will be cleared and the Q output remains TRUE. The ET edouard@3929: output reports the current elapsed time. edouard@3929: edouard@3929: edouard@3929: Additional function blocks edouard@3929: -------------------------- edouard@3929: edouard@3929: edouard@3929: .. list-table:: edouard@3929: edouard@3929: * - .. figure:: std_block-055.png edouard@3929: edouard@3929: RTC edouard@3929: Real Time Clock edouard@3929: edouard@3929: - The RTC function block sets the output CDT to the input value PDT at the next edouard@3929: evaluation of the function block following a transition from 0 to 1 of the IN input. The CDT output edouard@3929: of the RTC function block is undefined when the value of IN is 0. edouard@3929: edouard@3929: .. line-block:: edouard@3929: edouard@3929: PDT = Preset date and time, loaded on rising edge of IN edouard@3929: CDT = Current date and time, valid when IN=1 edouard@3929: Q = copy of EN edouard@3929: edouard@3929: .. code-block:: edouard@3929: edouard@3929: (BOOL:IN, PDT:DT) => (BOOL:Q, CDT:DT) edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-049.png edouard@3929: edouard@3929: INTEGRAL edouard@3929: Integral edouard@3929: edouard@3929: - The integral function block integrates the value of input XIN over edouard@3929: time.:: edouard@3929: edouard@3929: ( BOOL:RUN, BOOL:R1, REAL:XIN, REAL:X0, TIME:CYCLE ) => ( BOOL:Q, REAL:XOUT ) edouard@3929: edouard@3929: When input RUN is True and override R1 is False, XOUT will edouard@3929: change for XIN value depends on CYCLE time value sampling edouard@3929: period. When RUN is False and override R1 is True, XOUT will hold edouard@3929: the last output value. If R1 is True, XOUT will be set to the X0 edouard@3929: value.:: edouard@3929: edouard@3929: XOUT = XOUT + (XIN * CYCLE) edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-051.png edouard@3929: edouard@3929: DERIVATIVE edouard@3929: Derivative edouard@3929: edouard@3929: - The derivative function block produces an output XOUT edouard@3929: proportional to the rate of change of the input XIN.:: edouard@3929: edouard@3929: ( BOOL:RUN, REAL:XIN, TIME:CYCLE ) => ( REAL:XOUT ) edouard@3929: edouard@3929: When RUN is True, XOUT will change proportional to the rate of edouard@3929: changing of the value XIN depends on CYCLE time value sampling edouard@3929: period.:: edouard@3929: edouard@3929: XOUT = ((3 * (XIN - XIN(to-3))) + XIN(to-1) – XIN(to-2) ) / (10 * CYCLE) edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-060.png edouard@3929: edouard@3929: PID edouard@3929: Proportional, Integral, Derivative edouard@3929: edouard@3929: - The PID (Proportional, Integral, Derivative) function block edouard@3929: provides the classical three term controller for closed loop edouard@3929: control. It does not contain any output limitation parameters edouard@3929: (dead-band, minimum, maximum, …) or other parameters edouard@3929: normally used for real process control (see also PID_A).:: edouard@3929: edouard@3929: ( BOOL:AUTO, REAL:PV, REAL:SP, REAL:X0, REAL:KP, REAL:TR, REAL:TD, TIME:CYCLE ) => ( REAL:XOUT ) edouard@3929: edouard@3929: When AUTO is False, PID function block XOUT will follow X0 value. edouard@3929: When AUTO is True, XOUT will be calculated from error value (PV edouard@3929: process variable – SP set point), KP proportional constant, TR edouard@3929: reset time, TD derivative constant and CYCLE time value sampling edouard@3929: period.:: edouard@3929: edouard@3929: XOUT = KP * ((PV-SP) + (I_OUT/TR) + (D_OUT * TD)) edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-062.png edouard@3929: edouard@3929: RAMP edouard@3929: Ramp edouard@3929: edouard@3929: - The RAMP function block is modelled on example given in the edouard@3929: standard but with the addition of a 'Holdback' feature.:: edouard@3929: edouard@3929: ( BOOL:RUN, REAL:X0, REAL:X1, TIME:TR, TIME:CYCLE, BOOL:HOLDBACK, REAL:ERROR, REAL:PV ) => ( BOOL:RAMP, REAL:XOUT ) edouard@3929: edouard@3929: When RUN and HOLDBACK are False, XOUT will follow X0 value. edouard@3929: When RUN is True and HOLDBACK value is False, XOUT will change edouard@3929: for ``OUT(to-1) + (X1 – XOUT(to-1))`` every CYCLE time value sampling edouard@3929: period. edouard@3929: edouard@3929: edouard@3929: * - .. figure:: std_block-064.png edouard@3929: edouard@3929: HYSTERESIS edouard@3929: Hysteresis edouard@3929: edouard@3929: - The hysteresis function block provides a hysteresis boolean output edouard@3929: driven by the difference of two floating point (REAL) inputs XIN1 edouard@3929: and XIN2.:: edouard@3929: edouard@3929: ( REAL:XIN1, REAL:XIN2, REAL:EPS ) => ( BOOL:Q ) edouard@3929: edouard@3929: When XIN1 value will be grater than XIN2 + EPS value, Q becomes edouard@3929: True. When XIN1 value will be less than XIN2 - EPS value, Q edouard@3929: becomes False.