This document describes the API used by the EE workspace and other clients.
npm startserves the workspace athttp://127.0.0.1:4180and forwards/apiand/api/wsto its private engine service. See INTEGRATION.md for the gateway and session flow. It also prints a one-use administration link (see Local gateway administration). The desktop app starts the same gateway on the first free port from 4180, or from 4190 for the demo, trying 20 ports.- Devices on Tailscale and paired devices on the LAN reach that gateway through the Tailscale gateway and the LAN gateway, which forward only the requests listed for remote use (see Remote access).
- The separate CLI server,
etherlighting-evolved serve, listens onhttp://127.0.0.1:8787by default and serves interactive OpenAPI documentation at/docs; its page at/links there. That documentation belongs to the CLI server, not the workspace gateway. - Request and response bodies are JSON. Colors are
"#rrggbb"strings. The server also accepts"f0f", names such as"white",[r, g, b]and{"r":..,"g":..,"b":..}, but always returns#rrggbb. - Ports are numbered from 1, matching the labels on the switch. Use the state
portsandsfparrays for controllable port membership.hardware_profiledescribes the detected physical layout; its stacking ports are not lighting targets. Optical-only models have an empty copperportsarray. - Times use the local time of the machine running EE, in 24-hour
"HH:MM"format.
The desktop opens the saved switch in the usual Lighting workspace. Apply uses the
normal scene revision and PUT /api/scene. On a qualified Pro XG 8 PoE with a
saved login, EE also commits supported scenes to a lighting player on the switch. EE
keeps exclusive live output while connected. When it closes, or its grant expires after
connection loss, the powered switch resumes the committed scene from RAM.
Activity Glow, Live Traffic and Traffic Trails read port counters, PoE Usage reads
switch power measurements, and Daylight follows the switch clock. The base effects
continue offline. EE evaluates automation rules and schedules only while it runs.
GET /api/session reports the player in switch_playback: null without a player record, playing while EE's
player runs on the connected switch, last_confirmed when EE started with a record from an earlier run, and
handoff while Handoff to UniFi stops the player. offline_lighting_error is the message shown when the switch has
not taken the current scene, or null. POST /api/session/handoff stops the player and
returns lighting to UniFi.
State and frame messages include uplink_bandwidth, measured from the existing physical-port byte counters.
Upload is transmitted traffic and download is received traffic across the detected active uplink ports.
Each successful port-status read supplies a counter sample. Once two compatible samples are available,
the next workspace frame includes their measured rate. sample_period_ms records the actual time between
captures, including switch response time. A missed read leaves the last measurement at its original capture time.
Each physical uplink is counted once, including optical uplinks. Virtual aggregation rows are excluded.
| Field | Meaning |
|---|---|
status |
waiting, ready, stale, no_uplink, or unavailable |
ports |
Physical uplink port IDs included in the sample |
upload_bps, download_bps |
Directional bits per second, or null when a reading is unavailable |
history |
Measured intervals from the last minute as [offset_ms, upload_bps, download_bps], relative to the newest sample. Clears when counters or uplink membership reset. |
sample_period_ms, sample_age_ms |
Measurement duration and age in milliseconds |
sequence |
Increases for each completed measurement |
refresh_interval_ms |
Configured delay between port-status polls in milliseconds (default 1000) |
Counter resets, uplink membership changes, and reconnection start a new measurement window. A reading is current for ten seconds from capture. Each frame reports its age at the time of the snapshot. While the same uplink is connected, the panel can keep an expired measurement visible as “Last reading.” Its peak and chart then describe the minute ending at that measurement. A counter reset, uplink change, or disconnected session clears the previous readings. A missed port-status sample can age out while the switch connection stays active.
POST /api/session/recover revalidates the current switch and cleans up its owned output before resuming
the retained scene after an interrupted connection. It preserves saved credentials and rejects changed
device identity, changed capabilities, or unconfirmed helper cleanup. State/frame reconnect_required
indicates that explicit recovery is needed. Pending handoff must finish before recovery can resume lighting.
- Subscribe to session messages at
/api/wsand callGET /api/session. Iflogged_inis true, load the main screen. Otherwise show the login screen, filled in fromrememberedif present. Whileconnectingis true, show saved-login progress; a later session message reports completion or an actionable error. - The login screen has fields for IP address, SSH username and password, plus a Save login option.
It submits to
POST /api/session/login. Use saved login callsPOST /api/session/restorewithout sending credentials from the browser. When the session reportspending_scene_choice, ask whether to use the saved lighting or start a new setup and send the answer toPOST /api/session/scene-choice. - Keep the same WebSocket after entering the workspace. It sends the session, the full state, and then a frame with every port at the engine's frame rate (see WebSocket). Draw the ports from the frames.
- Lighting controls edit a local draft. Color pickers, effect settings and brightness sliders update the preview; Apply changes sends the draft through REST. Discard restores the applied view. Selecting a profile leaves output unchanged until its Apply profile action. Do not send writes while dragging controls or browsing previews.
- Scope saved browser drafts and selections by
workspace_id. Clear the previous workspace's in-memory state when it changes. Add the UniFi Network controller after the real switch is connected to enrich its port names.
REST and WebSocket mutations take effect immediately when received; Apply is a browser workflow, not a server
transaction. Serialize dependent requests and retain failed or unapplied draft changes for recovery. Other open
clients receive resulting state messages.
Logging in with the host demo connects to the built-in simulator, which the login screen can offer as a demo
option.
Errors include a code for the UI to check and a message that can be shown to the user:
{ "detail": { "code": "auth_failed", "message": "SSH login failed: wrong username or password" } }Some error objects carry more fields, such as the fingerprints of a changed SSH key or the schedules of a profile
in use. A few answers use a plain string as detail: the gateway's 503 when the engine cannot be reached
("The EE service is unavailable."), the 503 of the Tailscale and LAN gateways when the local gateway cannot be
reached ("EE is reconnecting. Try again shortly."), the 400, 405, 413 and 503 answers of the private access setting
routes, and the 409 of POST /api/workspace/close. A request body that does not match a route's model gets FastAPI's
422 with a list of problems in detail, except on the routes listed under invalid_credentials. Some saved-library
and port-name refusals carry message without code.
| Status | Code | Meaning |
|---|---|---|
| 400 | missing_host, missing_username, bad_port |
Login form incomplete |
| 400 | invalid |
Invalid request; the message gives the reason |
| 400 | invalid_settings |
The engine settings or the saved lighting setup could not be applied at login |
| 400 | invalid_scene_choice |
choice is not use_saved, start_new or cancel |
| 400 | scene_revision_required |
POST /api/presets has a scene without expected_revision |
| 401 | auth_failed |
Wrong SSH username or password |
| 401 | bad_token |
API token missing or wrong (only when the server has one set) |
| 403 | forbidden |
A browser request from another website, or a Host other than 127.0.0.1 or localhost at the local gateway or a local server |
| 403 | admin_required |
This local gateway action needs the per-launch administration key, or a browser opened from the desktop app or from the printed administration link |
| 403 | local_access_required |
Only the computer running EE can make this request: the Tailscale and LAN gateways refuse it, and POST /api/session/host-key/replace also refuses a caller whose address is not a loopback address |
| 403 | private_access_denied |
The Tailscale identity is not approved, or the path cannot be opened through private access |
| 403 | lan_access_denied, lan_pairing_required, lan_pairing_failed |
LAN access refusals; see LAN access |
| 404 | not_found |
No such zone, rule, preset, schedule, history entry or paired device |
| 409 | not_logged_in |
Not logged in to a switch |
| 409 | workspace_changed |
The X-EE-Workspace header names another switch session than the current one |
| 409 | handoff_unconfirmed |
A Handoff to UniFi has not been confirmed; lighting changes and connections wait for it |
| 409 | handoff_save_failed, handoff_recovery_required |
See POST /api/session/handoff |
| 409 | no_saved_login, saved_login_unavailable |
POST /api/session/restore finds no saved login, or the saved login cannot be read |
| 409 | output_recovery_required |
An earlier lighting session on this switch has no confirmed shutdown, and its recovery did not finish |
| 409 | output_unconfirmed |
The switch did not confirm a lighting or SFP output change |
| 409 | scene_changed |
The scene revision in the request is not the current one |
| 409 | scene_choice_expired, scene_choice_stale, saved_scene_unavailable |
See POST /api/session/scene-choice |
| 409 | host_key_changed |
The switch's SSH key differs from the saved key; nothing but the SSH key exchange was sent |
| 409 | host_key_stale |
The SSH keys in a key replacement are not the saved key and the key EE last saw at that address |
| 409 | host_key_in_use |
EE still has an open switch connection, so a changed SSH key cannot be accepted yet |
| 409 | switch_playback_reserved |
Switch playback is saved for a switch; also returned by POST /api/session/host-key/replace |
| 409 | not_simulated |
Simulator controls require a demo login |
| 409 | fans_unconfirmed |
The switch did not confirm a fan change; the previous fan settings are kept |
| 409 | history_unavailable |
Lighting history cannot be read for this session |
| 409 | profile_storage_unavailable, schedule_storage_unavailable |
Saved profiles or schedules cannot be read or saved, or were saved by a newer version of EE |
| 413 | too_large |
The request body is larger than 1 MiB, or than 1 KB for a LAN access setting or pairing |
| 422 | invalid_credentials |
The fields of POST /api/session/login, POST /api/session/host-key/replace, POST /api/controller/connect, POST /api/controller/consoles or PUT /api/controller/preferences were not accepted |
| 422 | no_etherlighting |
Logged in, but the device has no Etherlighting |
| 422 | compatibility_verification_required |
The switch was identified, but its model or firmware build has not been reviewed for lighting output |
| 422 | invalid_saved_scene |
The saved lighting for this switch cannot be used; see POST /api/session/login |
| 500 | saved_login_failed |
Saving failed; sign in with Save login turned off |
| 500 | saved_login_forget_failed |
The saved login could not be removed |
| 500 | scene_save_failed |
The lighting setup for the switch could not be saved |
| 500 | host_key_save_failed |
The saved SSH keys (known_switches.json) could not be read or updated, or were saved by a newer version of EE; the message says which. Returned by logins, restores and key replacements |
| 500 | fan_settings_save_failed |
The switch runs the new fan setting, but EE could not save it on this PC |
| 502 | unreachable, ssh_error |
The switch couldn't be reached, or SSH failed |
| 503 | offline_scene_unconfirmed |
The lighting is applied in EE, but the switch has not confirmed its offline copy |
| 503 | port_names_unavailable |
Port names cannot be read or saved, or were saved by a newer version of EE |
| 503 | workspace_closing |
EE is closing: POST /api/workspace/admin-link and LAN access changes |
The private access, LAN access, UniFi Network controller, profile, schedule and saved library sections list the codes of their own requests.
If the server has an API token, send Authorization: Bearer <token> with every request and with the WebSocket
upgrade. The workspace gateway creates the engine's token at each start and adds it to the requests it forwards, so
clients of the gateway send no token.
The engine refuses with 403 forbidden a change (any method other than GET, HEAD and OPTIONS) or a WebSocket
connection whose Origin is another site, and a request to /api/ that carries Sec-Fetch-Site: cross-site or
same-site, unless the Origin is the server itself or is listed in cors_origins. Requests without these headers,
such as those from scripts and the desktop app, are not affected. When the server listens only on this computer, it
also refuses a Host other than localhost, 127.0.0.1 or ::1. A refused WebSocket is closed with code 4403.
Request bodies are limited to 1 MiB. PUT /api/zones accepts at most 64 zones, and PUT /api/rules,
PUT /api/rules/order and POST /api/rules/test at most 256 rules; longer lists return 422. POST /api/rules
returns 400 invalid when 256 rules already exist, and PUT /api/scene, history restore, POST /api/presets with a
scene, and POST /api/presets/{name}/apply return 400 invalid for a scene with more than 256 rules. In
POST /api/session/login, a host longer than 253 characters, a username longer than 256 or a password longer
than 4096 returns 422 invalid_credentials.
A request that sends X-EE-Workspace with the workspace_id from GET /api/session is refused with
409 workspace_changed when the connected switch changed in the meantime. Every request that works on the connected
switch checks the header, and so do logout, handoff, PATCH /api/profiles/{profile_id} and the schedule changes.
The first connection to an address that has no saved SSH key signs in with the username and password and then
saves the key the switch presented (trust on first use). This applies to a login, a saved-login restore, the
automatic login at startup and the engine's reconnect. While a switch is connected, GET /api/session reports its
key in ssh_host_key and ssh_host_key_type, so a user can compare it with what an SSH client shows.
When the switch presents a key that differs from the saved one, EE ends the connection during the SSH key exchange,
before any username or password is sent, and the login, the restore, GET /api/session error and the WebSocket
session message report both keys with HTTP 409:
{ "code": "host_key_changed",
"message": "The switch's SSH key changed. Check the new fingerprint before signing in.",
"host": "192.168.1.2", "port": 22,
"ssh_host_key": "SHA256:Zt4Wc8Hn1Lq6Rv3Xb9Me2Kd7Pj0Ys5Ug8Fa1Ni4Ow7E",
"ssh_host_key_type": "ssh-rsa",
"saved_ssh_host_key": "SHA256:qmA9mR0m2rC3k7Yw1xB5nT8fJ4hL6sV0pD2eG9uZ1aQ" }host is the trimmed host of the attempt and port an integer. Fingerprints have the form that ssh and
ssh-keygen -l print. ssh_host_key_type is null when the type is not known. ssh_host_key is null only
when the SSH library refused the key without asking EE, for example a host certificate; there is then nothing to
accept. saved_ssh_host_key is the saved key. A changed key happens after the switch is reset or replaced, or when
another device answers at that address.
To accept a changed key, a client on the computer running EE shows both fingerprints and echoes them back to
POST /api/session/host-key/replace, then repeats the login or the restore. That
attempt checks the newly saved key during the key exchange. Keys saved by earlier releases are used as they are.
For a headless setup, accept a changed key with eectl probe and --accept-host-key, which refuses when switch
playback is saved for that switch. eectl forget-host removes a saved key; the next connection then saves the key
the switch presents.
Other devices reach the workspace through one of two gateways in the gateway process, both off until the owner turns them on:
- The Tailscale gateway (private access) listens on
127.0.0.1behind a Tailscale Serve route on the private HTTPS port, 8444 by default. It accepts a request only from Tailscale Serve on this computer, with oneHost,X-Forwarded-Host(both the private address),X-Forwarded-Proto: httpsand anX-Forwarded-ForTailscale address, and withoutTailscale-Funnel-Request,AuthorizationorForwarded. The identity must be the Tailscale account that set up private access, any account in the tailnet when the audience isaccounts, or a tagged device that the owner approved on this computer. Otherwise the answer is403 private_access_denied("Private access requires an approved Tailscale account or device."). - The LAN gateway listens on the computer's private IPv4 addresses and accepts paired devices.
Both apply the same Origin and Sec-Fetch-Site rules as the local gateway: a change or WebSocket upgrade must send
the gateway's own origin, and only a GET navigation to a workspace page may come from another site. A path that
contains an encoded slash or backslash, a dot segment, a double slash or a control character is refused before the
route check, with private_access_denied or lan_access_denied. Each gateway then compares the request's method
and decoded path, without the query and a trailing slash, with the entries in preview/remote-routes.mjs. A request
is forwarded only when at least one entry matches and every matching entry has "remote": true. Every other /api
request, including a route added later without an entry, gets this answer before anything reaches the engine:
{ "detail": { "code": "local_access_required", "message": "This action is available only on the computer running EE." } }The answer is 403 with Content-Type: application/json, Cache-Control: no-store and
X-Content-Type-Options: nosniff. The query string does not change the result, so
POST /api/session/logout?forget=true is refused like POST /api/session/logout. Workspace pages, scripts, styles
and images allow GET and HEAD.
These requests are local-only:
| Request | Reason |
|---|---|
POST /api/controller/cancel |
UniFi Network setup: cancels a pending site choice |
POST /api/controller/connect |
UniFi Network setup: sends and can save controller credentials |
POST /api/controller/consoles |
UniFi Network setup: sends an API key to UniFi |
POST /api/controller/disconnect |
UniFi Network setup: disconnects the controller |
PUT /api/controller/preferences |
UniFi Network setup: saves or removes the controller login |
PUT /api/fps |
Output tuning outside the scene; no client sends it |
GET /api/lan-access |
LAN access status, pairing code and paired devices on the computer running EE |
PUT /api/lan-access |
LAN access settings |
POST /api/lan-access/code |
Shows a new pairing code on the computer running EE |
DELETE /api/lan-access/devices/{device_id} |
Removes a paired LAN device |
POST /api/lan-access/pair |
Answered by the LAN gateway before route checks; never forwarded |
PUT /api/output |
Output tuning outside the scene; no client sends it |
PUT /api/private-access |
Tailscale settings |
POST /api/private-access/login |
Starts Tailscale sign-in on the host computer |
POST /api/private-access/refresh |
Runs Tailscale checks on the host computer |
POST /api/session/forget |
Deletes the saved switch login |
POST /api/session/host-key/replace |
Accepts a changed SSH host key, part of signing in to a reset or replaced switch |
POST /api/session/login |
Signs in to a switch or the demo with typed details |
POST /api/session/logout |
Ends the switch session; forget=true deletes the saved login |
PUT /api/simulator/anomaly/{port} |
Demo simulator test control; the demo starts only from a local login |
PUT /api/simulator/links/{port} |
Demo simulator test control; the demo starts only from a local login |
PUT /api/simulator/poe/{port} |
Demo simulator test control; the demo starts only from a local login |
POST /api/workspace/admin-link |
Issues a one-use administration link to the desktop app that started the gateway |
POST /api/workspace/close |
Stops the service on the host computer |
Both gateways answer GET /api/workspace and GET /api/private-access themselves. The private access answer is the
read-only status with can_configure, can_close_workspace and can_change_port false and setup_action and
action_url null, without admin_required and local. A WebSocket upgrade is accepted only at exactly /api/ws; a
query, trailing slash or encoded form is refused with 403 Forbidden. Every WebSocket command is available to remote
devices, so an action that must stay on the computer running EE needs a REST route.
A forwarded request carries only Accept, Accept-Language, Content-Type, Content-Length, X-EE-Workspace, the
cache and range headers and the WebSocket handshake headers, with Host and Origin set to the local gateway. No
Cookie, Authorization or X-EE-Admin-Key header reaches the local gateway, so an administration link is never
redeemed through a remote gateway, and Set-Cookie is removed from every answer. A request body over 1 MiB gets
413 too_large.
Answered by the gateway, never by the engine. live is the gateway's mode: true for the gateway that the installed
app or EE_PREVIEW_LIVE=1 starts, whose engine can log in to a real switch or open the demo, and false for the
demo gateway (--demo or EE_PREVIEW_LIVE=0). remote is true when the request came through the Tailscale or LAN
gateway:
{ "live": true, "remote": false }Through the Tailscale gateway the answer is always {"live": true, "remote": true}, because both remote gateways run
only in live mode. The LAN gateway adds lan and paired (see Pairing). When
remote is true, clients leave out switch login, Forget saved login and UniFi Network setup.
Answered by the local gateway and forwarded from the remote gateways. It reports how the previous workspace service ended, for Settings:
{ "available": true,
"last_session": { "time": "2026-11-16T20:10:12.000Z", "stage": "shutdown", "outcome": "closed", "build": "0.6.0" } }stage is engine, shutdown, parent_cleanup or desktop_exit, and outcome is closed, failed or
cleanup_unconfirmed. build is the EE version or null, and attempts (1 to 10) appears after a desktop
connection loss. last_session is null when nothing was recorded. available is false when the record cannot be
read. Other methods get 405 with an empty body.
The gateway at http://127.0.0.1:4180 answers the Tailscale settings, LAN access settings and workspace close
requests itself. Changing Tailscale or LAN access settings and closing the workspace need administration access.
Every other request, including GET /api/private-access and GET /api/lan-access, works without it.
A request has administration access when it carries one of these:
- The header
X-EE-Admin-Key: <key>. The key is 64 lowercase hexadecimal characters and changes each time the gateway starts. The desktop app creates it and passes it to the gateway in theEE_ADMIN_KEYenvironment variable. Without that variable the gateway creates its own key. The key is kept in memory only. - A cookie named
ee_admin_<port>, for exampleee_admin_4180, with the value the gateway set for this launch. A browser gets it by opening an administration link (GET /?admin_code=<code>). Everyee_admin_<port>entry in theCookieheader is checked.
The administration link sets three cookies with the same name and value, one for each path that reads them:
Set-Cookie: ee_admin_4180=<value>; Path=/api/private-access; HttpOnly; SameSite=Strict
Set-Cookie: ee_admin_4180=<value>; Path=/api/lan-access; HttpOnly; SameSite=Strict
Set-Cookie: ee_admin_4180=<value>; Path=/api/workspace/close; HttpOnly; SameSite=Strict
<value> is a random value created once per launch, separate from the key. The cookies have no expiry date, so they
last until the browser session ends, and a gateway started later does not accept them. The port is part of the name
so the demo gateway (4190) and the live gateway (4180) do not replace each other's cookie. Browsers do not separate
cookies by port, so another web server on 127.0.0.1 receives the cookie for requests under those three paths.
The gateway removes Origin, Cookie and X-EE-Admin-Key from every request and WebSocket upgrade it forwards to
the engine. The Tailscale and LAN gateways forward neither Cookie nor X-EE-Admin-Key and remove Set-Cookie from
their answers.
Opens the workspace and gives the browser administration access. The gateway handles it only for a GET without an
Origin header, which is how browsers navigate to a page; a HEAD request, a request with Origin, and requests
through the Tailscale and LAN gateways, which always send Origin, open the workspace without redeeming the code.
When the query has exactly one admin_code and it is a valid code that has not been used or expired, the code is
used up and the answer is 303 See Other with Location: /, the three cookies, Cache-Control: no-store,
Referrer-Policy: no-referrer and an empty body. Any other admin_code (unknown, used, expired, malformed or
repeated) gets the same answer without Set-Cookie, and no code is used. Other query parameters are ignored.
A code is 64 lowercase hexadecimal characters. A code from POST /api/workspace/admin-link expires after 120 seconds.
The code in the link that npm start prints has no time limit; it ends when it is used or when the gateway stops. At
most eight codes are outstanding; a ninth replaces the oldest.
Takes no request body and requires the X-EE-Admin-Key header; the cookies do not count. The desktop app uses it for
Open in browser:
{ "code": "<64 lowercase hexadecimal characters>" }The browser then opens http://127.0.0.1:<port>/?admin_code=<code>. Errors:
| Status | Answer |
|---|---|
| 403 | admin_required: "This request needs the administration key of the EE app that started this workspace." |
| 405 | Empty body, for any method other than POST |
| 503 | workspace_closing: "EE is closing. Open EE again to use the browser workspace." |
Always answers 200:
{
"available": true, "enabled": true, "ready": true, "url": "https://host.example.ts.net:8444", "error": null,
"setup_action": null, "action_url": null, "audience": "owner", "https_port": 8444, "can_change_port": false,
"can_configure": true, "can_close_workspace": true, "admin_required": false, "local": true
}enabled is the saved setting and ready is true while the private address works; url is that address, or
null. audience is owner (only the Tailscale account that set up private access) or accounts (any account in
the tailnet). https_port is the Tailscale HTTPS port, and can_change_port is true only while private access is
off and no cleanup is pending. setup_action names the Tailscale step to take next, install, signin or
approve, and action_url is its link or null. local is true in every answer of the local gateway, with or
without administration access, and tells clients that they run on the computer running EE.
admin_required is false with administration access. Without it, the answer is the read-only form that the remote
gateways give: setup_action and action_url are null, can_change_port, can_configure and can_close_workspace
are false, and admin_required is true. A pending Tailscale sign-in link therefore never reaches another local user.
Tailscale is optional. available is true once EE has read this computer's Tailscale identity. While private access
is off, EE reads it only after a PUT that turns private access on or a sign-in request since EE started, and a
PUT that turns it off ends that setup; a PUT that changes https_port reads it once to save the new address. On
a computer without Tailscale where private access was never turned on, the answer is therefore available: false,
enabled: false, error: null and setup_action: null. While private access is off, EE runs no other Tailscale
command once it has confirmed that its route is gone (see the startup check below).
error is null or {code, message}:
| Code | Message |
|---|---|
tailscale_not_installed |
Install Tailscale on this computer, sign in, then refresh status. |
tailscale_not_running |
Connect Tailscale on this computer, then refresh status. |
tailscale_signin_required |
Connect this computer to Tailscale, then check again. |
tailscale_approval_required |
Complete the approval in Tailscale, then refresh status and apply the setting. |
tailscale_permission_required |
Tailscale needs permission to manage private access. Open EE as an administrator and try again. |
tailscale_device_identity_required |
Use a personal Tailscale account on the computer running EE, then refresh status. |
tailscale_unavailable |
Open Tailscale on this computer, then check again. |
private_access_identity_changed |
The approved Tailscale account or computer identity changed. Turn private access off before setting it up again. |
private_access_port_in_use |
Another Tailscale service uses this port. Keep that service unchanged and choose a separate port for EE. |
private_access_port_change_requires_off |
Turn private access off and confirm cleanup before changing its port. |
private_access_funnel_enabled |
This port is configured for public access. EE requires a private Tailscale Serve address. |
private_access_route_unavailable |
The saved private address is unavailable. Apply the private access setting to reconnect it. |
private_access_listener_failed |
The private EE connection could not start. Check that its local port is available. |
private_access_save_failed |
The private access setting could not be saved. Check the local data folder and try again. |
private_access_setup_unconfirmed |
Private access setup could not be confirmed. Its EE connection remains closed; check again before retrying. |
private_access_cleanup_unconfirmed |
The private EE connection is closed, but removal of its Tailscale route is unconfirmed. Check again before retrying. |
private_access_shutdown_unconfirmed |
Private access shutdown could not be confirmed. Review the local connection before retrying. |
private_access_invalid_configuration |
The private access configuration could not be verified. Review its saved settings before retrying. |
When private access is on but cannot be opened because Tailscale is not running, not signed in or not answering yet, its address is unavailable or its listener could not start, the gateway runs the startup check again after 5, 10, 20 and 40 seconds, 1 and 2 minutes and then every 5 minutes, until the address works or the setting is turned off.
The demo gateway answers {"available": false, "enabled": false, "ready": false, "can_configure": false, "can_close_workspace": <access and not closing>, "admin_required": <no access>, "local": true}. The remote
gateways' answer has no admin_required field; clients treat a missing field as false.
Clients show their read-only help for a local tab without administration access when admin_required is true and
https_port is an integer, which only the live gateway reports. They show the close help in place of Close web
session when can_close_workspace is not true and admin_required is true.
PUT takes {"enabled": true, "https_port": 8444, "audience": "owner"}; https_port (1024–65535) and audience
(owner or accounts) are optional. The other two take no body. Without administration access each answers 403
before the body is read:
{ "detail": { "code": "admin_required", "message": "To change private access, choose Open in browser in the EE tray menu. If EE runs from source, use the administration link it printed when it started." } }With administration access the answer is the status fields above with can_configure true and admin_required
false, without can_close_workspace and local. A problem with Tailscale is reported in error with a 200 answer.
An invalid setting returns 400, a body over 1 KB returns 413, another method returns 405, a request while EE is
closing returns 503, and an unexpected failure returns 409 with
{"detail": {"code": "private_access_failed", "message": "Private access could not be updated. Refresh status and try again."}, "status": {...}}.
Refresh and sign-in repeat the startup check. When private access is on and its HTTPS port has no Tailscale Serve
configuration, that check adds EE's route again, so a refresh after the Tailscale HTTPS approval completes a saved
setup. Turning private access off removes the route and, once Tailscale Serve shows it gone, records that in
private-access.json; a saved setting that is off with that record runs no Tailscale command at startup, refresh or
stop. For a saved setting that is off without it, for example after a removal Tailscale could not confirm or a
setting turned off by release 0.5.1, the check reads the Tailscale Serve status. It records the removal when EE's
route is gone and reports private_access_cleanup_unconfirmed if it is still there; a Serve status that Tailscale
cannot give is not reported. Sign-in runs tailscale login only when Tailscale reports that it needs a login.
EE adds its own Serve route only on a port with no Serve configuration, and it never changes other Serve
configuration. When the gateway stops (Quit, Close web session or the installer closing EE), it removes exactly that
route within 4 seconds and keeps the setting, so the next start adds the route again; with a setting that is off and
whose removal is recorded, it runs no Tailscale command. A removal that cannot be confirmed is recorded as
private_route_cleanup_unconfirmed in service-diagnostics.log.
Returns the switch lighting, stops the engine, ends private access, closes the LAN listener and closes the gateway. In live mode, ending private access also removes EE's Tailscale Serve route; private access and LAN access stay on in their settings, and EE opens them again when it next starts. A removal that cannot be confirmed does not make the close fail.
| Status | Answer |
|---|---|
| 200 | {"closed": true} |
| 403 | admin_required: "To close the web session, choose Open in browser in the EE tray menu, or quit EE. If EE runs from source, use the administration link it printed when it started." |
| 405 | Empty body, for any method other than POST |
| 409 | {"detail": "The service has not confirmed shutdown. Wait and try again."} |
A refused request changes nothing, so lighting and private access keep working.
LAN access lets devices on the owner's network open the workspace at the address of the computer running EE, over
plain HTTP and without Tailscale. It is off until the owner turns it on, it runs only in live mode, and each device
pairs with a single-use code shown on the computer running EE. Paired devices get the same route limits as devices on
Tailscale: the LAN gateway compares each request with preview/remote-routes.mjs exactly as the Tailscale gateway does.
Tailscale private access and LAN access can both be on; they use separate listeners and separate device lists.
Traffic between a paired device and the computer running EE is not encrypted. Anyone who can watch or change traffic on the network can read what crosses it: lighting, fan and handoff commands and scene changes (REST and WebSocket); workspace data, including the session status (the switch address, SSH port and SSH username, never passwords), the switch model and port status, port names, the UniFi Network address and site names, device names and telemetry from UniFi Network when it is connected, profiles, schedules, rules, saved effect settings, fan status and the Tailscale private address when private access is on; the device's key, in its cookie, with every request; and the pairing code, once. With a copied key they can do anything a paired device can until that device is removed or LAN access is turned off, and they can change what a device shows.
LAN access never carries switch passwords and saved logins (POST /api/session/login, /api/session/forget,
/api/session/logout and the host-key routes are local-only, and GET /api/session returns no passwords), UniFi
Network passwords and API keys (the controller setup routes are local-only), the administration key or cookie, or
saved key hashes. The desktop client also refuses to send POST /api/session/login, POST /api/controller/connect,
POST /api/controller/consoles and PUT /api/controller/preferences to a LAN address, with
403 local_access_required, before anything is sent. Use Tailscale for an encrypted connection.
The LAN gateway listens on 0.0.0.0:<port>, IPv4 only, with port 4280 unless the owner chose another from 1024 to
65535. The port is fixed: when it is busy, LAN access reports lan_access_port_in_use instead of trying another, so
the addresses saved on devices keep working. The gateway keeps a connection only when it arrived at one of this
computer's current private IPv4 interface addresses (10/8, 172.16/12 or 192.168/16) from a private IPv4 address;
anything else, including Tailscale's 100.64/10 addresses, loopback, link-local, public and IPv6 addresses, is closed
before any HTTP is read. Any private source address is accepted, so devices on other networks that the router routes
to this computer can pair. The gateway accepts at most 64 connections, at most 16 from one address, and request
headers of at most 8 KB.
Each request is then checked:
Hostmust be exactly<address the connection arrived on>:<port>, and that address must still be one of this computer's private addresses. A DNS name, another port or a public address is refused, so a page on a name that resolves to this computer cannot use a device's cookie or guess codes.Host,Origin,Sec-Fetch-Site,Sec-Fetch-ModeandCookiemay appear only once, without control characters, and at most 1024 characters long (4096 forCookie). AnyAuthorization,ForwardedorX-Forwarded-*header is refused.Origin, when present, must behttp://<Host>, and changes and WebSocket upgrades must send it.Sec-Fetch-Siteother thansame-originornoneis refused except for aGETnavigation to a workspace page.- The
ee_lan_<port>cookie identifies a paired device. Without one, only workspace pages (GETandHEADoutside/api),GET /api/workspaceandPOST /api/lan-access/pairare answered.
Every refusal in steps 1 to 3 is:
{ "detail": { "code": "lan_access_denied", "message": "Open EE at the address shown in LAN access on the computer running EE." } }A path that cannot be classified gets lan_access_denied with "This request cannot be opened through LAN access.",
and any other request from a device that is not paired gets:
{ "detail": { "code": "lan_pairing_required", "message": "Pair this device first. Enter the pairing code shown on the computer running EE." } }A paired device's requests then follow the route entries: GET /api/private-access gets the same read-only Tailscale
status the Tailscale gateway gives, without local, and every request without a remote entry gets
403 local_access_required. A WebSocket upgrade is accepted only at exactly /api/ws and only for a paired device;
the gateway checks each socket again every 15 seconds and at once when a device is removed, including a socket whose
upgrade the engine has not answered yet. A request body over
1 MiB gets 413 too_large. The gateway forwards neither Cookie nor X-EE-Admin-Key, always sends an Origin
upstream, so /?admin_code= is never redeemed through it, and removes Set-Cookie from upstream answers.
Do not forward the LAN port on a router. A router that forwards a public port and rewrites the source address would
pass the connection check; the Host check and pairing still apply.
POST /api/lan-access/code on the computer running EE shows a code of 6 digits. Only one code is active; a new code
replaces the old one. A code works once and ends after 5 minutes, after 5 wrong attempts, when it is used, or when
LAN access turns off or EE stops. Codes are kept in memory only and never appear in a status without administration
access. Attempts are checked one at a time.
The device sends the code on the LAN gateway. The body is at most 1 KB:
{ "code": "482 913", "name": "Kitchen iPad", "client": "browser" }Spaces and hyphens in code are ignored. name is trimmed and must have 1 to 40 characters without control, format
or line and paragraph separator characters; duplicate names are allowed. client is browser (the default) or
app and only labels the device in the list. A body that fails these checks gets 400 invalid and costs no attempt.
A wrong or missing code gets 403 lan_pairing_failed. A matching code is used up at once; if the device cannot be
saved, the answer is 500 lan_pairing_save_failed and the owner shows a new code. Success:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer
Set-Cookie: ee_lan_4280=<64 lowercase hex>; Path=/api; Max-Age=31536000; HttpOnly; SameSite=Strict
{ "paired": true, "device": { "id": "3f9c0a1b2c3d4e5f", "name": "Kitchen iPad", "client": "browser", "paired_at": "2026-11-16T20:10:12.000Z" } }
The key is never in the body, and the cookie has no Secure attribute because the connection is plain HTTP. The
desktop client reads the key from Set-Cookie and sends Cookie: ee_lan_<port>=<key> itself, also on the WebSocket
upgrade. Every ee_lan_<port> entry in the Cookie header is compared with every saved key hash, so a decoy cookie
cannot hide the device's own. Browsers send cookies to every port of the same host: Path=/api limits the cookie to
API requests, but another service at the same address on a different port receives it for paths under /api, as the
administration cookie on 127.0.0.1 does.
A browser keeps the cookie for one year (Max-Age=31536000); after that it needs a new code, and its old entry stays
listed until it is removed. The desktop client keeps its key with no time limit. A device that pairs again gets a new
entry. At most 16 devices can be paired. A device's pairing does not depend on its own address. When the address of
the computer running EE changes, each device opens the new address and pairs again.
On the LAN gateway, GET /api/workspace answers whether this device is paired:
{ "live": true, "remote": true, "lan": true, "paired": false }The local gateway's answer has no lan field, and the Tailscale gateway's answer is unchanged.
| Request | Access | Body |
|---|---|---|
GET /api/lan-access |
Anyone local; administration access gets the full form | none |
PUT /api/lan-access |
Administration | {"enabled": true, "port": 4280}; port (1024–65535) is optional; no other keys; at most 1 KB |
POST /api/lan-access/code |
Administration | none |
DELETE /api/lan-access/devices/{device_id} |
Administration; device_id is 16 lowercase hexadecimal characters |
none |
Each answers 200 with the status below. Administration access is the key header or the ee_admin_<port> cookie from
an administration link, which also sets that cookie with Path=/api/lan-access. Without it, a change gets
403 admin_required before the body is read:
{ "detail": { "code": "admin_required", "message": "To change LAN access, choose Open in browser in the EE tray menu. If EE runs from source, use the administration link it printed when it started." } }Another method on these paths gets 405 with an empty body, and any other URL that starts with /api/lan-access,
including /api/lan-access/pair, gets 404 not_found ("This LAN access request does not exist.") and never
reaches the engine. In demo mode every request answers {"available": false, "enabled": false, "ready": false, "can_configure": false, "admin_required": <no access>}. These routes are local-only on both remote gateways.
Turning LAN access on opens the listener first and saves the setting only once it is open. Turning it off closes the
listener and every connection, ends the code, removes every paired device and saves the off setting; PUT with
"enabled": false writes it even when LAN access is already off. The port changes only while LAN access is off.
Removing a device refuses its requests at once, closes its WebSockets before the answer is sent, and then saves the
list. When EE closes, the listener stops and the setting stays, so the next start opens it again; a saved setting
that cannot open its port is reported in error, and PUT {"enabled": true} retries it.
With administration access:
{
"available": true, "enabled": true, "ready": true, "port": 4280,
"addresses": [ { "url": "http://192.168.1.2:4280", "interface": "Ethernet" } ],
"error": null,
"pairing": { "code": "482913", "expires_at": "2026-11-16T20:15:00.000Z", "attempts_left": 5, "ended": null },
"devices": [ { "id": "3f9c0a1b2c3d4e5f", "name": "Kitchen iPad", "client": "browser",
"paired_at": "2026-11-16T20:10:12.000Z", "paired_from": "10.0.0.1",
"last_used_at": "2026-11-16T20:14:03.000Z", "last_address": "10.0.0.1" } ],
"max_devices": 16, "can_configure": true, "can_change_port": false, "admin_required": false
}addresses lists each private IPv4 address of this computer's network interfaces, 192.168/16 first, then 10/8, then
172.16/12, with the interface name, as read at that moment; it is empty while LAN access is not ready. Hyper-V, WSL,
Docker and VPN adapters are listed too. pairing is null until a code is shown after LAN access turns on; after a
code ends, code is null and ended is used, expired, attempts or failed. last_used_at and last_address
are kept in memory only and are null until the device makes a request after EE starts. Without administration access,
pairing and devices are null, can_configure and can_change_port are false and admin_required is true. While
EE is closing, can_configure is false and changes get 503 workspace_closing ("EE is closing. Reopen EE to change
LAN access.").
A failure during an operation is reported in error with a 200 answer:
| Code | Message |
|---|---|
lan_access_port_in_use |
Another program uses this port. Choose another LAN port in Connection options. |
lan_access_listener_failed |
EE could not open its LAN port. Choose another LAN port in Connection options, then try again. |
lan_access_save_failed |
The LAN access setting could not be saved. Check the local data folder and try again. |
lan_access_turned_off |
The change could not be saved, so EE turned off LAN access and removed every paired device. Check the local data folder, then turn on LAN access again. |
lan_access_revoke_unsaved |
EE turned off LAN access and removed every paired device, but could not save this. Paired devices can connect again after EE restarts. Check the local data folder, then apply the setting again with LAN access off. |
lan_access_invalid_configuration |
The saved LAN access settings could not be read, so LAN access is off and no devices are paired. Turn it on to start again. |
lan_access_newer_configuration |
The LAN access settings were saved by a newer version of EE, so LAN access is off and its settings stay as they are. Update EE to use them. |
lan_access_port_change_requires_off |
Turn off LAN access before changing its port. |
When turning LAN access off or removing a device cannot be saved, EE turns LAN access off in memory and deletes its
settings file, which reads as off with no devices, so a restart cannot bring the devices back (lan_access_turned_off).
If the file cannot be deleted either, the status says so (lan_access_revoke_unsaved).
Requests refused with their own status:
| Status | Code | Message |
|---|---|---|
| 400 | invalid |
PUT: "Choose a valid LAN access setting and a port between 1024 and 65535." Pairing: "Enter the 6-digit pairing code and a name of up to 40 characters for this device." |
| 403 | lan_access_denied |
"Open EE at the address shown in LAN access on the computer running EE." or "This request cannot be opened through LAN access." |
| 403 | lan_pairing_required |
"Pair this device first. Enter the pairing code shown on the computer running EE." |
| 403 | lan_pairing_failed |
"The pairing code is wrong or has expired. Check the code on the computer running EE, or choose Pair a device there to show a new one." |
| 404 | not_found |
"That device is no longer paired." or "This LAN access request does not exist." |
| 409 | lan_access_off |
"Turn on LAN access before pairing a device." |
| 409 | lan_access_device_limit |
"16 devices are paired, the most EE allows. Remove one before pairing another." |
| 409 | lan_access_failed |
"LAN access could not be updated. Refresh status and try again." The answer also carries status. |
| 413 | too_large |
"The request is too large." A setting or pairing body over 1 KB, or any body over 1 MiB. |
| 500 | lan_pairing_save_failed |
"The device could not be saved on the computer running EE. Ask for a new pairing code there and try again." |
The setting and the paired devices are kept together in lan-access.json in the workspace data folder, next to
private-access.json, so turning LAN access off and removing every device is one write:
{ "version": 1, "enabled": true, "port": 4280,
"devices": [ { "id": "3f9c0a1b2c3d4e5f", "name": "Kitchen iPad", "client": "browser",
"key_sha256": "<64 lowercase hex>", "paired_at": "2026-11-16T20:10:12.000Z", "paired_from": "10.0.0.1" } ] }The file holds only the SHA-256 of each key. It must be a regular file of at most 16 KB, not a link, and on macOS and
Linux owned by the user with no group or other permissions. A file that does not match this layout exactly is
reported as lan_access_invalid_configuration and keeps LAN access off; the next successful PUT writes a new file
with no devices. A file whose version is an integer above 1 was saved by a newer version of EE: it is reported as
lan_access_newer_configuration, LAN access stays off, can_configure is false and every PUT leaves the file as it
is. A missing file means off with no devices. A per-user uninstall deletes the file.
The installer adds and removes no firewall rule, and EE does not check the firewall. The first time EE's node.exe
listens on the network, Windows shows a Windows Security Alert for Node.js JavaScript Runtime; the owner allows it on
private networks only. The rule belongs to the program path, so any script that this node.exe runs can accept
connections on the allowed networks, and the rule stays after LAN access is turned off and after uninstalling. A rule
for private networks does not apply while Windows lists the current network as public. The
desktop guide covers allowing, undoing Cancel and
removing the rule.
{
"logged_in": true,
"connected": true,
"connecting": false,
"host": "192.168.1.2",
"port": 22,
"username": "admin",
"simulated": false,
"workspace_id": "opaque-workspace-id",
"switch": { "hostname": "USW-Pro-XG-8-PoE", "etherlight_mcu": true, "port_rgb": true },
"ssh_host_key": "SHA256:qmA9mR0m2rC3k7Yw1xB5nT8fJ4hL6sV0pD2eG9uZ1aQ",
"ssh_host_key_type": "ssh-ed25519",
"error": null,
"remembered": { "host": "192.168.1.2", "port": 22, "username": "admin" },
"has_saved_login": true,
"saved_login_error": null,
"pending_scene_choice": null,
"automatic_connect_paused": false,
"handoff_state": "none",
"switch_playback": "playing",
"offline_lighting_error": null,
"handed_off": false,
"fan_handoff": null
}connected can become false while logged in, for example when the switch reboots. EE reconnects automatically,
and error holds the last connection error until it does. Connection errors are retried for as long as EE runs, with
delays that grow to one minute. For 10 minutes after a lost connection, a switch that answers but does not yet offer
its lighting is treated as still starting and retried too. When the connection was lost before EE could confirm its
lighting, EE runs the same checks as POST /api/session/recover on its own when the switch
answers, and resumes the lighting only if it was running before. A rejected login or SSH key, a changed lighting
owner, or capabilities that are still missing after 10 minutes stop the automatic attempts and set
reconnect_required.
pending_scene_choice is set while a new connection waits for the user to choose its lighting (see
POST /api/session/scene-choice), otherwise null. handoff_state is none,
pending while a Handoff to UniFi runs, complete after a confirmed handoff and unconfirmed after one that EE
could not confirm. automatic_connect_paused is true after a handoff until the next successful connection, so EE
does not reconnect at startup; handed_off is true after a confirmed handoff while no switch is connected.
switch_playback and offline_lighting_error describe the lighting player.
fan_handoff reports what Handoff to UniFi did with the fans:
| Value | Meaning |
|---|---|
"returned" |
During the last handoff EE stopped its fan control on the switch, and the switch confirmed that its own fan controller runs and is not paused. |
"unconfirmed" |
EE could not confirm that the fans are back on the switch's own controller: the switch was not connected or could not be read and EE could not rule out its own fan control, a fan command failed, or the 15-second limit ran out. |
null |
No EE fan control was found, the switch has no fan control, no handoff ran since the last connection, or no switch was connected. |
The value is kept in memory only. A successful connection resets it to null. A handoff that retries an
unconfirmed one after its switch connection was closed keeps the previous value; any other handoff sets it to its
own result, or to null when no switch was connected.
error is the engine's message while a switch is logged in and its engine has one; otherwise it is the error
object of the last failed attempt. That object can be an SSH host key error with its fingerprints,
also while another switch is logged in, so a client opens a key review only when logged_in is false. The WebSocket
session message carries the same object. When a reconnect is refused because the switch's key changed, the
engine's message asks the user to quit EE, open it again and review the key on the Connect page; the startup
connection then reports both fingerprints.
ssh_host_key and ssh_host_key_type describe the SSH key of the connected switch, which is the key EE saved for
its address: the fingerprint as ssh-keygen -l prints it and the key algorithm, such as ssh-ed25519. Both are
null while no switch is logged in, for the demo, and the type is null when it is not known.
connecting is true during automatic startup login and returns to false after success, failure or cancellation.
The server publishes both transitions as session messages. Clients must keep listening when their initial
session read happens before startup login completes. Explicit logout stops the lighting session without retrying;
the saved login remains available for the next app launch unless the user chooses Forget.
remembered contains only the address, SSH port and username. has_saved_login also remains true if a stored
record cannot be read; saved_login_error then contains an actionable message. Failed automatic login due to an
unreadable record sets error.code to saved_login_unavailable and leaves the stored record in place.
workspace_id is an opaque, stable identifier for browser-local drafts and preferences. A real workspace is
scoped to the normalized switch address, SSH port and username; demo has its own scope. It is null before a
workspace is selected. Treat it as a storage key, not an authentication token, and do not reuse a draft across
different workspace IDs.
{ "host": "192.168.1.2", "username": "admin", "password": "...", "port": 22, "remember": true }Returns the session as above, or an error. When switching to a different switch, the current session keeps running until the new login succeeds.
remember defaults to false. On Windows, true encrypts the entire login payload for the current Windows user
with DPAPI before replacing the saved record. Protection or saving failure leaves the previous session and
saved record intact. An existing legacy record is migrated atomically when loaded; migration must succeed before
automatic login uses it. Passwords are never included in API or WebSocket responses. Demo login preserves an
existing saved switch login.
The login reads the lighting saved for this switch, under the identity of its SSH key and port layout:
- When the switch has saved lighting, EE applies it and the session starts.
- When it has none, the connection stays open and the session reports
pending_scene_choicefor 5 minutes. The user chooses between the lighting saved by releases that kept one setup for every switch and a new setup. - When the saved file cannot be used and no switch playback record exists, EE moves the file aside as
<name>.corrupt-<UTC time>and offers the same choice. - With a playback record, an unusable file returns
422 invalid_saved_scene("The saved lighting for this switch could not be verified.") and stays where it is, because the player on the switch was built from it. A file that cannot be read, or that a newer version of EE saved ("...saved by a newer version of EE. Update EE to use it."), also returns422 invalid_saved_sceneand is never moved.
When known_switches.json cannot be read or was saved by a newer version of EE, the login returns
500 host_key_save_failed before it contacts the switch, and the file is kept. The message names the case ("SSH
host keys were saved by a newer version of EE. Update EE to use them." or "The saved SSH host keys in
known_switches.json could not be read. Check the EE data folder."). A first key that cannot be saved after the login
returns the same code. The clients show these messages, and the messages of invalid_saved_scene and
switch_playback_reserved, as the service sends them.
{ "connection_id": "<from pending_scene_choice>", "choice": "use_saved", "legacy_revision": "<from pending_scene_choice>" }Finishes a connection that waits for its lighting. pending_scene_choice holds connection_id,
legacy_revision (a hash of the older shared scene.json, or absent) and legacy_available (whether that file
holds a usable setup). choice is use_saved to apply that file, start_new to start from the default setup, or
cancel to close the connection. connection_id is 1 to 128 characters and legacy_revision at most 128. Returns
the session.
| Status | Code | When |
|---|---|---|
| 400 | invalid_scene_choice |
choice is another value |
| 409 | scene_choice_expired |
No connection waits with this ID, the 5 minutes ran out, or the switch connection changed |
| 409 | scene_choice_stale |
use_saved with a legacy_revision that no longer matches scene.json; the session reports the new revision |
| 409 | saved_scene_unavailable |
use_saved while scene.json holds no usable setup |
| 422 | invalid_saved_scene |
scene.json could not be applied to this switch |
| 500 | scene_save_failed |
The chosen setup could not be saved for this switch |
Takes no request body and reconnects using the server's protected saved switch login. Returns the session.
If a real switch session already exists, or a connection waits for its lighting choice, returns it unchanged.
Concurrent restore requests share one connection attempt. A demo session remains active until the saved real-switch
login succeeds. After a Handoff to UniFi (automatic_connect_paused), a restore returns the session unchanged unless
the query has resume=true, which the clients' Connect with saved login button sends.
The server publishes connecting: true and the final session transition. Missing saved credentials return
HTTP 409 with no_saved_login; an unreadable saved record returns HTTP 409 with saved_login_unavailable.
Connection errors use the normal login error contract. The saved record is retained, and its password is never
returned to the browser.
Devices on Tailscale or the LAN reconnect with this route. Like a login, a restore to an address without a saved SSH key saves the key the switch presents. Signing in with typed details and accepting a changed SSH host key are available only on the computer running EE.
Takes no request body. After an interrupted connection (reconnect_required in the state), it checks the current
switch again, cleans up EE's own output there and resumes the retained scene. Returns the state. It refuses a changed
device identity, changed capabilities or unconfirmed helper cleanup with 409 output_unconfirmed, and a pending
handoff with 409 handoff_unconfirmed.
Deletes the saved login, returns the updated session and publishes a session message. The current switch connection keeps running. This also removes an unreadable record when the user explicitly chooses Forget.
{ "host": "192.168.1.2", "port": 22,
"saved_ssh_host_key": "SHA256:qmA9mR0m2rC3k7Yw1xB5nT8fJ4hL6sV0pD2eG9uZ1aQ",
"ssh_host_key": "SHA256:Zt4Wc8Hn1Lq6Rv3Xb9Me2Kd7Pj0Ys5Ug8Fa1Ni4Ow7E" }Replaces a changed SSH key, after a host_key_changed error. host is 1 to 253 characters, port a JSON integer
from 1 to 65535 (default 22), and ssh_host_key and saved_ssh_host_key match ^SHA256:[A-Za-z0-9+/]{43}$.
Other fields and values of another JSON type return 422 invalid_credentials. saved_ssh_host_key must be the key
saved now and ssh_host_key the key EE last saw at that address. The route does not contact the switch: the
retried login or restore verifies the saved key during the SSH key exchange. It also deletes the switch playback
record of the replaced key, as a confirmed handoff does, because that player ran in the previous switch's memory.
Lighting, schedules and port names saved for the previous key stay saved but are not used with the new key. Returns
the session, clears a host_key_changed error for that address and publishes a session message.
| Status | Code | When |
|---|---|---|
| 200 | The key is replaced, or was already the saved key | |
| 400 | missing_host |
host is empty after trimming |
| 403 | local_access_required |
The caller's address is not a loopback address (127.0.0.0/8 or ::1) |
| 409 | host_key_in_use |
EE still has an open switch connection, a lighting choice waiting, or a shutdown it has not confirmed |
| 409 | host_key_stale |
No key is saved, the saved key is not saved_ssh_host_key, the two keys are equal, or ssh_host_key is not the key EE last saw there |
| 409 | switch_playback_reserved |
The switch playback record cannot be read, waits for a handoff, or belongs to another switch |
| 500 | host_key_save_failed |
The saved keys or the playback record could not be updated; the saved key and the record are unchanged |
The route refuses a caller whose address is not a loopback address before it reads the request body, and the
Tailscale and LAN gateways refuse it, so a changed SSH key is accepted only on the computer running EE. The desktop
app, the browser workspace and the gateway reach the service from 127.0.0.1. POST /api/session/forget-host-key no
longer exists and returns 404.
A client offers to accept a changed key only when the workspace gateway's GET /api/private-access returns
local: true. The gateway on the computer running EE includes that field in its answer, with or without permission
to change private access. The Tailscale and LAN gateways answer the request themselves without the field, and
clients treat a failed request as remote.
Stops EE from controlling the LEDs. The switch's own colors return within about two seconds. ?forget=true also
deletes the remembered login, and returns 409 switch_playback_reserved while switch playback is saved. A lighting
cleanup that the switch does not confirm returns 409 output_unconfirmed. Returns the session.
Takes no request body. Stops EE lighting and its switch helpers, returns the fans of a USW-Pro-XG-8-PoE to the
switch's own controller, closes the SSH connection, and pauses automatic connection until you connect again. Saved
logins, profiles, the lighting setup and the fan mode saved for each switch are kept. When switch playback is saved,
it also stops the lighting player, reconnecting with the saved login if needed. Returns the session. Errors:
409 handoff_unconfirmed when EE could not confirm that its lighting and SSH activity stopped (retry the handoff;
automatic connection stays paused), handoff_save_failed when the handoff state could not be saved, and
handoff_recovery_required when an earlier handoff has no confirmed shutdown. A player that could not be stopped is
retried every 30 seconds. The fan step takes at most 15 seconds; fan_handoff reports its result and never changes
handoff_state. The next connection to the switch restores its saved fan mode.
Returns name, short_name, version, tagline and disclaimer, the unofficial-project notice. The disclaimer
should be visible in the UI, for example on the login screen and an About page.
Returns {"ok": true, "name": "Etherlighting Evolved", "version": "<version>", "logged_in": false}. logged_in is
true while a switch or the demo is connected.
The controller connection enriches the connected switch's port information. Account login supplies names and
topology; an official API key supplies the selected console's port metadata. Lighting output, link state,
traffic and PoE measurements continue to come from the switch session. Controller setup requires a real switch
session; a missing or demo session returns HTTP 409 with switch_required.
Returns cached status without making a controller request:
{
"connected": true,
"configured": true,
"url": "https://controller.example:8443",
"controller_kind": "self_hosted",
"auth_method": "password",
"console_id": null,
"capabilities": {"client_mapping": true, "port_metadata": true},
"site": "default",
"sites": [{"id": "default", "name": "Home"}],
"pending_site_choice": null,
"switch_name": "Lighting switch",
"updated_at": "2026-10-30T18:00:00+00:00",
"stale": false,
"error": null,
"mapped_ports": 7,
"preferences_supported": true,
"remember_on_connect_supported": true,
"saved_target": null,
"auto_reconnect": false,
"saved_login_available": false,
"saved_login_matches_connection": false,
"can_save_login": true,
"reconnect_state": "off",
"saved_login_error": null
}configured includes a pending connection awaiting a certificate, verification code or site choice.
controller_kind is self_hosted, unifi_os, or cloud_connector; it is null before configuration.
auth_method is password or api_key. The capabilities flags describe the current adapter's data.
console_id identifies the selected Site Manager console for cloud access.
supported_auth_methods advertises the implemented setup options even before configuration:
{"self_hosted": ["password"], "unifi_os": ["password", "api_key"], "cloud_connector": ["api_key"]}.
console_discovery_supported: true enables the Cloud Connector's console picker.
connected requires an authenticated session and a successful, fresh match to the connected switch.
mapped_ports counts ports with controller-backed metadata, not linked ports. updated_at is the last successful
topology refresh in UTC; it is null before the first success. error is null or a sanitized object with
code and message.
EE refreshes the selected site approximately every 15 seconds. Data older than 45 seconds, or a failed refresh,
sets stale and removes controller enrichment from port responses. connected becomes false and mapped_ports
becomes zero until a successful refresh. Cached data is also scoped to the connected switch address.
The same status object appears as controller in GET /api/state and WebSocket state/frame messages.
Enriched entries in GET /api/ports and frame ports, plus state/frame sfp, can include:
{"port": 1, "name": "Workstation", "controller": {"source": "unifi", "kind": "client", "count": 1}}kind is client, device, multiple, or port_label. Names follow explicit controller switch-port topology;
multiple clients on one port produce a count label. Adopted-device topology takes precedence over clients behind
that device. Configured port labels provide a fallback. Existing lighting and telemetry fields are preserved.
Client mappings include a bounded controller.clients list with name and
name_source (assigned, hostname, or null). Assigned controller names appear
first, followed by hostname fallbacks. The port title uses assigned names when
available; Port details retains every returned associated client. count is the
total number of associated clients, and clients_truncated indicates more than
64 records. Multiple assigned names remain visible together in the port title.
The official API adapter adds controller.source: "unifi_integration", kind: "port",
client_mapping: false, the documented port state, optional speed_mbps, and optional poe
fields (enabled, type, standard, state). These stay inside controller; the switch session's
measurements and port names remain authoritative. The official schema does not supply the physical
client-to-port join used by account login. A UI can offer account login for device names when
capabilities.client_mapping is false.
{
"url": "https://controller.example:8443",
"controller_kind": "self_hosted",
"auth_method": "password",
"username": "controller-user",
"password": "...",
"site": null,
"certificate_sha256": null,
"verification_code": null
}controller_kind selects self_hosted for the standalone Network application, unifi_os for a UniFi console
or UniFi OS Server, or cloud_connector for an explicitly selected Site Manager console.
It defaults to self_hosted, and auth_method defaults to password, for existing callers. url is the direct HTTPS origin,
including its port. The usual ports are 8443 for standalone Network and 443 for UniFi OS; the supplied origin
is used exactly. Paths, query strings, embedded credentials and redirects are rejected.
site is the controller's site ID (a UUID for official API access). A single accessible
site is selected automatically. With multiple sites, the response includes
pending_site_choice: {"url": "https://controller:8443", "controller_kind": "self_hosted", "auth_method": "password", "console_id": null, "capabilities": {...}, "sites": [...]};
submit again with the selected ID. During first setup, the response also includes
error.code: "site_required" and the top-level sites choices. When replacing a working connection,
the top-level status and telemetry keep describing that connection until the candidate's selected
site has been read and matched successfully. Canceling or failing that selection preserves the
working connection. Saving a login is unavailable while a site choice is pending.
Omit remember or send false for a session-only connection. The previous saved login stays intact.
When remember_on_connect_supported is true, send "remember": true to save the new login after EE
authenticates it and matches the selected site to the connected switch. Include the flag on the final
request after certificate approval or site selection. Check saved_login_matches_connection in the result.
If Windows cannot save the login, the connection stays active and saved_login_error describes the failure.
The preferences endpoint can retry the save using that active connection.
Subsequent requests to the same origin, controller type, sign-in method and console ID
may leave the selected credential fields blank to continue that pending or active connection. An omitted fingerprint
retains the certificate already approved for that target. A failed replacement connection preserves a different
active controller connection. On the self-hosted path, verification_code is an optional one-time code of 6–8 digits; it is neither saved
nor automatically replayed.
TLS certificates are verified before credentials are sent. An untrusted certificate returns HTTP 400:
{"detail": {"code": "certificate_untrusted", "message": "Verify this controller certificate before signing in.",
"certificate_sha256": "64-hex-digit-fingerprint"}}Show the fingerprint for explicit user approval, then resubmit it as certificate_sha256. The client compares the
approved SHA-256 fingerprint before any authenticated request. A later mismatch returns certificate_changed
and requires approval of the new fingerprint. Certificate approval and account verification are separate steps.
Other actionable errors include invalid_url, credentials_required, authentication_failed,
two_factor_required, verification_failed, site_not_found, no_sites, switch_not_found, unreachable,
rate_limited, invalid_controller_kind, controller_local_account_required, and unsupported_controller.
UniFi OS accounts that require an additional authentication flow return controller_local_account_required;
use a local account with Network access. Use sanitized messages; response bodies do not include
controller diagnostics, passwords or cookies.
The self-hosted adapter posts to /api/login. The UniFi OS adapter posts to /api/auth/login.
Data requests are GETs to /api/self/sites, /api/s/{site}/stat/device, and /api/s/{site}/stat/sta,
with /proxy/network prepended for UniFi OS. Routes are selected explicitly; a failed login never tries
another controller type. Cookies and validated CSRF tokens remain scoped to the approved origin in server memory.
Direct console example:
{"url": "https://console.example", "controller_kind": "unifi_os", "auth_method": "api_key",
"api_key": "...", "console_id": null, "site": null, "certificate_sha256": null}Cloud Connector example:
{"url": "https://api.ui.com", "controller_kind": "cloud_connector", "auth_method": "api_key",
"api_key": "...", "console_id": "selected-console-id", "site": null, "certificate_sha256": null}Send only the selected authentication method's secret. API keys are sent as X-API-Key over verified
HTTPS; they are not returned in status or errors. Local console certificates use the explicit trust flow
above. Cloud access requires the fixed https://api.ui.com origin and public certificate validation;
it rejects certificate overrides. Keys remain in server memory unless the user explicitly saves
automatic reconnect, which uses the same Windows DPAPI protection as account login.
The adapter uses only the official Network Integration GET routes for sites, adopted devices and
device details. The direct prefix is /proxy/network/integration; the Cloud Connector prefix is
/v1/connector/consoles/{console_id}/proxy/network/integration. Each prefix is followed by
/v1/sites, /v1/sites/{site}/devices, or /v1/sites/{site}/devices/{device}. It does not fall back
to another origin or route family. This API-key path is offered for UniFi OS and Cloud Connector;
the standalone controller adapter continues to use account login.
Site and device lists are consumed completely in pages of 200, up to 1,000 entries. Invalid,
duplicate or incomplete lists fail with api_response_incomplete. Matching requires a unique
literal switch IP in the selected site and consistent device ID, MAC and IP between the list and
detail response. A switch connected by hostname returns switch_identity_required; reconnect it
by IP to use this adapter. Matching controller metadata does not qualify a device for lighting.
The verified SSH hardware profile and output ownership checks remain independent.
Requests are limited to 40 per minute per adapter. HTTP 429 honors a bounded Retry-After, with
a 60-second default. Automatic retries preserve the selected connection and back off; stale
metadata is removed until a complete refresh succeeds. HTTP 401/403 requires user action.
New errors include invalid_auth_method, api_key_required, invalid_api_key, invalid_console_id,
invalid_cloud_origin, switch_identity_required, api_response_incomplete, and integration_unavailable.
Route and field contracts follow the official Network 10.6.106 OpenAPI schema and Site Manager connector schema. Cloud Connector requires a console firmware version supporting that API (documented as 5.0.3 or later). Use the installed Network application's Integrations documentation to verify its available endpoints.
{"api_key": "..."}Reads the consoles available to the entered Site Manager key without changing the current controller
connection. The response is {"consoles": [{"id": "opaque-console-id", "name": "Console name", "type": "ucore", "blocked": false}]}. Use the selected id as console_id on the normal connect
request. name uses a bounded reported display name when supplied, otherwise a short ID label;
it is never used for device matching. A blocked console should remain visible but unavailable for selection.
Only GET https://api.ui.com/v1/hosts?pageSize=100 and encoded continuation tokens are used. The
complete result is capped at 1,000 consoles over ten pages. Duplicate IDs, repeated tokens and
incomplete pages are rejected. HTTP 429 cooldown and a request budget survive subsequent discovery
requests, including a changed key. Discovery's key is cleared after its operation and is not saved.
The response excludes account details, addresses and raw controller data. Empty access returns
no_consoles; existing sanitized authentication, transport and pagination errors also apply.
Discards a pending controller connection or site choice and returns the full controller status.
The current working connection, telemetry and saved reconnect record remain unchanged. The
response has pending_site_choice: null. This request clears candidate credentials from EE
memory without making a controller request.
Takes no request body. Clears the in-memory controller credentials, cookies and cached names, then returns the disconnected status. The switch session and its lighting remain active. If automatic reconnect is enabled, explicit Disconnect pauses it for this runtime without deleting the saved login. Normal application shutdown also preserves the saved opt-in.
{"auto_reconnect": true}This endpoint accepts only a JSON boolean auto_reconnect and rejects unknown fields. Enabling requires a
currently authenticated, fresh controller session that successfully matched the connected real switch.
It saves that session's canonical HTTPS origin, controller type, selected site, approved certificate pin and
sign-in credentials (account login or API key, including the selected cloud console ID when applicable) under
current-user Windows DPAPI, using a separate atomic controller record. Verification codes and cookies are never
saved. An unprotected plaintext record is rejected. A save failure leaves the current connection and prior
saved record intact. Existing protected records without a controller type load as self_hosted without rewriting
the file. The response is the full controller status.
Disabling deletes the saved controller record and leaves the active connection running. A deletion failure
returns an error and retains the persisted setting. Enabling without a matched live session returns HTTP 409
controller_login_required. Storage errors return HTTP 500 with controller_login_save_failed or
controller_login_remove_failed; loading failures appear as saved_controller_login_unavailable in status.
Feature-detect preferences_supported before showing this setting. auto_reconnect is the persisted opt-in;
saved_login_available means its protected record was successfully loaded. can_save_login describes the
active session's eligibility. saved_login_matches_connection distinguishes the saved login from a different
active controller or credential set. When it is false and saving is eligible, offer an explicit Apply even
if the checkbox is already checked. A new manual connection never implicitly replaces saved credentials.
Account-based controller requests may include an operation with a controller_error (login, sites, devices, or clients). An unexpected upstream HTTP status is returned as upstream_status. Controller response bodies are private.
reconnect_state is off, waiting, connecting, retrying, connected, paused, or attention.
saved_login_error is null or a sanitized {code,message} object. No saved credential fields are returned.
saved_target is null without a readable saved login. Otherwise it contains only url, controller_kind,
auth_method and console_id. A disconnected form can restore these choices while waiting for the switch.
Only an active or pending controller session can reuse credentials during a manual connection.
After a live switch session is established, the protected controller login is restored automatically within
the next local lifecycle tick. No restore runs for a missing, disconnected, or simulated switch session.
The controller's usual TLS validation and approved pin comparison remain mandatory.
Transient reachability, busy-controller and controller-service failures get at most three additional attempts after 5, 15 and 60 seconds. Authentication, certificate, verification-code, site and switch-match errors stop automatic requests until an explicit user action. Normal successful topology refresh remains approximately 15 seconds. An in-flight bounded controller operation drains before shutdown clears its in-memory session.
{
"mode": "running",
"connected": true,
"error": null,
"switch": { "hostname": "USWProXG8PoE-SIM", "etherlight_mcu": true, "port_rgb": true },
"num_ports": 8,
"fps": 25.0,
"brightness": 100,
"dimming": "rgb",
"output": { "gamma": 2.2, "transition": 0.6, "max_commands": 200.0 },
"zones": [
{ "id": "all", "name": "All ports", "ports": [1, 2, 3, 4, 5, 6, 7, 8],
"effect": { "id": "static", "name": "Static", "params": { "color": "#ffffff" } } }
],
"rules": [
{ "id": "e00e3872", "name": "Anomaly", "enabled": true, "match": "all", "ports": null,
"conditions": [{ "field": "anomaly", "op": "is", "value": true }],
"look": { "color": "#ff9f0a", "style": "blink", "rate": 0.5, "brightness": null } },
{ "id": "0ee7bc65", "name": "Offline", "enabled": true, "match": "all", "ports": null,
"conditions": [{ "field": "link", "op": "is", "value": false }],
"look": { "color": "#ff0000", "style": "solid", "rate": 1.0, "brightness": null } }
],
"overrides": { "3": { "color": "#bf5af2", "brightness": null } },
"revision": 12,
"stats": { "frames": 1830, "commands": 2401, "commands_per_second": 27.4, "command_budget": 30.0,
"switch_cpu_idle": 0.62, "switch_load": 0.85, "last_write_ms": 61.2, "avg_write_ms": 64.4 }
}modeisrunning, orreleasedwhen the LEDs have been handed back to the switch.revisionincreases with every change.outputholds the advanced output settings (see Global controls).statsis for a diagnostics view.commands_per_secondis how many port commands EE is sending,command_budgetthe most it will send right now (lower thanmax_commandswhile the switch is busy), andswitch_cpu_idleandswitch_loadcome from the switch (nulluntil read).last_write_msandavg_write_msinclude the elapsed frame write and pacing time.direct_rgbidentifies the direct socket output path.ack_p95_msis the recent per-port acknowledgment latency, excluding pacing waits, ornullwithout fresh samples.cpu_sample_age_msis the age of the latest usable CPU sample, ornullwhen unknown.switch_healthholds the switch's memory, temperature and storage readings,health_sample_age_mstheir age andhealth_errorisnull,unavailableorinvalid_response.reconnect_requiredis true when an interrupted connection needsPOST /api/session/recoverbefore lighting resumes. It stays false while EE retries the connection and recovers the lighting on its own.hardware_profiledescribes the detected model and its physical port layout, ornull.- The state also carries
schedule_clock(WebSocket),identify(Port identification),telemetryandpoe_summary(Port telemetry),history_error(Lighting history),sfpandsfp_sync(SFP indicator lighting),uplink_bandwidth(UI flow),fans(Fans,nulluntil the session attaches fan control) andcontroller(UniFi Network controller).
One entry per LED port. WebSocket frames contain the same entries.
{
"port": 2,
"color": "#ffffff",
"output": { "color": "#ffffff", "level": 100 },
"preview": "#ffffff",
"source": { "kind": "zone", "id": "all", "name": "All ports" },
"override": null,
"link": { "port": 2, "admin_up": true, "link_up": true, "speed_mbps": 2500, "full_duplex": true,
"rx_packets": 1636, "tx_packets": 5086, "rx_bytes": 1473091, "tx_bytes": 4577516,
"uplink": false, "stp_state": "forwarding", "anomaly": "0x0", "lag": null },
"poe": { "port": 2, "enabled": true, "delivering": true, "pd_class": 4, "power_w": 12.31,
"voltage_v": 53.6, "current_ma": 229.59, "mode": "Dot3bt-Type4", "tier": "poe+" },
"facts": { "link": true, "speed": 2500.0, "full_duplex": true, "uplink": false, "anomaly": false,
"stp_state": "forwarding", "lag": false, "traffic": 0.0, "poe": "poe+", "poe_power": 12.31 },
"traffic_bps": 0
}coloris the color chosen for the port.previewapproximates how the LED looks at its brightness and is the value to use when drawing the port.display_rgbis the composed color scaled by its brightness as three numbers from 0 to 255, before the switch's transfer curve, for clients that draw with more precision.sourceis what set the color:{"kind": "zone", ...},{"kind": "rule", "id", "name"},{"kind": "override"}for a manual color, or{"kind": "none"}for a port that isn't in a zone.linkandpoearenulluntil the switch has reported them.poestaysnullon switches without PoE.factscontains the values rules are checked against, using the same field names as rule conditions.
Live Traffic (traffic) uses each port's negotiated link speed as its capacity with logarithmic response.
If an online port reports zero speed, capacity defaults to 1,000 Mbps. Older scenes containing max_mbps
or scale load normally; those retired values are omitted on save.
Activity Glow compares eligible device ports against the busiest device, with minimum_mbps setting the
traffic rate at which the busiest device first reaches full glow.
PoE Usage (poe_usage) blends low_color and high_color using delivered power, with the fixed Pro XG 8 PoE
per-port reference of 60 W: min(1, log1p(watts) / log1p(60)). no_power_color supplies the resting color
when power is zero or unavailable. Only a delivering PoE reading supplies a positive power value; an uplink
can still supply power. Every color supports the standard independent brightness and randomization controls.
speed is Fade speed, 0.1–5× (default 1). Changing the power reading eases both the color and the powered-state
blend using elapsed time, with a 0.6-second time constant at 1×. Zone-local port indices retain the physical
port's power reading, including reordered groups.
On a qualified switch, GET /api/state and WebSocket state/frame messages include sfp, separate from the
copper ports array. This example is the Pro XG 8 PoE; other models report their own indicator IDs:
[{"port":9,"mode":"color","color":"#2288ff","brightness":70,"link":false,"anomaly":false},
{"port":10,"mode":"unmanaged","color":"#ffffff","brightness":100,"link":null,"anomaly":null}]PUT /api/sfp/{port} accepts a nonempty subset of these settings and returns the full state:
| Field | Values |
|---|---|
mode |
color, off, unmanaged (Link status) |
effect |
steady, pulse, color_cycle, two_color |
color, secondary_color |
RGB color |
brightness, color_brightness, secondary_brightness |
Integer 0–100 |
period |
Cycle duration, 2–30 seconds |
Color mode runs the selected effect; Off holds black while retaining custom ownership. Link status applies the scoped status-controlled LED baseline after draining output. This is not a snapshot of the controller's previous color policy. Settings remain saved when changing modes. Each color's brightness is applied before blending; SFP brightness and master brightness multiply the result once. Link and anomaly facts stay independent.
When switch.sfp_native_gradient is true, Pulse and Two-color fade use finite native segments for periods
2, 4, and 6 seconds (one, two, or three seconds per leg). Color cycle uses six native segments for periods
6, 12, and 18 seconds. Existing custom periods remain saved exactly and retain their software playback.
Clients should offer native durations for new selections and retain an explicit Custom value for an existing
period. Feature-detect the capability and sfp[].playback before displaying native playback controls.
The next selector is prepared within two command intervals plus one render tick of the next boundary. Each target waits until its prior acknowledged start plus the nominal segment duration. This is a timing estimate, not hardware completion readback. The selector is restored to steady after enrollment, including interrupted preparation. Keepalive never restarts a finite segment. The existing adaptive command ceiling, acknowledgment checks, and CPU backoff apply to every selector and target request. Custom software effects retain the independent SFP sample clock of up to 50 Hz under that same command budget.
Each indicator includes playback: {kind, periods, segment_seconds}. Kind is native, custom, steady,
or follow; periods lists the selected effect's native cycle durations. segment_seconds is null for custom
and steady playback. native_transition, when present, contains duration, clamped elapsed, from_rgb16,
and to_rgb16. RGB16 values are in 0–65280. Interpolation is linear between the encoded endpoints; the native
preview must not apply the custom effect's cosine or hue easing. display_rgb is the modeled current output
with the transfer curve inverted, based on acknowledged segment start times. It is not physical LED readback.
Pulse alternates primary and black. Two-color fade alternates primary and secondary. Color cycle has six equally spaced HSV hue anchors starting at the primary hue, with saturation at least 75%. Per-color, SFP, and master brightness are applied once before encoding each anchor through the configured gamma. Each SFP target is separately acknowledged; grouped enrollment is scoped to the qualified indicators and does not imply atomic hardware updates. Unknown or ambiguous output is reported through the existing control status.
Each SFP entry also contains revision, acknowledged_revision, and
control: {state, owned, error}. Control state is idle, active, pending, or uncertain. A matching
acknowledged revision confirms the requested output reached the native writer. The endpoint waits up to five
seconds for that acknowledgment; a longer or released operation returns explicit pending state. A failed
transition returns HTTP 409. Clients should preserve pending state until the matching state/frame arrives.
Indicators start in unmanaged. Settings save with scenes and restore after restart; older scenes
without sfp restore unmanaged indicators. Copper group effects, rules, and manual-color clearing leave SFP
settings intact. An optical indicator can opt into a regular effect through explicit membership in
zones[].ports. Its effect_zone is the group ID while enrolled or null otherwise. While enrolled,
effective_settings is null. The group uses the indicator's own position and telemetry. Matching explicit
SFP rules still take priority, and its own SFP brightness scales the result. Its saved indicator mode,
colors, native effects and synchronization settings resume when the port leaves the group.
PUT /api/sfp/{port} accepts a brightness-only edit while the port belongs to an effect group. To change
its indicator appearance, remove the port from the group first or stage both changes in one scene.
Global release drains output, ends native Breathing, and releases owned SFP indicators.
An unsupported or unidentified model reports an empty sfp array and rejects SFP writes.
State, frames, scenes, and presets include sfp_sync: {"mode":"independent","source_port":1}.
PUT /api/sfp/sync accepts a nonempty subset of these two fields and returns the full state after waiting for
the indicators' existing output acknowledgments. The same pending and failure behavior described above applies.
At least two qualified indicators are required for synchronization. In Ethernet mode, source_port must be
a member of the current copper layout. Optical-only models offer Independent and Together.
Unknown fields and invalid values return HTTP 400 without changing the scene.
independent: each indicator uses its own saved SFP settings (the default for new and older scenes).together: all use the lowest-numbered qualified SFP port's settings. Native target timing shares a boundary plan while respecting each indicator's prior segment duration. An unusually late acknowledgment realigns the next pair instead of accumulating phase drift. Each indicator retains its own acknowledged start time for display. Editing the leader waits for the affected outputs. Other indicators' independent settings stay saved for when independent mode returns.ethernet: all track the selected copper port's final composed color and brightness, including manual colors and matching rules. With native support, each one-second boundary samples the current source target during preparation and fades toward it; intermediate source changes do not restart the segment. This is a color follower, not an exact phase copy of fast effects. Source brightness is used once before the SFP transfer curve; dormant independent SFP settings do not dim or mask it. Without native support the existing software follower remains in use.
Explicitly targeted SFP rules retain priority over synchronized output. In together mode, the leader's explicit Off
setting retains the existing Off policy for its group. In ethernet mode, dormant Off settings do not
suppress the source or its targeted SFP rules. Each SFP state entry has effective_settings: its active SFP
settings for independent/together mode, or null when following a copper port or running a group effect. Top-level per-indicator fields
remain the saved independent settings. Synchronization preserves the existing writer, pacing, CPU backoff,
ownership, and release behavior.
breathing.playback selects custom or synchronized. Existing scenes default to Custom. Synchronized
playback uses a fixed primary color with its independent brightness. Copper members require
switch.native_breathing and use the native selector. SFP members use the regular effect frame and
their existing per-indicator writer.
pace is 1 (about 3.08 seconds), 2 (2 seconds), or 3 (1 second). All synchronized groups share that pace;
changing it updates every synchronized group. Custom settings remain saved when changing playback.
Manual copper colors and matching rules take priority.
Lists every effect and its settings. The UI should generate effect controls from this list.
{
"id": "comet",
"name": "Comet",
"description": "A bright point with a fading tail that moves along the ports.",
"category": "animated",
"params": [
{ "key": "color", "label": "Color", "type": "color", "default": "#64d2ff", "random_param": "random_color", "brightness_param": "brightness_color" },
{ "key": "background", "label": "Background", "type": "color", "default": "#000000", "random_param": "random_background", "brightness_param": "brightness_background" },
{ "key": "speed", "label": "Speed", "type": "float", "default": 1.0, "min": 0.25, "max": 12, "step": 0.25,
"unit": "ports/s" },
{ "key": "tail", "label": "Tail", "type": "float", "default": 3.0, "min": 0.5, "max": 8, "step": 0.5, "unit": "ports" },
{ "key": "bounce", "label": "Bounce", "type": "bool", "default": false },
{ "key": "random_color", "label": "Randomize color", "type": "bool", "default": false, "randomizes": "color" },
{ "key": "random_background", "label": "Randomize background", "type": "bool", "default": false, "randomizes": "background" },
{ "key": "brightness_color", "label": "Color brightness", "type": "float", "default": 100.0, "min": 0.0, "max": 100.0, "step": 1.0, "unit": "%", "dims": "color" },
{ "key": "brightness_background", "label": "Background brightness", "type": "float", "default": 100.0, "min": 0.0, "max": 100.0, "step": 1.0, "unit": "%", "dims": "background" },
{ "key": "color_transition", "label": "Color transition", "type": "float", "default": 8.0,
"min": 1.0, "max": 30.0, "step": 0.5, "unit": "s" }
]
}| Param type | Control |
|---|---|
color |
Color picker |
float, int |
Slider from min to max in steps of step, with unit shown next to the value |
bool |
Toggle |
choice |
Segmented control or menu of choices |
category is static, animated, time (Daylight follows the clock) or data (Live Traffic, Traffic
Trails and Activity Glow use port traffic).
Every explicit color also names a brightness_param. Its numeric companion identifies the color through
dims, ranges from 0 to 100 percent and defaults to 100 for existing scenes. It scales that color once after
randomization and before effect blending. Master brightness and output gamma still apply to the composed frame.
Both independent color brightness and randomization are retained in saved scenes.
Live Traffic, Traffic Trails and Activity Glow accept include_uplinks (default false). Enable it to
include the measured rates of selected uplinks. Live Traffic's explicit custom uplink color still wins when
enabled. Activity Glow (activity_glow) compares known-online rates within its group. minimum_mbps sets the minimum scale, speed adjusts the attack and release, and active_color and
idle_color set its endpoints. Unknown, offline or invalid-rate ports contribute zero traffic.
Every explicit color setting includes a random_param naming its independent randomization toggle, such as
random_background. The companion boolean includes randomizes: "background". Fixed colors remain saved
while randomization is enabled; disabling it restores the chosen color. color_transition sets the time between
random color targets, from 1 to 30 seconds, independently of movement speed. Transitions follow an eased hue
curve rather than choosing a new color every frame.
For example, this Marquee configuration keeps the primary color fixed and changes the background color:
{"id": "marquee", "params": {"color": "#eab977", "background": "#000000", "random_background": true,
"color_transition": 8.0}}Effect metadata may include exclusive_params, a list of boolean pairs. Starry Night's per-sparkle colors and
Strobe's per-flash colors each exclude continuous primary-color randomization. A partial update enabling one
automatically disables its alternative; explicitly enabling both in one request is rejected. Background colors
remain independent. Scenes and presets retain all these settings.
A zone is a group of ports running one effect. The default zone contains the copper ports. An explicit zone can contain copper ports, qualified SFP indicators, or both.
GET /api/zones |
The zones, as in the state |
PUT /api/effect |
{"id": "rainbow", "params": {...}}: one effect on all copper ports and previously enrolled SFP indicators (replaces all zones) |
PUT /api/zones |
{"zones": [{"name": "Desk", "ports": [1,2,3,4], "effect": {"id": "fire", "params": {}}}, ...]} |
PUT /api/zones/{id}/effect |
{"id": "comet", "params": {...}}: change one zone's effect |
PATCH /api/zones/{id}/params |
{"params": {"speed": 1.25}}: change some settings and keep the rest |
A port can be in only one zone. Copper ports outside a zone stay off unless a rule or manual color sets them.
SFP indicators outside a zone use their indicator settings. Zone IDs are made from the name ("Desk" becomes "desk") unless an id is given.
Both effect-setting routes accept "clear_overrides": true. The effect is validated and applied together with
removal of manual colors on its target ports. Other groups keep their manual colors. Omit the flag to retain
manual colors. The UI uses this flag when selecting an effect. WebSocket set_effect accepts the same flag.
Changing speed through the parameter route preserves animation position.
Rules set a port's color when their conditions match. They are checked in order, and the first match is used. The default setup is a static white zone plus an Offline rule that turns ports without a link red.
GET /api/rules |
The rules, in order |
POST /api/rules |
Add a rule. "position": 0 puts it first; by default it goes last |
PATCH /api/rules/{id} |
Change part of a rule: {"enabled": false}, {"look": {...}}, ... |
PUT /api/rules/order |
{"ids": [...]}: set the order (every id exactly once) |
PUT /api/rules |
{"rules": [...]}: replace all rules |
DELETE /api/rules/{id} |
Delete a rule |
GET /api/rules/fields |
The fields conditions can use (below) |
GET /api/rules/templates |
Ready-made rules |
POST /api/rules answers 201 and PATCH 200 with the rule; PUT, PUT /api/rules/order and DELETE return all
rules.
A rule:
{
"name": "PoE++ devices",
"enabled": true,
"match": "all",
"ports": null,
"conditions": [{ "field": "poe", "op": "in", "value": ["poe++", "poe+++"] }],
"look": { "color": "#bf5af2", "style": "pulse", "rate": 0.25, "brightness": null }
}match:allconditions must be true, oranyof them. A rule without conditions always matches.ports: explicit lighting ports, ornullfor all copper ports. Verified SFP indicators can be targeted explicitly with[9],[10], or[9,10].look.style:solid,blink,pulse,flashoreffect.effectkeeps the zone's color and only appliesbrightness, for example to dim ports at night.look.rate: cycles per second, with a minimum of 0.05. Maximums are 0.33 for pulse, 1 for blink and 0.5 for flash. Defaults are 0.25 for pulse and 0.5 for blink/flash. Older saved rates are clamped to these ranges.look.brightness: 0-100 to override the global brightness on matching ports, ornull.
An explicit SFP rule uses that indicator's link, anomaly, spanning-tree and other available port facts.
The first matching rule takes priority over its saved color or effect. A rule temporarily takes over
Link status while its condition matches, then restores Link status when cleared, disabled or deleted.
Outside regular effect groups, Independent Off and together mode's shared Off remain off. effect preserves the current Color effect or
followed copper color, or the enrolled port's group effect. It leaves independent Link status under switch control. In independent/together mode,
the effective SFP brightness still multiplies the chosen rule or master brightness. Ethernet mode uses the
source's composed brightness unless the SFP rule overrides it. SFP state includes rule
(id and name, or null), preview, and facts for the UI; scenes store rule settings and base SFP
settings, not transient rule ownership.
{
"fields": [
{ "key": "link", "label": "Link up", "type": "bool", "operators": ["is"],
"description": "A device is connected and the link is up." },
{ "key": "speed", "label": "Link speed", "type": "number",
"operators": ["gt", "ge", "lt", "le", "eq", "ne", "between"], "unit": "Mbps" },
{ "key": "poe", "label": "PoE type", "type": "choice", "operators": ["is", "is_not", "in", "not_in"],
"choices": ["off", "poe", "poe+", "poe++", "poe+++"] },
{ "key": "time", "label": "Time of day", "type": "time", "operators": ["between"] }
],
"styles": ["solid", "blink", "pulse", "flash", "effect"]
}All fields: link, speed, full_duplex, uplink, anomaly, stp_state, lag, traffic (Mbps), poe,
poe_power (W), time and weekday. Condition values by type:
| Type | value |
|---|---|
bool |
true or false |
number |
a number, or [low, high] for between |
choice |
one of choices, or a list of them for in and not_in |
time |
["22:00", "07:00"]; if the end is before the start, the range crosses midnight |
weekday |
["sat", "sun"] |
A condition on a value the switch hasn't reported (for example PoE on a switch without PoE) never matches.
A manual color overrides zones and rules on that port until it is cleared.
PUT /api/ports/{port} |
{"color": "#ff00ff", "brightness": 60} (brightness is optional) |
PUT /api/ports |
{"ports": {"1": {"color": "#ff0000"}, "2": {"color": "#00ff00"}}} |
DELETE /api/ports/{port} |
Clear one port |
DELETE /api/ports |
Clear all ports |
The browser keeps picker and brightness edits local until Apply. The WebSocket set_port equivalent remains
available to API clients and applies immediately.
PUT /api/brightness |
{"value": 0-100} |
PUT /api/fps |
{"value": 1-30}: highest copper animation frame rate |
PUT /api/output |
{"gamma": 2.2, "transition": 0.6, "max_commands": 200}, any of them (advanced) |
POST /api/release |
Hand the LEDs back to the switch's own Etherlighting |
POST /api/resume |
Resume control of the LEDs |
PUT /api/output settings:
gamma(1-3): the LEDs' brightness curve. Effects and brightness are in perceived terms; 1 turns the correction off.transition(0-5 s): how long a port takes to fade to a new color when its effect, zone or rule changes. Manual colors always apply at once.max_commands(5-200): requested port-command ceiling. Output starts at at most 30 and increases only on the direct SSH socket path, with fresh CPU and response-time evidence. The shell fallback stays capped at 30.stats.command_budgetreports the current effective ceiling. An explicitly configured value of 30 remains 30.
Fan control is available on the USW-Pro-XG-8-PoE. EE saves the fan mode for each switch, keyed by the same switch
identity as the switch's saved lighting. A switch EE has not controlled before starts in switch. The chosen mode
runs on the switch from RAM (/tmp/ee-fan-control-v1), so it continues while EE is closed, after logout and after
Quit. The engine checks it every 5 seconds and starts it again after a switch restart, and at the next connection
after a handoff. In switch mode the check stops EE fan control that has no owner line (started by releases up to
0.5.1) or that was started from this PC's saved settings, and returns the fans to the switch's own controller. It
leaves other fan control alone; see hold. EE writes an owner line with each setting it sends (the second line of
the controller's config file); the value is saved with the switch's fan file on this PC and never appears in an API
response.
Needs a connected switch or the demo, and answers null until the session attaches fan control:
{
"supported": true,
"unsupported_reason": null,
"settings": {"mode": "curve", "curve": "medium", "manual_percent": 60, "target_celsius": 55},
"reading": {
"cpu_celsius": 62.3, "board_celsius": 56.0, "sfp_celsius": 57.8, "port_celsius": 80.1,
"fans": [{"rpm": 3020, "percent": 55}, {"rpm": 3050, "percent": 55}],
"daemon": "paused", "controller": "running", "script_current": true,
"reason": "curve", "config": "curve 45 30 60 50 70 75 80 100", "duty": 55
},
"error": null,
"settings_error": null,
"hold": null,
"curves": {"low": {"name": "Low", "points": [[55, 30], [70, 40], [80, 60], [90, 100]]}, "...": {}},
"limits": {"manual_percent": [30, 100], "target_celsius": [45, 85]}
}settingsis the mode saved for the connected switch. Withholdsettings_unreadableorsettings_newerit isswitch, which is not enforced.readingisnulluntil the first sample.port_celsiusis the hottest port chip.daemonis the switch's own fan controller:running,pausedorabsent.controlleris EE's:running,stoppedorabsent.configis the setting line of EE's controller, without the owner line.reasonnames what set the speed in the last step: the mode,guardwhen a sensor near the switch's limit raised the speed (CPU 85-95 °C, SFP 65-75 °C, port chips 100-110 °C), orfaultwhen a sensor could not be read and the fans ran at 100%. After six failed reads EE's control stops and the switch's controller resumes.erroris the last fan command error, or else the message of a setting the switch runs but EE could not save (fan_settings_save_failed), or elsenull.settings_errorsays why the saved fan mode is not in use, for example because the fan file for this switch could not be read or was saved by a newer version of EE. It stays until a change is saved.holdisnullwhen the check followssettings.other_installation: EE fan control with another owner line, for example from EE on another PC with release 0.6.0 or later, is running; EE reads it and leaves it running. Fan control without an owner line, as release 0.5.1 started it, never counts asother_installation.settings_unreadable: the fan file for this switch could not be read or created; EE does not change running fan control and only cleans up a stopped EE controller. A successfulPUT /api/fansclears either of these holds.settings_newer: the fan file for this switch was saved by a newer version of EE. The check behaves as withsettings_unreadable, butPUT /api/fansrefuses every change,switchincluded, so the hold stays until EE is updated; Handoff to UniFi still returns the fans to the switch's own controller.holdisnullwhen fan control is not supported.
Any of {"mode": "switch" | "curve" | "manual" | "target", "curve": "low" | "medium" | "high" | "max", "manual_percent": 30-100, "target_celsius": 45-85}. Missing fields keep their saved values. The response is the
GET /api/fans object after the switch confirms the change. The change is saved for the connected switch only. It
replaces EE fan control started from other settings, and switch stops any EE fan control.
An invalid value returns 400 invalid; a change the switch does not confirm returns 409 fans_unconfirmed and
keeps the previous settings, including an unreadable fan file and its hold. A model without fan control returns
400 invalid with the reason. So does any change, switch included, while the fan file for this switch was saved
by a newer version of EE (hold settings_newer); nothing is sent to the switch and the file is not overwritten. A
change that arrives while Handoff to UniFi stops fan control returns 409 fans_unconfirmed with the message "Fan
control is stopping for Handoff to UniFi.". When the switch runs the new setting but EE cannot write the fan file, the
response is 500 fan_settings_save_failed with the message "The switch runs the new fan setting, but EE could not
save it on this PC. Check the data folder and choose the setting again." The new setting stays in effect for the
session, and the same message stays in error until a later save succeeds.
curvesets the fan speed from the CPU temperature along the curve's points, interpolated, and slows down by at most 2% per 5-second step.manualruns both fans atmanual_percent.targetadjusts the speed to keep the CPU at or belowtarget_celsiuswith the lowest fan speed. A new target starts at the speed estimated to hold it, from the CPU reading and the average speed of the last couple of minutes, and corrects from there without running the fans far above that speed.- A new mode or setting takes effect within about a second and starts at its own speed; it does not ease from the previous mode's speed.
The same object is fans in GET /api/state and WebSocket state messages, and arrives every 5 seconds as a
fans WebSocket message.
Each switch's fan mode is saved in device-fans/<identity>.json in the data directory as
{"version": 1, "identity": "<64 hex>", "owner": "<48 hex>", "settings": {...}}. A file that holds no JSON object
is moved aside as <identity>.json.corrupt-<UTC time>. A file that cannot be read, or that has an invalid format
version, another identity, an invalid owner or invalid settings, sets hold to settings_unreadable and stays where
it is until the next successful PUT /api/fans replaces it. A file with a newer format version sets hold to
settings_newer and is never replaced. The demo keeps fans-demo.json.
Releases up to 0.5.1 saved one fan mode for every switch in fans.json. When no switch has a fan file yet, the first
USW-Pro-XG-8-PoE that EE connects to receives that mode. Saving it sends nothing to the switch, and the fan control
that 0.5.1 started there has no owner line, so EE adopts it. Because fans.sh changed after 0.5.1 (script_current
is false), the first check on that switch restarts fan control once with the same mode and adds the owner line;
while it restarts, the switch's own controller runs the fans. fans.json stays in place and is no longer read, so
release 0.5.1 still finds its own setting after a downgrade; it ignores device-fans/. When fans.json or
device-fans/ cannot be read, or the new file cannot be written, the switch gets hold settings_unreadable and
the next connection tries again.
A preset stores zones, rules, brightness and manual colors.
GET /api/presets |
{"Movie night": {...}, ...} |
POST /api/presets |
{"name": "Movie night"} creates a profile from the current setup; existing names return 409 |
POST /api/presets/{name}/apply |
Load a preset |
DELETE /api/presets/{name} |
Delete a preset |
POST /api/presets/{name}/duplicate |
{"name":"New name"} copies the saved snapshot without applying it |
POST /api/presets/{name}/rename |
{"name":"New name"} renames the saved snapshot without applying it |
Apply uses the same scene transaction as PUT /api/scene with confirm_output, and returns the state after
the switch acknowledges the SFP output. It returns 409 output_unconfirmed when that output is not confirmed,
and 503 offline_scene_unconfirmed when the lighting is applied in EE but the switch has not confirmed its offline
copy.
To save a preview without applying it, POST /api/presets accepts scene and
expected_revision alongside name. The revision must match the current scene
(409 scene_changed), and a scene without it returns 400 scene_revision_required;
the supplied scene uses the same topology, capability, and setting validation as
Apply. Saving leaves engine output and the current scene unchanged. This endpoint creates
profiles only and answers 201 with the preset mapping. An existing name returns
409 already_exists, including when an older client sends overwrite: true. Omitting scene saves the applied
setup.
Rename and duplicate return the updated preset mapping; duplicate answers 201. An existing target name returns
409 already_exists; a missing source returns 404 not_found; an invalid name returns 400 invalid. Names contain
1–64 letters, numbers, spaces, periods, underscores, or hyphens. A failed save preserves the original file and returns
409 profile_storage_unavailable. DELETE /api/presets/{name} returns 409 profile_in_use while enabled schedules
use the profile.
GET /api/profiles returns {"profiles":[{"id":"...","revision":1,"name":"Evening","scene":{...},"schedules":[]}]}.
The ID survives rename. Duplicate creates a different ID. schedules lists dependent schedule
IDs, names, and enabled states. Legacy name-to-scene storage migrates atomically before IDs are returned.
GET /api/presets retains its name-to-scene response for older clients.
PATCH /api/profiles/{id} requires expected_revision and one of these actions:
{"action":"replace","expected_revision":1}replaces this existing profile with the applied setup.{"action":"rename","name":"Night","expected_revision":1}changes its name.{"action":"duplicate","name":"Night copy","expected_revision":1}copies the saved setup to a new ID.{"action":"delete","expected_revision":1,"disable_schedules":true}deletes it and disables enabled dependent schedules.
The response is the updated /api/profiles envelope. A missing or changed identity returns
409 profile_changed, so a stale editor cannot recreate a renamed/deleted profile. Deleting a profile
with enabled dependent schedules requires disable_schedules: true; otherwise it returns
409 profile_in_use with the affected schedules. Existing name-based delete also rejects enabled
dependents. Profile mutations do not change live output. The browser validates saved topology before
Apply, while the engine remains authoritative.
GET /api/scene returns {"scene":{...},"revision":"..."}. The scene includes groups,
rules, individual port colors, brightness, and SFP settings. The revision hashes canonical
scene content and treats integral JSON numbers such as 6 and 6.0 equally.
Version 3 scenes include topology: {version: 1, model, copper_ports, sfp_ports}. The model is the detected
profile ID, or null for a simulator. Port lists must match the current layout before any scene state changes.
Version 2 scenes retain their original eight-copper-port interpretation. Version 1 scenes containing only
an all-port effect can migrate to the current copper layout; port-specific legacy scenes require their
original layout. A topology mismatch returns 400 and leaves the current scene unchanged.
PUT /api/scene accepts {"scene":{...},"expected_revision":"..."}. The revision must
match the current scene before the existing snapshot validator restores the requested
setup. A changed scene returns 409; invalid settings return 400. The response contains
the restored scene and its revision. This operation preserves release/resume mode.
Names are 1-64 characters: letters, digits, spaces, ., _ or -. The current setup is also saved
automatically and restored on the next login.
GET /api/schedules |
{"schedules": [...], "actions": [...], "history": [...]} |
POST /api/schedules |
Add a schedule |
PATCH /api/schedules/{id} |
Change part of a schedule |
DELETE /api/schedules/{id} |
Delete a schedule |
POST /api/schedules/{id}/run |
Run a schedule now; returns the history entry |
{
"id": "349952d5",
"name": "Evening",
"enabled": true,
"at": "19:00",
"days": ["mon", "tue", "wed", "thu", "fri"],
"action": { "type": "brightness", "value": 40 },
"next_run": "2026-10-29T19:00"
}Actions: {"type":"preset","profile_id":"..."}, {"type":"brightness","value":40},
{"type":"release"}, and {"type":"resume"}. A profile action accepts a legacy preset name at
creation, resolves it immediately to a stable ID, and returns its current name for display. Rename
and name reuse never retarget a bound schedule. On migration, unresolved legacy references are
disabled and assigned a missing ID for explicit review. Saving another profile with that name does
not reconnect the schedule.
Omitted days defaults to every day. An explicit empty list or null is rejected. Times are on the EE
computer in its local time zone. /api/schedules includes clock, history_available, and the last
100 persisted runs. Each schedule includes revision, last_run, needs_device_confirmation,
profile_missing, and conflicts. clock is null while no switch is connected. Save binds the schedule to the
connected switch and returns 409 not_logged_in without one; POST answers 201 with the schedule, and DELETE
returns the remaining schedules. Browser edits, Delete, and Run now send expected_revision; a changed schedule
returns 409 schedule_changed. Run now returns 409 schedule_confirmation_required for a schedule that has not been
applied for the connected switch. A schedule file that cannot be read or saved, or that a newer version of EE saved,
returns 409 schedule_storage_unavailable.
The service writes an occurrence claim before any scheduled mutation. Its key contains schedule ID, bound device, local calendar date, and minute. Restart during that minute cannot repeat it. Both folds of a repeated DST minute count once. A skipped local minute is not caught up. Competing actions run in saved list order, and the editor asks for confirmation before saving a same-minute conflict. Manual Run now records a separate trigger and does not consume a timed occurrence.
A run starts as pending. Production execution waits for the existing release cleanup or relevant SFP
output acknowledgments before reporting ok. Failure or interruption remains failed/unconfirmed.
On restart, an unfinished persisted run displays an unconfirmed result and is not replayed. If the
occurrence journal cannot be read or claimed, scheduled writes stop until its history can be verified.
POST /api/rules/test accepts {"port":1,"at":"2026-11-04T18:30","rules":[...]}.
at is an optional local date/time on the EE computer; offsets are rejected. The endpoint parses the
supplied rule order and evaluates the engine's current port facts without writing a scene or lighting.
The response lists each condition's actual value and pass result, rule scope/enabled state, the first
matching rule, the effective source (including individual-color precedence), current output mode,
and the evaluated scene revision. Optical rules use the same explicit scope and native-setting
eligibility as the engine. Changing the supplied order tests priority without saving it.
GET /api/library/{kind} returns {"items":[...]} for kind equal to effect or selection.
Each item contains id, revision, kind, name, binding (an opaque switch scope for selections, null for
effect settings) and value. Effect settings are shared across switches.
Selections are bound to the connected switch and retain its port topology.
POST /api/library/{kind} creates an item with {"name":"...","value":{...}}.
An effect value is {"id":"activity_glow","params":{...}} and uses the existing effect validator.
A selection value is {"ports":[1,3,9]} and must use available ports. The stored selection also includes
its topology. Neither operation changes a lighting scene or selection in another client.
PUT /api/library/{kind}/{id} replaces or renames an item with name, value, and
expected_revision. DELETE on the same path requires {"expected_revision":"..."} and returns
{"deleted": true}. POST answers 201 and PUT 200 with the saved item.
Missing, changed, or out-of-scope items and a name already used in one kind/scope return 409 library_changed.
The host bounds the library to 256 items and preserves unreadable storage for review.
Recalling an effect creates a local lighting preview. Recalling a selection only selects ports.
These refusals carry only message: 404 for another kind, 400 for an invalid name or value or a full library,
and 503 when the library file cannot be read or saved.
POST /api/identify accepts {"port": 3} and starts a ten-second identification on one qualified
lighting port. It returns id, port, and seconds_remaining. Send that exact ID with
DELETE /api/identify, for example {"id": "<returned-id>"}, to stop early. A stale ID cannot stop a
newer identification. An overlapping start is rejected until the current identification finishes. port is a JSON
integer from 1 to 128 and id a 32-character string; other fields return 422. DELETE returns
{"identify": <the current identification or null>}.
Identification requires a connected, running output session owned by EE. The host owns the timer. The temporary white/blue indicator does not alter the scene or its revision. Expiry and Stop resume the current rules, effects, colors, and brightness, including changes applied during identification. Release, disconnect, and shutdown cancel the temporary intent. SFP identification uses the existing qualified optical output and release paths. An SFP following an identified Ethernet port continues showing the Ethernet port's underlying lighting.
State and frame messages contain identify, either null or the same active identification object.
The command response records accepted intent. Existing port output and SFP control fields continue
to report the displayed and acknowledged output state.
GET /api/history returns entries, limit, and error. Entries contain an opaque id, a UTC ISO
at timestamp, the scene revision, and the saved scene. Newest entries come first. History retains
up to 50 distinct successive scenes for the connected device and 250 entries across stored devices.
Identical successive scenes are deduplicated. Scene changes made by schedules and other clients are
included. Temporary identification and telemetry are excluded.
POST /api/history/{id}/restore requires {"expected_revision": "<current-scene-revision>"}. Read
GET /api/scene when opening the review and retain that revision through confirmation. Restore uses
the normal scene transaction, topology validation, revision guard, and SFP output confirmation.
An intervening edit returns scene_changed without replacing it. A successful restore creates a new
history entry so the replaced scene remains available.
History is scoped to the existing stable device binding, with a separate demo scope. A missing or
invalid history store returns history_unavailable; the original file remains in place. A save
failure is also exposed as history_error in state and frame messages and error in the history
response. It does not roll back an already applied lighting change.
State and frame messages contain telemetry with generation, sequence, sampled_at,
sample_age_ms, and stale. A sequence advances once per collected link sample, independently of
frame delivery. The opaque generation changes after reconnection. Use both fields to deduplicate
samples and begin a new event/trend window after a monitoring interruption. sampled_at is an ISO
host timestamp with its UTC offset. Clients also expire readings when incoming samples stop.
Per-port traffic_bps is combined receive plus transmit bits per second. Its corresponding
facts.traffic is Mbps. Missing samples, the first counter observation, and counter resets produce
null; two valid unchanged counter samples produce zero. These fields do not split upload and
download. The separate uplink bandwidth object retains its directional measurements.
The poe_summary object provides the reported switch-wide budget_w, measured draw_w,
headroom_w, complete, sample_age_ms, and consumers. Consumers contain port and power_w,
sorted by draw. All power values are watts. The budget comes from the parsed switch response.
| Status | Meaning |
|---|---|
ready |
Fresh complete table and reported budget; headroom is budget minus measured draw |
partial |
Some expected copper-port measurements are missing or malformed |
stale |
The sample aged out or the connection was interrupted |
budget_unavailable |
Complete fresh measurements without a reported total budget |
unavailable |
No parsed PoE measurements |
Only ready supplies a numeric headroom. A partial draw is the measured subset and must be labeled
as such. Negative headroom is retained if the measured draw exceeds the reported budget. The current
adapter requires a valid measurement row for every copper port before declaring a complete sample.
It uses the existing telemetry collection interval and adds no switch polling.
GET /api/effects |
Effects and their settings |
GET /api/rules/fields |
Rule fields, operators and styles |
GET /api/rules/templates |
Ready-made rules |
GET /api/colors |
Named colors ({"white": "#ffffff", ...}) for swatches |
GET /api/about |
Name, version and disclaimer (GET /api/about) |
GET /api/health |
Service status (GET /api/health) |
These endpoints work without logging in.
When an API token is configured, clients authenticate with an Authorization: Bearer <token> header. A missing
or wrong header closes the socket with code 4401. The token is not accepted as a query parameter, so it never
appears in URLs or access logs. The web gateway supplies the header for REST edits and WebSocket telemetry. The
engine closes a socket from another website's page with code 4403, and the local gateway drops an upgrade that fails
its Host and Origin checks or that is not exactly /api/ws.
Writable sockets are bound to the switch session present when the socket opens.
After login or session replacement, reopen the socket before sending changes.
A stale target returns workspace_changed. Optional X-EE-Workspace handshake
and workspace_id message values must match the original bound target; they do
not retarget an existing socket. Ping and session telemetry remain available. A command while no switch is connected
or a handoff is pending returns not_logged_in.
State and frame payloads include schedule_clock with local_iso (an ISO local
timestamp with UTC offset) and zone_name (the host OS display name). Use this
clock for schedule and Daylight previews. Re-anchor to each received sample;
zone_name is not an IANA timezone identifier. Clock metadata is not saved in
scene or profile snapshots.
Messages from the server:
type |
|
|---|---|
session |
{"type": "session", "session": {...}} on connect, and on every login, logout or connection change |
state |
{"type": "state", "state": {...}} on connect, and after every change from any client |
frame |
{"type": "frame", "mode": "running", "connected": true, "ports": [...], "sfp": [...], ...} every frame |
fans |
{"type": "fans", "fans": {...}} every 5 seconds, every 1.5 seconds for 30 seconds after a fan change, and after each change; see Fans |
ack |
{"type": "ack", "id": 7} when a message with an id has been applied |
pong |
{"type": "pong", "id": 7}, the reply to ping |
error |
{"type": "error", "id": 7, "code": "invalid", "message": "..."} |
The engine sends frames at its frame rate (fps in the state, 25 by default, set with PUT /api/fps), at up to 50
per second while SFP indicators animate, and soon after each change, at most 30 per second unless the frame rate is
higher. A frame carries mode, connected, error, reconnect_required, stats, ports, sfp, sfp_sync,
uplink_bandwidth, schedule_clock, identify, telemetry, poe_summary, history_error and controller, as in
the state. error codes are invalid (also for a message that is not an
object), not_logged_in, workspace_changed, not_found and output_unconfirmed.
Messages to the server (add an id to any of them to get an ack or error back):
{ "type": "set_port", "port": 3, "color": "#bf5af2", "brightness": 80 }
{ "type": "set_ports", "ports": { "1": { "color": "#ff0000" }, "2": { "color": "#00ff00" } } }
{ "type": "clear_port", "port": 3 }
{ "type": "clear_port" }
{ "type": "set_effect", "id": "rainbow", "params": { "speed": 0.5 }, "zone": "desk" }
{ "type": "set_params", "params": { "speed": 0.8 }, "zone": "desk" }
{ "type": "update_rule", "id": "0ee7bc65", "changes": { "look": { "color": "#ff375f" } } }
{ "type": "set_brightness", "value": 40 }
{ "type": "release" }
{ "type": "resume" }
{ "type": "ping" }A message with any other type gets an error with code invalid. Every command is available to devices on
Tailscale and the LAN. An action that must stay on the host computer needs a REST route. A release is acknowledged
after the switch has taken the released output.
zone is optional; without it the first zone is used. clear_port without a port clears all ports. Mutation
messages apply immediately; the browser sends lighting changes only after Apply. Actual switch writes follow
the configured output settings and adaptive command budget. If a client reads slowly, it gets the newest state,
frame and fan reading and skips older ones; acks and errors are never dropped.
These only work after a demo login.
PUT /api/simulator/links/{port} |
{"up": false} unplugs a cable, {"up": true} plugs it back in |
PUT /api/simulator/anomaly/{port} |
{"code": 4} raises an anomaly, {"code": 0} clears it |
PUT /api/simulator/poe/{port} |
{"class": 4} connects a PoE device of that class, {"class": null} removes it |
Each returns its port and new value, for example {"port": 3, "up": false}, {"port": 3, "code": "0x4"} or
{"port": 2, "class": 4}. class is 0 to 8, and a port without PoE returns 400 invalid. Without a demo login the
answer is 409 not_simulated.
The simulator starts with all 8 ports linked at mixed speeds, port 5 as the uplink, and PoE devices on ports 2 (class 4, PoE+), 4 (class 3, PoE), 6 (class 6, PoE++) and 7 (class 8, PoE+++). Link changes appear within about a second.
GET /api/port-names returns {revision, use_unifi, names} for the authenticated switch identity.
names maps physical port numbers (string keys) to saved manual display names. The default use_unifi is true.
PUT /api/port-names accepts {expected_revision, use_unifi, names}. Each supplied name updates that port;
an empty value clears it. Other port names are retained. Names accept up to 64 characters on one line.
The current revision is required; concurrent edits return 409 port_names_changed and require reloading. Send
X-EE-Workspace to guard against a switch change. Storage failures, and names saved by a newer version of EE, return
503 port_names_unavailable without accepting an in-memory-only edit. An invalid name returns 400 with only
message.
Port details → Edit names opens the naming editor. Manual names are saved per switch on the host, shared with other workspace clients, and retained when UniFi naming is selected. Clearing a manual name displays the physical port number. With UniFi naming selected, configured port names take priority, followed by the existing connected-device names. Existing controller refreshes update automatic names.
Port arrays from REST and WebSocket frames include name_mode (manual or unifi) and display_name
(a resolved custom name or null). Controller metadata retains client information and adds port_name
when a configured name is reported. Naming preferences have their own atomic storage and revision;
they do not change the lighting scene or send switch/controller configuration commands.