Controlling "ControlByWeb" Module Relays with Xymon Monitoring Software


Purpose

The instructions and script that follow are intended to be used to control the two relays on a ControlByWeb's 4-temp/2-relay temperature monitor module or the X-300 8-temp/3-relay 7-day programmable thermostat module when called by a Xymon monitoring server during an alert or alert recovery.

Here you will find the most current versions of our:

  • Instructions on integrating the xymon_cbw_relay.sh script with a Xymon server for use in controlling remote relays during Xymon alerts.
  • xymon_cbw_relay.sh - Xymon/ControlByWeb temperature module & X-300 thermostat module relay control script

Related Scripts

We have also written several other scripts that you may find useful. You may find them HERE




Instructions

ControlByWeb Temperature Module Configuration

First you need to do some basic configuration of the ControlByWeb temperature module. Instructions are included with the device, but the basic steps are as follows:

  • Connect: Connect to the device's default IP address using a web browser: http://192.168.1.2/setup.html (USER is blank, default password is webrelay)
  • Network Tab: Set up its network settings to match your network environment.
  • Email Tab: Optional since we will be alerting using Xymon.
  • Password Tab: Recommended, but also optional.
  • Main Tab: Optional for our ability to control the relays.
  • Sensor1 - Sensor4 Tabs: Optional for our ability to control the relays.
  • Reboot: Reboot the ControlByWeb module to complete the network configuration, and then try connecting to it at its new IP address.


Xymon Configuration

Install the custom external script

- Copy the bash shell script below into /usr/local/sbin (or other suitable directory of your choosing)
- Set the ownership and execution permissions on the script

chown xymon:xymon /usr/local/sbin/xymon_cbw_relay.sh
chmod +x /usr/local/sbin/xymon_cbw_relay.sh


Edit script to match your environment

- The script is pretty well documented, but you do need to modify just a couple of the pre-configured variables to get started:

  • Local system binaries: (TR, CUT & CURL)
  • HOST - The IP address or FQDN of the ControlByWeb device
  • USER - Leave blank for a ControlByWeb temperature module
  • PASS - Set to "webrelay", or set to same password used when you configured ControlByWeb device
  • PULSEONREC - If the Xymon alert is set to pulse a relay, should we also pulse the relay when the alert is recovered? Use "1" or "0"


Test script functionality without Xymon

To verify that you are able to control the relays on your module with the xymon_cbw_relay.sh script, you can run the following command as the xymon user (on one line):

xymon ~ $ RCPT="1:ON" RECOVERED="0" ./server/bin/bbcmd /usr/local/sbin/xymon_cbw_relay.sh

That command first populates the RCPT environment variable with "1:ON" (turn relay 1 on) and sets the RECOVERED environment variable to "0" telling the xymon_cbw_relay.sh script that this is NOT a recovery event, but an actual alert.

It then tells bbcmd to run the xymon_cbw_relay.sh script after reading in the hobbitserver.cfg file and populating the environment with all the variables in that file too.

This is the output of that command when using a 4-temp module (Notice the relay1state variable)

xymon ~ $ RCPT="1:ON" RECOVERED="0" ./server/bin/bbcmd /usr/local/sbin/xymon_cbw_relay.sh
2010-04-05 19:13:40 Using default environment file
/usr/local/xymon/server/etc/hobbitserver.cfg
<?xml version='1.0' encoding='utf-8'?>
<datavalues>
<units>F</units>
<sensor1temp>79.0</sensor1temp>
<sensor2temp>70.2</sensor2temp>
<sensor3temp>77.5</sensor3temp>
<sensor4temp>79.0</sensor4temp>
<relay1state>1</relay1state>
<relay2state>0</relay2state>
</datavalues>

...And relay 1 turns on and stays on.


When that command is run again with the RECOVERED environment variable set to "1 (telling the script that this a recovery event) the relay turns off. Here is the output of that command (Again, notice the relay1state variable):

xymon ~ $ RCPT="1:ON" RECOVERED="1" ./server/bin/bbcmd /usr/local/sbin/xymon_cbw_relay.sh
2010-04-05 19:19:52 Using default environment file
/usr/local/xymon/server/etc/hobbitserver.cfg
?xml version='1.0' encoding='utf-8'?>
<datavalues>
<units>F</units>
<sensor1temp>79.2</sensor1temp>
<sensor2temp>70.0</sensor2temp>
<sensor3temp>77.6</sensor3temp>
<sensor4temp>79.2</sensor4temp>
<relay1state>0</relay1state>
<relay2state>0</relay2state>
</datavalues>

