Lovelace Card

🎛️ SNMP Switch Manager Lovelace Card

The SNMP Switch Manager Lovelace card provides a visual, interactive representation of your network switch inside Home Assistant. It surfaces port status, negotiated speeds, live power controls, bandwidth traffic graphs, and hardware diagnostics at a glance.

---

🧭 Overview

The card displays your switch as a visual port layout (matching the physical switch faceplate) or as a phone-friendly status list. It provides deep integration with SNMP attributes and entities, allowing you to toggle port power, view historical throughput, and inspect temperature or PoE limits.

---

📦 Installation & Setup

🚫 No Installation or Manual Resource Configuration Required

The card is now bundled directly inside the primary SNMP Switch Manager integration and is automatically registered as a dashboard resource during integration setup.

Simply install the integration, restart Home Assistant, and reload your browser cache. The card will then be available in your card picker as: Custom: SNMP Switch Manager Card.

---

➕ Adding the Card

1. Open a Lovelace dashboard.
2. Click Edit dashboard (top-right menu).
3. Click Add card and search for SNMP Switch Manager.
4. Select the card. By default, it will auto-discover switch devices available in your Home Assistant registry.

---

🖥️ View Modes (Panel vs. List)

The card supports two visual layouts to accommodate different screen sizes and user preferences.

1. Panel View

🔍 What it is

A graphic panel that renders ports as interactive grids or custom layouts mapped directly over a background image of the network switch's front panel.

💡 When to use it

• On tablet dashboards, desktop screens, or wall mounts.
• When you want a visual, high-fidelity mapping that reflects the physical switch's port layout and LED locations.

👁️ When you should see it

• When view is set to panel (the default mode).
• Enabled on cards where a visual matrix of ports is desired.

⚙️ How to use it

1. In the Card Editor, set View Mode to Panel.
2. Customize the grid layout (e.g., Ports Per Row, Port Size, and Gaps).
3. Optionally, add a Background Image URL to place the ports over a real switch faceplate.

---

2. List View

🔍 What it is

A compact, text-based list layout displaying switch ports as structured list items/tiles showing port status, names, and speeds.

💡 When to use it

• On mobile devices, phone screens, or sidebar cards.
• When physical layout mapping is not needed and you want a clean, scrolling list of active interfaces.

👁️ When you should see it

• When view is set to list.
• Hidden features that only pertain to visual coordinates (like the Layout Editor, port scaling, and background images) will be hidden automatically.

⚙️ How to use it

1. In the Card Editor, set View Mode to List.
2. You can configure which ports to hide and whether to display the Diagnostics or Virtual Interfaces panels below.

---

🎨 Port Coloring Modes

Port status indicators change colors dynamically depending on the selected display mode.

1. Status-Based Coloring

🔍 What it is

A coloring mode where each port represents the administrative and operational link state of the switch interface.

💡 When to use it

• To quickly verify if a link is up, down, disconnected, or manually disabled (Admin Down).
• This is the standard, most common monitoring configuration.

👁️ When you should see it

• When color_mode is set to state.
• Supported by default for all ports.

⚙️ How to use it

1. In the Card Editor, set Color Mode to State.
2. The default color scheme is:
   • 🟩 Green: Admin Up · Oper Up (Normal active link)
   • 🟥 Red: Admin Up · Oper Down (Link fault / disconnected cable)
   • 🟧 Orange: Admin Down · Oper Down (Port manually disabled)
   • ⬜ Gray: Admin Up · Oper Not Present (SFP module missing)
3. Custom colors can be overridden in the configuration under state_colors.

---

2. Speed-Based Coloring

🔍 What it is

A coloring mode where each port block is color-coded according to the negotiated link speed of the interface.

💡 When to use it

• To spot speed mismatches (e.g., a port that should negotiate at 1 Gbps but is running at 100 Mbps due to a bad cable).
• To map high-speed backbones and multi-gig uplink ports at a glance.

👁️ When you should see it

• When color_mode is set to speed.

⚙️ How to use it

