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

Note

Omada gateways are treated as limb-only by design - firewall rules, static routes, NAT, DHCP, and WAN failover are managed via the OPNsense, pfSense, or MikroTik (brain) adapters, not through Omada. See the Brain/Limb architecture for the rationale.

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).

Caution

Setting use_ssl: false downgrades the connection to plain HTTP, which exposes credentials and configuration in transit. Only use plain HTTP on isolated networks where HTTPS is genuinely unavailable. When using HTTPS with a self-signed certificate, keep use_ssl: true and set verify_ssl: false instead.

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:

1. Set ADAPTER_READ_ONLY=false in your environment file (.env.pro, .env.max, etc.).
2. Restart the API service: docker compose --env-file .env.pro up -d api.
3. In the FreeSDN UI, stage a change (e.g., toggle a port PoE setting).
4. 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.

Tip

Even with ADAPTER_READ_ONLY=false, you retain full control. Every change is visible in Pending Changes before it touches the hardware. The “applying” status is visually distinct so you can see what is in flight.

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.

See also

• Adapter Overview - how adapters work, the full vendor matrix
• OPNsense - the firewall “brain” that pairs with Omada switches
• Adapter Contract - the full rubric