Community Submissions

👥 Community Submissions & OID Contributions

SNMP Switch Manager utilizes a dynamic, community-driven database system. Rather than relying on a single developer to maintain static MIB tables for thousands of switch models, the integration features a built-in contribution loop that allows you to submit custom OIDs, interface classification tokens, and vendor filters directly back to the repository from the Home Assistant Options UI.

Once merged, your submissions are automatically distributed via our dynamic database updater to all Home Assistant instances globally within 6 hours—without requiring a code release or a Home Assistant restart!

---

🛑 Guidelines for Contributions (Preventing Frivolous Submissions)

To keep the global database clean, reliable, and functional, we enforce strict submission rules. Submitting invalid or highly customized local rules can break integrations for other users sharing the same switch brand.

1. Local Personal Preferences vs. Global Community Rules

You must understand the difference between a local preference (which should stay on your machine) and a global rule (which benefits the community):

• ❌ Do NOT Submit (Keep Local):
  • Renaming a port because of what is plugged in (e.g., matching interface Gi1/0/5 and renaming it to Jamie's Gaming PC).
  • Setting a custom icon for a single port based on your home-lab hardware (e.g., mapping port Gi1/0/1 to mdi:printer).
  • Excluding a physical port simply because you don't have a cable plugged into it today.
• ✅ DO Submit (Share with Community):
  • The correct CPU, Memory, or Temperature OID for a Cisco, Dell, or Mikrotik switch.
  • A rule that normalizes standard interface abbreviations (e.g., mapping Loopback to lo0 or Port-Channel to Po) to fit the Lovelace card.
  • A vendor-wide exclusion filter (e.g., excluding internal enc interfaces on pfSense firewalls).

---

2. The Verification & Attestation Requirement

Before the integration allows you to submit a Pull Request to GitHub, the options flow forces you to explicitly check three Attestation Checkboxes:

1. Verification: "I attest that I have tested and verified that these OIDs/rules work as expected."
2. Genericity: "I attest that these filters/tokens are beneficial for everyone, are generic, and do not contain personal preferences."
3. Sharing: "Share this with the community."

If any of these attestations are unchecked, the contribution flow will block submission.

---

---

🔍 Category Breakdown: What to Submit & Where to Find It

⚡ Category A: Feature OID Overrides

Exposes health diagnostics (CPU, Memory, PSU, Fans, Temperature, Power, or PoE budgets) for unsupported switches.

What Data is Submitted:

• Dotted Numeric OID: A pure numeric identifier starting with 1.3.6.1... (do not include alpha characters).
• Vendor: The exact vendor/brand string (matching the switch brand name).
• Retrieve Method:
  • GET (Single OID value, e.g. CPU load on a single core).
  • WALK (Querying a table of OIDs, e.g. individual RPMs of multiple chassis fans).
• Scale: A float factor (e.g. 0.1 or 1.0) used to convert raw integer OIDs to actual values (e.g. converting a raw temperature integer like 385 to 38.5°C).
• Unit & Description: Descriptive tags (e.g. %, °C, RPM).

🛠️ Where to Find These OIDs:

1. Manufacturer MIB Documentation: Look up the switch model's technical manuals or standard MIB database files on the manufacturer's support site.
2. MIB Search Engines: Search using tools like MIB Depot or OIDView for terms like sysObjectID, cpu, temperature, or poe.
3. Local CLI Walk Command: Run a full SNMP walk against your device from a terminal on the same network and filter for numerical tables:

   # Extract the full OID map and grep for 'temp', 'cpu', 'rpm', or 'budget'
   snmpwalk -v 2c -c public <Switch_IP> 1.3.6.1.4.1 | grep -i "temp"

---

🖧 Category B: Interface Filters

Used to automatically hide virtual, loopback, or non-physical utility interfaces during port discovery.

What Data is Submitted:

• Rule Type: Include or Exclude.
• Match Type: Starts With, Contains, or Ends With (case-insensitive).
• Match Value: The standard string token (e.g. Null, Vlan, enc, pfsense_loopback).

🛠️ Where to Find These Values:

Query your switch's interface list (ifDescr table) using a CLI tool to inspect the raw names of virtual ports:

snmpwalk -v 2c -c public <Switch_IP> 1.3.6.1.2.1.2.2.1.2

If you see virtual utility adapters such as Vlan100, Null0, or VirtualEthernet1 appearing as empty port entities in Home Assistant, capture the common prefix (e.g. Null or VirtualEthernet) and submit it as a community exclude rule to clean up setups for all users of that vendor.

---

🔌 Category C: Interface Classification Tokens

Determines whether a port is classified as a physical front-panel port (e.g. physical) or a logical layer (e.g. virtual).

What Data is Submitted:

• Token List: Physical List or Virtual List.
• Token String: The exact shorthand string (e.g., vl, lo, lag, bond, irb, bdi).

🛠️ Where to Find These Tokens:

Analyze the standard interface names exposed by your switch's operating system:

• Juniper routers name loopbacks lo0 and VLAN aggregates irb.
• Cisco switches often name virtual loopbacks vl or bridge interfaces bdi.
• If a newly discovered switch brand shows standard virtual interfaces as physical ports, identify the prefix token used by the OS and submit it to the Virtual Token List so the integration's heuristic engine learns to classify it correctly.

---

🔑 The Secure OAuth Device Flow

To submit a PR, the integration uses the secure GitHub Device Flow protocol.

1. Sandboxed Authorization: The integration never requests your GitHub password or personal access tokens.
2. Minimal Permissions: The requested authentication scope is strictly limited to public_repo (which only allows the integration to create a temporary fork of the public database and submit a Pull Request to our master repo).
3. No Local Credentials Stored: The authorization token is used in memory to commit the JSON changes and is cleared immediately after the Pull Request is created.