s7-SCL-scripts/s7-1500/cylinder_monitor/README_CylinderMonitor.md

# FB_CylinderMonitor — S7-1500 SCL Universal Cylinder Supervisor

> **Platform:** Siemens S7-1500 | TIA Portal V18+ | SCL
> **Blocks:** `FB_CylinderMonitor` · `FB_CylFaultCollector`
> **Companion to:** [`FB_WeldSequencer`](../README.md)

A drop-in cylinder monitoring library for any pneumatic or hydraulic actuator. Handles all real-world sensor configurations — zero, one, or two position sensors — generates direction-aware timeout faults, detects sensor conflicts and lost positions, gates actuator outputs for safety, and feeds structured fault data directly to an HMI and machine sequencer.

---

## Table of Contents

1. [Why This Exists](#1-why-this-exists)
2. [Files](#2-files)
3. [Sensor Configuration Options](#3-sensor-configuration-options)
4. [Fault Logic Per Configuration](#4-fault-logic-per-configuration)
5. [FB_CylinderMonitor — Interface](#5-fb_cylindermonitor--interface)
6. [FB_CylFaultCollector — Interface](#6-fb_cylfaultcollector--interface)
7. [Output Gating Pattern](#7-output-gating-pattern)
8. [Integration with FB_WeldSequencer](#8-integration-with-fb_weldsequencer)
9. [Demo: Welding Cell (4 cylinders)](#9-demo-welding-cell-4-cylinders)
10. [HMI Integration](#10-hmi-integration)
11. [TIA Portal Setup](#11-tia-portal-setup)
12. [Timing Reference](#12-timing-reference)
13. [Fault Code Reference](#13-fault-code-reference)
14. [Adapting for Other Applications](#14-adapting-for-other-applications)
15. [Safety Notes](#15-safety-notes)

---

## 1. Why This Exists

Every cylinder in a machine needs the same boilerplate logic:

- Did it reach position in time? If not → fault
- Are both sensors TRUE at once? That's wiring or hardware failure → fault
- Did it leave position without being commanded? → fault
- What should the machine do when it faults — pause or stop?
- What should the operator see on the HMI?

Writing this 20+ times per machine is error-prone and inconsistent. `FB_CylinderMonitor` encapsulates it once, handles all sensor topologies, and gives you clean `AtFwd`/`AtBwd` booleans that replace raw sensor reads in your step advance conditions.

---

## 2. Files

```
📁 CylinderMonitor/
├── FB_CylinderMonitor.scl        # FB_CylinderMonitor + FB_CylFaultCollector
├── DEMO_WeldCellIntegration.scl  # Integration demo (4 cylinders + sequencer)
└── README_CylinderMonitor.md     # This file
```

---

## 3. Sensor Configuration Options

Set `SensorConfig` (INT) on each FB instance:

| Value | Constant | Sensor Setup | Typical Use |
|---|---|---|---|
| `0` | `CFG_NONE` | No sensors | Valves, no-feedback actuators |
| `1` | `CFG_ONE_FWD` | Sensor at FWD (extended) end only | Clamps, grippers — only care about "closed" |
| `2` | `CFG_ONE_BWD` | Sensor at BWD (retracted) end only | Ejectors — only care about "home" |
| `3` | `CFG_TWO` | Sensor at both ends | Weld heads, positioners, gates |

### Which configuration to use?

```
Q: Does the cylinder need to confirm both extended AND retracted?
   YES → CFG_TWO (3)

Q: Only need to know it's closed/extended?
   YES → CFG_ONE_FWD (1)

Q: Only need to know it's home/retracted?
   YES → CFG_ONE_BWD (2)

Q: No sensor at all (timer-only advance)?
   YES → CFG_NONE (0)
```

---

## 4. Fault Logic Per Configuration

### CFG_NONE (0) — No faults possible from position

```
Cmd_Fwd ON ──────────────────────────────────▶ CylCmd_FwdSafe ON
                                               CylState = AT_FWD (trusted)
No sensors → no timeout → no conflict
Advance logic: use sequencer's step timer
```

### CFG_ONE_FWD (1) — Fault on FWD only

```
Cmd_Fwd ON ──┬──────────────────────▶ CylCmd_FwdSafe ON
             │   Sen_Fwd? ──TRUE────▶ AtFwd = TRUE  ✓  (timer reset)
             │            └─FALSE───▶ T_Timeout running
             │                            │
             │                            ▼ T_Timeout elapsed
             │                         FaultCode = 1 (FWD TIMEOUT)
             │                         Fault_Active = TRUE
             │                         CylCmd_FwdSafe → FALSE (gated off)
             │
Cmd_Bwd ON ──▶ No BWD timeout possible (no BWD sensor)
               CylState reports AT_BWD when FWD sensor clears
```

### CFG_ONE_BWD (2) — Fault on BWD only

```
Cmd_Bwd ON ──┬──────────────────────▶ CylCmd_BwdSafe ON
             │   Sen_Bwd? ──TRUE────▶ AtBwd = TRUE  ✓  (timer reset)
             │            └─FALSE───▶ T_Timeout running
             │                            ▼ T_Timeout elapsed
             │                         FaultCode = 2 (BWD TIMEOUT)
             │
Cmd_Fwd ON ──▶ No FWD timeout (no FWD sensor)
               CylState reports AT_FWD when BWD sensor clears
```

### CFG_TWO (3) — Full fault coverage

```
Cmd_Fwd ON ──▶ Sen_Fwd? ─TRUE──▶ AtFwd ✓   timer cancelled
                        └─FALSE─▶ Timeout FWD → FaultCode 1

Cmd_Bwd ON ──▶ Sen_Bwd? ─TRUE──▶ AtBwd ✓   timer cancelled
                        └─FALSE─▶ Timeout BWD → FaultCode 2

BOTH sensors TRUE simultaneously → FaultCode 3 (CONFLICT) → immediate fault
No cmd + was at known pos + both sensors go FALSE → FaultCode 4 (LOST)
Both Cmd_Fwd AND Cmd_Bwd TRUE → FaultCode 3 (command conflict)
```

---

## 5. FB_CylinderMonitor — Interface

### VAR_INPUT

| Name | Type | Description |
|---|---|---|
| `CylName` | `String[32]` | Human name, e.g. `'Clamp Cylinder'` — used in HMI text |
| `SensorConfig` | `Int` | 0=NONE, 1=ONE_FWD, 2=ONE_BWD, 3=TWO |
| `T_Timeout` | `Time` | Max time for cylinder to reach position |
| `Cmd_Fwd` | `Bool` | Extend / close command |
| `Cmd_Bwd` | `Bool` | Retract / open command |
| `Cmd_Reset` | `Bool` | Rising edge clears fault |
| `Sen_Fwd` | `Bool` | Forward / extended position sensor |
| `Sen_Bwd` | `Bool` | Backward / retracted position sensor |
| `Enable` | `Bool` | FALSE = ignore commands, hold state |

### VAR_OUTPUT

| Name | Type | Description |
|---|---|---|
| `CylCmd_FwdSafe` | `Bool` | **Gated FWD output** — connect to DQ |
| `CylCmd_BwdSafe` | `Bool` | **Gated BWD output** — connect to DQ |
| `AtFwd` | `Bool` | Position confirmed at FWD |
| `AtBwd` | `Bool` | Position confirmed at BWD |
| `Intermediate` | `Bool` | Between positions (TWO config, no cmd) |
| `Moving` | `Bool` | Command active, not yet confirmed |
| `Fault_Active` | `Bool` | Any fault present |
| `Fault_FwdTimeout` | `Bool` | Specific fault bit |
| `Fault_BwdTimeout` | `Bool` | Specific fault bit |
| `Fault_Conflict` | `Bool` | Sensor conflict fault bit |
| `Fault_Lost` | `Bool` | Lost position fault bit |
| `FaultCode` | `Int` | Numeric code (0–4) |
| `CylState` | `Int` | State code (0–6) |
| `HMI_StatusText` | `String[80]` | Ready-to-display status |
| `HMI_FaultText` | `String[80]` | Ready-to-display fault message |

---

## 6. FB_CylFaultCollector — Interface

Aggregates up to 8 cylinder monitor faults into one summary. Wire its outputs to the sequencer's `Cmd_Pause` and `Cmd_Stop`.

### Key Outputs

| Name | Type | Description |
|---|---|---|
| `CylFaultAny` | `Bool` | OR of all cylinder faults |
| `CylFaultWord` | `Word` | Bitmask — bit 0 = Cyl1, bit 7 = Cyl8 |
| `Cmd_MachinePause` | `Bool` | **Wire to sequencer `Cmd_Pause`** |
| `Cmd_MachineStop` | `Bool` | **Wire to sequencer `Cmd_Stop`** |
| `Cmd_Warning` | `Bool` | Amber lamp — non-stopping fault |
| `FirstFaultText` | `String[80]` | First fault message for HMI banner |
| `ActiveFaultCount` | `Int` | Number of cylinders currently faulted |

### Machine Response Configuration

| Input | Value | Effect |
|---|---|---|
| `Response_Timeout` | `0` | Warning only — machine keeps running |
| `Response_Timeout` | `1` | Pause machine |
| `Response_Timeout` | `2` | Stop machine (requires Reset) |
| `Response_Conflict` | `0/1/2` | Same options |
| `Response_Lost` | `0/1/2` | Same options |

**Recommended defaults:**

```scl
Response_Timeout  := 1;   // Pause — timeout may be temporary, operator can check
Response_Conflict := 2;   // Stop  — two sensors both TRUE = hardware fault
Response_Lost     := 2;   // Stop  — cylinder moved without command = mechanical issue
```

---

## 7. Output Gating Pattern

The core safety pattern of this FB is **output gating**. Instead of writing:

```scl
// ❌ Unsafe — raw command goes direct to DQ
%Q0.1 := Act_HeadExtend;
```

You write:

```scl
// ✅ Safe — passes through monitor, gated off on fault
"DB_CylHead"(
    Cmd_Fwd := Act_HeadExtend,
    ...
);
%Q0.1 := "DB_CylHead".CylCmd_FwdSafe;   // Only energises if healthy
```

When a fault occurs (timeout, conflict, lost position):

1. `CylCmd_FwdSafe` → `FALSE` immediately (same scan as fault detection)
2. Solenoid valve de-energised → cylinder stops
3. `Fault_Active` → `TRUE` → collector → sequencer `Cmd_Pause` or `Cmd_Stop`
4. `HMI_FaultText` → operator message describes exactly what failed

---

## 8. Integration with FB_WeldSequencer

The two FBs communicate in both directions:

```
FB_CylinderMonitor                     FB_WeldSequencer
────────────────────                   ─────────────────────────────
AtFwd ─────────────────────────────▶  Sen_ClampClosed (step 2 advance)
AtFwd ─────────────────────────────▶  Sen_HeadAtWeldPos (step 3 advance)
AtBwd ─────────────────────────────▶  Sen_HeadRetracted (step 9 advance)
Fault_Active                           
   └──▶ FB_CylFaultCollector           
           Cmd_MachinePause ──────────▶  Cmd_Pause (OR with operator PB)
           Cmd_MachineStop  ──────────▶  Cmd_Stop  (OR with operator PB)

FB_WeldSequencer                       FB_CylinderMonitor
─────────────────────────────          ────────────────────
Act_HeadExtend ─────────────────────▶  Cmd_Fwd
Act_HeadRetract ────────────────────▶  Cmd_Bwd
Seq_Running OR Seq_Paused ──────────▶  Enable
```

### Step Advance with Monitor vs Raw Sensor

| Without Monitor | With Monitor |
|---|---|
| `_stepAdvReady := Sen_ClampClosed` | `_stepAdvReady := "DB_CylClamp".AtFwd` |
| Advances even if clamp timed out | Will not advance if monitor is faulted |
| No timeout detection | FaultCode 1 triggers machine pause |

Using `AtFwd`/`AtBwd` from the monitor instead of raw sensor inputs means a faulted cylinder **also prevents step advance**, so the sequencer's own watchdog timer provides a belt-and-braces fallback catch.

---

## 9. Demo: Welding Cell (4 Cylinders)

The demo file `DEMO_WeldCellIntegration.scl` shows all four configurations side by side:

| Instance | Cylinder | Config | Timeout | Fault Response |
|---|---|---|---|---|
| `DB_CylClamp` | Clamp | ONE_FWD | 2 s | Pause |
| `DB_CylHead` | Weld Head | TWO | 3 s | Pause (timeout) / Stop (conflict) |
| `DB_CylEject` | Part Ejector | ONE_BWD | 1.5 s | Pause |
| `DB_CylGas` | Gas Valve | NONE | n/a | n/a |

### Execution Order (critical)

In your OB (OB1 or OB30), call in this order:

```
1st  → "DB_CylClamp"(...)       FB_CylinderMonitor
2nd  → "DB_CylHead"(...)        FB_CylinderMonitor
3rd  → "DB_CylEject"(...)       FB_CylinderMonitor
4th  → "DB_CylGas"(...)         FB_CylinderMonitor
5th  → "DB_CylFaults"(...)      FB_CylFaultCollector
6th  → "DB_WeldSeq"(...)        FB_WeldSequencer
```

Monitors run first so that `AtFwd`/`AtBwd` and `Fault_Active` values are fresh when the sequencer evaluates step advance conditions and Cmd_Pause/Stop in the same scan.

---

## 10. HMI Integration

### Recommended Screen Objects

#### Cylinder Overview Faceplate (one per cylinder)

| Element | Tag | Type |
|---|---|---|
| Status text | `DB_CylClamp.HMI_StatusText` | Text field |
| Fault text | `DB_CylClamp.HMI_FaultText` | Text field (red, visible on fault) |
| State indicator | `DB_CylClamp.CylState` | Bar/value with colour map |
| Moving animation | `DB_CylClamp.Moving` | Animated cylinder graphic |
| At FWD lamp | `DB_CylClamp.AtFwd` | Green indicator |
| At BWD lamp | `DB_CylClamp.AtBwd` | Green indicator |
| Fault lamp | `DB_CylClamp.Fault_Active` | Red indicator |

#### CylState Colour Map (for bargraph or rectangle)

| Value | Colour | Label |
|---|---|---|
| 0 | Grey | Idle |
| 1 | Yellow | Moving FWD |
| 2 | Green | At FWD ✓ |
| 3 | Yellow | Moving BWD |
| 4 | Green | At BWD ✓ |
| 5 | Orange | Intermediate |
| 6 | Red | FAULTED |

#### Global Alarm Banner

```
Tag: DB_CylFaults.FirstFaultText
Visible: DB_CylFaults.CylFaultAny = TRUE
Background: Red
Example text: "Weld Head: FWD TIMEOUT — check cylinder, solenoid and FWD sensor"
```

#### Fault Bitmask Display (overview bar)

```
Tag: DB_CylFaults.CylFaultWord (WORD)
Display as: 8 individual bit lamps
Bit 0 = Clamp  Bit 1 = Head  Bit 2 = Ejector  Bit 3 = Gas  ...
```

#### Operator Guidance Text Logic

For each cylinder fault, the HMI_FaultText already tells the operator exactly what to check:

```
FaultCode 1 → "Clamp Cylinder: FWD TIMEOUT — check cylinder, solenoid and FWD sensor"
FaultCode 2 → "Weld Head: BWD TIMEOUT — check cylinder, solenoid and BWD sensor"
FaultCode 3 → "Weld Head: SENSOR CONFLICT — FWD + BWD both active. Check wiring/sensors"
FaultCode 4 → "Weld Head: LOST POSITION — cylinder moved without command. Check mechanics"
```

No lookup table needed — the text is generated inside the FB using the `CylName` you configured.

---

## 11. TIA Portal Setup

### Create Instance DBs

For each cylinder, right-click project tree → **Add new block** → **Data Block** → Instance DB of `FB_CylinderMonitor`:

```
DB_CylClamp  : FB_CylinderMonitor
DB_CylHead   : FB_CylinderMonitor
DB_CylEject  : FB_CylinderMonitor
DB_CylGas    : FB_CylinderMonitor
DB_CylFaults : FB_CylFaultCollector
```

### Initial Parameter Setup (in startup OB or first-scan block)

```scl
// Set cylinder names and configs once at startup
// (or set directly in instance DB initial values in TIA Portal)

"DB_CylClamp".CylName      := 'Clamp Cylinder';
"DB_CylClamp".SensorConfig := 1;
"DB_CylClamp".T_Timeout    := T#2S;

"DB_CylHead".CylName       := 'Weld Head';
"DB_CylHead".SensorConfig  := 3;
"DB_CylHead".T_Timeout     := T#3S;

"DB_CylEject".CylName      := 'Part Ejector';
"DB_CylEject".SensorConfig := 2;
"DB_CylEject".T_Timeout    := T#1500MS;

"DB_CylGas".CylName        := 'Gas Purge Valve';
"DB_CylGas".SensorConfig   := 0;
```

Alternatively, set initial values directly in the instance DB's data view in TIA Portal — these persist through power cycles.

---

## 12. Timing Reference

| Cylinder Type | Recommended T_Timeout | Notes |
|---|---|---|
| Fast pneumatic (< 50 mm) | `T#1S` | Small bore, short stroke |
| Standard pneumatic | `T#2S` | Most clamps, grippers |
| Long-stroke pneumatic | `T#3S`–`T#5S` | Weld heads, gates |
| Hydraulic | `T#5S`–`T#15S` | Slower by nature |
| Spring-return valve | N/A (NONE config) | No position sensor |

**Rule of thumb:** Set timeout to 3× the expected travel time. Fast enough to catch real faults, slow enough to avoid nuisance trips on normal variation.

---

## 13. Fault Code Reference

| Code | Name | Cause | HMI Message | Machine Action |
|---|---|---|---|---|
| `0` | No fault | Normal | *(empty)* | None |
| `1` | FWD timeout | Sen_Fwd not TRUE within T_Timeout after Cmd_Fwd | `"[Name]: FWD TIMEOUT — check cylinder, solenoid and FWD sensor"` | Pause (configurable) |
| `2` | BWD timeout | Sen_Bwd not TRUE within T_Timeout after Cmd_Bwd | `"[Name]: BWD TIMEOUT — check cylinder, solenoid and BWD sensor"` | Pause (configurable) |
| `3` | Conflict | Sen_Fwd AND Sen_Bwd both TRUE, or Cmd_Fwd AND Cmd_Bwd both TRUE | `"[Name]: SENSOR CONFLICT — FWD + BWD both active. Check wiring/sensors"` | Stop (configurable) |
| `4` | Lost position | Was at known position; both sensors dropped with no command | `"[Name]: LOST POSITION — cylinder moved without command. Check mechanics"` | Stop (configurable) |

---

## 14. Adapting for Other Applications

### Add a pressure/flow sensor as virtual FWD confirmation

```scl
// Gas valve with pressure feedback
"DB_CylGas"(
    CylName      := 'Gas Valve',
    SensorConfig := 1,                  // ONE_FWD
    T_Timeout    := T#1S,
    Cmd_Fwd      := Act_GasValve,
    Sen_Fwd      := PressureSwitch_OK,  // Add this DI
    ...
);
```

### Motor or servo (use as virtual "cylinder" with limit switches)

```scl
"DB_CylSlide"(
    CylName      := 'Transfer Slide',
    SensorConfig := 3,
    T_Timeout    := T#4S,
    Cmd_Fwd      := SlideMotor_Fwd,
    Cmd_Bwd      := SlideMotor_Rev,
    Sen_Fwd      := LS_SlideForward,
    Sen_Bwd      := LS_SlideReverse,
    ...
);
```

### Changing timeout at runtime

```scl
// Speed-dependent timeout (slow mode vs normal mode)
IF SlowMode THEN
    "DB_CylHead".T_Timeout := T#8S;
ELSE
    "DB_CylHead".T_Timeout := T#3S;
END_IF;
```

Note: `T_Timeout` is read by the TON each scan — changes take effect immediately on the next timer start.

### More than 8 cylinders

Extend `FB_CylFaultCollector` array declarations from `[1..8]` to `[1..N]` and add corresponding `VAR_INPUT` slots.

---

## 15. Safety Notes

> ⚠️ `FB_CylinderMonitor` is a **diagnostic and convenience layer**. It is NOT a safety function and should NOT be used as the sole means of protecting personnel from cylinder movement.

### This FB provides (diagnostic/operational layer):
- Timeout detection → pause or stop production
- Sensor conflict → immediate output gate + machine stop
- HMI guidance text for operator troubleshooting
- Output gating (software level only — not certified)

### This FB does NOT replace (safety layer):
- **Hardware safety valves** (5/2 safety valve with spring return for E-Stop)
- **Dual-channel safety relay** monitoring for guard interlocks
- **Safety PLC** (S7-1500F) for PLd/SIL2 applications
- **Mechanical hard stops** preventing overtravel
- **Pressure relief valves** on hydraulic systems

### Minimum safety architecture:

```
E-Stop ──▶ Safety Relay ──▶ Safety Valve ──▶ Cylinder (power removed in hardware)
                │
                └──▶ Safety_EStopOK input on FB_WeldSequencer (software layer)

Door open ──▶ Safety Switch ──▶ Safety Relay
                │
                └──▶ Safety_DoorClosed input on FB_WeldSequencer
```

The cylinder monitor's `CylCmd_FwdSafe` / `CylCmd_BwdSafe` outputs control directional valves only. Power removal for E-Stop must be done at the hardware safety relay level, not by this FB.

---

## Changelog

| Version | Date | Notes |
|---|---|---|
| 0.1 | 2025 | Initial release — 4 sensor config types, 4 fault codes, HMI text |

---

## Licence

MIT — free to use and adapt.

---

*For the full welding cell sequencer (10 steps, AUTO/INCR mode, stop categories), see [`README.md`](../README.md).*