Peplink Router / Switch

The Peplink Router / Switch driver controls the switch ports — including PoE power — on Peplink routers and managed PoE switches over the device's local HTTPS API. GEM can cut PoE power to a port, restore it, power-cycle a hung powered device, or disable a whole port outright. The classic use is putting a PoE camera, access point, intercom, or PoE-powered display under automation: a trigger or a maintenance macro bounces a frozen camera's port, or an "away" scene sheds power to non-essential ports — the network-closet equivalent of pulling and re-seating the patch cable, without a trip to the rack.

GEM talks to the Peplink device's own web-admin HTTPS API (the same interface you reach in a browser), logging in with an admin account and then using a token-based API client it provisions for itself on first connect.

Point at the Peplink device, not a controller

This driver connects directly to the router or switch at its own IP, on its local HTTPS API. It does not go through InControl (Peplink's cloud) or any separate controller. The device's web admin must be reachable from the GEM controller, and you need an admin account that is allowed to create API clients.

No live port feedback, and no plain on/off toggle

This driver sends commands only — it does not poll or display each port's live PoE state, and it does not register the generic on / off zone verbs. Turning a Peplink zone on or off from a bare UI toggle does nothing (GEM logs an "unknown command"). You drive ports by running the explicit port commands below — from a macro, a trigger, or the Commands tester — where the port number comes from the zone's address automatically. If you want a plain on/off tile, wire it up with a per-zone action override (see Making a plain on/off tile work).

Prerequisites

• A Peplink router or managed PoE switch whose local web admin is reachable from the GEM controller over HTTPS.
• An admin account on the Peplink device that is allowed to create API clients.
• The device's self-signed certificate is fine — GEM accepts it (see Connection details).
• The port numbers you intend to control, as printed on the device faceplate.

Setup

1. Create the device. Go to System → Devices (Open Devices), add a device, and pick Peplink Router / Switch as the driver. Set Enabled to Yes.
2. Fill in the connection fields:
   • IP Address (ip) — the LAN IP of the Peplink device's management interface (e.g. 192.168.1.1). Required.
   • Admin Username (username) — an admin account that can create API clients. Required on first setup.
   • Admin Password (password) — that account's password. Stored encrypted. Required on first setup.
3. Save. On first connect the driver logs in with those credentials, finds or creates an API client named "GEM" on the device, and stores the resulting client ID, client secret, and access token as device attributes. From then on it authenticates with the token and refreshes it automatically. Confirm the device comes up connected.
4. (Optional) clear the admin credentials. Once the API client secret is stored, the Admin Username and Admin Password are no longer needed for normal operation — you may clear them if you'd rather not keep them on the device. Leave them if you want the driver to be able to re-provision the client on its own.
5. Add a zone per port (next section) — one zone for each port you want to control. The driver does not create these zones for you.

Mapping ports to zones

Each port you want to drive becomes one GEM zone bound to the Peplink device. The zone's Address is the port number printed on the device faceplate (an integer), 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 Peplink device 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. 5 for port 5.
4. Save.

Once a port is a zone, running any of the port commands against that zone automatically supplies the port number from the zone's Address, so you don't retype it. On a multi-module unit (stacked or expansion modules), also pass a module_id argument to reach ports on modules other than the front panel — see the command reference.

The zone does not show a live state

Because the driver does not poll the device, a Peplink port zone has no running on/off indicator — the zone is a target for commands, not a status tile. If you need a live "is this port powered" readout, that expectation belongs to a switch driver that polls, such as the TP-Link Managed PoE Switch.

Controlling ports

There are two levels of control, and the difference matters:

• PoE only, at runtime — port_poe_enable / port_poe_disable toggle just the PoE power on a port, as a live command. This is what you use to power a PoE device up or down, or to power-cycle a hung camera or access point. It does not touch the port's data link and does not rewrite the saved configuration.
• The whole port, saved to config — port_enable / port_disable enable or disable the entire port (its data link and its PoE together) and write that change into the device's running configuration (the driver applies the config after the change). Use this to bring a port fully up or down, the way you would in the Peplink web UI. Because it is a saved config change, it persists across reboots until you set it back.

The two everyday ways to run these:

• From a macro. Add a Send Command step, choose the Peplink device (or a port zone) as the target, set the command to port_poe_disable / port_poe_enable (or port_disable / port_enable), and — if you targeted the device rather than a zone — put the port number in the step's arguments as address. Attach the macro to a trigger or a schedule to make it run on its own.
• From the Commands tester. Open the device's commands (the commands icon on its row in Devices, or via Commands), pick the Peplink device as the Test Device, fill in address with the port number (or run it against a port zone so the address fills itself), and use Test to fire it. This is the quickest way to confirm a port responds while commissioning.

Power-cycling a port

There is no single "reboot this port" command. To bounce a stuck PoE device, run port_poe_disable, wait a few seconds, then port_poe_enable — two steps in a macro with a delay between them. Use the PoE-only pair (not port_disable / port_enable) so you are only cutting power, not rewriting the port's saved configuration.

Making a plain on/off tile work

If you want a Peplink port to behave like a normal on/off zone on a UI (a single toggle that turns the port on and off), give the zone an on_action and off_action override that redirects the generic verb to a port command. In the zone's Attributes, add a JSON attribute named on_action such as:

{"command": "port_poe_enable", "device_id": 12, "args": {"address": "5"}}

and an off_action that calls port_poe_disable the same way (use the whole-port port_enable / port_disable pair instead if you want the on/off toggle to disable the port entirely). Replace 12 with the Peplink device's ID and 5 with the port number. With those overrides in place, a plain on/off toggle on that zone maps to the port command. This is the retrofit path — most installs simply drive the explicit commands from macros and triggers.

Diagnostic commands

These read from the device or manage the API client; they don't change any port:

• get_lan_clients — list the clients currently connected to the Peplink device (its DHCP / status client list). Handy for confirming what is plugged into a port.
• get_api_clients — list the API clients defined on the device. Use this to confirm the "GEM" client the driver created still exists.
• create_api_client — manually (re)create the "GEM" API client. The driver does this automatically on first connect; you only need it by hand if the client was deleted on the device.
• get_token — manually request a fresh access token from the stored client credentials. The driver refreshes the token on its own, so this is a diagnostic.
• login — post the admin username/password login. Rarely needed by hand; the driver logs in as part of provisioning.

note

get_port_config is listed but not wired up

The command list includes get_port_config, but the driver does not currently implement it — running it does nothing (GEM logs an "unknown command" for it). There is no per-port config read-back today; use the diagnostic commands above, or the Peplink web UI, to inspect a port's current state.

Device attributes

Attribute	Label	Type	Notes
ip	IP Address	string	LAN IP of the Peplink management UI (required)
username	Admin Username	string	Admin account that can create API clients. Required on first connect; may be cleared once the client secret is stored
password	Admin Password	string (secure)	The admin account password. Stored encrypted. Required on first connect
client_id	API Client ID	string (read-only)	The "GEM" API client's ID. Auto-populated after first successful login — leave blank on initial setup
client_secret	API Client Secret	string (secure, read-only)	Auto-populated after first login. Managed by the driver
token	Access Token	string (secure, read-only)	The current access token — refreshed automatically before expiry
token_time	Token Issued At	int (read-only)	When the current token was issued (epoch ms). Diagnostic only

The client_id, client_secret, token, and token_time attributes are written by the driver during provisioning and token refresh. They exist so the driver doesn't have to re-create its API client on every restart — you don't set them by hand, and clearing them forces the driver to re-provision on the next connect.

Commands

Command	Args	Effect
port_poe_enable	address, module_id, module_type	Turn PoE on for the port (runtime command). Powers up the connected device
port_poe_disable	address, module_id, module_type	Turn PoE off for the port (runtime command), cutting power to the device
port_enable	address, module_id	Enable the whole port (data link + PoE) and save it to the running config. Persistent
port_disable	address, module_id	Disable the whole port (data link + PoE) and save it to the running config. Persistent
get_lan_clients	—	List the device's connected LAN / DHCP clients. Diagnostic
get_api_clients	—	List the API clients defined on the device. Diagnostic
create_api_client	—	(Re)create the "GEM" API client. Normally automatic on first connect
get_token	—	Request a fresh access token from the stored client credentials. Normally automatic
login	—	Log in with the admin username/password. Rarely needed by hand

Arguments:

• address — the front-panel port number (integer). When a command runs against a port zone, this fills automatically from the zone's Address; against the device directly, supply it in the command's arguments.
• module_id — the module number on multi-module / stacked units. Defaults to 1 (the front-panel module), so on a single-unit device you can leave it off.
• module_type — advanced, PoE commands only: the module type string for unusual multi-module hardware. Leave it unset on standard units; the whole-port commands always target the front panel.

Connection details

• The driver connects over HTTPS to the device's web-admin API (https://<ip>/api/) on the standard management port (443). There is no port field — if your Peplink device's web admin is on a non-standard port, that is not currently configurable here.
• Peplink devices ship with a self-signed certificate, so GEM does not verify the certificate — the connection works without installing anything, but it is not certificate-validated.
• Authentication uses Peplink's client-credentials flow. On first connect the driver logs in with the admin username/password, reuses or creates the "GEM" API client, and stores its ID and secret. It then grants an access token (lifetime about 10 minutes) and refreshes it automatically roughly a minute before it expires, for as long as the device is enabled.
• On connect the driver needs either a stored token or an admin username to proceed. If both are missing (no credentials ever entered, or the stored auth was cleared), it logs that it is missing credentials and will not connect until you supply an admin username and password.

Troubleshooting

Symptom	Check
"peplink router missing client_secret or username/password" / won't connect on first setup	Both Admin Username and Admin Password must be set on first setup so the driver can log in and provision its API client. Once the client secret is stored, you may clear them.
"error creating peplink client" on first connect	Some Peplink firmware limits the number of API clients. Log into the Peplink web admin, remove unused API-client entries, and retry. get_api_clients lists what's defined.
Token keeps refreshing but commands come back unauthorized (401)	The "GEM" API client was probably deleted on the device. Clear the client_id, client_secret, and token attributes so the driver re-creates the client on the next connect (or run create_api_client).
A plain on/off zone toggle does nothing	Expected — the driver doesn't register the on / off verbs. Drive the explicit port commands, or add on_action / off_action overrides as shown above.
No indication of whether a port is powered	The driver doesn't poll port state — there's no live feedback. Verify a port with get_lan_clients or in the Peplink web UI. For live per-port status use a polling switch driver such as TP-Link Managed PoE Switch.
A port on a stacked / multi-module unit doesn't respond	Pass a module_id for that module (the default is the front-panel module 1).
A PoE device browns out when powered from a port	Confirm the port and the device are within the Peplink unit's PoE budget; GEM toggles PoE on/off but does not manage per-port power limits.

Automation ideas

• Bounce a hung camera or AP. A trigger on a device going offline, or a scheduled overnight maintenance macro, runs port_poe_disable, waits, then port_poe_enable on that port to power-cycle the device without leaving it off.
• Power a display with the room. Feed a PoE display from a Peplink port and let a room's scene run port_poe_enable and port_poe_disable alongside everything else.
• Load shedding. Have an "away" or energy-saving macro run port_poe_disable on non-essential PoE ports (signage, secondary APs) and port_poe_enable again when the site is occupied.

Related documentation

• Devices — adding the Peplink device and editing its connection settings.
• Zones — creating one zone per port and setting each zone's address.
• Attributes — where the on_action / off_action overrides and the stored API-client attributes live.
• Subsystems — the Power subsystem these port zones file under.
• Commands — running the port and diagnostic commands by hand from the tester to verify the link.
• Device Health — watching the device's own connection state.
• Macros and Triggers — the Send Command step and event/schedule triggers that fire these port commands automatically.
• TP-Link Managed PoE Switch — a PoE-switch driver that uses zones and polls live per-port state.
• Netgear Managed Switch (PoE) — a comparable command-only PoE-switch driver.
• UniFi Switch — the equivalent driver for Ubiquiti managed switches, driven through a UniFi controller.