mqtt325 0.1.0__tar.gz

mqtt325-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Osthege
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mqtt325-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: mqtt325
+Version: 0.1.0
+Summary: Republishes MQTT v3 messages as retained MQTT v5 messages.
+Author-email: Michael Osthege <michael.osthege@outlook.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paho-mqtt>=2.1.0
+Dynamic: license-file
+
+[![PyPI version](https://img.shields.io/pypi/v/mqtt325)](https://pypi.org/project/mqtt325)
+[![pipeline](https://github.com/michaelosthege/mqtt325/workflows/pipeline/badge.svg)](https://github.com/michaelosthege/mqtt325/actions)
+
+# MQTT 3 → 5
+
+This small Python app provides MQTT message re-routing to create retained messages from devices
+that don't implement MQTT v5 themselves.
+
+## Installation
+
+```bash
+pip install mqtt325
+```
+
+## Configuration
+
+Configure these environment variables:
+
+* `MQTT_HOST`
+* `MQTT_PORT` (optional)
+* `MQTT_USER` (optional)
+* `MQTT_PASSWORD` (optional)
+* `MQTT_TLS_CHAIN` (optional PEM encoded certificate chain of the broker)
+* `MQTT325_CONFIG_PATH` (optional path to a [`config.py` file](src/mqtt325/config.py) to use instead of the default)

mqtt325-0.1.0/README.md

@@ -0,0 +1,24 @@
+[![PyPI version](https://img.shields.io/pypi/v/mqtt325)](https://pypi.org/project/mqtt325)
+[![pipeline](https://github.com/michaelosthege/mqtt325/workflows/pipeline/badge.svg)](https://github.com/michaelosthege/mqtt325/actions)
+
+# MQTT 3 → 5
+
+This small Python app provides MQTT message re-routing to create retained messages from devices
+that don't implement MQTT v5 themselves.
+
+## Installation
+
+```bash
+pip install mqtt325
+```
+
+## Configuration
+
+Configure these environment variables:
+
+* `MQTT_HOST`
+* `MQTT_PORT` (optional)
+* `MQTT_USER` (optional)
+* `MQTT_PASSWORD` (optional)
+* `MQTT_TLS_CHAIN` (optional PEM encoded certificate chain of the broker)
+* `MQTT325_CONFIG_PATH` (optional path to a [`config.py` file](src/mqtt325/config.py) to use instead of the default)

mqtt325-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=62.6"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mqtt325"
+version = "0.1.0"
+description = "Republishes MQTT v3 messages as retained MQTT v5 messages."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    {name = "Michael Osthege", email = "michael.osthege@outlook.com"},
+]
+classifiers = [
+    "Programming Language :: Python",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+dependencies = [
+    "paho-mqtt>=2.1.0",
+]
+
+[dependency-groups]
+dev = [
+    "build>=1.2.2.post1",
+    "pre-commit",
+    "pytest>=8.3.5",
+    "pytest-cov>=6.0.0",
+    "twine>=6.1.0",
+]
+
+[project.scripts]
+mqtt325 = "mqtt325.main:run"

mqtt325-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mqtt325-0.1.0/src/mqtt325/__init__.py

@@ -0,0 +1,3 @@
+import importlib.metadata
+
+__version__ = importlib.metadata.version(__package__ or __name__)

mqtt325-0.1.0/src/mqtt325/config.py

@@ -0,0 +1,13 @@
+from mqtt325.models import AppConfig, Heartbeat, Retainer
+
+config = AppConfig(
+    availability_topic="availability/mqtt325",
+    heartbeat_routes=[
+        # Process anything under heartbeat/ into an availability message
+        Heartbeat("heartbeat/#", "availability/#"),
+    ],
+    retain_routes=[
+        Retainer("retain/#", "#"),
+    ],
+)
+"""Programmatic configuration, must be called "config" at module level."""

mqtt325-0.1.0/src/mqtt325/main.py

@@ -0,0 +1,155 @@
+import asyncio
+import importlib
+import logging
+import os
+from pathlib import Path
+
+import paho.mqtt.client as mqtt
+from paho.mqtt.packettypes import PacketTypes
+from paho.mqtt.reasoncodes import ReasonCode
+
+from mqtt325.models import AppConfig
+
+logger = logging.getLogger(__name__)
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s %(message)s", datefmt="%Y-%m-%d %H:%M:%S"
+)
+
+
+# required
+MQTT_HOST = os.environ["MQTT_HOST"]
+# optional
+MQTT_PORT = int(os.environ.get("MQTT_PORT", 1883))
+MQTT_USER = os.environ.get("MQTT_USER")
+MQTT_PASSWORD = os.environ.get("MQTT_PASSWORD")
+MQTT_TLS_CHAIN = os.environ.get("MQTT_TLS_CHAIN")
+MQTT325_CONFIG_PATH = os.environ.get(
+    "MQTT325_CONFIG", str(Path(__file__).parent.absolute() / "config.py")
+)
+
+
+class Mqtt325App:
+    def __init__(self, config: AppConfig):
+        self.config = config
+
+    def on_connect(
+        self,
+        mqttc: mqtt.Client,
+        userdata,
+        flags: mqtt.ConnectFlags,
+        reason_code: ReasonCode,
+        properties,
+    ):
+        if reason_code == 0:
+            logger.info("Connected. Subscribing...")
+            for rr in self.config.retain_routes:
+                logger.debug(
+                    "Subscribing (%s) to match (%s) and retain at (%s)",
+                    rr.input_topic,
+                    rr.input_pattern,
+                    rr.output_topic,
+                )
+                mqttc.subscribe(rr.input_topic)
+            for hb in self.config.heartbeat_routes:
+                logger.debug(
+                    "Subscribing (%s) to match (%s) and publish ONLINE/OFFLINE at (%s)",
+                    hb.input_topic,
+                    hb.input_pattern,
+                    hb.output_topic,
+                )
+                mqttc.subscribe(hb.input_topic)
+            logger.info("Subscriptions done.")
+            mqttc.publish(self.config.availability_topic, "ONLINE")
+        else:
+            logger.warning("Connection failed with reason code %s", reason_code)
+        return
+
+    def on_disconnect(
+        self,
+        client: mqtt.Client,
+        userdata,
+        flags: mqtt.ConnectFlags,
+        reason_code: ReasonCode,
+        properties,
+    ):
+        if reason_code == 0:
+            logger.info("Disconnected gracefully.")
+        elif reason_code > 0:
+            logger.warning("Disonnected unseccessfully. Reason code %s", reason_code)
+        return
+
+    def on_message(self, client: mqtt.Client, userdata, message: mqtt.MQTTMessage):
+        top = message.topic
+
+        logger.info("IN (%s)", top)
+        # process retention routes
+        for rr in self.config.retain_routes:
+            if ptopic := rr.to_output_topic(top):
+                logger.info("⏩ (%s) → (%s)", top, ptopic)
+                client.publish(ptopic, message.payload, retain=True)
+        # process heartbeats into ONLINE messages
+        for hb in self.config.heartbeat_routes:
+            if ptopic := hb.to_output_topic(top):
+                logger.info("💚 (%s) → (%s)", top, ptopic)
+                hb.register_beat(top)
+                client.publish(ptopic, "ONLINE", retain=True)
+        return
+
+    def process_lost_heartbeats(self, client: mqtt.Client):
+        for hb in self.config.heartbeat_routes:
+            for src in hb.yield_timed_out():
+                # beats are only registered from messages that match
+                # this heartbeat route, therefore the publish topic
+                # will always be available:
+                ptopic = hb.to_output_topic(src)
+                assert ptopic is None
+                logger.info("💔 (%s) → (%s) OFFLINE", src)
+                client.publish(ptopic, "OFFLINE")
+        return
+
+    async def run_async(self):
+        logger.info("Connecting MQTT to %s:%s", MQTT_HOST, MQTT_PORT)
+        client = mqtt.Client(
+            client_id="mqtt-325",
+            callback_api_version=mqtt.CallbackAPIVersion.VERSION2,
+        )
+        if MQTT_USER and MQTT_PASSWORD:
+            client.username_pw_set(MQTT_USER, MQTT_PASSWORD)
+        if MQTT_TLS_CHAIN:
+            client.tls_set(ca_certs=os.environ["MQTT_TLS_CHAIN"])
+        client.will_set(self.config.availability_topic, "OFFLINE")
+        client.connect(MQTT_HOST, MQTT_PORT, keepalive=5)
+        client.on_connect = self.on_connect
+        client.on_disconnect = self.on_disconnect
+        client.on_message = self.on_message
+
+        logger.info("Starting MQTT loop")
+        client.loop_start()
+        while True:
+            try:
+                self.process_lost_heartbeats(client)
+                await asyncio.sleep(1)
+            except (asyncio.CancelledError, KeyboardInterrupt):
+                logger.info("Shutting down...")
+                # Disconnect asking the server to publish the last will message
+                client.disconnect(ReasonCode(PacketTypes.DISCONNECT, "Disconnect", 4))
+                client.loop_stop()
+                break
+            except Exception:
+                logger.error("Error encountered.", exc_info=True)
+        return
+
+
+def run():
+    logger.info("⚙️ Importing config from '%s'", MQTT325_CONFIG_PATH)
+    config_module = importlib.machinery.SourceFileLoader(
+        "config", MQTT325_CONFIG_PATH
+    ).load_module()
+    config: AppConfig = getattr(config_module, "config")
+    app = Mqtt325App(config)
+    asyncio.run(app.run_async())
+    logger.info("Exiting.")
+
+
+if __name__ == "__main__":
+    run()

mqtt325-0.1.0/src/mqtt325/models.py

@@ -0,0 +1,80 @@
+"""Data models for mqtt325 app configuration."""
+
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Generator, Sequence
+
+
+@dataclass
+class Retainer:
+    """Base type of message retention router."""
+
+    input_topic: str
+    """Topic to subscribe.
+
+    Optionally use `+` where to expect the client ID.
+    Optionally append `#` to match any subtopic.
+    """
+
+    output_topic: str
+    """Where to publish retained messages."""
+
+    def __post_init__(self):
+        if self.input_topic == self.output_topic:
+            raise ValueError("Input and output topic must be different.")
+
+    @property
+    def input_pattern(self) -> str:
+        """RegEx pattern to match topics of actual messages."""
+        ip = self.input_topic.replace("+", r"(?P<client_id>.+?)")
+        ip = ip.replace("#", r"(?P<subtopics>.+?)")
+        return ip + "$"
+
+    def to_output_topic(self, in_topic: str) -> str | None:
+        """Determine the publish topic by matching the message topic with the ``input_pattern``."""
+        cmatch = re.match(self.input_pattern, in_topic)
+        out = None
+        if cmatch:
+            out = self.output_topic
+            gd = cmatch.groupdict()
+            if client_id := gd.get("client_id"):
+                out = out.replace("+", client_id)
+            if subtopics := gd.get("subtopics"):
+                out = out.replace("#", subtopics)
+        return out
+
+
+@dataclass
+class Heartbeat(Retainer):
+    """Sends retained ONLINE/OFFLINE messages to based on activity in the input topic."""
+
+    timeout: int = 15
+    """Seconds to wait before sending OFFLINE to the output topic."""
+
+    _beats: dict[str, float] = field(default_factory=dict)
+
+    def register_beat(self, source_topic: str):
+        """Register a heartbeat from a matching source topic."""
+        self._beats[source_topic] = time.time()
+
+    def yield_timed_out(self) -> Generator[str, None, None]:
+        """Iterate timed-out source topics, removing them from the cache."""
+        buffer = dict(self._beats)
+        for src, last_beat in buffer.items():
+            if time.time() > last_beat + self.timeout:
+                yield src
+                self._beats.pop(src)
+        return
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    availability_topic: str
+    """Where the app will publish ONLINE/OFFLINE as retained messages."""
+
+    heartbeat_routes: Sequence[Heartbeat]
+    """List of heartbeat routing configurations."""
+
+    retain_routes: Sequence[Retainer]
+    """Routes for re-publishing with message retention without altering the payload."""

mqtt325-0.1.0/src/mqtt325.egg-info/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: mqtt325
+Version: 0.1.0
+Summary: Republishes MQTT v3 messages as retained MQTT v5 messages.
+Author-email: Michael Osthege <michael.osthege@outlook.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paho-mqtt>=2.1.0
+Dynamic: license-file
+
+[![PyPI version](https://img.shields.io/pypi/v/mqtt325)](https://pypi.org/project/mqtt325)
+[![pipeline](https://github.com/michaelosthege/mqtt325/workflows/pipeline/badge.svg)](https://github.com/michaelosthege/mqtt325/actions)
+
+# MQTT 3 → 5
+
+This small Python app provides MQTT message re-routing to create retained messages from devices
+that don't implement MQTT v5 themselves.
+
+## Installation
+
+```bash
+pip install mqtt325
+```
+
+## Configuration
+
+Configure these environment variables:
+
+* `MQTT_HOST`
+* `MQTT_PORT` (optional)
+* `MQTT_USER` (optional)
+* `MQTT_PASSWORD` (optional)
+* `MQTT_TLS_CHAIN` (optional PEM encoded certificate chain of the broker)
+* `MQTT325_CONFIG_PATH` (optional path to a [`config.py` file](src/mqtt325/config.py) to use instead of the default)

mqtt325-0.1.0/src/mqtt325.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/mqtt325/__init__.py
+src/mqtt325/config.py
+src/mqtt325/main.py
+src/mqtt325/models.py
+src/mqtt325.egg-info/PKG-INFO
+src/mqtt325.egg-info/SOURCES.txt
+src/mqtt325.egg-info/dependency_links.txt
+src/mqtt325.egg-info/entry_points.txt
+src/mqtt325.egg-info/requires.txt
+src/mqtt325.egg-info/top_level.txt
+tests/test_matching.py

mqtt325-0.1.0/src/mqtt325.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mqtt325-0.1.0/src/mqtt325.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mqtt325 = mqtt325.main:run

mqtt325-0.1.0/src/mqtt325.egg-info/requires.txt

@@ -0,0 +1 @@
+paho-mqtt>=2.1.0

mqtt325-0.1.0/src/mqtt325.egg-info/top_level.txt

@@ -0,0 +1 @@
+mqtt325

mqtt325-0.1.0/tests/test_matching.py

@@ -0,0 +1,68 @@
+import pytest
+
+from mqtt325.models import Retainer
+
+
+def test_no_identical_in_out_topics():
+    with pytest.raises(ValueError, match="must be different"):
+        Retainer("foo/+/sub/#", "foo/+/sub/#")
+    pass
+
+
+def test_with_clientid_proxying():
+    r = Retainer(
+        input_topic="some/+/subtopic",
+        output_topic="proxied/some/+/subtopic",
+    )
+    assert (
+        r.to_output_topic("some/client_id/subtopic")
+        == "proxied/some/client_id/subtopic"
+    )
+    pass
+
+
+def test_withclientid_level_reorder():
+    r = Retainer(
+        input_topic="some/+/subtopic",
+        output_topic="+/some/subtopic",
+    )
+    assert r.to_output_topic("some/client_id/subtopic") == "client_id/some/subtopic"
+    pass
+
+
+def test_no_clientid_proxying():
+    r = Retainer(
+        input_topic="some/subtopic",
+        output_topic="another/subtopic",
+    )
+    assert r.to_output_topic("some/subtopic") == "another/subtopic"
+    pass
+
+
+def test_drop_clientid():
+    r = Retainer(
+        input_topic="some/+/subtopic",
+        output_topic="another/subtopic",
+    )
+    assert r.to_output_topic("some/cid/subtopic") == "another/subtopic"
+    pass
+
+
+def test_wildcard_only():
+    r = Retainer(
+        input_topic="any/#",
+        output_topic="other/#",
+    )
+    assert r.to_output_topic("any/subtopic") == "other/subtopic"
+    assert r.to_output_topic("any/sub/subtopic") == "other/sub/subtopic"
+    pass
+
+
+def test_clientid_and_wildcard():
+    r = Retainer(
+        input_topic="any/+/#",
+        output_topic="other/+/foo/#",
+    )
+    assert r.to_output_topic("any/cid/subtopic") == "other/cid/foo/subtopic"
+    assert r.to_output_topic("any/cid/sub/subtopic") == "other/cid/foo/sub/subtopic"
+    pass