<!-- Markdown copy of https://freshavlabs.com/docs/wattbox/ -->

PLUGIN MANUAL / v2.1.0

# WattBox IP Control

Q-SYS user plugin for SnapAV WattBox IP power controllers. Per-outlet switching and metering, UPS telemetry, auto-reboot configuration, and faceplate control over the WattBox Integration Protocol.

## Introduction

WattBox IP Control connects a Q-SYS Core to a SnapAV WattBox IP power controller over TCP, using the WattBox Integration Protocol. It switches and resets outlets, reads power and UPS values, and sets the WattBox's auto reboot. Every control on its panel is also a pin.

The `Model` property sizes the plugin, from one outlet on a WB-150 to 24 outlets on a Custom model.

Per-Outlet Control

On, Off, Toggle and a timed Reset for each outlet, with its state and its name.

Power Readings

System power, current and voltage, a safe-voltage check, and per-outlet readings.

UPS Status

Charge, load, runtime, health and power-lost state of a UPS on the WattBox.

Auto Reboot

Set the WattBox's own auto reboot timing from Q-SYS.

## Requirements

| Component      | Requirement                                                                                                                             |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Q-SYS Designer | Tested with Q-SYS Designer 10.4                                                                                                         |
| WattBox        | A model listed under `Model` in [Plugin Properties](https://freshavlabs.com/docs/wattbox/#properties), or Custom with 1 to 24 outlets   |
| Network        | A TCP path from the Core to the WattBox on `Port`, default 23. See [Connection Setup](https://freshavlabs.com/docs/wattbox/#connection) |
| License        | One activation code per Core. See [Licensing](https://freshavlabs.com/docs/wattbox/#licensing)                                          |

## Installation

The WattBox IP Control package contains one plugin file:

| File                        | Purpose                | License  |
| --------------------------- | ---------------------- | -------- |
| `WattBox_IP_Control.qplugx` | The WattBox controller | Licensed |

Step 1. Copy the plugin files

Copy each `.qplugx` file into `Documents\QSC\Q-Sys Designer\Plugins\`. A subfolder works; Designer scans the folder recursively. Double-clicking a file also installs it, into the Plugins folder itself. The plugin appears in Schematic Elements under Plugins, Fresh AV Labs.

Step 2. Add it to the design

Drag the plugin from Schematic Elements into the design.

Updating

Every release uses the same filename. Copy the new file over the old one. When you open the design, Designer offers the newer version, and the plugin's settings survive the update.

## Quick Start

Step 1. Set the model

Add WattBox IP Control to the design and select the block. Set `Model` to the WattBox model. For a model not in the list, set `Model` to Custom and set `Custom_Outlet_Count`. The Outlets page shows one card per outlet.

Step 2. Push the design

Push the design to the Core. The LICENSE box counts down, or reads `ACTIVATED`. Without a code the plugin runs a 10-minute demo, see [Licensing](https://freshavlabs.com/docs/wattbox/#licensing). The status bar shows `Fault - Missing: IP Address, Username, Password`.

Step 3. Enter the connection details

On the Status page, in the CONNECTION card, enter `IP Address`, `Username` and `Password`. Leave `Port` at 23 unless the WattBox uses another port. The status bar shows `Initializing - Connecting...`, then `Initializing - Authenticating...`.

Step 4. Confirm the connection

Look at the header and the SYSTEM INFO card. The `Connected` LED lights and the status bar reads `OK`. SYSTEM INFO shows the hostname, model, firmware and service tag.

Step 5. Check the outlets

Open the Outlets page. The `Status` LED on each outlet card is lit when that outlet is on.

The most common support call is a WattBox with its IP control (Telnet) service turned off, see [Connection Setup](https://freshavlabs.com/docs/wattbox/#connection).

## Plugin Properties

The connection details are controls on the Status page, not properties, see [Connection Setup](https://freshavlabs.com/docs/wattbox/#connection).

| Property                 | Range / Choices                                                                                                                                                             | Default        | Description                                                                                                                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Activation_Code`        | Text                                                                                                                                                                        | *blank*        | The activation code for this Core's Locking ID. Leave blank to run the demo. See [Licensing](https://freshavlabs.com/docs/wattbox/#licensing).                            |
| `Activation_Code_Backup` | Text                                                                                                                                                                        | *blank*        | The code for the other Core of a redundant pair. Leave blank on a single Core.                                                                                            |
| `Show_Locking_ID`        | No / Yes                                                                                                                                                                    | No             | When Yes, shows the LOCKING ID box in the header and gives its pin the `License~Locking ID` name. See [Control Pins](https://freshavlabs.com/docs/wattbox/#control-pins). |
| `Model`                  | WB-150-IPW-1 (1 outlet), WB-250-IPW-2 (2), WB-300-IP-3 (3), WB-700-IPV-12 (12), WB-800-IPVM-6 (6), WB-800-IPVM-12 (12), WB-800-IPVM-18 (18), Custom (`Custom_Outlet_Count`) | WB-800-IPVM-12 | Sets the outlet count of the panel and the pins. The count for each model is beside its name.                                                                             |
| `Custom_Outlet_Count`    | 1 - 24                                                                                                                                                                      | 12             | Shown when `Model` is Custom. The outlet count of the Custom model.                                                                                                       |
| `Poll_Rate`              | 1 - 60                                                                                                                                                                      | 15             | Seconds between polls. Each poll sends the next step of a six-step cycle, see [How It Works](https://freshavlabs.com/docs/wattbox/#how-it-works).                         |
| `Debug_Level`            | Standard / Verbose                                                                                                                                                          | Standard       | Verbose adds each command sent and each block of data received to the plugin's debug window. The plugin does not write the password there.                                |

## Connection Setup

The plugin opens a TCP connection to the WattBox and logs in with `Username` and `Password`. The WattBox's IP control (Telnet) service must be on. That is a setting on the WattBox, not in the plugin.

| Control      | Range | Default | Description                                                                        |
| ------------ | ----- | ------- | ---------------------------------------------------------------------------------- |
| `IP Address` | Text  | blank   | The WattBox's IP address.                                                          |
| `Port`       | Text  | `23`    | The WattBox's integration protocol port. Text that is not a number connects to 23. |
| `Username`   | Text  | blank   | The login username.                                                                |
| `Password`   | Text  | blank   | The login password. The field shows `******` after you enter it.                   |

The plugin keeps the password you entered and logs in with it, while the field shows `******`. To change the password, type the new one over the mask. To clear it, clear the field. Entering `******` itself leaves the kept password unchanged.

Two settings limit access to the credential this plugin stores:

* In Core Manager, under Access Management, turn on Access Control.
* If no external control system reads or drives this block, set its Script Access to Script.

### Connection behavior

* **Start.** One second after the design starts, the plugin connects if all four fields are filled.
* **Field changes.** While the plugin is not logged in, it connects as soon as all four fields are filled.
* **Retry.** After a closed connection, an error, a failed connect or a login timeout, the plugin tries again every 10 seconds.
* **Login timeout.** If the login does not complete 15 seconds after the connection opens, the plugin retries.
* **Login failure.** When the WattBox rejects the login, retries stop. Correct `Username` or `Password`, or press `Connect`, to try again.
* **Disconnect.** `Disconnect` closes the connection and stops retries until you press `Connect`.

### Connection status

The status bar under the header shows a state and a message. Q-SYS puts the state word in front of the message, so the bar reads, for example, `Fault - Login Failed - Check Credentials`. At demo expiry it shows the expiry message instead, see [License status](https://freshavlabs.com/docs/wattbox/#license-status).

| State        | Message                            | Cause                                                                                                                           | Remedy                             |
| ------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| Initializing | (none)                             | The design is starting.                                                                                                         | None.                              |
| Fault        | `Missing: <fields>`                | A connect was attempted with a field empty. `<fields>` names each empty one, in the order IP Address, Port, Username, Password. | Fill the named fields.             |
| Initializing | `Connecting...`                    | The connection is opening.                                                                                                      | None.                              |
| Fault        | `Connect failed: <error>`          | The connection could not start. `Reconnecting in 10s...` normally replaces it.                                                  | Check `IP Address` and `Port`.     |
| Initializing | `Authenticating...`                | The connection is open and the plugin is logging in.                                                                            | None.                              |
| OK           | (none)                             | Logged in.                                                                                                                      | None.                              |
| Fault        | `Login Failed - Check Credentials` | The WattBox rejected the login. Retries stop.                                                                                   | Correct `Username` or `Password`.  |
| Fault        | `Login timeout - retrying`         | The login did not complete in 15 seconds. `Reconnecting in 10s...` normally replaces it.                                        | None. The plugin retries.          |
| Initializing | `Reconnecting in 10s...`           | The plugin is waiting to retry.                                                                                                 | None.                              |
| Initializing | `Reconnecting...`                  | The connection dropped and is reopening.                                                                                        | None.                              |
| Fault        | `Connection Closed`                | The connection closed. `Reconnecting in 10s...` normally replaces it.                                                           | Check the WattBox and the network. |
| Fault        | `Error: <error>`                   | The connection reported an error. `Reconnecting in 10s...` normally replaces it.                                                | Check the WattBox and the network. |
| Fault        | `Disconnected`                     | `Disconnect` was pressed. Retries stop.                                                                                         | Press `Connect`.                   |
| Initializing | `Rebooting device...`              | `Reboot WattBox` was pressed. See [System card](https://freshavlabs.com/docs/wattbox/#system-card).                             | None. The plugin reconnects.       |

## Licensing

The plugin reads `Activation_Code` and `Activation_Code_Backup` when the design starts.

Three license states

1. **Blank.** The plugin runs a 10-minute demo with every function. The LICENSE box counts down. Restart the design to start another demo.
2. **Valid code.** The LICENSE box reads `ACTIVATED`. There is no time limit.
3. **Wrong code.** The plugin runs the same demo and the LICENSE box reads `DEMO (invalid code): M:SS remaining`, so a mistyped code is visible. Correct or clear the code before the demo ends.

### What demo expiry stops

The licensed product is the connection to the WattBox. At expiry the plugin closes the connection, stops polling and stops retrying, and the `Connected` LED goes off. `Connect` greys out, and so does every button and setting on the Outlets page and on the GLOBAL, AUTO REBOOT and SYSTEM cards. A press from a pin sends nothing. `Disconnect` and `Refresh` stay enabled, but there is no connection for them to act on. The readouts keep their last values and stop updating.

### Activate

Step 1. Read the Core's Locking ID

Set `Show_Locking_ID` to Yes and push the design. The Locking ID appears in the LOCKING ID box. Core Manager also shows it under Licensing, for any Core, with no design change. The Designer emulator reports `EMULATOR` or `*100000000000000`. The plugin marks it as not a Core ID. No code can be made for it.

Step 2. Get a code for that Locking ID

Buy or request an activation code at [freshavlabs.com](https://freshavlabs.com), quoting the Locking ID exactly.

Step 3. Enter the code and push the design

Paste the code into `Activation_Code` and push the design. The LICENSE box reads `ACTIVATED`. The plugin compares only the digits of the code, so punctuation and spaces do not matter. A code entered on a running design applies at the next design start.

Redundant Core pairs

Each Core has its own Locking ID and needs its own code. Put the primary Core's code in `Activation_Code` and the backup Core's code in `Activation_Code_Backup`. Read the backup Core's Locking ID from its own Core Manager; no failover is needed. Either code matching the running Core licenses the plugin, so a failover stays licensed.

### License status

Q-SYS prefixes the LICENSE box text with its own status word, so the box reads `OK - ACTIVATED` or `Compromised - DEMO: 9:59 remaining`.

| Status                              | Color  | Meaning                                                                           |
| ----------------------------------- | ------ | --------------------------------------------------------------------------------- |
| ACTIVATED                           | Green  | A code validated against this Core. No time limit.                                |
| DEMO: M:SS remaining                | Yellow | No code entered. Counting down.                                                   |
| DEMO (invalid code): M:SS remaining | Yellow | A code was entered and did not validate against this Core's Locking ID.           |
| DEMO EXPIRED - Activation Required  | Red    | The demo ran out. "What demo expiry stops" above says what the plugin still does. |

At expiry the plugin's `Status` control also reads `Fault - License required - demo expired`, so a Status Combiner sees the fault.

Codes are bound to one Core

An activation code works only on the Core whose Locking ID it was made for. It cannot move to another Core.

## Status Page

The Status page holds seven cards: CONNECTION, SYSTEM INFO and SYSTEM POWER on the left, and UPS STATUS, GLOBAL, AUTO REBOOT and SYSTEM on the right.

### Header

The header and the status bar are on both pages. The LOCKING ID and LICENSE boxes are at the top right of the header, LOCKING ID above LICENSE. LOCKING ID shows only when `Show_Locking_ID` is Yes. Below LICENSE are `Refresh` and the `Connected` LED. The status bar messages are in [Connection status](https://freshavlabs.com/docs/wattbox/#connection-status).

`Refresh` sends the login queries again. The SYSTEM INFO card, the outlet names and states, the power and UPS values and the auto reboot state then update. Without a login it sends nothing.

### Connection card

The CONNECTION card holds `IP Address`, `Port`, `Username`, `Password`, `Connect` and `Disconnect`, see [Connection Setup](https://freshavlabs.com/docs/wattbox/#connection).

### System Info card

| Control                                    | Range      | Description                                                                                                                                                                                                                    |
| ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Hostname` (`SystemName`)                  | Text       | The hostname the WattBox reports.                                                                                                                                                                                              |
| `Model`                                    | Text       | The model the WattBox reports.                                                                                                                                                                                                 |
| Model Mismatch indicator (`ModelMismatch`) | OK / Fault | At the end of the `Model` row. Shows a Fault when the reported model differs from the `Model` property, ignoring case and hyphens. Never a Fault when `Model` is Custom. Its pin carries `Fault - Mismatch: <reported model>`. |
| `Firmware` (`FirmwareVersion`)             | Text       | The firmware version the WattBox reports.                                                                                                                                                                                      |
| `Service Tag` (`ServiceTag`)               | Text       | The service tag the WattBox reports.                                                                                                                                                                                           |
| `Outlets` (`OutletCountFB`)                | Text       | The outlet count the WattBox reports. The Outlets page follows the `Model` property instead.                                                                                                                                   |

The card updates at login and on `Refresh`.

### System Power card

| Control                        | Range                            | Description                                                                                                                                                                |
| ------------------------------ | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Power` (`SystemPower`)        | `<n.nn> W`                       | System power.                                                                                                                                                              |
| `Current` (`SystemCurrent`)    | `<n.nn> A`                       | System current.                                                                                                                                                            |
| `Voltage` (`SystemVoltage`)    | `<n.nn> V`                       | System voltage, for example `120.00 V`.                                                                                                                                    |
| `Safe Voltage` (`SafeVoltage`) | `OK` or `Fault - Warning - <v>V` | `OK` when the voltage is 100 V to 130 V, or when the WattBox reports it as safe. Otherwise a Fault with the voltage to one decimal, for example `Fault - Warning - 92.4V`. |

The plugin sends no power queries when the WattBox reports a WB-150 or WB-250 model. Until the WattBox reports its model, the `Model` property decides. Without power queries this card and the outlet readouts do not update.

### UPS Status card

| Control                      | Range                        | Description                                                                           |
| ---------------------------- | ---------------------------- | ------------------------------------------------------------------------------------- |
| `Connected` (`UPSConnected`) | LED                          | On when the WattBox reports a UPS.                                                    |
| `Pwr Lost` (`UPSPowerLost`)  | LED                          | On when the UPS reports that power is lost.                                           |
| `Alarm` (`UPSAlarmEnabled`)  | LED                          | On when the UPS alarm is enabled.                                                     |
| `Muted` (`UPSAlarmMuted`)    | LED                          | On when the UPS alarm is muted.                                                       |
| `Charge` (`UPSCharge`)       | `<n>%`                       | Battery charge.                                                                       |
| `Load` (`UPSLoad`)           | `<n>%`                       | UPS load.                                                                             |
| `Runtime` (`UPSRuntime`)     | `<n> min`                    | Runtime in minutes.                                                                   |
| `Health` (`UPSHealth`)       | `OK - Good` or `Fault - Bad` | Battery health, as the WattBox sends it. Any word other than `Good` shows as a Fault. |

The plugin reads `Connected` at login and on `Refresh`, and polls the other values only while `Connected` is on. The values keep their last reading when the UPS goes away. Wire `UPS~Power Lost` to an alarm or a notification.

### Global card

| Control                             | Range               | Description                                                               |
| ----------------------------------- | ------------------- | ------------------------------------------------------------------------- |
| `All On` (`AllOn`)                  | Trigger             | Turns on every outlet the WattBox reports.                                |
| `All Off` (`AllOff`)                | Trigger             | Turns off every outlet the WattBox reports.                               |
| `Reset Delay (s)` (`ResetAllDelay`) | 1 to 600, default 3 | The delay, in seconds, that `Reset All` sends.                            |
| `Reset All` (`ResetAll`)            | Trigger             | Sends a reset with `Reset Delay (s)` to every outlet the WattBox reports. |

### Auto Reboot card

Auto reboot is a WattBox feature. The WattBox times out a host and reboots after a count of time-outs. The plugin sets the timing and has no control for the host.

| Control                                    | Range              | Description                                                                                                                                                 |
| ------------------------------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Enabled` (`AutoRebootEnabled`)            | On / off           | A press turns auto reboot on or off on the WattBox. Green (#16A34A) when on, #F9FAFB when off. Shows the WattBox's state as read at login and on `Refresh`. |
| `Timeout` (`AutoRebootTimeout`)            | 1 to 60, default 5 | Seconds the WattBox waits before it times out the host.                                                                                                     |
| `Count` (`AutoRebootCount`)                | 1 to 10, default 3 | Consecutive time-outs before an auto reboot.                                                                                                                |
| `Ping Dly` (`AutoRebootPingDelay`)         | 1 to 30, default 5 | Minutes the WattBox waits before it tests again after an auto reboot.                                                                                       |
| `Attempts` (`AutoRebootAttempts`)          | 0 to 10            | Reboot attempts. 0 is unlimited.                                                                                                                            |
| `Apply Settings` (`SetAutoRebootSettings`) | Trigger            | Sends `Timeout`, `Count`, `Ping Dly` and `Attempts` to the WattBox.                                                                                         |

The plugin never reads `Timeout`, `Count`, `Ping Dly` or `Attempts` from the WattBox. The fields show what Q-SYS last held, not what the WattBox holds.

Auto reboot operates outlets

Before you set auto reboot to on, make sure that the auto reboot host on the WattBox is correct.

### System card

| Control                           | Range      | Description                                                                                                                                                     |
| --------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Reboot WattBox` (`RebootSystem`) | Trigger    | Reboots the WattBox itself, not an outlet. The status bar shows `Initializing - Rebooting device...`, and the plugin reconnects after the WattBox acknowledges. |
| `Faceplate` (`FaceplatePresent`)  | LED        | On when the WattBox reports a faceplate.                                                                                                                        |
| `LED Level` (`FaceplateLedLevel`) | 0 to 65535 | Faceplate LED brightness. 0 is dimmest. Read from the WattBox.                                                                                                  |
| `Set` (`SetFaceplateLedLevel`)    | Trigger    | Sends `LED Level` to the WattBox.                                                                                                                               |

Faceplate control needs WattBox firmware 2.3.0.2 or later. Below it, `Faceplate` stays off and `Set` does nothing. The plugin checks the firmware at login and on `Refresh`.

## Outlets Page

The Outlets page has one card per outlet, two per row, outlet 1 at the top left. The `Model` property sets the number of cards.

### Outlet card

| Control                                                       | Range               | Description                                                                                                                                                                                                                   |
| ------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Status` (`OutletStatus`)                                     | LED                 | Beside the outlet number. On, green (#16A34A), when the outlet is on.                                                                                                                                                         |
| `Name` (`OutletName`)                                         | Text                | The outlet's name on the WattBox. Underscores show as spaces.                                                                                                                                                                 |
| `Set` (`UpdateOutletName`)                                    | Trigger             | Sends `Name` to the WattBox. Commas and line breaks are removed, spaces become underscores, and the name is cut to 31 characters.                                                                                             |
| `On` (`OutletOn`)                                             | Trigger             | Turns the outlet on.                                                                                                                                                                                                          |
| `Off` (`OutletOff`)                                           | Trigger             | Turns the outlet off.                                                                                                                                                                                                         |
| `Toggle` (`OutletToggle`)                                     | On / off            | Follows the outlet: white (#FFFFFF) when on, grey (#6B7280) when off. A press sends on or off for the new state.                                                                                                              |
| `Reset` (`OutletReset`)                                       | Trigger             | Sends a reset with `Delay (s)`.                                                                                                                                                                                               |
| `Delay (s)` (`OutletResetDelay`)                              | 1 to 600, default 3 | The delay, in seconds, that `Reset` sends.                                                                                                                                                                                    |
| `V:`, `W:`, `A:` (`OutletVolts`, `OutletWatts`, `OutletAmps`) | Numbers, no unit    | Outlet voltage with one decimal, power with two and current with three, for example `116.5`, `1.01`, `0.020`. See [System Power card](https://freshavlabs.com/docs/wattbox/#system-power-card) for the models that send none. |

`Status` and `Toggle` update when the WattBox sends an outlet status message, and when the plugin polls outlet state. That poll comes once every six polls: 90 seconds at the default `Poll_Rate` of 15.

### Pin-only outlet settings

These controls have no widget. Each is a pin per outlet, and the plugin never reads its value back from the WattBox.

| Pin                                                     | Range    | Description                                                                                          |
| ------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `Outlet N~Power On Delay` (`OutletPowerOnDelay`)        | 1 to 600 | The WattBox's power-on delay for the outlet. No default.                                             |
| `Outlet N~Set Power On Delay` (`SetOutletPowerOnDelay`) | Trigger  | Sends `Power On Delay` to the WattBox.                                                               |
| `Outlet N~Mode` (`OutletMode`)                          | Text     | `disabled` sets Disabled and `reset only` sets Reset Only, in any case. Any other text sets Enabled. |
| `Outlet N~Set Mode` (`SetOutletMode`)                   | Trigger  | Sends `Mode` to the WattBox.                                                                         |

## Control Pins

Every control on the panel is also a pin. Outlet pins read `Outlet N~<name>`, where N is the outlet number. In a control script an outlet control carries the number in its name, such as `OutletOn 3`. On a one-outlet model the name has no number, `OutletOn`.

### Connection and license pins

| Pin                     | Type    | Direction            |
| ----------------------- | ------- | -------------------- |
| `Connection~Status`     | Status  | Output               |
| `Connection~Connected`  | LED     | Output               |
| `Connection~IP Address` | Text    | Both                 |
| `Connection~Port`       | Text    | Both                 |
| `Connection~Username`   | Text    | Both                 |
| `Connection~Password`   | Text    | Both, reads `******` |
| `Connection~Connect`    | Trigger | Both                 |
| `Connection~Disconnect` | Trigger | Both                 |
| `Connection~Refresh`    | Trigger | Input                |
| `License~Status`        | Status  | Output               |
| `License~Locking ID`    | Text    | Output               |

`License~Locking ID` has that name only when `Show_Locking_ID` is Yes.

### System pins

| Pin                     | Type    | Direction |
| ----------------------- | ------- | --------- |
| `System~Hostname`       | Text    | Output    |
| `System~Model`          | Text    | Output    |
| `System~Model Mismatch` | Status  | Output    |
| `System~Firmware`       | Text    | Output    |
| `System~Service Tag`    | Text    | Output    |
| `System~Outlet Count`   | Text    | Output    |
| `System~Reboot`         | Trigger | Input     |

### Power pins

| Pin                  | Type   | Direction |
| -------------------- | ------ | --------- |
| `Power~System Power` | Text   | Output    |
| `Power~Current`      | Text   | Output    |
| `Power~Voltage`      | Text   | Output    |
| `Power~Safe Voltage` | Status | Output    |

### UPS pins

| Pin                 | Type   | Direction |
| ------------------- | ------ | --------- |
| `UPS~Connected`     | LED    | Output    |
| `UPS~Charge`        | Text   | Output    |
| `UPS~Load`          | Text   | Output    |
| `UPS~Runtime`       | Text   | Output    |
| `UPS~Health`        | Status | Output    |
| `UPS~Power Lost`    | LED    | Output    |
| `UPS~Alarm Enabled` | LED    | Output    |
| `UPS~Alarm Muted`   | LED    | Output    |

### Global and auto reboot pins

| Pin                     | Type    | Direction |
| ----------------------- | ------- | --------- |
| `Global~All On`         | Trigger | Input     |
| `Global~All Off`        | Trigger | Input     |
| `Global~Reset All`      | Trigger | Input     |
| `Global~Reset Delay`    | Integer | Both      |
| `AutoReboot~Enabled`    | Toggle  | Both      |
| `AutoReboot~Timeout`    | Integer | Both      |
| `AutoReboot~Count`      | Integer | Both      |
| `AutoReboot~Ping Delay` | Integer | Both      |
| `AutoReboot~Attempts`   | Integer | Both      |
| `AutoReboot~Apply`      | Trigger | Input     |

### Outlet pins

| Pin                           | Type    | Direction |
| ----------------------------- | ------- | --------- |
| `Outlet N~Status`             | LED     | Output    |
| `Outlet N~Name`               | Text    | Both      |
| `Outlet N~Update Name`        | Trigger | Input     |
| `Outlet N~On`                 | Trigger | Input     |
| `Outlet N~Off`                | Trigger | Input     |
| `Outlet N~Toggle`             | Toggle  | Both      |
| `Outlet N~Reset`              | Trigger | Input     |
| `Outlet N~Reset Delay`        | Integer | Both      |
| `Outlet N~Volts`              | Text    | Output    |
| `Outlet N~Watts`              | Text    | Output    |
| `Outlet N~Amps`               | Text    | Output    |
| `Outlet N~Power On Delay`     | Integer | Both      |
| `Outlet N~Set Power On Delay` | Trigger | Input     |
| `Outlet N~Mode`               | Text    | Both      |
| `Outlet N~Set Mode`           | Trigger | Input     |

### Faceplate and network pins

| Pin                   | Type    | Direction |
| --------------------- | ------- | --------- |
| `Faceplate~Present`   | LED     | Output    |
| `Faceplate~LED Level` | Integer | Both      |
| `Faceplate~Set LED`   | Trigger | Input     |
| `Network~Hostname`    | Text    | Both      |
| `Network~DHCP`        | LED     | Output    |
| `Network~IP`          | Text    | Output    |
| `Network~Subnet`      | Text    | Output    |
| `Network~Gateway`     | Text    | Output    |
| `Network~DNS1`        | Text    | Output    |
| `Network~DNS2`        | Text    | Output    |

The `Network~` pins have no widget, and they fill only on WattBox firmware 2.3.0.8 or later. A value written to `Network~Hostname` is not sent to the WattBox.

## Troubleshooting

#### The plugin never connects

* Read the status bar message in [Connection status](https://freshavlabs.com/docs/wattbox/#connection-status).
* Verify the Core can reach the WattBox IP on TCP 23, or on the port set in `Port`.
* Confirm the WattBox's IP control (Telnet) service is on, see [Connection Setup](https://freshavlabs.com/docs/wattbox/#connection).

#### The plugin stopped retrying

* A login failure, `Disconnect` and demo expiry all stop retries, see [Connection behavior](https://freshavlabs.com/docs/wattbox/#connection-behavior) and [What demo expiry stops](https://freshavlabs.com/docs/wattbox/#what-demo-expiry-stops).

#### Buttons are greyed out

* The demo has expired, see [What demo expiry stops](https://freshavlabs.com/docs/wattbox/#what-demo-expiry-stops).

#### The outlet count is wrong

* The Outlets page follows the `Model` property. If the Model Mismatch indicator in SYSTEM INFO shows a Fault, correct `Model` and push the design. See [System Info card](https://freshavlabs.com/docs/wattbox/#system-info-card).

#### Power readings do not update

* The plugin sends no power queries to a WB-150 or WB-250, see [System Power card](https://freshavlabs.com/docs/wattbox/#system-power-card).

#### Faceplate controls do nothing, or the network pins are empty

* Both need a minimum WattBox firmware. Compare `Firmware` in SYSTEM INFO with [System card](https://freshavlabs.com/docs/wattbox/#system-card) and [Faceplate and network pins](https://freshavlabs.com/docs/wattbox/#faceplate-and-network-pins).

#### The auto reboot fields do not match the WattBox

* The plugin never reads them back, see [Auto Reboot card](https://freshavlabs.com/docs/wattbox/#auto-reboot-card).

#### Reading the debug output

* Set `Debug_Level` to Verbose, see [Plugin Properties](https://freshavlabs.com/docs/wattbox/#properties), and open the plugin's debug window.

## How It Works

The plugin holds one TCP connection to the WattBox and speaks the SnapAV WattBox Integration Protocol. Queries start with `?`, commands start with `!`, and the WattBox also sends unsolicited `~OutletStatus` messages. The protocol document states that the WattBox accepts 10 connections at a time.

### Login

The plugin sends `Username` at a `Username:` or `login:` prompt and the password at a `Password:` prompt. A line with `Successfully Logged In` or `Login successful` completes the login. A line with `Login incorrect`, `Invalid` or `denied` fails it.

Half a second after login the plugin sends `?OutletCount`, `?Model`, `?Firmware`, `?ServiceTag`, `?Hostname`, `?OutletStatus`, `?OutletName`, `?PowerStatus`, `?UPSConnection` and `?AutoReboot`. Two seconds after login it sends `?OutletPowerStatus=<n>` for each outlet. The two power queries go only where power queries are sent. `Refresh` sends the same queries, plus `?NetworkGet` where the firmware supports the network pins.

### Polling

Each `Poll_Rate` tick sends the next step of this cycle:

1. `?OutletStatus`
2. `?PowerStatus`, where power queries are sent
3. `?UPSStatus`, while the UPS `Connected` LED is on
4. `?OutletPowerStatus=<n>` for the next outlet, where power queries are sent
5. The same as step 4
6. `?NetworkGet`, where the firmware supports the network pins, see [Faceplate and network pins](https://freshavlabs.com/docs/wattbox/#faceplate-and-network-pins)

The model, firmware, service tag, hostname, outlet names and auto reboot state are not polled.

### Commands

| Command                                                           | Sent by                                                       |
| ----------------------------------------------------------------- | ------------------------------------------------------------- |
| `!OutletSet=<n>,ON` and `!OutletSet=<n>,OFF`                      | `On`, `Off`, `Toggle`, `All On`, `All Off`                    |
| `!OutletSet=<n>,RESET,<delay>`                                    | `Reset`, `Reset All`                                          |
| `!OutletNameSet=<n>,<name>`                                       | `Set` on an outlet card                                       |
| `!OutletPowerOnDelaySet=<n>,<delay>`                              | `Outlet N~Set Power On Delay`                                 |
| `!OutletModeSet=<n>,<mode>`                                       | `Outlet N~Set Mode`, with 0 Enabled, 1 Disabled, 2 Reset Only |
| `!AutoReboot=1` and `!AutoReboot=0`                               | `Enabled`                                                     |
| `!AutoRebootTimeoutSet=<timeout>,<count>,<ping delay>,<attempts>` | `Apply Settings`                                              |
| `!FaceplateLedLevelSet=<level>`                                   | `Set` in the SYSTEM card                                      |
| `!Reboot`                                                         | `Reboot WattBox`                                              |
| `!Exit`                                                           | `Disconnect`, while logged in                                 |

## Support

* Support tickets: [freshavlabs.com/support](https://freshavlabs.com/support/)
* Website: [freshavlabs.com](https://freshavlabs.com)
* Email: <support@freshavlabs.com>

Include with a request:

* Q-SYS Designer version
* WattBox model and firmware version, shown in the SYSTEM INFO card
* Plugin version, shown under the plugin name in the header
* The Locking ID, for a license question
* Debug output captured with `Debug_Level` set to Verbose