WattBox IP Control

01.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.

02.Requirements

Component	Requirement
Q-SYS Designer	Tested with Q-SYS Designer 10.4
WattBox	A model listed under Model in Plugin 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
License	One activation code per Core. See Licensing

03.Installation

The WattBox IP Control package contains one plugin file:

File	Purpose	License
WattBox_IP_Control.qplugx	The WattBox controller	Licensed

04.Quick Start

The most common support call is a WattBox with its IP control (Telnet) service turned off, see Connection Setup.

05.Plugin Properties

The connection details are controls on the Status page, not properties, see Connection Setup.

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.
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.
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.
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.

06.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.

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.	None. The plugin reconnects.

07.Licensing

The plugin reads Activation_Code and Activation_Code_Backup when the design starts.

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

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.

08.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.

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.

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.

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.

09.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 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.

10.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.

11.Troubleshooting

The plugin never connects

• Read the status bar message in 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.

The plugin stopped retrying

• A login failure, Disconnect and demo expiry all stop retries, see Connection behavior and What demo expiry stops.

Buttons are greyed out

• The demo has expired, see 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.

Power readings do not update

• The plugin sends no power queries to a WB-150 or WB-250, see 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 and Faceplate and network pins.

The auto reboot fields do not match the WattBox

• The plugin never reads them back, see Auto Reboot card.

Reading the debug output

• Set Debug_Level to Verbose, see Plugin Properties, and open the plugin's debug window.

12.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

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

13.Support

• Support tickets: freshavlabs.com/support
• Website: freshavlabs.com
• Email: [email protected]

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