1. In the Card Editor, set Color Mode to Speed.
2. Check the Show all supported speeds option if you want the editor to expose color pickers for all tiers, even those not currently negotiated on the switch.
3. The default speed-color mapping ranges from 10 Mbps up to 100 Gbps:
   • ⬜ Gray — 10 Mbps
   • 🟧 Orange — 100 Mbps
   • 🟩 Green — 1 Gbps
   • 🪟 Teal — 2.5 Gbps
   • 💎 Cyan — 5 Gbps
   • 🟦 Blue — 10 Gbps
   • 🟣 Indigo/Violet/Purple/Pink — 20G to 100G
   • 🟥 Red — Disconnected
4. Override specific speed colors using the editor's color swatches or the speed_colors YAML configuration.

---

🛠️ Layout Editor (Visual Calibration)

🔍 What it is

An interactive, on-card drag-and-drop tool that allows you to visually position, arrange, and scale the ports and uplinks directly over a custom background image.

💡 When to use it

• When configuring a custom background image of your switch faceplate.
• When ports are organized in non-standard physical configurations (e.g., stacked port pairs, staggered alignments, separate SFP blocks).

👁️ When you should see it

• Visible only when Layout Editor is enabled in the Card Editor.
• When enabled, the visual bounding box overlays, scale slider handles, and on-card control bar are visible on the card face.

⚙️ How to use it

1. Enable the Layout Editor toggle in the Card Editor options.
2. An edit overlay will appear on the card:
   • Move Groups: Click and drag the Ports or Uplinks box to move all ports inside them as a single unit.
   • Scale: Drag the handles on the edges of the box to resize the ports. The ports scale smoothly and maintain tight boundaries.
   • Drag Individual Ports: If you need to map ports manually to specific image coordinates, drag the individual ports directly.
   • Sync Indicators: Status LED dots and text labels automatically move with the port blocks, maintaining absolute alignment.
3. Use the on-card control bar to quickly change port ordering (Odd/Even vs. Numeric) or to Reset coordinates.
4. When finished, click the close (✕) button directly on the card to lock the layout and exit editor mode.
5. Save the dashboard card configuration to persist your changes. The exact viewBox coordinates (viewbox: { w, h }) and scale parameters are saved into the Lovelace config, ensuring alignment is identical across all devices and screen sizes.

---

🏷️ Port Labels & Customizations

🔍 What it is

Visual labels layered over or around ports to display port names or numbers in Panel View.

💡 When to use it

• To identify which port is which without having to click on it.
• To outline numbers for high-contrast visibility against detailed backgrounds.

👁️ When you should see it

• When Show Labels is enabled in the card configuration.
• Positions and alignments change depending on the selected configuration.

⚙️ How to use it

1. Enable Show Labels in the Card Editor.
2. Label Position: Set to above, below, inside, or split (renders top row labels above and bottom row labels below the ports).
3. Numeric Labels: Enable Labels: numbers only to keep the interface tidy.
4. Numbers Source: Select Numbers from in the editor:
   • Index: Uses the SNMP interface index value.
   • Port name: Extracts the right-most numeric portion of the interface name (e.g., Gi1/0/24 → 24, FastEthernet2 → 2).
5. Label Outline: Toggle Outline port labels to add a solid outline for high legibility on dark/bright background images.

---

📋 Port Information Popup

🔍 What it is

A modal dialog that opens when clicking a switch port, consolidating all SNMP metrics and live controls for that specific interface.

💡 When to use it

• To check detailed interface information, negotiating speed, PoE consumption, and associated VLANs.
• To toggle port power (Administrative Status) or modify PoE priority settings.

👁️ When you should see it

• Visible when clicking any port on the card.
• Works identically in both Attributes Mode and Sensors Mode.
• Toggle buttons and controls are shown only if the user has not enabled read-only safety mode.

⚙️ How to use it

1. Click any port on the card.
2. The popup displays:
   • Interface Status: Admin and Operational states.
   • Bandwidth: Real-time throughput (RX/TX throughput, cumulative totals).
   • PoE Status: Shows current PoE power usage and offers a PoE Priority dropdown (Low, Medium, High, Critical) and PoE toggle buttons (Auto/On vs Off).
   • VLAN / Trunk details and Interface Index.
