{"id":35710785,"url":"https://github.com/vroomfondel/mqttstuff","last_synced_at":"2026-01-06T04:08:10.990Z","repository":{"id":328546986,"uuid":"1115936706","full_name":"vroomfondel/mqttstuff","owner":"vroomfondel","description":"Lightweight Python utilities for MQTT: easy publish/subscribe wrappers, retained message readers, Tasmota device discovery \u0026 control, Pydantic config, and Docker support","archived":false,"fork":false,"pushed_at":"2025-12-14T12:58:09.000Z","size":11047,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-15T18:03:58.370Z","etag":null,"topics":["docker","home-automation","iot","loguru","mqtt","mqtt-client","mqtt-publisher","mqtt-subscriber","mqtt-utilities","mqtt-wrapper","paho-mqtt","pydantic","python","python3","smart-home","tasmota"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/mqttstuff/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vroomfondel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-13T21:21:35.000Z","updated_at":"2025-12-14T12:58:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vroomfondel/mqttstuff","commit_stats":null,"previous_names":["vroomfondel/mqttstuff"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/vroomfondel/mqttstuff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vroomfondel%2Fmqttstuff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vroomfondel%2Fmqttstuff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vroomfondel%2Fmqttstuff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vroomfondel%2Fmqttstuff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vroomfondel","download_url":"https://codeload.github.com/vroomfondel/mqttstuff/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vroomfondel%2Fmqttstuff/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28221563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-06T02:00:07.049Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","home-automation","iot","loguru","mqtt","mqtt-client","mqtt-publisher","mqtt-subscriber","mqtt-utilities","mqtt-wrapper","paho-mqtt","pydantic","python","python3","smart-home","tasmota"],"created_at":"2026-01-06T04:08:10.128Z","updated_at":"2026-01-06T04:08:10.979Z","avatar_url":"https://github.com/vroomfondel.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![mypy and pytests](https://github.com/vroomfondel/mqttstuff/actions/workflows/mypynpytests.yml/badge.svg)\n![Cumulative Clones](https://img.shields.io/endpoint?logo=github\u0026url=https://gist.githubusercontent.com/vroomfondel/8a315c36125952c9976548dfbf45cb7b/raw/mqttstuff_clone_count.json)\n[![PyPI Downloads](https://static.pepy.tech/personalized-badge/mqttstuff?period=total\u0026units=INTERNATIONAL_SYSTEM\u0026left_color=BLACK\u0026right_color=GREEN\u0026left_text=PyPi+Downloads)](https://pepy.tech/projects/mqttstuff)\n\n[![https://github.com/vroomfondel/mqttstuff/raw/main/Gemini_Generated_Image_mqttstuff_i3269fi3269fi326_250x250.png](https://github.com/vroomfondel/mqttstuff/raw/main/Gemini_Generated_Image_mqttstuff_i3269fi3269fi326_250x250.png)](https://github.com/vroomfondel/mqttstuff)\n\n# MQTTStuff\n\nLightweight helper utilities for working with MQTT via Paho, with convenient wrappers for:\n\n- Connecting and subscribing to topics, including retained-message handling\n- Publishing one or many messages with consistent metadata and timestamps\n- Reading “last/most recent” messages with timeout-based collection and optional type conversion\n- Developer helpers for JSON pretty-printing, deep updates, and logging configuration\n\n- Repository: https://github.com/vroomfondel/mqttstuff\n- Package: `mqttstuff`\n\n## Overview\n\nMQTTStuff provides a higher-level interface over `paho-mqtt` to simplify common patterns:\n\n- A `MosquittoClientWrapper` to configure, connect, subscribe, and publish with minimal boilerplate\n- A `MQTTLastDataReader` utility to retrieve the most recent messages for one or more topics quickly\n- A `MWMqttMessage` normalization data format for sending/receiving data (optional metadata) from/to IOT devices/sensors\n\n## Installation\n\nOptions:\n\n- From source (editable):\n  - `python -m venv .venv \u0026\u0026 source .venv/bin/activate`\n  - `pip install -r requirements-dev.txt`\n  - `pip install -e .`\n\n- Build distributions with Hatch:\n  - `make pypibuild`\n  - Artifacts are created under `dist/`\n\n## Quick Start\n\nSimple publish and subscribe using the wrapper:\n\n```python\nfrom mqttstuff import MosquittoClientWrapper\n\nclient = MosquittoClientWrapper(\n    host=\"localhost\", port=1883, username=\"user\", password=\"pass\",\n    topics=[\"test/topic\"],\n)\n\ndef on_any_message(msg, userdata):\n    # msg is an instance of MWMqttMessage with convenient fields\n    print(msg.topic, msg.value)\n\nclient.set_on_msg_callback(on_any_message, rettype=\"valuemsg\")\nclient.connect_and_start_loop_forever()\n\n# elsewhere or in another process\nclient.publish_one(\"test/topic\", {\"hello\": \"world\"}, retain=False)\n```\n\nRead last retained or recent messages with a timeout:\n\n```python\nfrom mqttstuff import MQTTLastDataReader\n\ndata = MQTTLastDataReader.get_most_recent_data_with_timeout(\n    host=\"localhost\", port=1883, username=\"user\", password=\"pass\",\n    topics=[\"tele/+/STATE\", \"stat/+/STATUS\"],\n    retained=\"only\",  # \"yes\" | \"no\" | \"only\"\n    rettype=\"str_raw\", # or \"json\", \"valuemsg\", \"str\", \"int\", \"float\"\n)\nprint(data)\n```\n\n## Notes on configuration\n\nThis repository does not provide a central `config.py` anymore. Pass your MQTT connection settings directly to the wrapper (see examples above) or manage configuration in your own application code.\n\n## Python Modules\n\nEach Python module provided by this repository is documented here with a focused explanation of its purpose and usage.\n\n### Package: `mqttstuff`\n\nKey classes and responsibilities:\n\n- `MWMqttMessage` (Pydantic model)\n  - Normalized container for incoming/outgoing MQTT messages\n  - Helpers like `from_pahomsg(...)` and fields for `topic`, `qos`, `retain`, `payload`, `value`, `created_at`, and optional `metadata`\n\n- `MosquittoClientWrapper`\n  - Thin wrapper around `paho.mqtt.client.Client`\n  - Simplifies connection setup and topic subscriptions via `set_topics([...])`\n  - Register callbacks per-topic (`add_message_callback(topic, callback, rettype=...)`) or a global callback (`set_on_msg_callback`)\n  - Publish utilities:\n    - `publish_one(topic, value, created_at=None, metadata=None, rettype=\"valuemsg\", retain=False, timeout=None)`\n    - `publish_multiple(list[MWMqttMessage], timeout=None)`\n  - Connection loop helpers:\n    - `connect_and_start_loop_forever(topics=None, timeout_connect_seconds=None)`\n    - `wait_for_connect_and_start_loop()`\n  - Convenience: automatic payload conversion for int/float/str/JSON/valuemsg\n\n- `MQTTLastDataReader`\n  - Static helper to retrieve the most recent messages within a configurable timeout window\n  - Supports retained-only, no-retained, or mixed operation via `retained` parameter\n  - Returns results in different representations via `rettype` and `fallback_rettype`\n\nExample – per-topic callback with type conversion:\n\n```python\nfrom mqttstuff import MosquittoClientWrapper\n\nclient = MosquittoClientWrapper(\n    host=\"localhost\", port=1883, username=\"user\", password=\"pass\",\n    topics=[\"home/+/temperature\"],\n)\n\ndef on_temperature(msg, userdata):\n    # msg.value is already a number if rettype=\"int\"/\"float\"\n    print(\"Temp:\", msg.value)\n\nclient.add_message_callback(\"home/+/temperature\", on_temperature, rettype=\"float\")\nclient.connect_and_start_loop_forever()\n```\n\n\u003c!-- The former `mqttcommander` and `config` modules have been removed from this repository. --\u003e\n\n### Module: `Helper`\n\nSmall utilities used across the project:\n\n- `ComplexEncoder` for JSON serialization of complex types (UUID, datetimes, dict/list pretty rendering)\n- `print_pretty_dict_json`, `get_pretty_dict_json`, `get_pretty_dict_json_no_sort`\n- `update_deep(base, u)` for deep dict/list merge/update\n- `get_exception_tb_as_string(exc)` for converting exception tracebacks to strings\n- `get_loguru_logger_info()` to introspect Loguru handlers and filters\n\n## Docker\n\nDocker image building and publishing have been removed from this repository. If you need containerization, consider creating a separate Docker setup in your own project using this package from PyPI.\n\n## Development\n\nHelpful `Makefile` targets:\n\n- `make help` – list available targets with short descriptions\n- `make install` – create virtualenv and install development requirements\n- `make venv` – ensure `.venv` exists and dev requirements are installed\n- `make tests` – run pytest\n- `make lint` – run Black code formatter\n- `make isort` – fix and check import order\n- `make tcheck` – run mypy type checks over `*.py`, `scripts/`, and `mqttstuff/`\n- `make commit-checks` – run pre-commit hooks on all files\n- `make prepare` – run tests and commit-checks (useful before committing/PRs)\n- `make pypibuild` – build sdist and wheel with Hatch into `dist/`\n- `make pypipush` – publish built artifacts with Hatch (configure credentials first)\n\n## Testing\n\nTests live under `tests/`. Run all tests with:\n\n```bash\npytest -q\n```\n\n## License\n\nThis project is licensed under the LGPL where applicable/possible — see [LICENSE.md](LICENSE.md). Some files/parts may be governed by other licenses and/or licensors, such as [MIT](LICENSEMIT.md) | [GPL](LICENSEGPL.md) | [LGPL](LICENSELGPL.md). Please also check file headers/comments.\n\n## Acknowledgments\n\nSee inline comments in the codebase for inspirations and references.\n\n## ⚠️ Disclaimer\n\nThis is a development/experimental project. For production use, review security settings, customize configurations, and test thoroughly in your environment. 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. Use at your own risk.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvroomfondel%2Fmqttstuff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvroomfondel%2Fmqttstuff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvroomfondel%2Fmqttstuff/lists"}