TP-Link Managed PoE Switch

The TP-Link Managed PoE Switch driver controls the PoE ports on TP-Link managed switches (the JetStream / Omada series) so you can turn PoE power on or off per port, power-cycle a stuck powered device, and read each port's live power state from GEM. The classic use is putting a PoE camera, access point, intercom, 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 — the network-closet equivalent of pulling and re-seating the cable.

GEM logs in to the switch's own web interface using its IP and admin credentials, then reads and writes PoE state through the switch's JSON endpoints.

Point at the switch, not a controller

Unlike the UniFi Switch driver — which talks to a UniFi controller — this driver connects directly to the switch at the switch's own IP address and logs in to its local web UI. The switch must therefore be running its standalone web interface with an admin password set. A switch that has been fully adopted into an external SDN/Omada controller, where the local web UI is locked out, won't expose the endpoints this driver uses.

Prerequisites

• A TP-Link managed switch (JetStream / Omada managed series) with PoE ports, running its standalone web interface.
• An admin password set on the switch web UI (log in once in a browser and set one if the switch is still on defaults).
• The switch on the same LAN as the GEM controller, reachable over HTTP (default port 80).
• The port numbers you want to control, as printed on the switch faceplate (1-based).

Setup

1. Create the device. Go to System → Devices (Open Devices), add a device, and pick TP-Link Managed PoE Switch as the driver. Set Enabled to Yes.
2. Fill in the connection fields:
   • Switch IP Address (ip) — the LAN address of the switch itself.
   • Admin Username (username) — defaults to admin.
   • Admin Password (password) — the switch web-UI admin password. Stored encrypted.
   • HTTP Port (port) — leave at 80 unless you've moved the switch's web UI to another port.
   • Port-Status Poll Interval (ms) (status_interval) — how often GEM re-reads every port's PoE state. Defaults to 30000 (30 seconds).
3. Save. GEM logs in to the switch, then begins polling PoE port states on the interval. Confirm the device comes up connected.
4. Map ports to zones (next section) — one zone per port you want to control or monitor. The driver does not create these zones for you.

Mapping ports to zones

Each PoE port you want to drive becomes one GEM zone bound to the switch. The 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 TP-Link 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. Save. On the next poll the zone picks up its live state (on when the port is delivering PoE, off when it isn't).

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, so you don't re-type the port number.

What on / off / reboot actually do

On/off writes a persistent change to the switch

on / off (and their explicit forms power_on / power_off) change the port's PoE enable/disable setting in the switch configuration — exactly as if you toggled PoE for that port in the switch web 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.

To momentarily reboot a stuck powered device without leaving it powered off, use reboot instead — see below.

reboot is a one-shot power-cycle of a single port: it cuts PoE, waits about three seconds, and restores it. Use it to bounce a frozen camera or access point. Note that reboot here reboots the device the port feeds, not the whole switch — this driver has no "reboot the entire switch" command.

set_poe_power is the explicit form of on/off: pass state = on or off to set the port's PoE state directly. It does the same persistent write as power_on / power_off.

Device attributes

Attribute	Label	Type	Default	Notes
ip	Switch IP Address	string	—	LAN IP of the switch itself (required)
username	Admin Username	string	admin	Web-UI admin account (required)
password	Admin Password	string (secure)	—	Stored encrypted (required)
port	HTTP Port	int	80	The switch web-UI HTTP port
status_interval	Port-Status Poll Interval (ms)	int	30000	How often port PoE state is refreshed

Zone attributes

Attribute	Type	Notes
address	int	Faceplate port number, 1-based (required)
state	string	on / off, set by polling — on when the port is delivering PoE

Commands

Command	Args	Effect
on / power_on	address	Enable PoE on the port. Persistent override. address = port number
off / power_off	address	Disable PoE on the port, cutting power to the device. Persistent override
set_poe_power	address, state	Set the port's PoE to state = on / off directly (same persistent write)
reboot	address	Power-cycle the port: PoE off, ~3 seconds, on — reboots the powered device without leaving it off
get_port_status	—	Re-read every port's PoE state and update all zone states. Runs automatically on the poll

The port commands take address = the port number; on a control they bind to the zone's address so a port picker is offered. The standard on / off zone verbs resolve to power_on / power_off automatically, so a plain on/off zone toggle drives the port with no extra configuration.

Limitations and quirks

• Single stack unit. The driver reads and writes the switch's first unit only. On a stacked JetStream setup, ports on member units 2 and up are not controlled or monitored by this device — add each physical switch as its own device.
• Session refresh is automatic. The switch web UI hands out a session token that rotates; the driver re-authenticates periodically on its own. No action is needed, but a burst of login activity in the logs around each rotation is normal.
• Firmware JSON differences. Some older JetStream firmware returns a slightly different PoE-grid JSON shape. If the device connects but port state never updates, the firmware's web-UI response doesn't match what the driver expects — update the switch firmware.
• Fixed reboot interval. The reboot power-cycle uses a fixed ~3-second off interval; it isn't adjustable per command.

Troubleshooting

Symptom	Check
Device won't connect / login fails	Confirm Switch IP Address, Admin Username, and Admin Password against the switch web UI, and that the switch's local web interface is reachable (not locked out by an external controller).
Connects but no port state / zones stay blank	Confirm each zone's Address is the faceplate port number, and that the switch actually has PoE on that port. On very old firmware the PoE JSON shape may differ — update firmware.
Ports on a stacked switch don't respond	This driver only sees the first stack unit. Add member switches as separate devices.
A port turns off but the device never comes back	off is a persistent PoE disable — the port stays off until something turns it back on. Use reboot (a power-cycle) when you only meant to bounce the device.
reboot didn't fix a hung device	The device may need a longer down time than the fixed ~3-second cycle; run off, wait, then on from a macro for a longer power-off.

Automation ideas

• Bounce a hung camera or AP. A trigger on a device going offline, or a scheduled overnight maintenance macro, can run reboot on that port to power-cycle the device without leaving it off.
• Power a display or sign with the room. Wire a PoE display to a switch port, make it a Power 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.

Related documentation

• Devices — adding the switch as a device and editing its connection settings.
• Zones — creating one zone per port and setting each zone's address.
• Subsystems — the Power subsystem these port zones file under.
• Commands — running reboot, get_port_status, 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 Switch — the equivalent driver for Ubiquiti managed switches, driven through a UniFi controller instead of the switch directly.