omada-client

Python client for Tp-Link Omada Controller (Omada Software Controller). Allows executing API calls to the Omada Controller from Python code.

Library created for automating and integrating with TP-Link Omada SDN Controllers. Unlike raw HTTP scripts or outdated wrappers, this library provides a clean, typed interface that enables developers and network engineers to manage Omada infrastructure with minimal effort and maximum reliability.

It abstracts away authentication, session handling, CSRF tokens, and endpoint routing, allowing you to focus on logic instead of network plumbing. The library is fully compatible with modern Python environments (>=3.11), supports structured data models via Pydantic, and includes utilities for batching large requests, safely manipulating network routes, and managing connected devices.

Installation

Using python:

pip install omada-client

Quick Start

Using direct credentials

from omada_client import OmadaClient

omada = OmadaClient(
    "OMADA_DOMAIN",    # URL of Omada WebUI
    "OMADA_USER",      # Username
    "OMADA_PASSWORD",  # Password
    "SITE_ID"          # Site identify (Optional. Default: First site in list)
)

Using environment variables

from dotenv import load_dotenv
import os
from omada_client import OmadaClient

load_dotenv()

omada = OmadaClient(
    os.getenv("OMADA_DOMAIN"),
    os.getenv("OMADA_USER"),
    os.getenv("OMADA_PASSWORD"),
    os.getenv("SITE_ID")
)

print(omada.get_devices())

Methods Reference

Advanced Example

Create static routes from large data sets

from dotenv import load_dotenv
import os
from omada_client import OmadaClient

load_dotenv()

omada = OmadaClient(
    os.getenv("OMADA_DOMAIN"),
    os.getenv("OMADA_USER"),
    os.getenv("OMADA_PASSWORD")
)

data = [
    {"name": "group_1", "ips": "99.99.99.99/24, 88.88.88.88/24"},
    {"name": "group_2", "ips": "99.99.99.99/24, 88.88.88.88/24"}
]

wan = omada.get_wan_ports_by_desc("openwrt")

omada.create_static_route_to_inteface_with_big_data(
    data_static_routes=data,
    interface_id=wan.port_uuid,
    next_hop_ip=wan.wan_port_ipv4_setting.get("ipv4Static").get("gateway"),
    enable=False
)

Notes

• Replace all IPs, MAC addresses, and credentials with real values.
• Environment variables help keep sensitive credentials out of code.
• Use badges above to quickly check test status and PyPI version.