Integration Configuration

⚙️ Integration & Device Options Configuration (Comprehensive Reference)

This page is the definitive reference manual for configuring SNMP Switch Manager inside Home Assistant. It details the how, why, and when for every option, step, and feature toggled in the Device Options flow.

---

🧭 Navigating the Options Flow

All configurations are applied per switch and can be modified dynamically at any time.

To access these settings:

1. Navigate to Settings → Devices & Services in Home Assistant.
2. Locate the SNMP Switch Manager card.
3. Click the Configure button on the switch device you wish to modify.

This will present the Main Options Menu, which is split into 5 top-level submenus to keep the user interface clean and performant:

• Connection & Name
• Manage Interfaces
• Bandwidth Sensors
• Environmental Sensors
• Feature OID Overrides

---

🧠 Attributes Mode vs. Sensors Mode (Deep Dive)

Before configuring diagnostics, you must understand the architectural difference between Attributes Mode and Sensors Mode. This choice directly impacts Home Assistant's CPU usage, memory, database size, and Lovelace card performance.

🧠 Attributes Mode (Recommended)

• How it works: Rich diagnostic metrics are packed as metadata attributes on parent entities. For example, cumulative port traffic and real-time speeds are attached as attributes to the main port switch entity. Ambient temperature, CPU, and memory are attached as attributes to a single sensor.switch_environment entity.
• Why use it:
  • Registry Cleanliness: A 48-port switch requires only ~50 entities total.
  • Database Optimization: Home Assistant's recorder only writes state changes for the parent entity, drastically reducing disk writes and database size.
  • Dashboard Speed: The custom SNMP Switch Manager Lovelace Card is engineered to read attributes directly from parent port entities. It performs significantly faster in this mode.
• Limitations: You cannot easily generate standard Home Assistant history charts (graphs) for individual attributes in the default UI without creating template sensors.

📊 Sensors Mode

• How it works: Home Assistant generates a separate, standalone entity for every single tracked metric.
• Why use it:
  • Native Automation: Standard triggers can easily monitor entities (e.g., triggering a notification when sensor.switch_cpu_utilization exceeds 90%).
  • Long-Term Statistics: You get out-of-the-box historical graphs, data logging, and energy tracking (for port PoE power sensors) in Home Assistant.
• Limitations:
  • High Entity Count: A 48-port switch with bandwidth, environment, and PoE enabled will generate over 250 entities.
  • Database bloat: High entity counts with frequent polling (e.g., bandwidth every 10 seconds) will cause Home Assistant's database to grow rapidly, which can lead to slow system performance on low-power hardware (like Raspberry Pi).

---

1. Connection & Name

This menu handles connection parameters, protocol version adjustments, and performance settings.

• SNMP Version: Allows you to switch the switch connection between SNMP v2c and SNMP v3 dynamically.

  • [!IMPORTANT]
    Registry Stabilization (legacy_device_id)
    In Home Assistant, a device’s unique ID is traditionally derived from its initial connection parameters (e.g. Host/Port/Community). Upgrading an existing switch from SNMP v2c to SNMP v3 would normally cause Home Assistant to think a new device has been added, creating duplicate entities and breaking your Lovelace cards. SNMP Switch Manager automatically detects and persists a legacy_device_id registry token so you can toggle versions seamlessly without losing historical data or breaking dashboards.

• SNMP v2c Credentials:
  • SNMP Community Override: Enter a custom community string if you need to override the initial setup. Use a Read-Write (RW) community to enable active control toggles.
  • SNMP Port Override: Overrides the standard UDP port (default is 161).
• SNMP v3 Credentials:
  • Username: The SNMPv3 username configured on your physical switch.
  • Authentication Protocol: Choose HMAC-SHA, HMAC-MD5, or None (must match the switch).
  • Authentication Password: Your authentication password.
  • Privacy Protocol: Choose CBC-DES or None (must match the switch). Note: AES is reserved for future expansion.
  • Important: Password lengths must be strictly between 8 and 31 characters. Short passwords will be rejected by the integration to avoid silent connection drops.
