Skip to content

mutatronika/ServidorMQTT

BranchesTags

Repository files navigation

Ornidia MQTT Broker - README

🌿 Professional IoT MQTT Server Platform designed for microcontrollers and edge computing.

Overview

Ornidia is a production-ready MQTT broker built with hbmqtt and FastAPI, specifically designed for IoT applications supporting:

  • ESP32 - Full featured WiFi microcontroller
  • ESP8266 - Low-cost WiFi module
  • Arduino - Classic microcontroller platform
  • Raspberry Pi 3/4 - Single-board computer

Key Features

✅ Professional MQTT Broker

  • Full MQTT 3.1.1 protocol support
  • Topic-based publish/subscribe messaging
  • QoS levels 0, 1, and 2
  • Persistent message storage
  • WebSocket support for browser clients

✅ REST API

  • Real-time broker management
  • Client connection statistics
  • Topic subscription monitoring
  • Message publishing
  • System metrics and health checks

✅ Enterprise-Grade Infrastructure

  • Comprehensive logging system
  • Configuration management
  • Graceful shutdown
  • Docker containerization
  • Database persistence (SQLAlchemy)

✅ IoT Ready

  • Example client implementations for all supported devices
  • Pre-configured authentication
  • Topic hierarchy best practices
  • Payload validation

Quick Start

Prerequisites

  • Python 3.8+
  • pip package manager
  • Virtual environment support

Installation

  1. Clone and navigate to project:
cd /path/to/ServidorMQTT
  1. Create virtual environment:
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install dependencies:
pip install -r requirements.txt
  1. Configure environment:
cp .env.example .env
# Edit .env with your settings
  1. Start the server:
python src/main.py

The server will start both:

  • 🔌 MQTT Broker on 0.0.0.0:1883
  • 📊 REST API on 0.0.0.0:8000

Architecture

ServidorMQTT/
├── src/
│   ├── broker/          # MQTT Server core
│   ├── config/          # Configuration & logging
│   ├── api/             # FastAPI REST endpoints
│   ├── database/        # Data models
│   ├── utils/           # Validators & helpers
│   └── main.py          # Entry point
├── tests/               # Test suites & examples
├── docs/                # Documentation
└── docker/              # Container setup

See ARCHITECTURE.md for detailed information.

Configuration

Environment Variables

MQTT Settings:

  • MQTT_HOST - Broker address (default: 0.0.0.0)
  • MQTT_PORT - Broker port (default: 1883)
  • MQTT_MAX_CONNECTIONS - Maximum simultaneous connections
  • MQTT_WS_ENABLED - Enable WebSocket support (default: true)
  • MQTT_WS_PORT - WebSocket port (default: 8081)

API Settings:

  • API_HOST - API address
  • API_PORT - API port (default: 8000)
  • API_RELOAD - Auto-reload on code changes (dev only)

General:

  • ENVIRONMENT - development | production
  • LOG_LEVEL - DEBUG | INFO | WARNING | ERROR
  • DEBUG - Enable debug mode

See .env.example for complete list.

REST API Documentation

Health Check

GET /health

Broker Management

GET  /api/broker/stats      # Get broker statistics
POST /api/broker/start      # Start broker
POST /api/broker/stop       # Stop broker

Client Management

GET    /api/clients              # List all clients
GET    /api/clients/{id}         # Get client details
DELETE /api/clients/{id}         # Disconnect client

Topics & Subscriptions

GET /api/topics              # List all topics
GET /api/topics/{name}       # Get topic subscribers

Metrics

GET /api/metrics             # Get performance metrics
GET /api/version             # Get version info
GET /api/config              # Get configuration

Full OpenAPI documentation available at: /api/docs

Client Examples

ESP32 MQTT Client

// See: tests/fixtures/client_scripts/esp32.ino
// Configure WiFi and MQTT settings
// Upload to ESP32 Dev Module

Key features:

  • WiFi connectivity management
  • JSON sensor payloads
  • Command subscriptions
  • Automatic reconnection

Raspberry Pi Python Client

# See: tests/fixtures/client_scripts/raspberry_pi.py
python tests/fixtures/client_scripts/raspberry_pi.py

Key features:

  • DHT22 sensor integration
  • GPIO control
  • Threaded publishing
  • Graceful shutdown

See CLIENT_SETUP.md for detailed setup guides.

Testing

Unit Tests

pytest tests/ -v

Integration Tests

pytest tests/ -v --integration

Connecting a Real Device

  1. Start the server
  2. Configure client with broker IP/port
  3. Upload firmware to device
  4. Monitor via REST API:
curl http://localhost:8000/api/clients

Deployment

Local Development

python src/main.py

Docker

docker-compose -f docker/docker-compose.yml up

Production

  1. Set ENVIRONMENT=production
  2. Configure firewall rules
  3. Set secure SECRET_KEY
  4. Use reverse proxy (nginx)
  5. Enable SSL/TLS

See DEPLOYMENT.md for detailed instructions.

Topic Hierarchy

Recommended topic structure for IoT applications:

ornidia/
├── sensors/
│   ├── temperature
│   ├── humidity
│   └── pressure
├── devices/
│   ├── esp32_001/
│   │   ├── status
│   │   ├── command
│   │   └── telemetry
│   ├── rpi_001/
│   │   ├── status
│   │   └── command
│   └── arduino_001/
│       ├── status
│       └── command
└── system/
    ├── broker/status
    └── broker/stats

Best Practices

✅ Security

  • Change default credentials
  • Enable authentication
  • Use strong passwords
  • Monitor connections

✅ Performance

  • Use QoS 1 for most use cases
  • Implement client-side reconnection logic
  • Monitor active connections
  • Set appropriate message intervals

✅ Scalability

  • Separate sensor topics by location/type
  • Use topic wildcards for subscriptions
  • Monitor broker metrics
  • Plan for load balancing

✅ Development

  • Use meaningful client IDs
  • Implement error handling
  • Log important events
  • Version your configurations

Monitoring

View Broker Status

curl http://localhost:8000/api/broker/stats | jq

List Connected Devices

curl http://localhost:8000/api/clients | jq

Monitor Topics

curl http://localhost:8000/api/topics | jq

Check Performance

curl http://localhost:8000/api/metrics | jq

Troubleshooting

Broker won't start

  • Check port availability: lsof -i :1883
  • Review logs: tail -f logs/mqtt_server.log
  • Verify configuration in .env

Client connection fails

  • Confirm broker is running
  • Check firewall rules
  • Verify client credentials
  • Review client logs

High CPU usage

  • Monitor active connections
  • Check message frequency
  • Review broker metrics
  • Consider message filtering

Contributing

Contributions welcome! Please:

  1. Follow PEP8 style guidelines
  2. Add tests for new features
  3. Update documentation
  4. Create pull requests

License

MIT License - See LICENSE file

Support

  • 📖 Documentation: docs/
  • 🐛 Bug reports: GitHub Issues
  • 💬 Questions: GitHub Discussions

Roadmap

  • Cluster/Federation support
  • Advanced authentication (OAuth2)
  • Message filtering
  • Admin web dashboard
  • Performance tuning for 1M+ connections
  • Kubernetes deployment guide

Version History

v1.0.0 (Initial Release)

  • Core MQTT broker implementation
  • REST API for management
  • Example clients for all platforms
  • Docker support

🌿 Built with ❤️ for IoT Applications | Ornidia Development Team

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages