Metadata-Version: 2.4
Name: mqtt-docker-controller
Version: 0.1.5
Summary: A comprehensive and handy MQTT and Docker broker management tool
Author-email: Dylan Wall <dylan@someemail.com>
License: MIT
Project-URL: Homepage, https://github.com/DylanWall96/mqtt-docker-controller
Project-URL: Bug Reports, https://github.com/DylanWall96/mqtt-docker-controller/issues
Project-URL: Source, https://github.com/DylanWall96/mqtt-docker-controller/
Keywords: mqtt,docker,broker,iot,messaging,controller,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Communications
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paho-mqtt>=1.6.1
Requires-Dist: docker>=6.1.0
Provides-Extra: dev
Requires-Dist: check-manifest; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: license-file

# MQTT Docker Controller

A Python-based tool for managing MQTT operations and Docker-based MQTT brokers. This tool provides a unified interface for both MQTT client operations (publish/subscribe) and Docker-based Mosquitto broker management.

## Features

- 🐳 Docker-based MQTT broker management
  - Start/stop Mosquitto broker containers
  - Automatic configuration management
  - Container health monitoring
  - Automatic error detection and recovery
- 📨 MQTT client operations
  - Publish messages with configurable QoS and retain settings
  - Subscribe to topics with automatic reconnection
  - Support for multiple connection parameters
- 🛠️ Command-line interface
  - Simple, intuitive commands
  - Comprehensive help system
  - Error handling and logging

## Prerequisites

- Python 3.8 or higher
- Docker installed and running
  - macOS: Docker Desktop
  - Linux: Docker Engine
  - Windows: Docker Desktop
- Network access for MQTT operations
- Available ports:
  - 1883 (MQTT)
  - 9001 (WebSocket)

## Installation

```bash
# Install the package
pip install mqtt-docker-controller
```

## Usage

### Starting a Local MQTT Broker
```bash
# Start a new broker instance
mqtt-docker-controller start-broker

# Stop the running broker
mqtt-docker-controller stop-broker
```

### Publishing Messages
```bash
# Basic publish
mqtt-docker-controller publish --broker localhost --topic test/topic --message "Hello World"

# Publish with QoS and retain
mqtt-docker-controller publish \
    --broker localhost \
    --topic test/topic \
    --message "Hello World" \
    --qos 1 \
    --retain
```

### Subscribing to Topics
```bash
# Basic subscribe
mqtt-docker-controller subscribe --broker localhost --topic test/topic

# Subscribe with specific QoS
mqtt-docker-controller subscribe \
    --broker localhost \
    --topic test/topic \
    --qos 1
```

## Error Handling and Troubleshooting

### Docker-Related Issues

1. Docker Not Running
   ```
   ERROR: Docker daemon is not running
   Please start Docker with one of these commands:
     - macOS: open -a Docker
     - Linux: sudo systemctl start docker
     - Windows: Start Docker Desktop
   ```

2. Port Conflicts
   ```
   ERROR: Port 1883 or 9001 is already in use
   Please check if another broker or service is running on these ports
   ```

3. Image Issues
   - The tool will automatically attempt to pull the Mosquitto image if not found
   - Network issues during pull will be reported clearly

### MQTT-Related Issues

1. Connection Problems
   - Broker unreachable
   - Authentication failures
   - Invalid topic format

2. Common Fixes
   - Ensure Docker is running
   - Check port availability
   - Verify network connectivity
   - Confirm broker address is correct

## Configuration

### Default Broker Settings
- MQTT Port: 1883
- WebSocket Port: 9001
- Default Configuration Location: ~/mqtt-docker-controller-test/mosquitto.conf

### Client Settings
- Default QoS: 0
- Default Keep Alive: 60 seconds
- Auto-reconnect: Enabled

## Development

### Setting Up Development Environment
```bash
# Clone the repository
git clone https://github.com/DylanWall96/mqtt-docker-controller.git
cd mqtt-docker-controller

# Install in development mode with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Check code style
flake8 mqtt_docker_controller
black mqtt_docker_controller

# Type checking
mypy mqtt_docker_controller
```

### Project Structure
```
mqtt_docker_controller/
├── __init__.py         # Package initialisation
├── cli.py             # Command-line interface
├── broker.py          # Docker broker management
├── client.py          # MQTT client operations
├── config.py          # Configuration management
└── __main__.py        # Direct execution support
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Licence

This project is licensed under the MIT Licence - see the LICENCE file for details.
