mqtty 0.1.0__tar.gz

mqtty-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install build dependencies
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mqtty-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025, Mark Featherston
+
+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.
+

mqtty-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: mqtty
+Version: 0.1.0
+Summary: Bridges MQTT topics to a pseudo-terminal device
+Author-email: Mark Featherston <mark@embeddedTS.com>
+Project-URL: homepage, https://github.com/embeddedts/mqtty
+Project-URL: bugs, https://github.com/embeddedts/mqtty/issues
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paho-mqtt
+Dynamic: license-file
+
+# mqtty
+
+`mqtty` bridges an MQTT topic to a local pseudoterminal (PTY), allowing you to interact with serial ports over MQTT as if they were local TTY devices.
+
+This is useful for debugging, automation, or tunneling serial communication through a networked MQTT broker.
+
+## Usage
+
+```bash
+mqtty mqtt://<host>/<topic> [--pts-only | --wrap-picocom]
+```
+
+You must choose one of the two modes:
+
+* `--pts-only`, `-p`:
+  Print the path to the PTS device and keep it open. Useful for tools or scripts that want to use the virtual serial port.
+
+* `--wrap-picocom`, `-w`:
+  Launch `picocom --quiet` attached to the PTS device. This allows interactive use of a remote serial port over MQTT.
+
+The `<topic>` segment of the URI is used as the base path for MQTT messages:
+
+* `.../device_serial_input` receives data from your local PTY (sent to the device)
+* `.../device_serial_output` sends incoming data from the device to your PTY
+
+## Example
+
+```bash
+mqtty mqtt://broker.local/mydevice --wrap-picocom
+```
+
+This opens a local PTS device, bridges it to `mydevice/device_serial_input` and `mydevice/device_serial_output`, and launches `picocom` on the virtual port.
+
+## License
+
+MIT

mqtty-0.1.0/README.md

@@ -0,0 +1,36 @@
+# mqtty
+
+`mqtty` bridges an MQTT topic to a local pseudoterminal (PTY), allowing you to interact with serial ports over MQTT as if they were local TTY devices.
+
+This is useful for debugging, automation, or tunneling serial communication through a networked MQTT broker.
+
+## Usage
+
+```bash
+mqtty mqtt://<host>/<topic> [--pts-only | --wrap-picocom]
+```
+
+You must choose one of the two modes:
+
+* `--pts-only`, `-p`:
+  Print the path to the PTS device and keep it open. Useful for tools or scripts that want to use the virtual serial port.
+
+* `--wrap-picocom`, `-w`:
+  Launch `picocom --quiet` attached to the PTS device. This allows interactive use of a remote serial port over MQTT.
+
+The `<topic>` segment of the URI is used as the base path for MQTT messages:
+
+* `.../device_serial_input` receives data from your local PTY (sent to the device)
+* `.../device_serial_output` sends incoming data from the device to your PTY
+
+## Example
+
+```bash
+mqtty mqtt://broker.local/mydevice --wrap-picocom
+```
+
+This opens a local PTS device, bridges it to `mydevice/device_serial_input` and `mydevice/device_serial_output`, and launches `picocom` on the virtual port.
+
+## License
+
+MIT

mqtty-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61.0", "setuptools-scm"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mqtty"
+description = "Bridges MQTT topics to a pseudo-terminal device"
+readme = "README.md"
+authors = [
+    {name = "Mark Featherston", email = "mark@embeddedTS.com"}
+]
+dependencies = [
+    "paho-mqtt"
+]
+
+dynamic = ["version"]
+
+[tool.setuptools_scm]
+version_scheme = "guess-next-dev"
+local_scheme = "node-and-date"
+
+[project.urls]
+homepage = "https://github.com/embeddedts/mqtty"
+bugs = "https://github.com/embeddedts/mqtty/issues"
+
+[project.scripts]
+mqtty = "mqtty.mqtty:main"
+
+[tool.mypy]
+files = "."
+# Use strict defaults
+strict = true
+warn_unreachable = true
+warn_no_return = true
+
+[tool.ruff]
+line-length = 120

mqtty-0.1.0/setup.cfg

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

mqtty-0.1.0/src/mqtty/.vscode-ctags

