filter

Overview

The filter node (also known as RBE - Report By Exception) blocks messages unless the value has changed. Essential for reducing noise from sensors that constantly report the same value, saving bandwidth and processing.

Properties

Filter Modes

In:  25 25 25 26 26 25 25
Out: 25 ── ── 26 ── 25 ──

// Gap: 2
In:  25 25.5 26 27 28 27.5
Out: 25 ─── ── 27 ── ────

// Gap: 2 (spike filter)
In:  25 25.5 26 30 26.5 27
Out: 25 25.5 26 ── 26.5 27

Example: Temperature Sensor Noise

Reduce noise from temperature sensor that fluctuates by ±0.5°C.

// Filter node configuration - Deadband mode
{
  "func": "deadband",
  "property": "payload",
  "gap": 1,           // Only pass if change > 1°C
  "septopics": true   // Track each sensor separately
}

// Input sequence from sensor:
// 22.1 → 22.3 → 22.0 → 22.5 → 23.2 → 23.0 → 24.5
//  ↓       ✗       ✗       ✗       ↓       ✗       ↓
// 22.1                           23.2            24.5

// Result: 70% reduction in messages while preserving significant changes

Example: Motion Sensor Change Detection

Only trigger on motion state changes, not repeated detections.

// Filter node configuration - RBE mode
{
  "func": "rbe",
  "property": "payload",
  "septopics": true
}

// PIR sensor continuously reports:
// Input:  0, 0, 0, 1, 1, 1, 1, 1, 0, 0, 0
// Output: 0 ─────→ 1 ─────────→ 0
//         (only state changes pass through)

// Perfect for:
// - "Motion started" notification on 0→1
// - "Motion ended" notification on 1→0

Example: Multiple Sensors (Topic Separation)

Track each sensor independently using msg.topic.

// Filter node with septopics: true

// Sensor 1 (topic: "sensor/kitchen")
// 25°C → 25°C → 26°C → 26°C
// ↓ (first)   ↓ (changed)
// 25°C         26°C

// Sensor 2 (topic: "sensor/bedroom")
// 22°C → 22°C → 22°C → 23°C
// ↓ (first)            ↓ (changed)
// 22°C                  23°C

// Each topic maintains its own "last value"

Percentage-Based Deadband

Use percentage change instead of absolute value.

// Filter node configuration
{
  "func": "deadband",
  "gap": "5%"         // Only pass if change > 5%
}

// Example with varying base values:
// Value: 100 → 103 → 106 → 108 → 115
//              ✗      ↓      ✗      ↓
//                    106           115

// 5% of 100 = 5, so 103 is blocked (only 3% change)
// 106 passes (6% change from 100)
// 115 passes (8.5% change from 106)

Common Use Cases