Enterprise-grade network automation platform with intelligent device discovery, verified configuration management, and comprehensive UniFi Protect integration.
This project provides a complete suite of tools for managing UniFi networks:
- Network Automation: LLDP/CDP-based discovery with automatic port naming
- Device Intelligence: Model-specific capability detection and update strategies
- Ground Truth Verification: Multi-read consistency checking prevents false positives
- 25+ Analysis Tools: Network health, performance, security diagnostics
- UniFi Protect Integration: Real-time event processing and Home Assistant MQTT bridge
- MCP Server: AI-assisted network troubleshooting via FastMCP
# Install dependencies
uv sync
# Install shell completions (optional)
uv run python -m unifi_mapper.cli install-completions bash
# or for zsh:
uv run python -m unifi_mapper.cli install-completions zshCreate configuration file following XDG Base Directory specification:
mkdir -p ~/.config/unifi_management_cli
cp .env.example ~/.config/unifi_management_cli/prod.envRequired Settings:
UNIFI_URL=https://192.168.1.1 # UniFi controller URL
UNIFI_SITE=default # Site name (usually 'default')
UNIFI_CONSOLE_API_TOKEN=your_api_token # Recommended authentication
# Alternative: Username/Password
# UNIFI_USERNAME=admin
# UNIFI_PASSWORD=your_password
UNIFI_VERIFY_SSL=false # false for self-signed certificates
UNIFI_TIMEOUT=10 # API timeout in seconds# Discover network and generate reports (read-only)
unifi-mapper --connected-devices
# Apply port name updates with verification
unifi-mapper --verify-updates --connected-devices
# Dry run - preview changes
unifi-mapper --dry-run --verify-updates# Network health diagnostics
unifi-network-toolkit diagnose network-health
# Link quality analysis
unifi-network-toolkit analyze link-quality
# Device discovery
unifi-network-toolkit find device "Office"
unifi-network-toolkit find ip 192.168.1.100# List devices with upgrade information
unifi-mapper inventory list --filter switch --show-upgrade
# Check for firmware updates
unifi-mapper inventory check-updates# Ground truth verification with consistency checking
python -m unifi_mapper.verify_cli --verify-all --consistency-check
# Device capability analysis
python -m unifi_mapper.analyze_network_capabilitiesThe system implements a layered architecture:
User Interface Layer
├── CLI Interface (unifi-mapper)
├── Network Toolkit CLI (unifi-network-toolkit)
└── Verification CLI
Intelligence Layer
├── Smart Port Mapper
├── Device Capabilities Database
└── Ground Truth Verifier
API Integration Layer
├── UniFi Network API Client
├── UniFi Protect Client
└── MCP Server (FastMCP)
Analysis Toolkit
├── Network Analysis (9 tools)
├── Diagnostics (4 tools)
├── Discovery (4 tools)
└── Port Mirroring
The UniFi API returns stale cached responses, causing false positive verification. This system implements multi-read consistency checking with cache-busting techniques to detect when the API reports incorrect configuration persistence.
Different UniFi models have varying port naming support and firmware limitations. The device capability database provides model-specific update strategies, automatically handling restrictions on devices like the US-8-60W and USW Flex series.
Previous implementations skipped necessary updates because the API reported stale "already correct" names. This version uses LLDP-based update decisions independent of API claims.
| Device Model | Support Level | Notes |
|---|---|---|
| USW Flex 2.5G 8 PoE | Full | Reliable API port naming |
| USW-Ultra-210W | Full | Enterprise-grade reliability |
| Dream Machine Pro Max | Full | Gateway with full support |
| USW Flex Mini | Full | Compact switch, full features |
| USW Flex 2.5G 5 | Limited | Network override restrictions |
| US 8 60W | Limited | Port profile auto-reset in some firmware |
| USW Lite 8 PoE | Limited | VLAN selection issues in older firmware |
UniFi Network Application 10.0.162+ resolves most device-level rejection issues.
- Capacity Planning: Port utilization forecasting
- Link Quality: Interface error and drop analysis
- MAC Address Analysis: MAC table inspection and conflict detection
- VLAN Diagnostics: VLAN configuration validation
- Storm Detection: Broadcast storm identification
- Firmware Advisor: Device firmware compatibility analysis
- IP Conflicts: IP address conflict detection
- LAG Monitoring: Link Aggregation Group status
- QoS Validation: Quality of Service rule verification
- Network Health: Overall infrastructure health monitoring
- Performance Analysis: Bottleneck identification
- Connectivity Analysis: Connection troubleshooting
- Security Audit: Security configuration review
- Find Device: Search by name/IP/MAC
- Find IP: Locate device/port by IP address
- Find MAC: MAC address location tracking
- Client Trace: End-to-end client path analysis
Comprehensive async Python library for UniFi Protect with real-time event processing and Home Assistant integration.
| Feature | Description |
|---|---|
| Event Analytics | Real-time event correlation and smart detection tracking |
| AI Port Management | Smart detection subscriptions with paired camera tracking |
| Health Monitoring | Proactive device health tracking with configurable thresholds |
| MQTT Bridge | Home Assistant integration with automatic device discovery |
from unifi_mapper.protect import ProtectConfig, UniFiProtectClient
config = ProtectConfig(
host="192.168.1.1",
username="admin",
password="your_password",
verify_ssl=False,
)
async with UniFiProtectClient(config) as client:
for camera in client.cameras.values():
print(f"{camera.name}: {camera.state}")from unifi_mapper.protect import MQTTBridge, MQTTConfig
mqtt_config = MQTTConfig(
host="192.168.1.100",
port=1883,
topic_prefix="unifi/protect",
discovery_prefix="homeassistant",
)
async with UniFiProtectClient(protect_config) as client:
bridge = MQTTBridge(client, mqtt_config)
await bridge.start()The bridge automatically creates Home Assistant entities for cameras, doorbells, sensors, and smart detections.
# Install development dependencies
uv sync --group dev
# Run tests
uv run pytest tests/ -v
# Run linting
uv run ruff check src/
uv run ruff format src/
# Type checking
uv run pyright src/Port names not persisting:
- Check device compatibility with
python -m unifi_mapper.analyze_network_capabilities - Use verification:
unifi-mapper --verify-updates - Upgrade to UniFi Network Application 10.0.162+
API authentication failures:
- Verify controller URL and port (443 for UniFi OS, 8443 for legacy)
- Check API token validity
- Ensure local controller account (not UniFi Cloud account)
Verification failures:
- Use ground truth verification:
python -m unifi_mapper.verify_cli --consistency-check - Check for device auto-reset behavior
- Consider manual UI configuration for problematic devices
This project owes significant gratitude to the uiprotect library, an unofficial Python API for UniFi Protect.
The uiprotect library has been invaluable for:
- Debugging UniFi AI 3rd party camera issues: Understanding how AI Port detection subscriptions work with non-Ubiquiti cameras
- AI Port troubleshooting: Diagnosing smart detection failures and pairing issues
- Protocol understanding: Reverse-engineering the UniFi Protect WebSocket event protocol
- Bootstrap data structures: Comprehensive models for cameras, sensors, and NVR configurations
Original Authors and Maintainers:
- Bjarne Riis - Original creator
- Christopher Bailey - Previous maintainer
The uiprotect project demonstrates exceptional reverse-engineering work on an undocumented API, and this project builds upon that foundation for its Protect integration capabilities.
License: MIT
- unifi-protect by HJD - TypeScript UniFi Protect API implementation used as protocol reference (ISC License)
MIT License - See LICENSE.md for details.
Built with systematic debugging and comprehensive UniFi device research.