Ubiquiti UniFi Switch

The UniFi Switch driver controls Ubiquiti UniFi managed switches (USW / Pro / Enterprise) so you can turn PoE on or off per port, power-cycle a powered device, administratively enable or disable a port, and reboot the whole switch from GEM — plus read each port's live PoE draw and link state. The classic use is putting the power to a PoE camera, access point, or PoE-powered display under automation: a scene or trigger can cut power to a port, restore it, or bounce a hung device with a single power-cycle.

Point at the controller, not the switch

GEM talks to your UniFi Network Controller — the UniFi OS console (UDM, UDM Pro, UDR, Cloud Key Gen2+) or a self-hosted UniFi Network application — not to the switch's own IP. The switch is identified by its MAC address, and all commands flow through the controller's local API. If you point the device at the switch itself, nothing will connect.

Prerequisites

• A UniFi Network Controller that has already adopted the switch, reachable from the GEM controller over HTTPS (default 443 on a UniFi OS console, 8443 on a self-hosted standalone controller).
• A local admin account on the controller. Ubiquiti SSO / cloud accounts and any account with multi-factor authentication are rejected by the local API — create a dedicated local admin (a "Site Admin" / "Limited Admin" local user is enough).
• The switch's MAC address, in colon-separated form (aa:bb:cc:dd:ee:ff). Find it in the UniFi UI under Devices → (the switch) → Overview, or read it back from GEM with the get_devices command below.

Setup

1. Create the device. Go to System → Devices (Open Devices), add a device, and set Driver to unifi_switch. Set Enabled to Yes.
2. Fill in the connection fields:
   • Controller IP / Host (ip) — the LAN address of the UniFi controller. Not the switch.
   • Admin Username (username) and Admin Password (password) — the local admin account. The password is stored encrypted.
   • Switch MAC Address (device_mac) — the MAC of the switch these zones will control, e.g. aa:bb:cc:dd:ee:ff.
   • Controller Port (port) — leave at 443 for a UniFi OS console; set 8443 for a self-hosted standalone controller.
   • UniFi OS Console (unifi_os) — leave on for UDM / UDM Pro / UDR / Cloud Key Gen2+. Turn it off only for a standalone self-hosted UniFi Network application.
   • Site (site) — leave as default unless your controller manages multiple sites, in which case enter the site's short-name (see troubleshooting).
3. Save. GEM logs in to the controller and begins polling the switch. Confirm the device comes up connected.
4. Find the MAC if you don't have it. From System → Commands (Open Commands) or the Script Console, run get_devices against the device to list every adopted device (name, model, MAC). Copy the switch's MAC into Switch MAC Address if you left it blank.
5. Map ports to zones (next section) — one zone per port you want to control or monitor.

Verify from the Script Console

await gem.command({device: <device_id>, action: 'get_device'});

This returns the switch record the driver is tracking, including its port_table. If it comes back with data, the login and MAC are correct.

Mapping ports to zones

This driver does not create zones automatically — you add one zone per port you care about. Each zone's Address is the port number printed on the switch faceplate (1-based), and that port number is how every command targets the port.

1. Go to System → Zones (Open Zones) and add a zone.
2. Pick the UniFi switch as the zone's Device. The Subsystem pre-selects Power (one of the default subsystems); leave it there unless you have a reason to file the port elsewhere.
3. Set Address to the faceplate port number — e.g. 4 for port 4.
4. Port Type (port_type) — an optional zone attribute:
   • poe (default) — the zone's on/off state tracks whether the port is delivering PoE. Use this for PoE cameras, APs, and PoE displays.
   • data — the zone's state tracks whether the port's link is up. Use this for a non-PoE port you only want to enable/disable or monitor.
5. Save. On the next poll the zone picks up its live state, poe_power, and link_up values.

Once a port is a zone, it behaves like any other on/off zone: it can sit on a UI as a toggle, be switched from a macro, or be driven by a trigger. On a control that offers a port picker, the port commands bind to the zone's address automatically.

What on / off actually do

On/off writes a persistent change to the controller

on / off (and their explicit forms port_poe_enable / port_poe_disable) change the port's PoE override in the controller's configuration — exactly as if you toggled PoE for that port in the UniFi UI. The change persists until something sets it back. Turning a zone off cuts PoE and powers down whatever the port feeds; turning it back on restores PoE (auto mode).

To momentarily reboot a stuck powered device without changing its configured PoE state, use port_poe_cycle instead — it issues a one-shot power-cycle and leaves the port's saved settings untouched.

port_enable / port_disable are the separate data-forwarding override — they administratively bring the port up or down (forward = all vs disabled), independent of PoE. reboot_switch restarts the entire switch and briefly drops every port on it, so treat it as a deliberate operator action, not routine automation.

Device attributes

