TP-Link Omada

The Omada adapter is the gold-standard reference implementation for FreeSDN. It manages TP-Link Omada controller-managed switches, access points, and wireless networks via the Omada Software/Hardware Controller REST API. Every other adapter in the platform is checked against the patterns established here.

Fact	Detail
Maturity	Production
Gold-standard contract	DG ✓ CB ✓ RR ✓ TS ✓ SSRF ✓ RG ✓
Omada controller versions tested	Software Controller 5.x / Hardware Controller

What it manages

Switches

Port enable/disable, PoE on/off/cycle/schedule (802.3af/at/bt)
VLAN CRUD with an interactive port-VLAN matrix (untagged / tagged / excluded per cell)
LAG (Link Aggregation Group) CRUD - LACP and static modes
Port mirroring, port profiles CRUD
ACL rules, QoS, STP, IGMP snooping, DHCP snooping
Per-port statistics (utilization, PoE draw, LLDP neighbor)
SFP module info (type, vendor, wavelength, temperature)
Cable diagnostic test, ping, traceroute

Access points

SSID / WLAN CRUD with per-AP overrides
Channel utilization (RF Health) per band (2.4 / 5 / 6 GHz)
Rogue-AP detection table (BSSID, SSID, classification)
Site-wide radio settings (channel plan, TX power, DFS, band steering, 802.11r/k/v fast roaming)
802.1X configuration and per-port mode (auto / force-authorized / force-unauthorized)
Hotspot / captive portal config + voucher management
Mesh topology, AP radio config, LED, location

Clients

List, block, unblock, kick, reconnect, batch operations

Firmware

Upgrade, batch firmware operations with scheduling; upgrade history log
Platform-level rollback via POST /api/v1/firmware/devices/{id}/rollback (not Omada-API-native)

Config

Backup and restore (controller-level config archive)
Config history with diff viewer (side-by-side change audit)

Real-time

21 WebSocket event handlers for live port link up/down, PoE faults, client connect/disconnect, firmware upgrade progress

Frontend pages

Page	Description
`SwitchesPage`	total (2,250 main + 12 tab components in `switches/tabs/`): overview, ports, VLANs, LAGs, profiles, network, config, config history, logs, clients, diagnostics, advanced
`AccessPointsPage`	, 8 tabs: overview, radios (AP radio config), SSIDs (WiFi/SSID management), clients, config, RF Health, rogue APs, radio settings
`VlansPage`	VLAN list + interactive port-VLAN assignment matrix + cross-controller alignment view
`FirmwarePage`	Firmware dashboard, staged rollout, upgrade history
`ControllerDetailPage`	Controller health and runtime stats (CPU/memory/disk), managed devices list, firmware status, and connection settings (4 tabs: overview, devices, firmware, settings)

Backend route prefixes

/api/v1/switches/*
/api/v1/access-points/*
/api/v1/network/*
/api/v1/gateway-firmware/*   ← Omada adapter: firmware upgrade, batch upgrade, schedule CRUD, history
/api/v1/firmware/*           ← platform-wide: generic firmware rollback endpoint
/api/v1/poe/*
/api/v1/controllers/*

Connection requirements

The Omada adapter connects to the Omada Software Controller or Hardware Controller HTTP/HTTPS API.

Credentials

Field	Value
`credential_type`	`username_password`
`username`	Omada controller administrator username
`password`	Omada controller administrator password

Controller URL

Point host at the base URL of your Omada controller, including the protocol and port:

https://omada.example.com:8043

Or, for an Omada hardware controller accessible over HTTP (not recommended for production):

http://192.168.1.1:8088

Set use_ssl: true (the default) to use HTTPS when connecting to the controller. The adapter also supports a separate verify_ssl field (default false) to control whether the TLS certificate is validated - set verify_ssl: false when your controller uses a self-signed certificate you cannot import as a trusted CA. Set use_ssl: false only when your controller is accessible over plain HTTP (not recommended in production).

Adding the controller

# Create the controller record (credentials are passed inline  -  no separate credential store step needed)
curl -X POST https://<freesdn-host>/api/v1/controllers \
  -H "Cookie: freesdn_access=<token>" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "omada-prod",
    "controller_type": "omada",
    "host": "omada.example.com",
    "port": 8043,
    "use_ssl": true,
    "verify_ssl": false,
    "site_id": "<freesdn-site-uuid>",
    "username": "admin",
    "password": "<controller-password>"
  }'

# Trigger discovery
curl -X POST https://<freesdn-host>/api/v1/discovery/controllers/<controller-id> \
  -H "Cookie: freesdn_access=<token>" \
  -H "X-CSRF-Token: <csrf>"

Enabling write operations

By default FreeSDN operates read-only. To allow the Omada adapter to push changes to your controller:

Set ADAPTER_READ_ONLY=false in your environment file (.env.pro, .env.max, etc.).
Restart the API service: docker compose --env-file .env.pro up -d api.
In the FreeSDN UI, stage a change (e.g., toggle a port PoE setting).
Navigate to Pending Changes and approve the change, confirming force: true.

Both gates must be open simultaneously - the environment flag alone is not enough. Changes are always reviewed on the Pending Changes page before anything is sent to the controller.

Resilience

The Omada client wraps every request with:

Token-bucket rate limiter (default 60 req/min, configurable via OmadaClientConfig.rate_limit_rpm)
Concurrency semaphore (default 5 concurrent in-flight requests, rate_limit_concurrent)
Retry with exponential backoff (default 3 retries; retries on TimeoutException, connection errors, 502/503/504, 429; does not retry other 4xx or 5xx including 500)
Circuit breaker (trips after 5 consecutive failures; 30 s cooldown; exposes freesdn_adapter_circuit_state{adapter,host} Prometheus gauge)

Observability

The Omada adapter emits the following Prometheus metrics:

Metric	Type	Labels
`freesdn_adapter_requests_total`	Counter	`adapter, method, outcome`
`freesdn_adapter_request_duration_seconds`	Histogram	`adapter, method`
`freesdn_adapter_errors_total`	Counter	`adapter, error_type`
`freesdn_adapter_circuit_state`	Gauge	`adapter, host`
`freesdn_adapter_pending_changes`	Gauge	`adapter, status`

Controller health (login status, error rate, avg latency, circuit state) is exposed via POST /api/v1/controllers/{id}/test.

Path-segment validation

The Omada client does not URL-encode path segments; the adapter validates every path parameter through validate_id() (1-64 chars, [A-Za-z0-9_.\\-*:], no .. or /) and validate_mac() (standard MAC notation with either colon or hyphen separators, case-insensitive - e.g. AA:BB:CC:DD:EE:FF or aa-bb-cc-dd-ee-ff) before they reach the HTTP client. Requests with invalid identifiers are rejected at the adapter layer with HTTP 400.

Known limitations

Omada gateways are limb-only - no Layer 3 gateway/firewall orchestration through this adapter.
HA pair status is readable; orchestrated CARP failover is not exposed.