Multicast DNS Device Discovery

A robust and enterprise-ready mDNS (multicast DNS) communication system for master-client device discovery and monitoring in local networks. This system provides automatic service discovery, health monitoring, and network resilience with sophisticated error recovery.

🚀 Features

Core Capabilities

• Automatic Service Discovery: Zero-configuration device discovery using mDNS/Bonjour
• Master-Client Architecture: Scalable architecture supporting one master and multiple clients
• Health Monitoring: Advanced mDNS service presence monitoring with configurable timeouts
• Network Resilience: Automatic interface monitoring and service re-registration
• Smart Reconnection: Exponential backoff reconnection with automatic master rediscovery

Advanced Features

• Interface Prioritization: Configurable network interface preferences (Ethernet over WiFi)
• Graceful Shutdown: Proper cleanup and service unregistration
• Comprehensive Logging: Structured logging with file and console output
• Configuration Management: JSON-based configuration with validation
• Cross-Platform: Works on Linux, macOS, and Windows

📋 Requirements

• Python 3.8 or higher
• Network interfaces supporting multicast (mDNS)
• Administrative privileges may be required on some systems

🛠️ Installation

From Source

# Clone the repository
git clone https://github.com/sithulaka/mdns_device_discovery.git
cd mdns_device_discovery

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Quick Setup

# Create sample configuration files
python3 main.py --create-configs

# Test the installation
python3 main.py --help

🚀 Quick Start

Running as Master Device

# Quick start as master
python3 main.py --master

# Or with custom configuration
python3 main.py --config config_master.json

Running as Client Device

# Quick start as client
python3 main.py --client

# Or with custom configuration
python3 main.py --config config_client.json

Using Custom Configuration

# Run with specific config file
python3 main.py --config my_custom_config.json

# Enable verbose logging
python3 main.py --client --verbose

⚙️ Configuration

Sample Master Configuration

{
    "client_id": "master_device",
    "is_master": true,
    "port": 5000,
    "master_ip": null,
    "network_preferences": {
        "allow_wifi": false,
        "prefer_ethernet": true,
        "interface_priority": ["eth", "en", "wlan", "wlp"]
    },
    "timeouts": {
        "master_discovery_timeout": 30,
        "master_wait_timeout": 60,
        "health_check_interval": 10,
        "network_check_interval": 5
    },
    "health_check": {
        "enabled": true,
        "max_failures": 3,
        "timeout": 3,
        "service_timeout": 30
    }
}

Configuration Options

Parameter	Description	Default
client_id	Unique device identifier	"device_001"
is_master	Whether device acts as master	false
port	Service port number	5000
allow_wifi	Allow WiFi interfaces	true
prefer_ethernet	Prefer Ethernet over WiFi	true
health_check_interval	Health check frequency (seconds)	10
max_failures	Max consecutive failures before disconnect	3

📖 Usage Examples

Basic Master-Client Setup

Terminal 1 (Master Device):

python3 main.py --master

Terminal 2 (Client Device):

python3 main.py --client

Programmatic Usage

from mdns_module import MDNSCommunicator

# Initialize communicator
communicator = MDNSCommunicator("config.json")

# Start the service
communicator.start()

# Check device type
if communicator.is_master_device():
    print("Running as master device")
else:
    print("Running as client device")
    master_ip = communicator.get_master_ip()
    if master_ip:
        print(f"Connected to master at {master_ip}")

# Get connection status
status = communicator.get_connection_status()
print(f"Status: {status}")

# Cleanup
communicator.stop()

🏗️ Architecture

System Components

┌─────────────────┐    ┌─────────────────┐
│   Master Device │    │  Client Device  │
│                 │    │                 │
│  mDNS Service   │◄──►│ mDNS Discovery  │
│  Registration   │    │ Service Browser │
│                 │    │                 │
│  Network        │    │ Health Monitor  │
│  Monitoring     │    │ Reconnection    │
└─────────────────┘    └─────────────────┘

Key Classes

• MDNSDevice: Core device management and service registration
• MDNSCommunicator: High-level API for application integration
• HealthMonitor: mDNS service presence monitoring
• NetworkManager: Network interface detection and monitoring
• ReconnectionManager: Automatic reconnection with exponential backoff

🔧 Development

Setting Up Development Environment

# Clone and setup
git clone https://github.com/sithulaka/mdns_device_discovery.git
cd mdns_device_discovery

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=mdns_system

# Run specific test
python -m pytest tests/test_mdns_module.py

Code Formatting

# Format code
black .

# Check formatting
black --check .

# Sort imports
isort .

📊 Monitoring and Logging

The system provides comprehensive logging at multiple levels:

• Console Output: Real-time status updates
• File Logging: Detailed logs saved to mdns_communication.log
• Debug Mode: Verbose logging with --verbose flag

Log Levels

• INFO: Normal operation status
• WARNING: Recoverable issues (network changes, reconnections)
• ERROR: Serious issues requiring attention
• DEBUG: Detailed diagnostic information

🌐 Network Requirements

Supported Networks

• Ethernet: Primary preference for stability
• WiFi: Supported with configuration option
• Virtual Interfaces: Docker, VPN interfaces are filtered out

mDNS Requirements

• Multicast support on network infrastructure
• Port 5353 (mDNS) must be open
• Same network segment for device discovery

Firewall Configuration

Ensure the following ports are open:

• UDP 5353: mDNS service discovery
• TCP 5000: Application service port (configurable)

🔍 Troubleshooting

Common Issues

Master Not Found

# Check network connectivity
ping <master_ip>

# Verify mDNS is working
avahi-browse -rt _master-device._tcp  # Linux
dns-sd -B _master-device._tcp         # macOS

Service Registration Failed

# Check interface status
ip addr show  # Linux
ifconfig      # macOS/Unix

# Verify permissions
sudo python3 main.py --master  # Try with elevated privileges

Health Check Failures

# Test mDNS resolution
nslookup master-device.local

# Check service advertisement
avahi-resolve -n master-device.local  # Linux

Debug Mode

Enable verbose logging for detailed troubleshooting:

python3 main.py --client --verbose

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

Code Standards

• Follow PEP 8 style guidelines
• Add type hints to all functions
• Include docstrings for all public methods
• Write tests for new features
• Update documentation as needed

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

📚 Related Documentation

• Setup Instructions - Detailed setup guide
• API Documentation - Complete API reference
• Examples - Usage examples and tutorials

🆘 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

🙏 Acknowledgments

• python-zeroconf - mDNS implementation
• psutil - System and network utilities

---

Made with ❤️ by sithulaka