• Uptime Refresh Interval:
  • Why it matters: System uptime (sysUpTime) is a low-priority metric that rarely changes. Polling it every 10 seconds is a waste of switch CPU and network bandwidth.
  • How to use: Set a higher interval (e.g. 300s / 5 minutes) to keep system data fresh while minimizing polling load on older hardware. Range: 30s to 3600s.

---

2. Manage Interfaces

Controls which switch ports are discovered and how they are displayed and classified in Home Assistant.

Interface IP Display

• Option: Hide IP field on Physical Interfaces (CONF_HIDE_IP_ON_PHYSICAL_INTERFACES).
• Why it matters: Certain switch brands (e.g., Zyxel, TP-Link) report their management or SVI IP address on every single physical port index inside their SNMP bridge tables. This causes IP addresses to incorrectly display on every port tile on your dashboard.
• How to use: Enabling this option dynamically hides IP addresses on interfaces classified as physical, while keeping them visible on virtual layers (VLANs, management, or SVIs).

Excluded & Included Interfaces (Custom Match Rules)

• Apply regex or simple string filters to restrict which ports generate Home Assistant entities.
• Match Types: Starts With, Contains, or Ends With (case-insensitive).
• Example: If you only want to monitor SFP ports, add an Include rule for SFP. If you want to skip phone connections, add an Exclude rule for VoIP.
• Note: Exclude rules always take precedence over Include rules.

Built-in Vendor Filters

• Toggle built-in vendor-specific exclusion rules (such as skipping internal management, stacking ports, or control planes on pfSense, OPNsense, or Cisco). These rules live in the dynamic vendor database and can be turned on or off via checkboxes.

Interface Name Rules

Custom Rename Rules (Regex)

Allows you to cleanly format long, complex system names into intuitive, short labels suitable for the Lovelace card grid.

• Rules are applied in order and take priority over built-in renaming rules.
• Pattern: A regular expression matching the switch's raw name (e.g., ^GigabitEthernet(\d+)/0/(\d+)$).
• Replacement: The output format using match groups (e.g., Gi-\1-\2, which transforms GigabitEthernet1/0/5 to Gi-1-5).
• Common Regex Examples:
  • Cisco / Dell: Pattern ^GigabitEthernet(\d+)/0/(\d+)$ -> Replacement Gi-\1-\2
  • Juniper: Pattern ^ge-(\d+)/(\d+)/(\d+)$ -> Replacement ge-\1/\2/\3
  • MikroTik: Pattern ^ether(\d+)$ -> Replacement Eth-\1

Built-in Rename Rules

Checkboxes to toggle standard pre-configured transformations:

• Normalize link aggregates to Po (e.g. LinkAggregate1 -> Po1).
• Normalize loopbacks to lo0.
• Normalize Port-Channels to Po.
• Normalize Slot/Port counters (e.g. Fa1/0/1 normalizations).

Entity Icon Rules

Expose custom icons for interfaces based on character matching.

• Example: If a port description contains the word Uplink, map it to mdi:router-wireless. If it contains Camera, map it to mdi:webcam.

Submit Community Filter/Token

If you identify a generic virtual interface prefix or a vendor filter rule that is universally helpful for your switch brand, submit it back to our central database here.

• [!IMPORTANT]
  Submit Generic Data Only: Before using this menu, please read our Community Submissions Guide to review our strict guidelines and ensure your submission is generic and beneficial for everyone, rather than a personal layout preference.

---

3. Bandwidth Sensors

Configure real-time throughput and traffic totals.

