source: pvMail/doc/source/index.rst @ 946

.. $Id: index.rst 946 2012-06-19 18:55:16Z jemian $

PvMail
==================================

https://subversion.xray.aps.anl.gov/admin-bcdaext/pvMail

PvMail was built to watch (monitor) an EPICS PV and send an email
when the value of that PV changes from 0 to 1.  

..      sidebar:: IMPORTANT:

        PvMail *only* triggers when the trigger_PV makes a transition from 0 to 1.
        
        * It will ignore transitions (in floating-point PVs) to
          1.0000... that do not come directly from 0.0000...
          If you wish to watch a PV that presents values other than 0 and 1,
          then use a calculation PV as the trigger which results in a 
          transition from 0 to 1.
        * Reset the value of the trigger_PV to 0 to resume watching 
          for the next triggered event.

The PV being watched (that *triggers* the sending of the email)
can be any EPICS record type or field
that results in a value of 0 (zero) that changes to 1 (one).  This 
includes these EPICS records (and possibly more):
*ai*, *ao*,  *bi*, *bo*, *calcout*, *scalcout*, *swait*, ...

When an event causes an email to be triggered, PvMail will retrieve
the value of another PV that is the first part of the message to be 
sent.  Additional metadata will be appended to the message.

.. note::
        Email is sent using a call to the ``sendmail`` program on the native OS.
        This almost certainly precludes its use on Windows systems.
        The GUI or command-line versions will operate but likely no email
        is sent.  Also, the host computer must allow and be configured for
        sending email to the intended recipients.

PvMail provides either a command-line interface or a graphical user
interface.  Both are accessed from the same command, using different
command-line options.  The command-line version is intended to run 
as a background program, it has no user interaction but logs all its
output into a log file.  The GUI version provides a screen to edit
each of the parameters before the background process is started.  
It also provides buttons to start and stop the background process.

Overview of Contents
========================

.. toctree::
   :maxdepth: 2
   
   contents


Glossary
========

:index:`CA`
    EPICS Channel Access protocol

:index:`CLI`
    command-line interface

:index:`EPICS`
    http://www.aps.anl.gov/epics

:index:`GUI`
    graphical user interface

:index:`IOC`
    EPICS Input/Output Controller, the EPICS server

:index:`message PV`
    EPICS PV that provides the text to be sent by email,
    additional metadata is appended to this text

:index:`OS`
    operating system

:index:`PV`
    EPICS process variable

:index:`PyEpics`
    Python package to manage connections with PVs served by an EPICS IOC

:index:`Traits`
    Python package to simplify construction of a GUI

:index:`trigger PV`
    EPICS PV that signals an email is to be sent


Dependencies
============

This software was built with various standard Python packages
available in Python 2.7.  Additionally, this program uses: 

.. index:: PyEpics

*PyEpics* (EPICS interface) 
        http://cars9.uchicago.edu/software/python/pyepics3/

.. index:: Traits

*Traits* (GUI library) 
        http://code.enthought.com/projects/traits/

Both of these are available for 
`easy_install <http://packages.python.org/distribute/easy_install.html>`_ 
from the Python Package Index (http://pypi.python.org/pypi).


*This documentation was built:* |today|