@@ -0,0 +1,22 @@
+!_TAG_EXTRA_DESCRIPTION	anonymous	/Include tags for non-named objects like lambda/
+!_TAG_EXTRA_DESCRIPTION	fileScope	/Include tags of file scope/
+!_TAG_EXTRA_DESCRIPTION	pseudo	/Include pseudo tags/
+!_TAG_EXTRA_DESCRIPTION	subparser	/Include tags generated by subparsers/
+!_TAG_FIELD_DESCRIPTION	epoch	/the last modified time of the input file (only for F\/file kind tag)/
+!_TAG_FIELD_DESCRIPTION	file	/File-restricted scoping/
+!_TAG_FIELD_DESCRIPTION	input	/input file/
+!_TAG_FIELD_DESCRIPTION	name	/tag name/
+!_TAG_FIELD_DESCRIPTION	pattern	/pattern/
+!_TAG_FIELD_DESCRIPTION	typeref	/Type and name of a variable or typedef/
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_OUTPUT_EXCMD	mixed	/number, pattern, mixed, or combineV2/
+!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
+!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
+!_TAG_OUTPUT_VERSION	0.0	/current.age/
+!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
+!_TAG_PROC_CWD	/home/mark/Downloads/tmp/mqtt2pty/src/mqtt2pty/	//
+!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
+!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+!_TAG_PROGRAM_VERSION	6.0.0	//

mqtty-0.1.0/src/mqtty/mqtty.py

