uniFiAP — Indigo Plugin

Version: 2022.49.435 Bundle ID: com.karlwachs.uniFiAP Platform: macOS · Indigo Home Automation 3.0+ Forum: Indigo community thread

Monitors and controls Ubiquiti UniFi network infrastructure from Indigo. Tracks client devices (WiFi, DHCP, switch-connected), Access Points, Switches, Gateways, and UniFi Protect cameras. Fires Indigo events when clients come online/go offline and exposes network health data as device states.

Requirements

• macOS — Monterey 12+ recommended
• Indigo — 2022+ (Server API 3.0)
• Python — 3 (bundled with Indigo)
• UniFi — Controller / Cloud Key / UDM / UDM-Pro / Hosted

Installation

1. Double-click uniFiAP.indigoPlugin to install.
2. Open Plugins → uniFiAP → Configure and enter controller credentials and IP addresses.

To reload after an update: Plugins → Reload Plugins.

Supported Hardware

• UniFi Controller (std / Cloud Key) — full support
• UniFi Dream Machine (UDM) — full support
• UniFi Dream Machine Pro (UDM-Pro) — full support including sensor/temperature data
• Hosted controller — full support
• Access Points (any model) — status, LED control, reboot
• Switches (4–52 port, Flex, Mini) — per-port state, PoE control via SSH or controller API
• Gateway / UGA — WAN1/WAN2 monitoring, failover detection
• UniFi Protect cameras — events, image capture, full PTZ and settings control
• WiFi clients — online/offline tracking
• DHCP clients — online/offline tracking
• Switch-connected clients — online/offline via port uptime
• Neighbours — passive visibility

Device Types

Client Devices (auto-created by plugin)

• UniFi — generic client with configurable detection method
• neighbor — neighbouring device seen passively on the network

Status detection method: WiFi association to an AP, with optional idle-time threshold.

Status states: UP → DOWN → EXPIRED. Transitions are debounced with a configurable expiration timer (10 s – 10 min, default 90 s). Optional ping confirmation before marking UP or DOWN.

Infrastructure Devices (auto-created by plugin)

• Device-AP — Access Point
• Device-SW-4 … Device-SW-52 — Managed Switch (4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 18, 26, 52 port variants)
• gateway — UniFi Gateway / UGA
• system_controller — UniFi Controller system (disk, CPU, memory)
• system_protect — UniFi Protect system (disk, CPU, memory)
• camera_protect — UniFi Protect camera

Device States

Client device (UniFi)

• onOffState — online (true) / offline (false)
• status — UP, DOWN, or EXPIRED
• displayStatus — human-readable status string
• MAC — MAC address
• ipNumber — current IP address
• hostname — device hostname
• vendor — NIC vendor from OUI lookup
• AP — access point the client is associated with
• GHz — WiFi band (2.4 / 5 GHz)
• essid — SSID
• signalWiFi — signal strength (dBm)
• noiseWiFi — noise floor (dBm)
• rx_tx_RateWiFi — RX/TX rate
• tx_Bytes_Last5Minutes / rx_Bytes_Last5Minutes — traffic last 5 min
• lastStatusChange — timestamp of last UP/DOWN transition
• lastStatusChangeReason — why the status changed
• groupMember — comma-separated group membership
• blocked — client blocked on controller (true/false)
• firstSeen / lastSeen — first/last seen timestamps

Gateway device

• wan / wan2 — WAN interface names
• wanUpTime / wan2UpTime — WAN uptime
• wanLatency / wan2Latency — latency (ms)
• wanPingTime / wan2PingTime — ping time
• wanDownload / wanUpload — download/upload bandwidth
• wanSpeedTest / wan2SpeedTest — speed test results
• publicIP / wan2PublicIP — public IP addresses
• wanSetup — WAN configuration type

Switch device

• port_1 … port_52 — per-port status / PoE state
• firmwareVersion — switch firmware version
• model — switch model string
• temperature_CPU / temperature_PHY — temperatures (°C)

Camera device (camera_protect)

• onOffState — camera reachable
• eventType — last event type (motion, ring, smartDetect)
• eventStart / eventEnd / eventLength — event timing
• eventJpeg — path to captured event image
• lastCameraEvent — last event summary
• isLedEnabled — LED state
• irLedMode / irLedLevel — IR LED settings
• isMicEnabled / micVolume — microphone state and volume
• isSpeakerEnabled / speakerVolume — speaker state and volume
• motionAlgorithm — motion detection algorithm
• smartDetect — smart detection types active
• zoomPosition / dZoomCenterX / dZoomCenterY — zoom/PTZ position
• isDark — low-light state

System device (system_controller / system_protect)

• disk_total / disk_used / disk_free — disk space (GB)
• cpuPercent / cpu_load / cpu_temp — CPU metrics
• memPercent / memory_total / memory_used / memory_free — memory metrics
• fanLevel — fan speed

Actions

Camera (UniFi Protect)

• LED on/off — enable camera LED with configurable blink rate
• Speaker volume — set speaker volume and system sounds on/off
• IR LED — set IR mode, level, and sensitivity
• Microphone volume — set mic volume
• Contrast / brightness / saturation / sharpness / hue — image quality settings
• Recording on/off — configure recording mode (motion, schedule, smart detection)
• Get snapshot — capture still image at selected resolution
• Pan/tilt — move camera with speed control
• Zoom — set zoom level
• Pan/tilt/zoom to preset — recall a saved PTZ preset position
• General API command — send any Protect API command directly

Switch PoE port control