...And relay 1 is now off again.


Configure a Xymon alert to use the xymon_cbw_relay.sh script

For ease of management and configuration, Xymon allows for macros in the ~xymon/server/etc/hobbit-alerts.cfg file. Macros are useful for defining things like email addresses, "windows of time" or other variables that may be used over and over again throughout the rest of the file.

An important thing to note here is that Xymon assigns everything after the equal sign to the macro. For this reason you should not quote your macro assignments as you might a variable in a bash shell script.

In our hobbit-alerts.cfg example below, we make use of a couple macros:

top of ~xymon/server/etc/hobbit-alerts.cfg

# GLOBAL MACRO ASSIGNMENTS
# ------------------------
# A future version of the xymon_cbw_relay.sh script will be
# modified to use environment variables for all variables
# For now we still define some of them in the script.
# 
# Here we assign the relay script to the 
# macro "$xymon_cbw_relay"
# ---------------------------------------------------------
$xymon_cbw_relay=/usr/local/sbin/xymon_cbw_relay.sh

# If we have more than one relay module, we define them here
# (for future use)
#$cbw_relay_module1=temp1.example.com
#$cbw_relay_module2=temp2.example.com

# Define macros to control and the relay (1 or 2) and the
# mode (ON, OFF, PULSE, TOGGLE)
# -------------------------------------------------------
#
# Turn Relay 1 ON
# ---------------
$cbw_cmd_relay1_ON=1:ON

# Turn Relay 2 ON
# ---------------
$cbw_cmd_relay2_ON=2:ON

# Pulse Relay 1
# -------------
$cbw_cmd_relay1_PULSE=1:PULSE

# Pulse Relay 2
# -------------
$cbw_cmd_relay2_PULSE=2:PULSE

# Toggle Relay 1
# --------------
$cbw_cmd_relay1_TOGGLE=1:TOGGLE

# Toggle Relay 2
# --------------
$cbw_cmd_relay2_TOGGLE=2:TOGGLE



And then we set up a specific test to alert on. In the following example, the test we are alerting on has nothing to do with the temperatures that the module is monitoring. We have decided to trigger our two relays based on the results of our example web server's HTTP test. You are not limited to any specific test to trigger the ControlByWeb relays.

~xymon/server/etc/hobbit-alerts.cfg continued...

# SPECIFIC ALERTING RULES
# -----------------------
# Define a set of simple test alerts for a host and 
# a service where we want to control a relay for an 
# alert
#
# If http test on www.example.com is 
# red, yellow, or purple for more than 5 minutes, do
# the following:
#
# - Turn relay 1 ON
# - Do not repeat alert
# - Run script when alert is recovered (to reset relay)
#
# 
# If http test on www.example.com is
# red, yellow, or purple for more than 10 minutes, do 
# the following:
#
# - Turn relay 2 ON
# - Do not repeat
# - Run script when alert is recovered (to reset relay)
# -----------------------------------------------------
HOST=www.example.com SERVICE=http
   SCRIPT $xymon_cbw_relay $cbw_cmd_relay1_ON DURATION>5m REPEAT=52w COLOR=red,yellow,purple RECOVERED
   SCRIPT $xymon_cbw_relay $cbw_cmd_relay2_ON DURATION>10m REPEAT=52w COLOR=red,yellow,purple RECOVERED





xymon_cbw_relay.sh

