unifi-network-maps 1.4.15__tar.gz → 1.5.0__tar.gz

{unifi_network_maps-1.4.15 → unifi_network_maps-1.5.0}/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.5.0] - 2026-02-05
+### Added
+- Add wireless connection quality metrics to edge data for Home Assistant integration (#24)
+  - Signal strength (dBm), noise floor, TX/RX rates, satisfaction score
+  - Automatic quality classification (excellent/good/fair/poor)
+- Add `minimal-dark` theme with grayscale monochromatic styling
+- Add topology diff API for change detection (#21)
+  - New `Topology` class with `to_dict()`, `from_dict()`, and `diff()` methods
+  - `compare_topologies()` function for stateless comparison
+  - Event-style change list with human-readable descriptions
+  - JSON serialization support for persistence and MQTT transmission
+- Add SVG grouped layout mode (`--svg-layout-mode grouped`) with visual boundaries for network segments (#19)
+- Add VLAN information to edge metadata with color-coded visualization (#20)
+- Add `--theme` CLI argument for built-in themes: `unifi`, `unifi-dark`, `minimal`, `classic`, `classic-dark` (#22)
+- Add theme properties: background, text colors, status indicators, WAN globe, grid color
+- Add WAN upstream visualization with ISP label, link speed, and status indicator (`--wan-label`, `--wan-speed`, `--wan2-label`, `--wan2-speed`)
+- Add `--icon-set` CLI argument for selectable icon sets: `isometric`, `modern` (#23)
+- Add modern icon set with minimalistic isometric device icons
+- Add themeable isometric grid color (`grid_color`) for per-theme floor grid styling
+- Add `--max-vlan-colors` and `--include-vlan-legend` options for VLAN visualization
+- Add `--collapse-clients` to group clients by uplink into cluster nodes with count badges
+- Add theme matrix generator script (`make theme-matrix`) with composite PNG overview
+- Theme YAML schema now supports `icon_set` and `grid_color` fields
+
+### Changed
+- Align UniFi light/dark themes with official ui.com color palette from techspecs.ui.com/brand
+- SVG renderer now uses theme-aware colors for background, text labels, and WAN box
+- WAN port detection uses `wan_networkconf_id` field instead of hardcoded port numbers
+- Light theme isometric grids use darker grid lines for better contrast (blue-tinted for UniFi, grey for others)
+
+### Removed
+- Remove flat (Heroicons) and outline (Lucide) icon sets; consolidate to `isometric` and `modern`
+
+### Fixed
+- Normalize gateway WAN port speeds from Gbps to Mbps for correct display (e.g., "10GbE" instead of "10MbE")
+
 ## [1.4.15] - 2026-02-01
 ### Changed
 - Displaying of friendly device/model names
@@ -206,7 +244,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Introduced SVG renderer and tree layout fixes.
 - Increased test coverage and added coverage tooling.
 
-[Unreleased]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.14...HEAD
+[Unreleased]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.15...v1.5.0
+[1.4.15]:https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.14...v1.4.15
 [1.4.14]:https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.11...v1.4.14
 [1.4.13]:https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.11...v1.4.13
 [1.4.12]:https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.11...v1.4.12

unifi_network_maps-1.5.0/CONTRIBUTING.md

@@ -0,0 +1,170 @@
+# Contributing
+
+Thanks for considering a contribution!
+
+## Project Overview
+
+**unifi-network-maps** is a Python CLI tool that generates network diagrams from UniFi Network Controller data via LLDP topology discovery.
+
+## Architecture
+
+The project follows a clean pipeline architecture:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              Data Flow                                       │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐             │
+│  │  Source  │───▶│  Model   │───▶│  Render  │───▶│  Export  │             │
+│  └──────────┘    └──────────┘    └──────────┘    └──────────┘             │
+│       │               │               │               │                    │
+│  UniFi API       Topology        Mermaid/SVG      Files/                  │
+│  Mock data       Devices         MkDocs           stdout                  │
+│                  Edges           JSON                                      │
+│                  VLANs                                                     │
+│                                                                            │
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Module Structure
+
+```
+src/unifi_network_maps/
+├── cli/                 # CLI entry point
+│   ├── args.py          # Argument definitions
+│   ├── main.py          # Entry point, orchestration
+│   ├── render.py        # Render dispatch logic
+│   └── runtime.py       # Runtime context management
+│
+├── adapters/            # External data sources
+│   ├── config.py        # Environment/config loading
+│   └── unifi.py         # UniFi API adapter
+│
+├── model/               # Core domain models
+│   ├── topology.py      # Device, Edge, Topology dataclasses
+│   ├── clients.py       # Client device handling
+│   ├── connection.py    # Wireless connection quality metrics
+│   ├── lldp.py          # LLDP neighbor parsing
+│   ├── labels.py        # Label generation utilities
+│   ├── ports.py         # Port handling and mapping
+│   ├── vlans.py         # VLAN inventory management
+│   ├── mock.py          # Mock data structures
+│   ├── snapshot.py      # Topology serialization
+│   └── diff.py          # Topology change detection
+│
+├── render/              # Output renderers
+│   ├── mermaid.py       # Mermaid diagram output
+│   ├── mermaid_theme.py # Mermaid theming
+│   ├── svg.py           # SVG output (orthogonal + isometric)
+│   ├── svg_theme.py     # SVG theming dataclass
+│   ├── theme.py         # Theme loading and resolution
+│   ├── legend.py        # Legend rendering
+│   ├── mkdocs.py        # MkDocs format output
+│   ├── lldp_md.py       # LLDP markdown tables
+│   └── templating.py    # Jinja2 template utilities
+│
+├── io/                  # File I/O operations
+│   ├── export.py        # File export utilities
+│   ├── mock_data.py     # Mock data loading
+│   ├── mock_generate.py # Mock data generation (Faker)
+│   ├── paths.py         # Path resolution utilities
+│   └── debug.py         # Debug dump utilities
+│
+└── assets/              # Static assets
+    ├── icons/           # SVG device icons (isometric, modern, modern-flat)
+    └── themes/          # Theme YAML files
+```
+
+### Key Concepts
+
+- **Topology**: Collection of `Device` nodes and `Edge` connections
+- **Device**: Network device with type, name, MAC, model, ports
+- **Edge**: Connection between devices with PoE status, VLAN, port info
+- **ConnectionInfo**: Wireless quality metrics (signal, noise, rates)
+- **Theme**: Visual styling for both Mermaid and SVG output
+
+## Development Setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements-build.txt
+pip install -r requirements-dev.txt -c constraints.txt
+pre-commit install
+```
+
+Editable install:
+
+```bash
+pip install -e .
+```
+
+## Running Checks
+
+```bash
+ruff check .          # Linting
+ruff format .         # Formatting
+pyright               # Type checking
+pytest                # Unit tests
+behave                # BDD tests
+```
+
+Or run everything with:
+
+```bash
+make ci
+```
+
+### Testing Overview
+
+| Type | Location | Command | Purpose |
+|------|----------|---------|---------|
+| Unit | `tests/` | `pytest` | Core logic |
+| BDD | `features/` | `behave` | User scenarios |
+| Contract | `tests/test_contract_unifi.py` | `pytest` | API fixtures |
+| Visual | `tests/test_visual_regression.py` | `pytest` | SVG rendering |
+| Smoketest | `scripts/smoketest.sh` | `make smoketest-mock` | End-to-end |
+
+Notes:
+- Live contract tests require `UNIFI_CONTRACT_LIVE=1` plus UniFi env vars.
+- Visual regression uses `cairosvg` + `Pillow` for pixel comparison.
+- Update visual baselines with `make visual-baselines` after intentional changes.
+
+## Useful Make Targets
+
+```bash
+make ci               # Run all checks
+make smoketest-mock   # End-to-end with mock data
+make visual-regression # Compare SVG output
+make visual-baselines # Update baseline images
+make theme-matrix     # Generate theme preview image
+make mock-data        # Generate mock JSON
+make makefile-help    # List all targets
+```
+
+## Release
+
+```bash
+git tag -a vX.Y.Z -m "vX.Y.Z"
+git push origin vX.Y.Z
+python -m build
+twine upload dist/*
+```
+
+See `LICENSES.md` for third-party license info.
+
+## Code Guidelines
+
+- Clear, intention-revealing names
+- Small, focused functions (>15 lines is a code smell)
+- Type annotations throughout
+- No prints in core modules (use `logging`)
+- Pure functions where possible
+- Add tests for behavior changes
+- Run `make ci` before opening a PR
+
+## Related Projects
+
+- **Home Assistant integration**: [unifi-network-maps-ha](https://github.com/merlijntishauser/unifi-network-maps-ha)
+  

unifi_network_maps-1.5.0/LICENSES.md

@@ -0,0 +1,77 @@
+# Third-Party Licenses
+
+This document lists the licenses for third-party assets used in this project.
+
+## Icon Sets
+
+### Isometric Icon Set (Default)
+
+#### markmanx/isopacks (MIT)
+
+Isometric SVG icons in the isometric set are vendored under `src/unifi_network_maps/assets/icons/isometric/`.
+The upstream MIT license is included at:
+
+```
+src/unifi_network_maps/assets/icons/isometric/ISOPACKS_LICENSE
+```
+
+### Modern Icon Set
+
+The modern icon set (`src/unifi_network_maps/assets/icons/modern/`) combines custom isometric
+base shapes with Heroicons rendered on top using isometric matrix transforms.
+
+#### Isometric Base Shapes (MIT)
+
+Custom isometric base shapes created for this project, using the isopacks color palette
+(#CDD9EE light, #B5C5DC medium, #6885A9 dark, #231F20 outline).
+
+#### Heroicons (MIT)
+
+Icon symbols from [Heroicons](https://heroicons.com/) by Tailwind Labs.
+
+- Source: https://github.com/tailwindlabs/heroicons
+- License: MIT License
+- Icons used: globe-alt, server, wifi, computer-desktop
+
+| Icon | Base Shape | Heroicon |
+|------|------------|----------|
+| gateway.svg | Cube | globe-alt |
+| switch.svg | 1U rack | server |
+| ap.svg | Disc | wifi |
+| client.svg | Cube | computer-desktop |
+| other.svg | Cube | server |
+
+## Fonts
+
+### Inter (SIL Open Font License 1.1)
+
+The [Inter](https://rsms.me/inter/) typeface by Rasmus Andersson is used in the UniFi and UniFi Dark themes.
+Variable WOFF2 files are vendored under `src/unifi_network_maps/assets/fonts/`.
+
+- Source: https://github.com/rsms/inter
+- License: SIL Open Font License 1.1
+- License file: `src/unifi_network_maps/assets/fonts/INTER_LICENSE`
+
+### Space Grotesk (SIL Open Font License 1.1)
+
+The [Space Grotesk](https://floriankarsten.github.io/space-grotesk/) typeface by Florian Karsten is used in the Minimal theme.
+Variable WOFF2 files are vendored under `src/unifi_network_maps/assets/fonts/`.
+
+- Source: https://github.com/floriankarsten/space-grotesk
+- License: SIL Open Font License 1.1
+- License file: `src/unifi_network_maps/assets/fonts/SPACE_GROTESK_LICENSE`
+
+## License Compatibility
+
+When sourcing icons for this project, use license-compatible sources:
+
+**Compatible licenses:**
+- Public Domain / CC0
+- MIT License
+- Apache 2.0
+- CC-BY (with attribution)
+- BSD
+
+**Not compatible:**
+- CC-NC (Non-Commercial)
+- GPL/LGPL (copyleft)

{unifi_network_maps-1.4.15 → unifi_network_maps-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.4.15
+Version: 1.5.0
 Summary: Dynamic UniFi -> network maps in mermaid or svg
 Author: Merlijn
 License-Expression: MIT
@@ -26,13 +26,17 @@ Requires-Dist: python-dotenv==1.2.1
 Requires-Dist: PyYAML==6.0.3
 Requires-Dist: Jinja2==3.1.6
 Provides-Extra: dev
+Requires-Dist: cairosvg==2.8.2; extra == "dev"
 Requires-Dist: Faker==40.1.2; extra == "dev"
 Requires-Dist: behave==1.3.3; extra == "dev"
+Requires-Dist: Pillow==12.1.0; extra == "dev"
 Requires-Dist: pre-commit==4.5.1; extra == "dev"
 Requires-Dist: pytest==9.0.2; extra == "dev"
 Requires-Dist: pytest-cov==7.0.0; extra == "dev"
 Requires-Dist: pyright==1.1.408; extra == "dev"
-Requires-Dist: ruff==0.14.14; extra == "dev"
+Requires-Dist: radon==6.0.1; extra == "dev"
+Requires-Dist: ruff==0.15.0; extra == "dev"
+Requires-Dist: xenon==0.9.3; extra == "dev"
 Dynamic: license-file
 
 # unifi-network-maps
@@ -158,6 +162,54 @@ unifi-network-maps --format json --output ./payload.json
 The live Home Assistant integration (Config Flow + coordinator + custom card) lives in a separate repo:
 - https://github.com/merlijntishauser/unifi-network-maps-ha
 
+## Programmatic API
+
+Beyond the CLI, you can use the library programmatically for topology comparison and change detection.
+
+### Topology Diff API
+
+Compare two topology snapshots to detect network changes:
+
+```python
+from unifi_network_maps.model.topology import Topology
+
+# Create or load topologies
+old_topology = Topology.from_dict(json.load(open("old_snapshot.json")))
+new_topology = Topology(devices=devices, clients=clients, edges=edges)
+
+# Compare and get structured change events
+diff = old_topology.diff(new_topology)
+
+for event in diff.events:
+    print(f"{event.event_type}: {event.description}")
+    # Example: "node_added: Device 'switch-2' appeared on network"
+    # Example: "node_changed: Client 'laptop' changed VLAN from 10 to 20"
+
+# Serialize for persistence or MQTT
+json_str = diff.to_json()
+```
+
+Event types:
+- `node_added` / `node_removed` / `node_changed` - Device or client changes
+- `edge_added` / `edge_removed` / `edge_changed` - Connection changes
+
+Each event includes:
+- `event_type`, `entity_type` (device/client), `identifier` (MAC)
+- `name`, `description` (human-readable)
+- `details` (full snapshot or change dict)
+
+Serialize topology snapshots for storage:
+
+```python
+# Save snapshot
+snapshot = topology.to_dict()
+json.dump(snapshot, open("topology.json", "w"))
+
+# Load snapshot
+data = json.load(open("topology.json"))
+topology = Topology.from_dict(data)
+```
+
 ## Examples (mock data)
 
 These examples are generated from `examples/mock_data.json` (safe, anonymized fixture).
@@ -178,6 +230,13 @@ unifi-network-maps --mock-data examples/mock_data.json   --include-ports --inclu
 
 ![Isometric network example](examples/output/network_ports_clients_iso.svg)
 
+### Themes & Icon Sets
+
+Built-in themes (`--theme`) and icon sets (`--icon-set`) can be combined freely.
+Regenerate this overview with `make theme-matrix`.
+
+![Theme × icon-set matrix](examples/themes/theme_matrix.png)
+
 Mermaid example with ports:
 
 ```mermaid
@@ -204,9 +263,6 @@ graph TB
 See `examples/mkdocs/` for a ready-to-use setup that renders Mermaid diagrams
 with Material for MkDocs, including a sample `unifi-network` page and legend.
 
-The built-in themes live at `src/unifi_network_maps/assets/themes/default.yaml` and
-`src/unifi_network_maps/assets/themes/dark.yaml`.
-
 
 ## Options
 
@@ -220,44 +276,63 @@ Source:
 Mock:
 - `--generate-mock`: write mock data JSON and exit.
 - `--mock-seed`: seed for deterministic mock generation.
-- `--mock-switches`: number of switches to generate.
-- `--mock-aps`: number of access points to generate.
-- `--mock-wired-clients`: number of wired clients to generate.
-- `--mock-wireless-clients`: number of wireless clients to generate.
+- `--mock-switches`: number of switches to generate (default 1).
+- `--mock-aps`: number of access points to generate (default 2).
+- `--mock-wired-clients`: number of wired clients to generate (default 2).
+- `--mock-wireless-clients`: number of wireless clients to generate (default 2).
 
 Functional:
 - `--include-ports`: show port labels (Mermaid shows both ends; SVG shows compact labels).
-- `--include-clients`: add active wired clients as leaf nodes.
+- `--include-clients`: add active clients as leaf nodes.
 - `--client-scope wired|wireless|all`: which client types to include (default wired).
-- `--only-unifi`: only include neighbors that are UniFi devices; when clients are included, filters to UniFi-managed clients (by explicit UniFi flags or vendor/OUI).
+- `--collapse-clients`: group clients by uplink device into cluster nodes with count badges.
+- `--only-unifi`: only include neighbors that are UniFi devices; when clients are included, filters to UniFi-managed clients.
 - `--no-cache`: disable UniFi API cache reads and writes.
 
 Mermaid:
-- `--direction LR|TB`: diagram direction for Mermaid (default TB).
-- `--group-by-type`: group nodes by gateway/switch/AP in Mermaid subgraphs.
-- `--legend-scale`: scale legend font/link sizes for Mermaid outputs (default 1.0).
+- `--direction LR|TB`: diagram direction (default TB).
+- `--group-by-type`: group nodes by gateway/switch/AP in subgraphs.
+- `--legend-scale`: scale legend font/link sizes (default 1.0).
 - `--legend-style auto|compact|diagram`: legend rendering mode (auto uses compact for mkdocs).
-- `--legend-only`: render just the legend as a separate Mermaid graph (Mermaid only).
+- `--legend-only`: render just the legend as a separate Mermaid graph.
 
 SVG:
 - `--svg-width/--svg-height`: override SVG output dimensions.
-- `--theme-file`: load a YAML theme for Mermaid + SVG colors (see `examples/theme.yaml` and `examples/theme-dark.yaml`).
+- `--theme`: built-in theme (`unifi`, `unifi-dark`, `minimal`, `classic`, `classic-dark`).
+- `--theme-file`: custom theme YAML (takes priority over `--theme`; see `examples/theme.yaml`).
+- `--icon-set isometric|modern`: icon set to use (default: determined by theme, or `isometric`).
+- `--svg-layout-mode physical|grouped`: layout mode for SVG output (default physical).
+- `--wan-label/--wan-speed`: WAN1 ISP name and provisioned speed.
+- `--wan2-label/--wan2-speed`: WAN2 ISP name and provisioned speed.
+- `--max-vlan-colors`: limit VLAN colors shown on edges (default: no limit).
+- `--include-vlan-legend`: add VLAN color legend to SVG output.
 
 Output:
 - `--format mermaid|svg|svg-iso|lldp-md|mkdocs|json`: output format (default mermaid).
 - `--stdout`: write output to stdout.
-- `--markdown`: wrap Mermaid output in a code fence.
-- `--mkdocs-sidebar-legend`: write assets to place the compact legend in the MkDocs right sidebar.
+- `--output`: write output to file.
+- `--markdown`: wrap Mermaid output in a code fence for notes tools like Obsidian.
+- `--mkdocs-sidebar-legend`: write sidebar legend assets next to the output file.
 - `--mkdocs-dual-theme`: render light/dark Mermaid blocks for Material theme switching.
-- `--mkdocs-timestamp-zone`: timezone for mkdocs timestamp (`Europe/Amsterdam` default; use `off` to disable).
+- `--mkdocs-timestamp-zone`: timezone for mkdocs timestamp (default `Europe/Amsterdam`; use `off` to disable).
 
 Debug:
 - `--debug-dump`: dump gateway + sample devices to stderr for debugging.
 - `--debug-sample N`: number of non-gateway devices in debug dump (default 2).
 
-## Theme file
+## Themes
+
+Five built-in themes are available via `--theme`:
 
-Example theme YAML (override only the values you want):
+| Theme | Style | Default icon set |
+|-------|-------|-----------------|
+| `unifi` | Clean light theme based on the [ui.com](https://ui.com) color palette | modern |
+| `unifi-dark` | Dark variant using official Ubiquiti dark surface colors | modern |
+| `minimal` | Neutral grey tones, understated | isometric |
+| `classic` | Warm default palette with distinct device colors | isometric |
+| `classic-dark` | Dark variant of classic | modern |
+
+For custom colors, create a theme YAML and pass it with `--theme-file`. Override only the values you need:
 
 ```yaml
 mermaid:
@@ -267,28 +342,29 @@ mermaid:
       stroke: "#d98300"
   poe_link: "#1e88e5"
 svg:
+  icon_set: modern
+  grid_color: "#c0c8d0"
+  background: "#f9fafa"
   links:
     standard:
-      from: "#2ecc71"
-      to: "#1b8f4a"
-    poe:
-      from: "#1e88e5"
-      to: "#0d47a1"
+      from: "#006fff"
+      to: "#0560d4"
   nodes:
     switch:
-      from: "#d6ecff"
-      to: "#b6dcff"
+      from: "#4dd88a"
+      to: "#38cc65"
 ```
 
+See `examples/theme.yaml` and `examples/theme-dark.yaml` for full examples.
+
 ## Notes
 
 - Default output is top-to-bottom (TB) and rendered as a hop-based tree from the gateway(s).
 - Nodes are color-coded by type (gateway/switch/AP/client) with a sensible default palette.
-- PoE links are highlighted in blue and annotated with a power icon when detected from `port_table`.
+- PoE links are annotated with a power icon when detected from `port_table`.
 - Wireless client links render as dashed lines to indicate the last-known upstream.
-- SVG output uses vendored device glyphs from `src/unifi_network_maps/assets/icons`.
-- Isometric SVG output uses MIT-licensed icons from `markmanx/isopacks`.
 - SVG port labels render inside child nodes for readability.
+- Icon licenses and attribution are documented in [LICENSES.md](LICENSES.md).
 
 
 ## AI Disclosure