Adaptive filtering library for Time-of-Flight (ToF) distance sensors (VL53L0X, VL53L1X, etc.).
It allows flexible noise reduction and stabilization of raw distance data.

The library includes several optional filters (all disabled by default).
You can enable each one individually if needed.

• Median filter (always ON) → removes single-sample spikes.
• Offset calibration → correct sensor bias.
• Range validation → clamp or reject invalid values.
• Publish interval → ensures stable update rate.
• Optional filters (disabled by default):
  • Alpha/EMA smoothing (with log-sigmoid adaptive curve).
  • Deadband (ignore tiny variations).
  • DeltaNorm (normalize reactivity to changes).
  • Stability lock (freeze value when no motion is detected).
  • Percent filter (ignore small relative changes at long distances).
• Returns distance in meters or NAN if out of range.

1. Copy this folder into your Arduino libraries/ directory.
2. Restart Arduino IDE.
3. Include with:

   #include <ToFFilter.h>

Examples are included in the examples/ folder

Open them directly from Arduino IDE → File → Examples → ToFFilter.

• Purpose: Constant calibration offset.
• Always applied.
• Default: 10 mm.
• Usage:

  tofFilter.setOffset(15);

• Purpose: Define valid measurement range.
• Below minMm → returns 0.0.
• Above maxMm → returns NAN.
• Default: 15 – 2000 mm.
• Usage:

  tofFilter.setRangeLimits(20, 3000);

• Purpose: Minimum time between published results.
• Prevents flooding cloud/serial with too many updates.
• Default: 200 ms.
• Usage:

  tofFilter.setPublishInterval(500); // 2 Hz max

• Purpose: Enable/disable EMA smoothing.
• Disabled by default.
• minAlpha → small updates when stable.
• maxAlpha → fast updates on rapid change.
• Usage:

  tofFilter.setAlpha(true, 0.015f, 0.75f); // enable EMA
  tofFilter.setAlpha(false);               // completely disable

• Purpose: Ignore tiny changes within ±deadband mm.
• Disabled by default.
• Usage:

  tofFilter.setDeadband(true, 30); // enable
  tofFilter.setDeadband(false);    // disable

• Purpose: Normalize responsiveness to movement.
• Disabled by default.
• Larger value = smoother, smaller = more reactive.
• Usage:

  tofFilter.setDeltaNorm(true, 70); // enable
  tofFilter.setDeltaNorm(false);    // disable

• Purpose: Freeze value if changes stay below mm for ms milliseconds.
• Disabled by default.
• Usage:

  tofFilter.setStability(true, 50, 3000); // enable freeze after 3s
  tofFilter.setStability(false);          // disable stability lock

• Purpose: Ignore small relative changes at long distances.
• Disabled by default.
• pct = relative threshold (e.g. 0.1 = 10%).
• startMm = distance at which filter activates (default: half of max range).
• Usage:

  tofFilter.setPercentFilter(true, 0.1f, 2000); // active above 2000 mm
  tofFilter.setPercentFilter(false);            // disable

• Input: raw measurement in millimeters (from sensor).
• Output: filtered value in meters (double).
• Returns NAN if out of range.
• Returns 0.0 if below minimum valid range.

• Works best with VL53L0X/VL53L1X in continuous mode (startContinuous(0)).
• Adjust setDeltaNorm and setDeadband for your environment (indoor/outdoor, reflective surfaces).
• Calibration: put a white target at known distance (e.g. 100 mm), measure offset, set via setOffset().

If you don’t want to fine-tune every parameter, you can use ready presets:

Good for quick reaction (e.g. gesture sensing, parking).

tofFilter.setOffset(10);
tofFilter.setRangeLimits(15, 2000);
tofFilter.setPublishInterval(100);

tofFilter.setAlpha(true, 0.05f, 0.8f);
tofFilter.setDeadband(true, 2);
tofFilter.setDeltaNorm(true, 40);

For tanks, room monitoring, stable targets.

tofFilter.setOffset(10);
tofFilter.setRangeLimits(15, 4000);
tofFilter.setPublishInterval(500);

tofFilter.setAlpha(true, 0.01f, 0.4f);
tofFilter.setDeadband(true, 10);
tofFilter.setDeltaNorm(true, 100);
tofFilter.setStability(true, 30, 5000);

For very long distances where percent filter helps.

tofFilter.setOffset(10);
tofFilter.setRangeLimits(15, 4000);
tofFilter.setPublishInterval(300);

tofFilter.setAlpha(true, 0.02f, 0.5f);
tofFilter.setDeadband(true, 5);
tofFilter.setDeltaNorm(true, 80);
tofFilter.setPercentFilter(true, 0.1f, 2500);

MIT License