#!/bin/bash
#
# NAME
# ----
# - xymon_cbw_relay.sh
#
# DESCRIPTION
# -----------
# - Simple Bash shell script to control the two relays on a ControlByWeb
#   4-temp/2-relay module
#
# - The most current version of this script may be found
#   at http://www.revpol.com/xymon_cbw_relay_script
#
# - Instructions to integrate this with a Xymon Monitoring server may also
#   be found at the above URL
#
# - *NOTE* - This script has the added "bonus" of also dealing with relays
#            that are normally ON that you want Xymon to turn OFF on alert
#            and then back ON when the alert is recovered. Why you would want
#            to use this "reverse logic" is unknown to this author, but the
#            option is available. :)
#
#          - Also, the modules accept a TOGGLE option. Why you might want to
#            use this mode with a Xymon alert script is also unknown, but the
#            option is provided just in case.
#
# - If you find this script useful, I'd love to know. Send me an email!
#
# William A. Arlofski
# Reverse Polarity, LLC
# 860-824-2433 Office
# http://www.revpol.com/
#
# HISTORY
# ------
# - 20100325 - Initial version release
#            - Major same-day "logic" rewrite after Ryan from ControlByWeb
#              provided module-specific information for controlling the relays
# - 20100326 - Fixed glaring problem with restoring relay to "normal" condition
#              when script was called during an alert recovery. This was due
#              to the major logic changes made previously
# - 20100331 - Minor modifications to some of the comments
#
###############################################################################
#
# Copyright (C) 2010 William A. Arlofski - waa-at-revpol-dot-com
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License, version 2, as
# published by the Free Software Foundation.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
# or visit http://www.gnu.org/licenses/gpl.txt
#
###############################################################################
#
# Set some variables
# ------------------
# Local System Binaries
# ---------------------
TR="/usr/bin/tr"
CUT="/usr/bin/cut"
CURL="/usr/bin/curl"


# Location/device specific variables
# ----------------------------------
#
# FQDN or IP address of the ControlByWeb
# temperature monitor  and user login
# and password (User should be blank)
#---------------------------------------
HOST="temp.example.com"
USER=""
PASS="password"


# If the Xymon alert was configured to pulse
# the relay, do we also pulse on a recovery?
# ------------------------------------------
PULSEONRECOV="0"


###############################################################################
# --------------------------------------------------
# Nothing should need to be modified below this line
# --------------------------------------------------
###############################################################################


if [ -z "$RCPT" ] || [ -z "$RECOVERED" ]; then
 echo ""
 echo "*NOTE* Must be called by Xymon with RCPT, and RECOVERED environment variables set"
 echo "        RCPT must be in the form X:MODE"
 echo "        where X is 1 or 2 and"
 echo "        MODE is ON, OFF, PULSE, or TOGGLE"
 echo ""
 exit
fi


# Get Relay and Mode from environment
# -----------------------------------
RELAY=`echo "$RCPT" | "$CUT" -d':' -f1`
MODE=`echo "$RCPT" | "$CUT" -d':' -f2 | "$TR" [a-z] [A-Z]`


# Verify that an appropriate avalue was set for the relay number
# --------------------------------------------------------------
if [ ! "$RELAY" == "1" ] && [ ! "$RELAY" == "2" ] ; then
  echo "Relay must be one of either 1 or 2"
  exit 1
fi


# Determine the MODE (ON, OFF, PULSE or TOGGLE) and convert
# the mode to its numeric value
#
# Here we also decide what to do if we were called due to a
# recovery of an alert:
# If we are recovering from an alert, Xymon calls the same
# script with the same command line variables, but sets the
# environment variable $RECOVERED to "1" otherwise $RECOVERED
# is set to "0" when the script is called for an alert
#
# The special case of "pulse on recovery" is also tested
# -----------------------------------------------------------
case "$MODE" in

        ON   )
          if [ "$RECOVERED" == "1" ] ; then
            MODE="0"
              else
                MODE="1"
          fi
          ;;

        OFF  )
          if [ "$RECOVERED" == "1" ] ; then
            MODE="1"
              else
                MODE="0"
          fi
          ;;

       PULSE )
          # If this is not a recovery alert, just pulse the correct relay
          # OR
          # If this is a recovery of an alert, AND we want to "pulse on recovery"
          # then pulse the relay, otherwise we are done and just exit
          # ---------------------------------------------------------------------
          if [ "$RECOVERED" == "0" ] || [ "$RECOVERED" == "1" -a "$PULSEONREC" == "1" ] ; then
           MODE="2"
            else
              exit 1
          fi
          ;;

     TOGGLE )
          MODE="5"
          ;;

        *   )
         echo "No mode, or improper mode given... use ON, OFF, PULSE, or TOGGLE"
         exit
         ;;
esac


# Send command to the module using curl
# -------------------------------------
"$CURL" -s -u "$USER:$PASS" "$HOST/state.xml?relay$RELAY""State=$MODE"

Post new comment

  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <b> <i> <u> <strong> <cite> <code> <pre> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.

More information about formatting options

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
R
r
t
R
3
^
Enter the code without spaces and pay attention to upper/lower case.