3. Toggle Admin status using the Turn on / Turn off buttons. Changes update live in the dialog immediately.
4. Click the Graph button to view traffic history.

---

🔒 Safety & Read-Only Mode

🔍 What it is

A security configuration that hides administrative control buttons (port toggles, PoE toggles) from the card UI.

💡 When to use it

• On wall-mounted control tablets, shared screens, or dashboards accessible to guests or kids.
• When you want to prevent accidental port shutdowns or power interruptions to critical hardware.

👁️ When you should see it

• When Hide control buttons (hide_buttons: true) is enabled.
• All "Turn on / Turn off" and "PoE priority" selectors will be completely hidden from the port detail modals.

⚙️ How to use it

1. Open the Card Editor.
2. Enable the Hide control buttons (Read-only) toggle.
3. Save the card.

---

📊 Diagnostics Panel

🔍 What it is

A collapsible status panel displayed above or below the ports, showing aggregate, switch-level health and environmental metrics.

💡 When to use it

• To monitor overall device temperature, manufacturer data, uptime, and total Power over Ethernet (PoE) consumption.

👁️ When you should see it

• Enabled by default when high-signal sensors or attributes exist on the switch.
• Hidden if Hide diagnostics is enabled.

⚙️ How to use it

1. Toggle the panel by clicking the diagnostics header.
2. Automatic Defaults: The card automatically discovers and displays temperature, temp status, total PoE power used, and available PoE budget if supported.
3. Reordering & Customization: You can add, remove, and reorder diagnostic items directly in the Card Editor list.
4. Attribute Syntax (Advanced): When using Attributes Mode, you can pull specific attributes from parent sensors using the # syntax: sensor.switch_device_environment#System Temperature (°C)

---

📈 Bandwidth History Graphs

🔍 What it is

An interactive popup chart plotting real-time and historical RX and TX bandwidth throughput in a single consolidated graph.

💡 When to use it

• To diagnose bandwidth spikes, monitor network load, or verify download/upload trends.

👁️ When you should see it

• Shown when clicking the Graph button inside the Port Info popup.
• Can be configured to open directly on port click using the speed_click_opens_graph option (requires Speed color mode).
• The graph is styled using theme-resilient colors that automatically adapt to Home Assistant's Light and Dark modes.

⚙️ How to use it

1. Open a port popup and click Graph (or click the port directly if speed-graph shortcuts are active).
2. The Statistics Graph modal displays RX and TX history.
3. Refresh Rate: Use the drop-down selector to set an auto-refresh interval (e.g. 5s, 10s, 30s) or click the Manual Refresh button to query new throughput data.

---

⚙️ YAML Options Reference

Parameter	Type	Default	Description
type	String	Required	Must be custom:snmp-switch-manager-card
device	String	Preferred	The Home Assistant device ID for the network switch
view	String	panel	View layout: panel or list
color_mode	String	state	Port status coloring: state or speed
hide_buttons	Boolean	false	Disable toggling port administrative status and PoE (Read-only mode)
ports_per_row	Number	24	Number of ports shown in a single row (Panel view)
panel_width	Number	0	Width of the card in pixels. If set to 0, the card scales dynamically to fit the dashboard
ports_scale	Number	1.0	Uniform scale multiplier for port icons
background_image	String	""	Optional background faceplate image URL
viewbox	Object	null	Persistent viewBox bounds {w, h} saved during calibration
show_labels	Boolean	true	Show port name/number labels
label_position	String	below	Position of labels relative to ports: above, below, inside, split
label_numbers_only	Boolean	false	Display only numbers in port labels
label_numbers_source	String	index	Source for numeric labels: index or name
label_outline	Boolean	false	Outline text labels in black for legibility
hide_diagnostics	Boolean	false	Completely hide the Diagnostics panel
hide_virtual_interfaces	Boolean	false	Completely hide the Virtual Interfaces list
speed_click_opens_graph	Boolean	false	Clicking a port immediately launches the bandwidth graph popup (Speed mode only)

---

❓ Troubleshooting & FAQs

Refer to the primary Troubleshooting wiki page for detailed connectivity, device selector issues, and SNMP collection errors.