• Power cycle port (SSH) — cycle, enable, or disable a PoE port via SSH to switch
• Power cycle port (controller) — cycle, enable, or disable a PoE port via controller API (supports Flex/Mini switches without SSH)

Client management

• Reconnect WiFi device — kick a client off the AP to force re-association
• Block client — block a MAC address on the controller
• Unblock client — remove block from a client

AP / Infrastructure

• Enable AP — re-enable a disabled AP on the controller
• Disable AP — disable an AP on the controller
• Reboot device — reboot any UniFi system device
• Suspend system device — mark a system device as suspended (plugin-only state)
• Activate system device — clear suspended state
• LED on / off (all APs) — turn all AP LEDs on or off
• LED blink on/off — blink one specific AP's LED

Plugins Menu (one-off actions)

• PRINT parameters — log plugin configuration to Indigo log
• PRINT controller DB info — dump system, clients, health, ports, users, or DPI data from controller
• PRINT communication stats — TCP/IP performance metrics and processing wait times
• TRACK specific MAC — start/stop verbose logging for one MAC address
• (UN)IGNORE clients — prevent auto-creation of an Indigo device for selected clients
• Reset SSH known_hosts — clear the SSH known_hosts file (fixes host key mismatch errors after device replacement)
• LISTENERS — manage — restart or reset SSH prompt detection for AP / Switch / Gateway listeners
• Groups — manage types — add or remove device types from a group
• Groups — manage individual — add or remove specific devices from a group
• Camera — info and settings — view camera properties, adjust settings, trigger actions
• Camera — send test commands — test camera API commands interactively
• Copy controller backups — copy backup files from controller to Indigo preferences directory
• SET ALL device props — bulk-update WiFi mode, expiration time, or ping settings across all devices
• Power cycle port — one-off PoE port cycle/enable/disable
• Reconnect WiFi client — one-off client kick
• (UN)BLOCK client — one-off block/unblock
• Enable/disable/reboot device — one-off AP or infrastructure device control
• Suspend/activate system device — one-off suspend/activate
• Set AP LEDs on/off — one-off all-AP LED control

Device Groups

Up to 8 named groups can be configured. Any client device can be a member of one or more groups. Group membership is stored in the groupMember device state and can be used in Indigo triggers and conditions to react to group-level presence (e.g. "anyone home").

Groups are managed via Plugins menu → Groups … Manage.

Plugin Preferences

General

• UP→DOWN expiration timer — how long a device stays DOWN before becoming EXPIRED (10 s – 10 min)
• Auto-adjust expiration time — automatically tune based on observed device behaviour
• DOWN→EXPIRED multiplier — multiplier applied to expiration timer for the EXPIRED transition
• Ignore new clients — do not auto-create Indigo devices for newly seen clients
• Broadcast events — enable plugin–plugin events for use with the Events plugin
• MAC to vendor lookup — OUI database refresh interval (off / 7 / 14 / 21 / 30 days)
• Web request method — curl or python-requests for HTTP calls to the controller
• Group names (0–7) — custom display names for each of the 8 groups

Controller

• Controller type — std / UDM / UDM-pro / hosted
• Controller IP / port — network address of the controller
• Site name — UniFi site identifier (default: default)
• Controller UserID / Password — authentication credentials
• UniFi UserID / Password — separate credentials for device SSH access
• UDM UserID / Password — credentials specific to UDM
• Protect UserID / Password — credentials for Protect system (if different from controller)
• SSL / strict login — TLS verification settings
• DB info usage — all / off / per-device — how much controller DB data to pull each cycle
• Backup config — enable automatic backup file retrieval

Devices

• AP 0–9 — IP address, enable/disable, debug flag per AP
• Switch 0–9 — IP address, enable/disable, debug flag per switch
• Gateway IP — Gateway / UGA network address
• Protect system IP — UniFi Protect NVR address
• Controller system IP — controller host address
• Camera polling interval — how often to poll for Protect camera events

Debug

Per-area debug flags enable verbose logging for controller communication, SSH listeners, device state changes, camera events, DPI data, group operations, and individual device tracking.

Architecture Notes

• Single source file — Contents/Server Plugin/plugin.py (~13 000 lines), one Plugin class subclassing indigo.PluginBase.
• SSH / Expect scripts — device listeners (AP, Switch, Gateway) use expect scripts for persistent SSH sessions that tail log streams and retrieve dictionary data. Scripts are in Contents/Server Plugin/*.exp.
• Queue-based message processing — log and dict data from listeners flow into logQueue / logQueueDict and are consumed by dedicated background threads.
• Controller REST API — client list, DPI, port states, and system health are fetched via HTTP/HTTPS to the UniFi controller or UDM on a configurable schedule.
• Protect event stream — camera events are polled via the Protect WebSocket/REST API in a dedicated background thread.
• MAC to Vendor — MAC2Vendor.py maintains a local OUI database refreshed on a configurable schedule.
• Deep Packet Inspection — unifi_dpi.json (176 KB) maps DPI category/application IDs to human-readable names.
• No build system / no test framework. Testing is manual via the Indigo UI.

Version History

See Contents/changeLog.txt for the full change log.

Current release — 2022.49.435 (2026-05-12) - Fixed ValueError crash on empty string in controller config validation

Recent notable additions - PoE port control via controller API (supports Flex/Mini switches without SSH) - Per-port state updates for Flex/Mini via controller HTTP query - System controller and system Protect devices with disk/CPU/memory states - UDM-Pro sensor data (temperatures, fan) - Separate credentials for Protect vs controller - Auto-configure Mini switches (no SSH required) - Print event log to preferences directory as JSON