aiosnmpswitch

PyPI	Python	Release Date	Downloads

CI	License	Typed	Issues	Discussions

A Python library that reads what your managed network switches know over SNMP: ports with link, speed and traffic, PoE, the MAC address table, LLDP neighbours, trunks and spanning tree. Across several switches it works out which device is connected to which port. It only reads and never changes a setting.

It uses standard MIBs only, so it is vendor-neutral; HPE OfficeConnect 1920S and HPE Instant On 1930 are the tested references. It is built as a foundation for Home Assistant, but works in any asyncio program.

Documentation: aiosnmpswitch.eize.dev

Which switches work?

Each getter returns an empty result when the switch lacks its MIB. How to report your model: Compatibility.

Quick start

You need Python 3.12 or newer and SNMP read access to the switch: SNMPv3 (recommended) or a v2c community. To locate devices across several switches, LLDP must be on on each of them.

pip install aiosnmpswitch

import asyncio

from aiosnmpswitch import AuthProtocol, PrivProtocol, SnmpSwitch, UsmAuth
from aiosnmpswitch.helpers import SwitchData, locate_macs


async def main() -> None:
    auth = UsmAuth("monitor", "auth-key", "priv-key", AuthProtocol.SHA, PrivProtocol.AES128)
    async with await SnmpSwitch.connect("192.0.2.10", auth) as switch:
        system = await switch.get_system()
        print(system.name, system.descr)
        interfaces = await switch.get_interfaces()
        for port in interfaces.values():
            print(port.name, port.oper_status, port.high_speed, port.alias)

        data = SwitchData(
            interfaces=interfaces,
            bridge_ports=await switch.get_bridge_ports(),
            fdb=await switch.get_fdb(),
            lldp=await switch.get_lldp(),
            lag_ports=await switch.get_lag_ports(),
        )
        for mac, where in locate_macs({"core": data}).items():
            print(mac, "on port", where.port_name)


asyncio.run(main())

Documentation

• Getting started: install, SNMPv3 or v2c, first read
• What it can read: every getter, one per MIB group, and the helpers
• Locating devices: which device is on which port, across switches
• Errors and Diagnostics: a report to attach to an issue, without personal data
• Compatibility and Design

Roadmap

Planned work is grouped in milestones.

Contributing

Reports with your switch model and firmware help most. See CONTRIBUTING.md; for security issues SECURITY.md.

License

MIT. Provided "as is", without warranty of any kind. The icon and header images are CC BY 4.0; their source is in eizedev/brand.