Attribute	Label	Type	Default	Notes
ip	Controller IP / Host	string	—	LAN IP/hostname of the UniFi controller (required)
username	Admin Username	string	—	Local admin account (required)
password	Admin Password	string (secure)	—	Stored encrypted (required)
device_mac	Switch MAC Address	string	—	Switch MAC, aa:bb:cc:dd:ee:ff (required)
port	Controller Port	int	443	443 for UniFi OS, 8443 for standalone
unifi_os	UniFi OS Console	bool	true	Off for a self-hosted standalone controller
site	Site	string	default	Controller site short-name
status_interval	Status Poll Interval (ms)	int	30000	How often port state is refreshed

Zone attributes

Attribute	Type	Notes
address	int	Faceplate port number, 1-based (required)
port_type	string	poe (default) tracks PoE power as state; data tracks link up/down
state	string	on / off, set by polling — on when the port is delivering PoE (poe zones) or the link is up (data zones)
poe_power	float	Live PoE draw on the port, in watts
link_up	bool	Whether the port's link is up

Commands

Command	Effect
on / port_poe_enable	Enable PoE on the port (poe_mode = auto). Persistent override. address = port number
off / port_poe_disable	Disable PoE on the port (poe_mode = off), cutting power to the device. Persistent override
port_poe_cycle	One-shot power-cycle of the port's PoE — reboots the powered device without changing its saved settings
port_enable	Administratively enable the port (data forwarding = all). Persistent override
port_disable	Administratively disable the port (data forwarding = disabled). Persistent override
reboot_switch	Reboot the entire switch — drops every port, use deliberately
get_devices	List every device the controller has adopted (name, model, MAC) — use to find the switch MAC
get_device	Return the tracked switch record, including its port table
get_clients	List clients currently connected to the site
login	Force a fresh login to the controller

The five port commands take address = the port number; on a control they bind to the zone's address so a port picker is offered. The session cookie and CSRF token are refreshed automatically, and the driver re-authenticates on its own if the controller expires the session.

Controller API reference

Useful when you are matching GEM's behavior to what you see in the UniFi controller. Paths differ between a UniFi OS console and a standalone controller — GEM chooses automatically from the UniFi OS Console toggle:

Action	UniFi OS console	Standalone controller
Login	POST /api/auth/login	POST /api/login
Site path prefix	/proxy/network/api/s/<site>	/api/s/<site>
List devices	<site>/stat/device	same
The switch record	<site>/stat/device/<mac>	same
PoE / port override	PUT <site>/rest/device/<id> with port_overrides	same
Power-cycle a port	POST <site>/cmd/devmgr {cmd: power-cycle, mac, port_idx}	same
Reboot the switch	POST <site>/cmd/devmgr {cmd: restart, mac}	same

The controller's TLS certificate is self-signed, so GEM does not verify it — point the device at a controller IP you control on a trusted LAN.

Automation ideas

• Bounce a hung camera or AP. A trigger on a camera going offline, or a scheduled overnight maintenance macro, can run port_poe_cycle on that port to power-cycle the device without touching its configured PoE state.
• Power a display or sign with the room. Wire a PoE display to a switch port, make it a poe zone, and let a room's on/off scene turn the port on and off with everything else.
• Load shedding. Turn off non-essential PoE ports (signage, secondary APs) from an "away" or energy-saving macro, and on again when the site is occupied.
• Watch PoE draw. poe_power records each port's wattage over time — history charts show consumption and can flag a device drawing more than expected.

Troubleshooting

Symptom	Check
Device won't connect / login fails with 400 or 401	You're using a Ubiquiti SSO / cloud or MFA account — the local API only accepts a local admin account. Create one on the controller.
Connects but no port data / device not found	Switch MAC Address must match the switch exactly (colon-separated, lowercase). Run get_devices to confirm the MAC.
get_devices comes back empty	Wrong Site short-name. The default site's short-name is literally default; for multi-site controllers, check the site's short-name in the UniFi UI.
Everything times out / wrong page returned	Check the Controller Port and UniFi OS Console toggle match your controller — 443 + on for a UniFi OS console, 8443 + off for a standalone controller.
A port override seems to have no effect	Some models ignore a port override until the port has a port profile assigned. Check Devices → (switch) → Ports in the UniFi UI.
Zone state doesn't update	Confirm the zone Address is the faceplate port number and that the port appears in the switch's port table (get_device).

Related documentation

• Devices — adding the UniFi controller as a device and editing its connection settings.
• Zones — creating one zone per port and setting each zone's address and Port Type.
• Subsystems — the Power subsystem these port zones file under.
• Commands — running get_devices, port_poe_cycle, and the rest by hand to verify the link.
• Device Health — watching the switch's connection state.
• Macros and Triggers — power-cycling ports and shedding PoE loads on a schedule or in response to events.
• UniFi Protect — the companion driver for Ubiquiti's Protect cameras/NVR.