WattBox PDU (SnapAV)

The WattBox driver controls SnapAV WattBox power distribution units over their local HTTP API on the customer LAN. It turns each switched outlet into a controllable zone — on, off, and reboot (power-cycle) — and polls the unit a few times a second for outlet state, whole-unit voltage/current/power, and (on UPS-equipped models) battery telemetry.

WattBox ships two very different firmware generations, and the driver auto-detects which one it is talking to on the first poll, so you do not pick a mode:

• Legacy IP-300 series — speaks XML at /wattbox_info.xml for status and /control.cgi for switching, using HTTP Basic authentication. This firmware mis-frames its chunked HTTP responses (framing that standard HTTP clients reject outright), so the driver fetches legacy endpoints with a tolerant raw HTTP reader — handled automatically, nothing to configure.
• OvrC Embedded Server (e.g. the WB-800-IPVM-12 and similar newer units) — has no XML status endpoint, so the driver reads the unit's web dashboard at /main and switches outlets at /outlet/{on,off}, using HTTP Digest authentication.

Detection re-runs every time the device connects, so a firmware upgrade or a swapped unit is picked up automatically.

Prerequisites

• A WattBox on the same LAN as the GEM controller, reachable over HTTP. The IP-300 series and newer ship with the local HTTP API enabled by default.
• The unit's web-UI username and password. WattBox ships with wattbox / wattbox — change these on the device and use the new credentials here.
• A static IP (or DHCP reservation) for the WattBox, so the address GEM polls does not move.

Setup

1. Assign a static IP to the WattBox (or reserve its DHCP lease), and confirm you can reach its web UI in a browser.
2. Create the device under System → Devices (Open Devices) with driver wattbox. Set:
   • WattBox IP (ip) — the unit's address, e.g. 192.168.1.124. You may include a port (192.168.1.124:8080) if the unit serves its web UI somewhere other than port 80.
   • Username (username) — defaults to wattbox.
   • Password (password) — stored encrypted.
   • (optional) Status Poll Rate (ms) (poll_rate) — how often the unit is polled for outlet/voltage telemetry. Default 3000 (3 seconds).
3. Save. On the first successful poll the driver discovers the outlets and auto-creates one zone per outlet in the Power subsystem (see below). No manual zone setup is needed for normal control.
4. Verify from the Script Console:

   await gem.command({device_id: <device_id>, command: 'get_status'});

   After a poll cycle the device picks up its telemetry attributes and the outlet zones appear under System → Zones in the Power subsystem.

tip

The DeviceCreator form shows a short inline quick-start for the driver and a View integration guide toggle that opens this page. If the toggle is missing, the driver name on the device does not match wattbox.

How outlets become zones

On the first poll after each connect, the driver reads the outlet list (states and names) straight from the WattBox and creates a zone for every outlet it finds:

• The zones land in the Power subsystem (one of the default subsystems; the driver recreates it if it has been deleted).
• Each zone's address is the 1-based outlet number — outlet 1 is address 1, matching the physical labeling on the WattBox (there is no outlet 0).
• The zone's label comes from the outlet name configured on the WattBox. If an outlet still has a generic name (Outlet 3), the zone is labeled Outlet 3; once you name the outlet on the WattBox, that name is used.
• Each zone is created with the power_default control, so it renders as a simple on/off control on UIs and reports its current state (on / off).

Discovery runs once per connection. Renaming an outlet on the WattBox after the zones already exist does not rename an existing zone — edit the zone label under System → Zones if you want it to follow.

Device attributes

You enter the connection attributes; everything else is read from the unit each poll and is read-only. Which telemetry appears depends on the firmware generation and whether the unit has a UPS battery.

