Updates

Author: 27pchrisl

README.md

@@ -170,7 +170,7 @@ $pi->output1()->reset();
 
 ### Monitoring IO Variables
 
-The `DigitalMonitor` will cause the callback to be called whenever the monitored value changes.
+The monitor will cause the callback to be called whenever the monitored value changes.
 
 ```php
 use Flat3\RevPi\Monitors\DigitalMonitor;
@@ -183,6 +183,27 @@ $pi->input1()->monitor(new DigitalMonitor, function($newValue) {
 });
 ```
 
+#### Monitor::debounce
+
+Wraps a callback to fire **only after changes stop** for the given interval (in milliseconds).
+
+```php
+$pi->input1()->monitor(new DigitalMonitor, Monitor::debounce(function($value) {
+    // Handle change after quiet period
+}, 200));
+```
+
+#### Monitor::throttle
+
+Wraps a callback to fire **at most once per interval** (in milliseconds).
+
+```php
+$pi->input1()->monitor(new DigitalMonitor, Monitor::throttle(function($value) {
+    // Handle change no more than every 200ms
+}, 200));
+```
+
+
 ### Process Image (Low-Level)
 
 Get the raw process image interface for advanced access:
@@ -309,13 +330,13 @@ $port = app(\Flat3\RevPi\Interfaces\SerialPort::class); // Usually you want $pi-
 
 ### Monitoring with Custom Monitors
 
-If you want to create a custom monitor (beyond DigitalMonitor):
+If you want to create a custom monitor:
 
 ```php
-use Flat3\RevPi\Interfaces\Monitor;
+use Flat3\RevPi\Monitors\Monitor;
 
-class MyMonitor implements Monitor {
-    public function evaluate(int|bool|null $next): bool {
+class MyMonitor extends Monitor {
+    public function evaluate(int|bool $next): bool {
         // Implement custom transition/action logic here
         // e.g. if crossing a threshold
         // Return true if the monitor has detected sufficient change

src/IO/IO.php

@@ -5,7 +5,7 @@
 namespace Flat3\RevPi\IO;
 
 use Flat3\RevPi\Interfaces\Module;
-use Flat3\RevPi\Interfaces\Monitor;
+use Flat3\RevPi\Monitors\Monitor;
 
 abstract class IO
 {

src/Interfaces/Module.php

@@ -5,6 +5,7 @@
 namespace Flat3\RevPi\Interfaces;
 
 use Flat3\RevPi\Led\LedPosition;
+use Flat3\RevPi\Monitors\Monitor;
 
 /**
  * Interface Module

src/Interfaces/Monitor.php

@@ -7,9 +7,9 @@
 use Flat3\RevPi\Constants;
 use Flat3\RevPi\Events\PollingEvent;
 use Flat3\RevPi\Interfaces\Module as ModuleInterface;
-use Flat3\RevPi\Interfaces\Monitor;
 use Flat3\RevPi\Interfaces\ProcessImage;
 use Flat3\RevPi\Interfaces\SerialPort;
+use Flat3\RevPi\Monitors\Monitor;
 use Illuminate\Support\Facades\Event;
 use Revolt\EventLoop;
 

src/Modules/Module.php

@@ -5,9 +5,8 @@
 namespace Flat3\RevPi\Monitors;
 
 use Flat3\RevPi\Exceptions\NotSupportedException;
-use Flat3\RevPi\Interfaces\Monitor;
 
-class DeadbandMonitor implements Monitor
+class DeadbandMonitor extends Monitor
 {
     protected bool $wasOutside = false;
 

src/Monitors/DeadbandMonitor.php

@@ -4,9 +4,7 @@
 
 namespace Flat3\RevPi\Monitors;
 
-use Flat3\RevPi\Interfaces\Monitor;
-
-class DigitalMonitor implements Monitor
+class DigitalMonitor extends Monitor
 {
     protected int|bool|null $previous = null;
 

src/Monitors/DigitalMonitor.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flat3\RevPi\Monitors;
+
+use Revolt\EventLoop;
+
+abstract class Monitor
+{
+    abstract public function evaluate(int|bool $next): bool;
+
+    public static function debounce(callable $callback, int $milliseconds): callable
+    {
+        $timerId = null;
+
+        return function (...$args) use (&$timerId, $callback, $milliseconds) {
+            if ($timerId !== null) {
+                EventLoop::cancel($timerId);
+            }
+
+            $timerId = EventLoop::delay($milliseconds / 1000, function () use (&$timerId, $callback, $args) {
+                $callback(...$args);
+                $timerId = null;
+            });
+        };
+    }
+
+    public static function throttle(callable $callback, int $milliseconds): callable
+    {
+        $throttling = false;
+
+        return function (...$args) use (&$throttling, $callback, $milliseconds) {
+            if ($throttling) {
+                return;
+            }
+
+            $throttling = true;
+            $callback(...$args);
+
+            EventLoop::delay($milliseconds / 1000, function () use (&$throttling) {
+                $throttling = false;
+            });
+        };
+    }
+}

src/Monitors/Monitor.php

@@ -4,9 +4,7 @@
 
 namespace Flat3\RevPi\Monitors;
 
-use Flat3\RevPi\Interfaces\Monitor;
-
-class MovingAverageMonitor implements Monitor
+class MovingAverageMonitor extends Monitor
 {
     /**
      * @var array<int|bool>

src/Monitors/MovingAverageMonitor.php

@@ -2,9 +2,7 @@
 
 namespace Flat3\RevPi\Monitors;
 
-use Flat3\RevPi\Interfaces\Monitor;
-
-class RangeMonitor implements Monitor
+class RangeMonitor extends Monitor
 {
     public function __construct(protected int|float $min, protected int|float $max) {}