Sankofa/infrastructure/omada/api/README.md

# TP-Link Omada API Client

Python and Go client libraries for interacting with the TP-Link Omada Controller API.

## Overview

The Omada API client provides a high-level interface for managing TP-Link Omada SDN infrastructure, including access points, switches, gateways, and network policies.

## Features

- Controller authentication and session management
- Site and device management
- Access point configuration
- Network policy management
- Client device tracking
- Analytics and monitoring

## Installation

### Python

```bash
pip install omada-api
```

### Go

```bash
go get github.com/sankofa/omada-api
```

## Usage

### Python

```python
from omada_api import OmadaController

# Initialize controller
controller = OmadaController(
    host="omada.sankofa.nexus",
    username="admin",
    password="secure-password",
    verify_ssl=True
)

# Authenticate
controller.login()

# Get sites
sites = controller.get_sites()
for site in sites:
    print(f"Site: {site['name']} (ID: {site['id']})")

# Get access points
aps = controller.get_access_points(site_id="us-east-1")
for ap in aps:
    print(f"AP: {ap['name']} - {ap['status']}")

# Configure access point
controller.configure_ap(
    ap_id="ap-123",
    name="AP-Lobby-01",
    radio_config={
        "2.4GHz": {
            "channel": "auto",
            "power": "high",
            "bandwidth": "20/40MHz"
        },
        "5GHz": {
            "channel": "auto",
            "power": "high",
            "bandwidth": "20/40/80MHz"
        }
    }
)

# Create SSID
controller.create_ssid(
    site_id="us-east-1",
    name="Sankofa-Employee",
    security="wpa3",
    password="secure-password",
    vlan=100
)

# Logout
controller.logout()
```

### Go

```go
package main

import (
    "fmt"
    "log"
    "github.com/sankofa/omada-api"
)

func main() {
    // Initialize controller
    client := omada.NewClient(
        "omada.sankofa.nexus",
        "admin",
        "secure-password",
    )
    
    // Authenticate
    if err := client.Login(); err != nil {
        log.Fatal(err)
    }
    defer client.Logout()
    
    // Get sites
    sites, err := client.GetSites()
    if err != nil {
        log.Fatal(err)
    }
    
    for _, site := range sites {
        fmt.Printf("Site: %s (ID: %s)\n", site.Name, site.ID)
    }
    
    // Get access points
    aps, err := client.GetAccessPoints("us-east-1")
    if err != nil {
        log.Fatal(err)
    }
    
    for _, ap := range aps {
        fmt.Printf("AP: %s - %s\n", ap.Name, ap.Status)
    }
}
```

## API Reference

### Authentication

```python
# Login
controller.login()

# Check authentication status
is_authenticated = controller.is_authenticated()

# Logout
controller.logout()
```

### Sites

```python
# Get all sites
sites = controller.get_sites()

# Get site by ID
site = controller.get_site(site_id="us-east-1")

# Create site
site = controller.create_site(
    name="US East Datacenter",
    timezone="America/New_York"
)

# Update site
controller.update_site(
    site_id="us-east-1",
    name="US East Datacenter - Updated"
)

# Delete site
controller.delete_site(site_id="us-east-1")
```

### Access Points

```python
# Get all access points for a site
aps = controller.get_access_points(site_id="us-east-1")

# Get access point by ID
ap = controller.get_access_point(ap_id="ap-123")

# Configure access point
controller.configure_ap(
    ap_id="ap-123",
    name="AP-Lobby-01",
    location="Lobby",
    radio_config={
        "2.4GHz": {"channel": "auto", "power": "high"},
        "5GHz": {"channel": "auto", "power": "high"}
    }
)

# Reboot access point
controller.reboot_ap(ap_id="ap-123")

# Update firmware
controller.update_firmware(ap_id="ap-123", firmware_url="...")
```

### SSIDs

```python
# Get all SSIDs for a site
ssids = controller.get_ssids(site_id="us-east-1")

# Create SSID
ssid = controller.create_ssid(
    site_id="us-east-1",
    name="Sankofa-Employee",
    security="wpa3",
    password="secure-password",
    vlan=100,
    radios=["2.4GHz", "5GHz"]
)

# Update SSID
controller.update_ssid(
    ssid_id="ssid-123",
    name="Sankofa-Employee-Updated"
)

# Delete SSID
controller.delete_ssid(ssid_id="ssid-123")
```

### Network Policies

```python
# Get network policies
policies = controller.get_policies(site_id="us-east-1")

# Create policy
policy = controller.create_policy(
    site_id="us-east-1",
    name="Guest-Policy",
    bandwidth_limit=10,  # Mbps
    vlan=200,
    firewall_rules=[
        {"action": "allow", "ports": [80, 443]},
        {"action": "block", "ports": "all"}
    ]
)

# Apply policy to SSID
controller.apply_policy(ssid_id="ssid-123", policy_id="policy-123")
```

### Clients

```python
# Get client devices
clients = controller.get_clients(site_id="us-east-1")

# Get client by MAC
client = controller.get_client(mac="aa:bb:cc:dd:ee:ff")

# Block client
controller.block_client(mac="aa:bb:cc:dd:ee:ff")

# Unblock client
controller.unblock_client(mac="aa:bb:cc:dd:ee:ff")
```

## Error Handling

```python
from omada_api import OmadaError, AuthenticationError

try:
    controller.login()
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except OmadaError as e:
    print(f"Omada API error: {e}")
```

## Configuration

### Environment Variables

```bash
export OMADA_HOST=omada.sankofa.nexus
export OMADA_USERNAME=admin
export OMADA_PASSWORD=secure-password
export OMADA_VERIFY_SSL=true
```

### Configuration File

```yaml
omada:
  host: omada.sankofa.nexus
  port: 8043
  username: admin
  password: ${OMADA_PASSWORD}
  verify_ssl: true
  timeout: 30
```

## Related Documentation

- [Omada Management](../README.md)
- [Infrastructure Management](../../README.md)