• Enable Bandwidth Collection: Toggle bandwidth tracking.
• Bandwidth Data As: Attributes (no history) or Sensors (history).
• Poll Interval: Set the bandwidth update interval in seconds (range: 5s to 3600s). Lower intervals give near-real-time updates but increase network and switch CPU usage. Default is 30s.
• Bandwidth Include / Exclude Rules:
  • Apply only to bandwidth sensor generation and are independent of standard interface filters.

  • [!WARNING]
    Avoiding Database & Entity Bloat
    A 48-port switch with bandwidth enabled in Sensors mode will create 192 individual sensors (4 sensors per port: RX Throughput, TX Throughput, RX Total, TX Total). This can impact Home Assistant startup time and database size. It is strongly recommended to use Bandwidth Include/Exclude rules to only generate bandwidth entities for critical interfaces (such as uplinks, servers, or media devices), leaving unused or client ports off.

• Bandwidth Sensor Icons: Override default icons for RX Throughput, TX Throughput, RX Total, and TX Total sensors.

---

4. Environmental Sensors

Enable chassis health and Power over Ethernet (PoE) diagnostics.

• Enable Environmental Sensors: Toggle chassis health polling (Temperature, Fan RPM, PSU status, CPU, Memory). Choose Sensors mode (historical charts) or Attributes mode (real-time diagnostics on a single entity).
• Enable PoE Statistics: Toggle overall PoE monitoring. Choose Sensors or Attributes mode.
• Create Per-Port PoE Power Sensors: When running in Sensors mode, enabling this generates an active power sensor (W) for every physical port that is PoE-capable, showing the exact draw of that specific connected device.
• PoE Control Loops: Toggle the background loops that manage port power limits and active port resets.
• Environmental/PoE Polling Intervals: Independently configure how often chassis environment and PoE metrics are polled (range: 5s to 3600s).

---

5. Feature OID Overrides (Advanced)

For advanced users or unsupported switch hardware, this panel allows you to manually override the SNMP OIDs used to query system metrics:

Override Submenu	Key Fields	Description & Use Case
Override Power	Power OID, scale, unit, method	Track active chassis power draw in Watts.
Override CPU	CPU OID, scale, unit, method (GET/WALK)	Track system processor load. GET queries a single core; WALK queries a table of cores.
Override Memory	Free/Total Memory OIDs, or percentage OID, type, scale, method	Track memory utilization. Can be mapped as free/total bytes or direct percentage.
Override Fans	Fan RPM OID, Fan Status OID, scale, method	Track RPM speeds and health status.
Override PSU	PSU Status OID, label, filter regex	Monitor redundant power supplies and status codes.
Override Temperature	Temp OID, State OID, Label OID, scale, method	Track ambient and core temperature sensors.
Override PoE	Total/Used PoE Budget OIDs, Port Power OID, PoE Port Admin OID, Power Priority OID	Expose switch-level budgets and per-port active power draw.
Override Device Info	Manufacturer, Model, Firmware, Hostname, Uptime, Contact, Name, and Location OIDs	Customize hardware and software properties.

---

🚀 Direct GitHub PR Submissions (The Community Loop)

When you manually configure custom OIDs, interface filters, or classification tokens that successfully resolve an unsupported switch, the integration will prompt you:

• "Do you want to submit this override to the repository to help other users?"

If you select Yes, the integration initializes the secure GitHub Device OAuth Flow:

1. It displays a unique 8-character verification code and a link to github.com/login/device.
2. Open the link, authenticate with your GitHub account, and enter the code.
3. Click Submit in Home Assistant. The integration will automatically fork the main repository, create a git branch, commit your new database additions, and submit a Pull Request back to the core repository!
4. Once merged, the background dynamic OID updater will push your new switch templates to all other users' devices globally within 6 hours!

Caution

Check the Guidelines First
Before finalizing your Pull Request, you must read the Community Submissions Guide. Frivolous, incorrect, or heavily customized local OID configurations submitted as PRs can break health indicators for other community members. Ensure you have fully tested and verified the numerical data on actual hardware.

---

🚀 Next Step

With configuration complete, learn more about what diagnostics are exposed and how to interpret chassis-level health metrics:

👉 Go to Diagnostics & Health Metrics