A Flexible Service for Monitoring the EPICS Distributed Control System

• Web interface for monitoring process variables.
• Send messages to notify of process variable changes.

All devices are referenced using a URI

EPICS devices use the scheme, epics, and have the general form: epics:ProcessVariable?option1=value1&option2=value2

The ProcessVariable component is required but correct URL encoding is not enforced (ie PCT2026X-01%3AmA%3Afbk and PCT2026X-01:mA:fbk both work).

The supported options are:

• buffer - Use a buffer of the specified length. Only useful for charting type fields. (Integer)
• rate - Specified period in seconds to force a device value update. (Real)
• ratelimit - Specified period in seconds to limit device value updates. (Real)
• lowedge - Device value updated when its value goes below the specified value. (Real)
• highedge - Device value updated when its value goes above the specified value. (Real)
• threshold - Device value updated when its value goes above or below the specified value. (Real)
• name - Specify the name of the device. Displayed on Y-axis of chart. (String)
• units - Specify the units of the device. (String)
• precision - Specify the precision (number of decimal places) of a device value to show. (Integer)
• scale - Multiply the device value by the constant value specified. (Real)
• offset - Add to the device value the constant value specified. (Real)

Control System Web can be configured to serve files from any location:

from twisted.web.static import File
from twisted.web.resource import Resource

fileResource = File('/home/directory/csweb')
webroot.putChild('myfiles', fileResource)

With the above configuration the contents of /home/directory/csweb is served at http://hostname/myfiles.

To enable integration with Control System web, include these JS libraries and CSS style sheets in an HTML document:

 <script type="text/javascript" src="/static/lib/jquery/1.8/jquery.min.js"></script>
 <script type="text/javascript" src="/static/lib/dygraph/dygraph.min.js"></script>
 <script type="text/javascript" src="/static/js/csweb.js"></script>
 <script type="text/javascript" src="/static/js/cswui.js"></script>

Then, within the body of an HTML document, CSW fields are specified with the following markup:

<div class="[CSW_FIELD]">
    <div name="[CSW_FIELD_OPTION]">[VALUE]</div>
    <div name="[CSW_FIELD_OPTION]">[VALUE]</div>
    ...
</div>

Supported values for CSW_FIELD are the following:

• csw-readonly-field - A readonly text field that display the value of the specified device.
• csw-strip-chart - A strip chart that displays the value of the specified device over time.

Supported values for CSW_FIELD_OPTION are the following:

• device - Specify the path component of the device URI. Generally this is the PV name.
• protocol - Specify the scheme of the device URI. This is optional and defaults to epics.
• All other options and their values are added to the query component of the device URI.

<div class="csw-strip-chart">
    <div name="device">TM2026X-101</div>
    <div name="buffer">20</div>
</div>

Sending Email notification is as simple as configuring a SMTP agent and then registering the destination addresses:

from csweb.util.smtp import SMTPAgent
from csweb.notify.mail import MailNotifier

mailNotifier = MailNotifier(SMTPAgent("smtp.host.com", 25), "From Name <from@host.com>")

mailNotifier.register("epics:SR2026X:Status", "Real Name <email@host.com>")

Sending SMS notification is as simple as configuring a Twilio agent and then registering the destination numbers:

from csweb.util.http import BasicHTTPAgent
from csweb.util.twilio import TwilioSMSAgent
from csweb.notify.sms import SMSNotifier

smsAgent = TwilioSMSAgent(BasicHTTPAgent("username","password"))
smsNotifier = SMSNotifier(smsAgent, "+1FromNumber")

smsNotifier.register("epics:SR2026X:Status?lowedge=0", "+1ToNumber")

Support for alternative SMS message services can easily be added to CSW.

Updating your Twitter status is as simple as configuring a Twitter agent and registering it with a TwitterNotifier:

import oauth2 as oauth
from csweb.util.http import OAuthHTTPAgent
from csweb.util.twitter import TwitterAgent
from csweb.notify.twitter import TwitterNotifier
 
twitterNotifier = TwitterNotifier()
 
token = oauth.Token("TokenKey", "TokenSecret")
consumer = oauth.Consumer("ConsumerKey", "ConsumerSecret")
twitterNotifier.addAgent("AgentName", TwitterAgent(OAuthHTTPAgent(consumer, token)))
 
twitterNotifier.register("epics:SR2026X:Status", "AgentName")

To simplify the configuration of the various notifiers, a configuration manager is used. This configuration manager uses a single configuration file to setup recipients for all notifiers and periodically checks for changes to the configuration file and updates the notifiers without needing to restart the server.

Configure the notifier configuration manager by specifying a configuration file path and a notifier mapping:

import os.path

from csweb.notify.config import GeneralFileConfig

notifierConfig = GeneralFileConfig(os.path.join(csweb_home, "config", "notifiers.cfg"), { "mail":mailNotifier, "sms":smsNotifier, "twitter":twitterNotifier })

The configuration file uses the ConfigParser format as specified by the Python standard library. Each section is named with a device URL and the configuration options in each section must match the names provided for each notifier in the above configuration.

An example notifier configuration file:

[DEFAULT]
USER1_EMAIL:user1@host.com

[ epics:PCT2026X-01:mA:fbk?threshold=50&name=Beam+Current ]
mail: %(USER1_EMAIL)s, user2@host.com (2013-03-15)
sms: 13065551234, 13065554321

In addition to specifying a recipient, an optional expiry time can be provided within parenthesis. Notifications will not be sent to the recipient if the current time is after the expiry time. Permitted formats for the expiry time are YYYY-MM-DD, YYYY-MM-DD HH:MM, YYYY/MM/DD, YYYY/MM/DD HH:MM (see csweb.util.dateutil module for more details)