Metadata-Version: 2.5
Name: aiosnmpswitch
Version: 0.3.0
Summary: Async Python client for managed network switches over SNMP - ports, PoE, MAC address table and LLDP neighbours; read-only, typed, vendor-neutral
Project-URL: Homepage, https://github.com/eizedev/aiosnmpswitch
Project-URL: Documentation, https://aiosnmpswitch.eize.dev/
Project-URL: Issues, https://github.com/eizedev/aiosnmpswitch/issues
Project-URL: Changelog, https://github.com/eizedev/aiosnmpswitch/blob/main/CHANGELOG.md
Author-email: eizedev <oss@eize.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: asyncio,home-assistant,hpe,instant-on,lldp,mac-address-table,managed-switch,network-switch,officeconnect,poe,snmp,switch
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: cryptography>=44
Requires-Dist: pysnmp>=7.1.27
Description-Content-Type: text/markdown

# aiosnmpswitch

<!-- === Badges: Release & distribution === -->

| PyPI | Python | Release Date | Downloads |
| ---- | ------ | ------------ | --------- |
| [![PyPI](https://img.shields.io/pypi/v/aiosnmpswitch?cacheSeconds=3600)](https://pypi.org/project/aiosnmpswitch/) | [![Python versions](https://img.shields.io/pypi/pyversions/aiosnmpswitch?cacheSeconds=3600)](https://pypi.org/project/aiosnmpswitch/) | [![GitHub release date](https://img.shields.io/github/release-date/eizedev/aiosnmpswitch?cacheSeconds=3600)](https://github.com/eizedev/aiosnmpswitch/releases/latest) | [![PyPI downloads](https://img.shields.io/pypi/dm/aiosnmpswitch?cacheSeconds=3600)](https://pypistats.org/packages/aiosnmpswitch) |

<!-- === Badges: Quality & community === -->

| CI | License | Typed | Issues | Discussions |
| -- | ------- | ----- | ------ | ----------- |
| [![CI](https://github.com/eizedev/aiosnmpswitch/actions/workflows/ci.yml/badge.svg)](https://github.com/eizedev/aiosnmpswitch/actions/workflows/ci.yml) | [![License](https://img.shields.io/github/license/eizedev/aiosnmpswitch.svg?cacheSeconds=3600)](https://github.com/eizedev/aiosnmpswitch/blob/main/LICENSE) | [![Checked with mypy](https://img.shields.io/badge/mypy-strict-2a6db2)](https://mypy-lang.org/) | [![GitHub issues](https://img.shields.io/github/issues-raw/eizedev/aiosnmpswitch?cacheSeconds=3600)](https://github.com/eizedev/aiosnmpswitch/issues) | [![GitHub discussions](https://img.shields.io/badge/Discussions-ask%20and%20share-lightgrey)](https://github.com/eizedev/aiosnmpswitch/discussions) |

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/eizedev/aiosnmpswitch/main/assets/header-dark.svg">
  <img alt="aiosnmpswitch" src="https://raw.githubusercontent.com/eizedev/aiosnmpswitch/main/assets/header-light.svg" height="72">
</picture>

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, so it is vendor-neutral; a vendor table is read only where the standard
one is missing and the table was measured on that model (temperatures of the HPE Instant On
1930). 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](https://aiosnmpswitch.eize.dev/)**

## Which switches work?

| | |
| --- | --- |
| ✅ **Tested** | HPE OfficeConnect 1920S (JL383A, PD.02.22), HPE Instant On 1930 (JL680A, 3.4.0.0) |
| 🟡 **Expected to work** | Managed switches with SNMP and the standard MIBs (IF-MIB, Q-BRIDGE-MIB, LLDP-MIB) |
| ❔ **Partly** | Switches without LLDP or Q-BRIDGE-MIB: fewer details, no uplink detection; PoE watts per port are not in the standard MIB |
| ❌ **Not in scope** | Unmanaged and "smart" switches without SNMP, changing settings |

Each getter returns an empty result when the switch lacks its MIB. How to report your model:
[Compatibility](https://aiosnmpswitch.eize.dev/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.

```sh
pip install aiosnmpswitch
```

```python
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](https://aiosnmpswitch.eize.dev/getting-started/): install, SNMPv3 or v2c, first read
- [What it can read](https://aiosnmpswitch.eize.dev/reading/): every getter, one per MIB group, and the helpers
- [Locating devices](https://aiosnmpswitch.eize.dev/locating/): which device is on which port, across switches
- [Errors](https://aiosnmpswitch.eize.dev/errors/) and [Diagnostics](https://aiosnmpswitch.eize.dev/diagnostics/): a report to attach to an issue, without personal data
- [Compatibility](https://aiosnmpswitch.eize.dev/compatibility/) and [Design](https://aiosnmpswitch.eize.dev/design/)

## Roadmap

Planned work is grouped in [milestones](https://github.com/eizedev/aiosnmpswitch/milestones).

## Contributing

Reports with your switch model and firmware help most. See [CONTRIBUTING.md](https://github.com/eizedev/aiosnmpswitch/blob/main/CONTRIBUTING.md);
for security issues [SECURITY.md](https://github.com/eizedev/aiosnmpswitch/blob/main/SECURITY.md).

## License

[MIT](https://github.com/eizedev/aiosnmpswitch/blob/main/LICENSE). Provided "as is", without warranty of any kind. The icon and header images are
CC BY 4.0; their source is in [eizedev/brand](https://github.com/eizedev/brand).