@@ -0,0 +1,152 @@
+import os
+import pty
+import select
+import threading
+from typing import Any, Dict, Optional, Literal
+from paho.mqtt.client import Client, MQTTMessage
+from paho.mqtt.properties import Properties
+from paho.mqtt.reasoncodes import ReasonCode
+from paho.mqtt.enums import CallbackAPIVersion
+from urllib.parse import urlparse
+import sys
+import argparse
+import subprocess
+import signal
+
+
+class MQTTY:
+    def __init__(self, mqtt_uri: str) -> None:
+        self.mqtt_uri = urlparse(mqtt_uri)
+
+        if self.mqtt_uri.scheme not in ["mqtt", "ws", "wss"]:
+            raise ValueError("Invalid URI scheme. Expected 'mqtt://', 'ws://', or 'wss://'.")
+
+        self.mqtt_host = self.mqtt_uri.hostname
+        self.mqtt_port = self.mqtt_uri.port or (443 if self.mqtt_uri.scheme == "wss" else 80)
+        self.mqtt_transport: Literal["tcp", "websockets"] = (
+            "websockets" if self.mqtt_uri.scheme in ["ws", "wss"] else "tcp"
+        )
+
+        base_path = self.mqtt_uri.path.lstrip("/")  # Remove leading slash from path
+        self.device_serial_input_topic = f"{base_path}/device_serial_input"
+        self.device_serial_output_topic = f"{base_path}/device_serial_output"
+
+        self.mqtt_client = Client(
+            transport=self.mqtt_transport,
+            callback_api_version=CallbackAPIVersion.VERSION2,
+        )
+
+        self.master_fd, self.slave_fd = pty.openpty()
+        self.slave_name = os.ttyname(self.slave_fd)
+
+        self.connected = False
+        self.stop_event = threading.Event()
+
+    def on_message(self, _client: Client, _userdata: object, msg: MQTTMessage) -> None:
+        try:
+            os.write(self.master_fd, msg.payload)
+        except Exception as e:
+            sys.stderr.write(f"Error writing to PTY: {e}\n")
+
+    def mqtt_connect(self) -> None:
+        self.mqtt_client.on_message = self.on_message
+
+        def on_connect(
+            client: Client,
+            userdata: Any,
+            flags: Dict[str, Any],
+            reason_code: ReasonCode,
+            properties: Optional[Properties],
+        ) -> None:
+            if reason_code == 0:
+                self.connected = True
+                client.subscribe(self.device_serial_output_topic)
+            else:
+                sys.stderr.write(f"Failed to connect to MQTT broker, return code {reason_code}\n")
+
+        def on_disconnect(
+            client: Client,
+            userdata: Any,
+            reason_code: ReasonCode | int | None,
+            properties: Optional[Properties],
+            packet_from_broker: object,
+        ) -> None:
+            self.connected = False
+
+        self.mqtt_client.on_connect = on_connect
+        self.mqtt_client.on_disconnect = on_disconnect
+
+        if self.mqtt_host is None:
+            raise ValueError("MQTT URI must include a hostname.")
+        try:
+            self.mqtt_client.connect_async(self.mqtt_host, self.mqtt_port)
+            self.mqtt_client.loop_forever()
+        except Exception as e:
+            sys.stderr.write(f"MQTT connection failed: {e}\n")
+
+    def pty_to_mqtt(self) -> None:
+        while not self.stop_event.is_set():
+            try:
+                ready, _, _ = select.select([self.master_fd], [], [], 1)
+                if self.master_fd in ready:
+                    data = os.read(self.master_fd, 1024)
+                    if self.connected:
+                        self.mqtt_client.publish(self.device_serial_input_topic, data)
+            except Exception as e:
+                sys.stderr.write(f"Error reading from PTY: {e}\n")
+                break
+
+    def start_threads(self) -> None:
+        mqtt_thread = threading.Thread(target=self.mqtt_connect, daemon=True)
+        mqtt_thread.start()
+
+        pty_thread = threading.Thread(target=self.pty_to_mqtt, daemon=True)
+        pty_thread.start()
+
+    def shutdown(self) -> None:
+        self.stop_event.set()
+        self.mqtt_client.loop_stop()
+        self.mqtt_client.disconnect()
+        os.close(self.master_fd)
+        os.close(self.slave_fd)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="MQTTY: Bridge MQTT to PTY.")
+    parser.add_argument("mqtt_uri", help="MQTT URI (e.g., mqtt://broker/topic)")
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument(
+        "-p",
+        "--pts-only",
+        action="store_true",
+        help="Only create and expose the PTS device",
+    )
+    group.add_argument(
+        "-w",
+        "--wrap-picocom",
+        action="store_true",
+        help="Wrap and run picocom on the PTS device",
+    )
+    args = parser.parse_args()
+
+    try:
+        bridge = MQTTY(args.mqtt_uri)
+        if args.pts_only:
+            print(bridge.slave_name, flush=True)
+        bridge.start_threads()
+
+        if args.pts_only:
+            signal.signal(signal.SIGINT, lambda sig, frame: bridge.shutdown())
+            signal.pause()  # Wait until interrupted
+        elif args.wrap_picocom:
+            try:
+                subprocess.run(["picocom", "--quiet", bridge.slave_name])
+            finally:
+                bridge.shutdown()
+
+    except ValueError as e:
+        sys.stderr.write(f"Error: {e}\n")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: mqtty
+Version: 0.1.0
+Summary: Bridges MQTT topics to a pseudo-terminal device
+Author-email: Mark Featherston <mark@embeddedTS.com>
+Project-URL: homepage, https://github.com/embeddedts/mqtty
+Project-URL: bugs, https://github.com/embeddedts/mqtty/issues
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paho-mqtt
+Dynamic: license-file
+
+# mqtty
+
+`mqtty` bridges an MQTT topic to a local pseudoterminal (PTY), allowing you to interact with serial ports over MQTT as if they were local TTY devices.
+
+This is useful for debugging, automation, or tunneling serial communication through a networked MQTT broker.
+
+## Usage
+
+```bash
+mqtty mqtt://<host>/<topic> [--pts-only | --wrap-picocom]
+```
+
+You must choose one of the two modes:
+
+* `--pts-only`, `-p`:
+  Print the path to the PTS device and keep it open. Useful for tools or scripts that want to use the virtual serial port.
+
+* `--wrap-picocom`, `-w`:
+  Launch `picocom --quiet` attached to the PTS device. This allows interactive use of a remote serial port over MQTT.
+
+The `<topic>` segment of the URI is used as the base path for MQTT messages:
+
+* `.../device_serial_input` receives data from your local PTY (sent to the device)
+* `.../device_serial_output` sends incoming data from the device to your PTY
+
+## Example
+
+```bash
+mqtty mqtt://broker.local/mydevice --wrap-picocom
+```
+
+This opens a local PTS device, bridges it to `mydevice/device_serial_input` and `mydevice/device_serial_output`, and launches `picocom` on the virtual port.
+
+## License
+
+MIT

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

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+.github/workflows/release.yml
+src/mqtty/.vscode-ctags
+src/mqtty/mqtty.py
+src/mqtty.egg-info/PKG-INFO
+src/mqtty.egg-info/SOURCES.txt
+src/mqtty.egg-info/dependency_links.txt
+src/mqtty.egg-info/entry_points.txt
+src/mqtty.egg-info/requires.txt
+src/mqtty.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

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

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

@@ -0,0 +1 @@
+paho-mqtt

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

@@ -0,0 +1 @@
+mqtty