xomoxcc/mqttstuff repository overview

⁠Quick Reference

• Maintained by: vroomfondel⁠
• Where to get help: GitHub Issues⁠
• Where to file issues: GitHub Issues⁠
• Source code: GitHub Repository⁠
• Supported architectures: amd64, arm64

⁠What is MQTTStuff?

MQTTStuff is a lightweight Python toolkit providing high-level utilities for working with MQTT brokers via Paho. It simplifies common MQTT patterns like connecting, subscribing, publishing, and reading retained messages, with special support for Tasmota device management.

Key Features:

• 🔌 Simple MQTT Wrapper - Convenient abstractions over paho-mqtt for quick connection and topic management
• 📨 Smart Message Handling - Automatic payload conversion (JSON, int, float, string) with metadata and timestamps
• 📖 Last Message Reader - Retrieve most recent messages from topics with timeout-based collection
• 🏠 Tasmota Integration - Built-in tools for discovering and commanding Tasmota smart home devices
• ⚙️ Pydantic Configuration - YAML-based config with environment variable overrides
• 🐳 Docker Ready - Pre-built multi-arch images for instant deployment

⁠How to use this image

⁠Basic Usage - Interactive Shell

docker run -it --rm \
  -e MQTTSTUFF_MQTT_HOST=your-broker \
  -e MQTTSTUFF_MQTT_PORT=1883 \
  -e MQTTSTUFF_MQTT_USERNAME=user \
  -e MQTTSTUFF_MQTT_PASSWORD=pass \
  xomoxcc/mqttstuff:latest bash

⁠Read Retained Messages

docker run --rm \
  xomoxcc/mqttstuff:latest \
  python -c "from mqttstuff.mosquittomqttwrapper import MQTTLastDataReader; \
  print(MQTTLastDataReader.get_most_recent_data_with_timeout(\
    'broker', 1883, 'user', 'pass', ['tele/+/STATE'], retained='only'))"

⁠Using Configuration Files

Mount your config.yaml to configure the MQTT connection:

docker run -it --rm \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  -e MQTTSTUFF_CONFIG_PATH=/app/config.yaml \
  xomoxcc/mqttstuff:latest python your_script.py

⁠Custom Python Script

docker run --rm \
  -v $(pwd)/my_script.py:/app/my_script.py:ro \
  -e MQTTSTUFF_MQTT_HOST=broker \
  xomoxcc/mqttstuff:latest python /app/my_script.py

⁠Environment Variables

Configure the container via environment variables:

• MQTTSTUFF_MQTT_HOST - MQTT broker hostname
• MQTTSTUFF_MQTT_PORT - MQTT broker port (default: 1883)
• MQTTSTUFF_MQTT_USERNAME - MQTT username
• MQTTSTUFF_MQTT_PASSWORD - MQTT password
• LOGURU_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR)
• MQTTSTUFF_CONFIG_PATH - Path to config YAML file
• MQTTSTUFF_CONFIG_DIR_PATH - Config directory path

⁠Use Cases

⁠1. MQTT Testing & Debugging

Quickly test MQTT connections and inspect message payloads without installing dependencies locally.

⁠2. Tasmota Device Management

Discover, monitor, and control Tasmota smart home devices via MQTT topics in bulk.

⁠3. MQTT Data Collection

Collect and process retained messages from multiple topics with automatic type conversion.

⁠4. Home Automation Integration

Build automation scripts that interact with MQTT-based IoT devices.

⁠What's Included

• Python 3.14 on Debian Trixie
• Pre-installed packages: paho-mqtt, pydantic, loguru, pytz, PyYAML
• System utilities: htop, vim, ping, tini (init system)
• Source code: Full MQTTStuff library at /app

⁠Image Variants

⁠xomoxcc/mqttstuff:latest

The latest stable build with Python 3.14 on Debian Trixie.

⁠xomoxcc/mqttstuff:<version>

Specific version tags for reproducible builds.

⁠Links

• GitHub: https://github.com/vroomfondel/mqttstuff⁠
• PyPI: https://pypi.org/project/mqttstuff/⁠
• Documentation: See README.md⁠

⁠License

LGPL-3.0-or-later (see LICENSE.md⁠)

⁠⚠️ Disclaimer

This 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.