py-mercury-switch-api 0.3.0

A library for interacting with Mercury switches.

py-mercury-switch-api

中文文档

A Python library for interacting with Mercury (水星) network switches via their web interface.

Features

• 🔍 Auto-detection - Automatically detects switch model
• 📊 System Info - Retrieve switch model, MAC address, IP, firmware version
• 🔌 Port Status - Monitor port states, connection speeds, and link status
• 📈 Traffic Statistics - Get TX/RX packet counts per port
• 🏷️ VLAN Support - Read 802.1Q VLAN configuration
• 🧪 Offline Mode - Test with saved HTML pages for development

Installation

pip install py-mercury-switch-api

Quick Start

from py_mercury_switch_api import MercurySwitchConnector

# Create connector
connector = MercurySwitchConnector(
    host="192.168.1.1",
    username="admin",
    password="password"
)

# Login and get switch information
if connector.get_login_cookie():
    # Auto-detect switch model
    connector.autodetect_model()
    print(f"Detected: {connector.switch_model.MODEL_NAME}")
    
    # Get all switch information
    info = connector.get_switch_infos()
    print(info)

API Reference

MercurySwitchConnector

The main class for interacting with Mercury switches.

Constructor

MercurySwitchConnector(host: str, username: str, password: str)

Parameter	Type	Description
host	str	IP address or hostname of the switch
username	str	Login username (usually admin)
password	str	Login password

Methods

Method	Description
get_login_cookie()	Authenticate and obtain session cookie. Returns True on success.
autodetect_model()	Detect and configure the switch model automatically.
get_switch_infos()	Retrieve all available switch information as a dictionary.
get_unique_id()	Get a unique identifier for the switch (model + IP).

Return Data Structure

The get_switch_infos() method returns a dictionary containing:

{
    # System Information
    "switch_model": "SG108-Pro",
    "switch_mac": "AA:BB:CC:DD:EE:FF",
    "switch_ip": "192.168.1.1",
    "switch_firmware": "1.0.0",
    "switch_hardware": "V1.0",
    
    # Port Status (for each port 1-N)
    "port_1_state": "on",           # Port enabled state
    "port_1_status": "on",          # Link status (connected/disconnected)
    "port_1_speed": "1000M Full",   # Configured speed
    "port_1_connection_speed": "1000M Full",  # Actual connection speed
    
    # Traffic Statistics (for each port)
    "port_1_tx_good": 123456,       # TX good packets
    "port_1_tx_bad": 0,             # TX bad packets
    "port_1_rx_good": 654321,       # RX good packets
    "port_1_rx_bad": 0,             # RX bad packets
    
    # VLAN Information
    "vlan_enabled": True,
    "vlan_type": "802.1Q",
    "vlan_count": 2,
    "vlan_1_name": "default",
    "vlan_1_tagged_ports": "1, 2",
    "vlan_1_untagged_ports": "3, 4, 5, 6, 7, 8",
}

Supported Models

Model	Ports	Status
SG108Pro	8	✅ Supported
SG105E	5	🚧 Planned

Home Assistant Integration

This library is designed to be used with Home Assistant. A custom integration is available at:

Coming soon

Development

Setup

# Clone the repository
git clone https://github.com/daxingplay/py-mercury-switch-api.git
cd py-mercury-switch-api

# Install in development mode
pip install -e ".[dev]"
# Or install dependencies manually
pip install -e .
pip install pytest pytest-cov ruff mypy

Running Tests

pytest

Code Quality

# Format code
ruff format .

# Lint
ruff check .

# Type check
mypy src/py_mercury_switch_api

Adding New Model Support

See CONTRIBUTING.md for detailed instructions on how to add support for new Mercury switch models.

Quick Overview

1. Create a model class in models.py:

class SG116E(AutodetectedMercuryModel):
    """Mercury SG116E 16-port switch."""
    
    MODEL_NAME = "SG116E"
    PORTS = 16
    
    CHECKS_AND_RESULTS: ClassVar = [
        ("check_system_info_model", ["SG116E"]),
    ]

2. Add test fixtures in tests/fixtures/MODEL_NAME/0/

3. Run tests to verify the model works correctly

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

How to Contribute

1. Fork the repository
2. Create your feature branch (git checkout -b feature/new-model)
3. Commit your changes (git commit -am 'Add support for SG116E')
4. Push to the branch (git push origin feature/new-model)
5. Open a Pull Request

License

This project is licensed under the Apache Software License 2.0 - see the LICENSE file for details.

Acknowledgments

• Inspired by py-netgear-plus