feat: publish NIRO Gen5W research overview and reviewed source examples

backend/php/NiroMqttKeepalive.php

@@ -0,0 +1,31 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Tracks the MQTT client keepalive independently from inbound broker traffic.
+ *
+ * MQTT keepalive is a client-to-broker obligation. Receiving a continuous
+ * stream of PUBLISH packets must therefore never postpone the next PINGREQ.
+ */
+final class NiroMqttKeepalive
+{
+    private int $lastPingAt;
+
+    public function __construct(int $connectedAt, private readonly int $intervalSeconds = 15)
+    {
+        if ($intervalSeconds < 1) {
+            throw new InvalidArgumentException('MQTT keepalive interval must be positive');
+        }
+        $this->lastPingAt = $connectedAt;
+    }
+
+    public function isDue(int $now): bool
+    {
+        return $now - $this->lastPingAt >= $this->intervalSeconds;
+    }
+
+    public function markSent(int $now): void
+    {
+        $this->lastPingAt = $now;
+    }
+}