diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..f9a096f
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,381 @@
+# 📡 S7-1500 Advanced Signal Filtering Library
+### SCL Function Blocks for Siemens TIA Portal
+
+---
+
+## Overview
+
+This library provides a collection of advanced signal filtering Function Blocks (FBs) written in **Structured Control Language (SCL)** for the **Siemens S7-1500 PLC** platform. All blocks share a consistent interface and are designed for real-time analog signal processing in industrial automation environments.
+
+Each filter uses a **circular buffer** architecture — no memory shifting per scan — keeping CPU load minimal and deterministic.
+
+---
+
+## Contents
+
+| FB Name | Filter Type | Best Use Case |
+|---|---|---|
+| `FB_MovingAverage` | Simple Moving Average (SMA) | General noise reduction |
+| `FB_EMA` | Exponential Moving Average | Fast response + smoothing |
+| `FB_WMA` | Weighted Moving Average | Emphasize recent samples |
+| `FB_MedianFilter` | Median / Order Statistics | Spike & glitch rejection |
+| `FB_RateLimiter` | Slew Rate Limiter | Actuator protection |
+| `FB_SignalFilter` | Unified wrapper (all above) | Single-block deployment |
+
+---
+
+## Requirements
+
+- **PLC:** Siemens S7-1500 (any CPU)
+- **TIA Portal:** V16 or later
+- **Language:** SCL (Structured Control Language)
+- **OB:** Can be called from any OB (OB1, cyclic OB, etc.)
+- **No special libraries required**
+
+---
+
+## Interface — Common Pattern
+
+All FBs follow the same interface convention:
+
+```pascal
+VAR_INPUT
+    xEnable     : BOOL;     // Enable filtering; FALSE = passthrough + reset
+    rInput      : REAL;     // Raw analog input value
+    iWindowSize : INT;      // Buffer/window size (filter-specific)
+END_VAR
+
+VAR_OUTPUT
+    rOutput     : REAL;     // Filtered output value
+    xReady      : BOOL;     // TRUE when buffer is full (SMA/WMA/Median)
+END_VAR
+```
+
+> **Note:** When `xEnable = FALSE`, each FB resets its internal state and passes `rInput` directly to `rOutput`. This allows safe runtime switching between filter modes without output jumps.
+
+---
+
+## Filter Reference
+
+---
+
+### 1. `FB_MovingAverage` — Simple Moving Average (SMA)
+
+Computes the arithmetic mean of the last *N* samples using a circular buffer and a running sum. No per-scan array iteration — the sum is updated incrementally.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `xEnable` | BOOL | — | Enable filter |
+| `rInput` | REAL | — | Analog input |
+| `iWindowSize` | INT | 10 | Window size (1–100) |
+| `rOutput` | REAL | — | Filtered output |
+| `xReady` | BOOL | — | TRUE when buffer full |
+
+**Formula:**
+
+```
+Output(n) = [ Sum of last N samples ] / N
+```
+
+**Characteristics:**
+- Equal weight to all samples in window
+- Output lags behind input by N/2 samples
+- Larger window = more smoothing = more lag
+- Very low CPU load (no division per element)
+
+**Typical window sizes:**
+
+| Signal Type | Recommended Window |
+|---|---|
+| Thermocouple / temperature | 20–50 |
+| Pressure sensor | 5–15 |
+| Flow meter | 10–20 |
+| Current / power | 5–10 |
+
+---
+
+### 2. `FB_EMA` — Exponential Moving Average
+
+Applies exponentially decreasing weights to past samples. No buffer required — only the previous output value is stored. Ideal when fast response with smoothing is needed.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `xEnable` | BOOL | — | Enable filter |
+| `rInput` | REAL | — | Analog input |
+| `rAlpha` | REAL | 0.1 | Smoothing factor (0.0–1.0) |
+| `rOutput` | REAL | — | Filtered output |
+
+**Formula:**
+
+```
+Output(n) = α × Input(n) + (1 − α) × Output(n−1)
+```
+
+**Alpha selection guide:**
+
+| Alpha | Effect | Equivalent SMA Window |
+|---|---|---|
+| 0.05 | Heavy smoothing, slow response | ~39 samples |
+| 0.1 | Balanced (default) | ~19 samples |
+| 0.2 | Light smoothing, fast response | ~9 samples |
+| 0.5 | Minimal smoothing | ~3 samples |
+
+**Characteristics:**
+- Minimal memory footprint (no array)
+- Infinite impulse response — past samples never fully forgotten
+- Best choice when memory is constrained or window must be very large
+
+---
+
+### 3. `FB_WMA` — Weighted Moving Average
+
+Similar to SMA but assigns linearly increasing weights to more recent samples. The newest sample gets weight *N*, the oldest gets weight *1*.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `xEnable` | BOOL | — | Enable filter |
+| `rInput` | REAL | — | Analog input |
+| `iWindowSize` | INT | 8 | Window size (1–16) |
+| `rOutput` | REAL | — | Filtered output |
+
+**Formula:**
+
+```
+Output(n) = Σ [ weight(i) × sample(i) ] / Σ weight(i)
+weight(i) = N for newest, 1 for oldest
+```
+
+**Characteristics:**
+- Responds faster to changes than SMA at same window size
+- More computationally intensive than SMA or EMA
+- Good compromise between lag and smoothing
+
+---
+
+### 4. `FB_MedianFilter` — Median / Order Statistics Filter
+
+Collects the last *N* samples, sorts them using insertion sort, and outputs the middle value. Completely immune to impulse spikes regardless of magnitude.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `xEnable` | BOOL | — | Enable filter |
+| `rInput` | REAL | — | Analog input |
+| `iWindowSize` | INT | 7 | Window size, odd recommended (1–15) |
+| `rOutput` | REAL | — | Filtered output |
+
+**Characteristics:**
+- **Best** filter for rejecting sensor glitches, wire bounce, EMI spikes
+- Non-linear filter — does not distort signal shape between spikes
+- Use **odd** window sizes (3, 5, 7, 9...) for a clean median value
+- Higher CPU load than SMA/EMA due to in-place sort each scan
+
+**Recommended window sizes:**
+
+| Application | Window |
+|---|---|
+| Remove single-sample spikes | 3 |
+| General spike rejection | 5–7 |
+| Heavy transient environment | 9–11 |
+
+> **Tip:** Combine Median + EMA for best results: Median removes spikes, EMA smooths residual noise.
+
+---
+
+### 5. `FB_RateLimiter` — Slew Rate Limiter
+
+Limits the maximum rate of change (rise and fall) of a signal per scan cycle. The output tracks the input but cannot change faster than the configured rate. Protects actuators from sudden setpoint jumps.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `xEnable` | BOOL | — | Enable filter |
+| `rInput` | REAL | — | Analog input |
+| `rMaxRiseRate` | REAL | 10.0 | Max units/second rising |
+| `rMaxFallRate` | REAL | 10.0 | Max units/second falling |
+| `rCycleTimeS` | REAL | 0.1 | OB cycle time in seconds |
+| `rOutput` | REAL | — | Rate-limited output |
+
+**Formula:**
+
+```
+MaxStep = MaxRate × CycleTime
+Output(n) = Output(n-1) + clamp(Input(n) − Output(n-1), −MaxStep, +MaxStep)
+```
+
+**Characteristics:**
+- Not a noise filter — purely a change-rate constraint
+- Asymmetric rise/fall rates supported (e.g. slow open, fast close)
+- Must be configured with correct `rCycleTimeS` to function correctly
+- Does not affect steady-state accuracy
+
+> **Important:** Set `rCycleTimeS` to match your OB cycle time. For OB1 at 100ms, use `0.1`. You can read this from `OB_CYCL.CYCLE_TIME` if needed.
+
+---
+
+### 6. `FB_SignalFilter` — Unified Wrapper
+
+A single FB that encapsulates all five filters. Select the active filter at runtime via `iMode`. Internally instantiates all FBs; only the selected one processes each scan.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `xEnable` | BOOL | — | Enable filter |
+| `rInput` | REAL | — | Analog input |
+| `iMode` | INT | 0 | Filter selection (see below) |
+| `iWindowSize` | INT | 10 | Window for SMA / WMA / Median |
+| `rAlpha` | REAL | 0.1 | Alpha for EMA |
+| `rMaxRate` | REAL | 10.0 | Rate for RateLimiter |
+| `rCycleTimeS` | REAL | 0.1 | Cycle time for RateLimiter |
+| `rOutput` | REAL | — | Filtered output |
+| `xReady` | BOOL | — | Buffer ready flag |
+
+**Mode selection:**
+
+| `iMode` | Filter |
+|---|---|
+| 0 | Passthrough (no filtering) |
+| 1 | Simple Moving Average |
+| 2 | Exponential Moving Average |
+| 3 | Weighted Moving Average |
+| 4 | Median Filter |
+| 5 | Rate Limiter |
+
+---
+
+## Performance Comparison
+
+| Filter | Noise Reduction | Spike Rejection | Response Speed | CPU Load | Memory |
+|---|---|---|---|---|---|
+| SMA | ★★★★☆ | ★★☆☆☆ | ★★☆☆☆ | Low | Medium |
+| EMA | ★★★☆☆ | ★★☆☆☆ | ★★★★☆ | Very Low | Minimal |
+| WMA | ★★★★☆ | ★★☆☆☆ | ★★★☆☆ | Medium | Medium |
+| Median | ★★★☆☆ | ★★★★★ | ★★★☆☆ | Medium-High | Medium |
+| Rate Limiter | ★☆☆☆☆ | ★★★☆☆ | ★★★☆☆ | Very Low | Minimal |
+
+---
+
+## Recommended Filter Combinations
+
+For best results in demanding environments, chain two filters:
+
+```
+Raw Signal → Median (spike removal) → EMA (noise smoothing) → Control loop
+```
+
+```pascal
+// Example: Median pre-filter + EMA smoothing
+fbMedian(xEnable := TRUE, rInput := rRawAnalog, iWindowSize := 5);
+fbEMA(xEnable := TRUE, rInput := fbMedian.rOutput, rAlpha := 0.15);
+rCleanSignal := fbEMA.rOutput;
+```
+
+---
+
+## Usage Example
+
+```pascal
+// Declarations
+VAR
+    fbFilter     : FB_SignalFilter;
+    rRawAnalog   : REAL;    // From analog input card (e.g. scaled 0.0–100.0)
+    rFiltered    : REAL;
+END_VAR
+
+// In OB1 or cyclic FC
+fbFilter(
+    xEnable      := TRUE,
+    rInput       := rRawAnalog,
+    iMode        := 1,          // 1 = SMA
+    iWindowSize  := 15,
+    rCycleTimeS  := 0.1         // 100ms OB cycle
+);
+
+rFiltered := fbFilter.rOutput;
+```
+
+---
+
+## Circular Buffer Architecture
+
+All array-based filters use a **circular (ring) buffer** pattern:
+
+```
+Buffer: [ 12.4 | 13.1 | 12.8 | 13.0 | 12.6 ]
+                  ↑ Index pointer (oldest slot, next to overwrite)
+
+New sample arrives → overwrite oldest → advance index
+No shifting, O(1) write per scan
+```
+
+This ensures constant, predictable scan-time contribution regardless of window size.
+
+---
+
+## Signal Flow Diagram
+
+```
+Analog Input Card
+      │
+      ▼
+ ┌─────────────┐
+ │  Raw REAL   │  e.g. 0.0 – 100.0 (engineering units, already scaled)
+ └──────┬──────┘
+        │
+        ▼
+ ┌─────────────────────────────────────┐
+ │         FB_SignalFilter             │
+ │                                     │
+ │  iMode=1 → FB_MovingAverage         │
+ │  iMode=2 → FB_EMA                   │
+ │  iMode=3 → FB_WMA                   │
+ │  iMode=4 → FB_MedianFilter          │
+ │  iMode=5 → FB_RateLimiter           │
+ └──────────────────┬──────────────────┘
+                    │
+                    ▼
+             rOutput (REAL)
+                    │
+          ┌─────────┴──────────┐
+          ▼                    ▼
+     PID Controller        HMI / SCADA
+```
+
+---
+
+## Integration Notes
+
+- **Analog scaling:** All FBs operate on pre-scaled REAL values in engineering units (°C, bar, %, m³/h, etc.). Scale your analog input before passing to any filter FB.
+- **First scan:** On the first scan after `xEnable` goes TRUE, output equals input. No startup spike.
+- **Mode switching:** Changing `iMode` at runtime resets the newly selected filter on its next call. A brief transient (1–2 scan cycles) may occur.
+- **Cycle time:** Only `FB_RateLimiter` is cycle-time sensitive. All other filters are cycle-time agnostic — window size implicitly defines the time constant based on your OB period.
+
+---
+
+## Related Libraries
+
+This library pairs naturally with:
+
+- **`FB_StateAlarmManager`** — State-based alarm management with bitmask suppression, hysteresis, on-delay, and priority. Feed filtered signals into alarm manager for dramatically fewer nuisance alarms.
+- **`FB_CUSUM`** *(planned)* — Cumulative sum control chart for slow drift detection
+- **`FB_KalmanFilter`** *(planned)* — State estimation and sensor validation
+
+---
+
+## License
+
+Internal use. Adapt freely for your project.  
+Tested on: **S7-1500 CPU 1515-2 PN**, TIA Portal V18.
+
+---
+
+*Generated for S7-1500 SCL Signal Filtering Library — Advanced Process Control Series*
\ No newline at end of file