Get the Omada controller's own identity: controller_version, omadac_id, configured. Unauthenticated (GET /api/info) - works regardless of which auth mode this server is configured with.

List sites managed by this controller: id + name.

Requires legacy login (OMADA_USER/OMADA_PASS) - see README's auth x endpoint matrix for why the Open API path can't serve this in v0.1.

List devices on a site, normalized to one consistent shape regardless of auth mode (see formatting.normalize_device): connected, uptime_seconds, per-radio wifi_2g/wifi_5g channel info, and every raw field this package knows how to normalize - fields unavailable in the active auth mode are present as null rather than omitted, so a caller never has to branch on auth mode.

site_id defaults to OMADA_SITE_ID, or auto-selects if the controller manages exactly one site (legacy auth only).

Get the richest available detail for one device by MAC address (any common separator - colon, hyphen, Cisco-dotted, or bare - is accepted and normalized).

Legacy auth: full detail (ssidOverrides, lanPortSettings, ledSetting, ...) for AP/EAP devices via /eaps/{MAC}; other device types fall back to their grid/devices summary row (no richer verified endpoint yet - see README). Open API auth: the matching (reduced-field) row from the device list.

The normalized fields (see list_devices) are included, plus the complete raw response under raw so nothing the controller returned is lost.

Per-AP WiFi summary: 2.4GHz/5GHz channel (parsed from the controller's irregularly-formatted actualChannel string), client counts per band, and radio utilization. One entry per AP on the site, or just the one matching mac if given.

Requires legacy login (OMADA_USER/OMADA_PASS) - the Open API device list has no per-radio fields at all (confirmed against real hardware; see README's auth x endpoint matrix).

List Insight/known clients on a site: mac, name, download/upload (bytes), duration_seconds, last_seen_ms, guest/wireless flags, vid (VLAN), and block/manager flags. This is the controller's "Insight" view (historical + known clients), not just currently-associated ones.

Requires legacy login (OMADA_USER/OMADA_PASS) - no Open API equivalent has been verified against real hardware yet.

List active alerts on a site.

The pagination envelope is confirmed against real hardware; the shape of an individual alert row is NOT (no alert was active during verification) - each entry includes a best-effort module/level/ content/time guess AND the untouched raw row, so nothing is lost if the guess is wrong. See docs/api-notes.md.

Requires legacy login (OMADA_USER/OMADA_PASS) - no Open API equivalent has been verified against real hardware yet.

Set an AP's 2.4GHz ("2g") or 5GHz ("5g") radio channel.

WRITE tool, guarded: blocked entirely unless the server is running with OMADA_ALLOW_WRITE=true. Call with confirm=False (the default) to get a before/after preview (channel + freq) without changing anything; call again with confirm=True to actually apply it.

applied=True is only ever returned once a post-write re-read confirms the change (comparing freq, the one reliable round-trip value) - a bare "the controller said Success" is never trusted on its own. If the controller accepted the write but the re-read shows no change, applied=False and message explains why - see guard.set_radio_channel's docstring and docs/api-notes.md. Every call also carries a warning: changing a channel restarts the radio (clients on that band briefly disconnect and reassociate), plus, on 5GHz, the confirmed channel-persists-as-internal-index caveat.

Legacy auth only. channel is the operator-facing channel number (e.g. 11 on 2.4GHz, 149 on 5GHz) - this tool always derives the matching frequency itself (channels.py) and resends the complete current radio configuration with only channel/freq changed, so the confirmed real-hardware silent-discard gotcha (int channel, or a missing freq) can't be hit by construction - see docs/api-notes.md.