Attribute	Type	Notes
ip	string	Required. WattBox IP, optionally host:port.
username	string	Required. Web-UI username (default wattbox).
password	string	Required, stored encrypted.
poll_rate	int (ms)	Status poll interval. Default 3000.
host_name	string	Unit's host / system name.
hardware_version	string	Hardware revision (legacy) / model (OvrC).
serial_number	string	Serial / service tag.
firmware_version	string	Firmware version (OvrC firmware only).
mac_address	string	MAC address (OvrC firmware only).
voltage_value	number (V)	Whole-unit input voltage.
current_value	number (A)	Whole-unit current draw.
power_value	number (W)	Whole-unit power draw.
outlet_<n>_state	string	Per-outlet on / off (mirrors the outlet zone's state).
outlet_<n>_power_w	number (W)	Per-outlet power (OvrC firmware only).
outlet_<n>_current_a	number (A)	Per-outlet current (OvrC firmware only).
hasUPS	int	1 when a UPS battery module is present.
battery_charge	int (%)	Battery charge level (UPS units).
est_run_time	int (min)	Estimated battery runtime (UPS units).
battery_load	int (%)	Battery load (UPS units).
auto_reboot	int / string	Auto-reboot feature state.

Legacy IP-300 firmware additionally reports safe_voltage_status, cloud_status, audible_alarm, battery_test, battery_health, power_lost, and mute when the unit exposes them. Per-outlet wattage and amperage (outlet_<n>_power_w / outlet_<n>_current_a) come from OvrC firmware only — legacy units report whole-unit power but not per-outlet metering.

Legacy units are normalized to real units

Legacy firmware puts voltage and current on the wire in tenths (1200 = 120.0 V, 4 = 0.4 A; power is already whole watts). The driver divides these by 10 so voltage_value / current_value / power_value read in real volts, amps, and watts on both firmware generations. If you built a trigger or dashboard against the old raw tenths values on a legacy unit, update it once after upgrading.

Zone attributes

Attribute	Type	Notes
address	string	Required. 1-based outlet number. Auto-set on discovery.
state	string	on / off, refreshed every poll.

Commands

getCommands() declares the following. The standard on/off verbs map to the matching commands, so an on/off control on an outlet zone works with no extra configuration; the named commands are there for macros and triggers.

Command	Aliases	Effect
on	power_on	Turn the outlet on. address = outlet number.
off	power_off	Turn the outlet off. address = outlet number.
reboot	—	Power-cycle the outlet: off → wait → on. address = outlet number; optional delay (ms).
get_status	—	Poll the unit now and refresh all attributes. Takes no arguments.

The outlet commands take address = the outlet number; on a UI they bind to [@zone.address], so a zone picker is offered when you build a command.

Reboot is an off→delay→on power-cycle

reboot is performed by the driver as off, wait, then on — it does not rely on a device-side reset (the legacy unit's built-in reset only works when the outlet is already on, and behaves inconsistently). The wait defaults to 5000 ms (5 s). If a load needs longer to power down cleanly before it comes back, pass a longer delay:

await gem.command({device_id: <id>, command: 'reboot', args: {address: '4', delay: 12000}});

Automation ideas

• Scheduled reboot of a stuck device. A macro schedule firing reboot on the outlet feeding a flaky modem, AP, or media player overnight clears a lockup before anyone notices.
• Recovery trigger. Pair a device-offline condition with a reboot of that device's outlet to auto-power-cycle gear that has hung, with a guard so it doesn't loop.
• Power telemetry. power_value (and per-outlet outlet_<n>_power_w on OvrC units) charts draw over time; trigger on an unexpected drop to zero to catch a tripped breaker or a load that died.
• UPS-aware shutdown. On battery-equipped units, trigger on est_run_time dropping below a threshold (or battery_charge going low) to shed non-critical outlets before the battery is exhausted.

Troubleshooting

Symptom	What to check
401 / "Unauthorized" on every request	Verify the username and password by logging into the WattBox web UI directly. OvrC-firmware units require HTTP Digest rather than Basic — the driver auto-detects this, so a persistent 401 almost always means wrong credentials or an unreachable address.
"could not detect api mode" in the logs	The driver tried the legacy XML endpoint and the OvrC dashboard and got neither. Confirm the configured IP/port serves the WattBox web UI directly (not a captive portal or a redirect), and that nothing is blocking HTTP between GEM and the unit.
Legacy unit reachable in a browser, but logs show Parse Error: Invalid character in chunk size	Legacy firmware's malformed chunked framing being rejected by an older GEM build. Current GEM reads legacy endpoints with a tolerant raw HTTP reader — update GEM.
Outlet states or telemetry stuck on an OvrC unit	OvrC firmware has no status API, so the driver reads the dashboard markup; a firmware update can change that markup. The driver re-detects when a poll returns garbage — if it stays stuck after a firmware change, capture the unit's /main page and report it.
reboot leaves the outlet off	The 5 s default delay was too short for that load to settle — pass a larger delay (ms) as shown above.
Outlet flips back unexpectedly	If the WattBox is also cloud-managed through OvrC, a concurrent OvrC command can race GEM's. Decide on one controller for switching, or expect occasional fights over outlet state.

Related

• Devices — adding and configuring the WattBox device.
• Zones — the auto-created outlet zones and their labels.
• Subsystems — the Power subsystem the outlets land in.
• Commands — how the on/off/reboot verbs are dispatched.
• Triggers and Macros — building the automation ideas above.
• CyberPower UPS — the other PDU/UPS power driver, over SNMP.