System Operations Reference

Plum Voice Platform v. 2.6

© 2007 Plum Group, Inc. All rights reserved.
More on VoiceXML at Plumvoice.com

Introduction

This reference manual describes the configuration files, executables, and log directories for each subsystem of a fully-configured Plum Voice Platform, version 2.5. The Plum Voice Platform runs on the Red Hat Linux Version 7.3 Operating System. This manual assumes the reader has experience with UNIX systems operation.

Outline

  1. General System Operations
    1. Dialogic System Release 5.1 Service Pack 1
    2. Dialogic Global Call 3
    3. Apache HTTP Server
  2. Plum Platform Operations
    1. Plum Voice Platform
    2. TTS Engine
    3. ASR Engine

1. General System Operations

1.1 Dialogic System Release 5.1 Service Pack 1

The Dialogic drivers provide an interface between the Plum Voice Platform service and the Dialogic telephony hardware. The drivers rely on the dialogic.cfg configuration file to determine what hardware to look for and what signal processing firmware to load onto the hardware. Please note that the drivers must be started before the Plum Voice Platform service is started and must be stopped after the Plum Voice Platform is stopped.

Executable Files

/usr/dialogic/bin/dlstart No parameters.

dlstart starts the Dialogic drivers and, in the case of a digital (T1) telephony interface, establishes a link with the central office or PBX. 
/usr/dialogic/bin/dlstop No parameters.

dlstop stops the Dialogic drivers and, in the case of a digital (T1) telephony interface, tears down the link with the central office or PBX.
/etc/rc.d/init.d/dialogic { start | stop }

The dialogic init script calls either dlstart or dlstop when called with 'start' or 'stop'.
/etc/rc.d/rc3.d/S90dialogic S90dialogic is symlinked to dialogic.

Configuration Files

/usr/dialogic/cfg/dialogic.cfg The dialogic.cfg configuration file specifies the number and type of Dialogic boards installed in the server and the signal processing firmware to load on the boards. This file is created when the hardware is installed, and it should only be edited by a Plum technician.

1.2 Dialogic Global Call 3

The Dialogic Global Call country-dependent parameter files control telephony protocol behavior. Modifying these files -- in particular the files related to channelized T1 protocol behavior -- may result in complete loss of connectivity. These files should never be edited and are mentioned here for informational purposes only.

Configuration Files

/usr/dialogic/cfg/pdk_na_an_io.cdp pdk_na_an_io.cdp specifies telephony protocol behavior for analog "POTS" lines. 
/usr/dialogic/cfg/pdk_us_ls_fxs_io.cdp pdk_us_ls_fxs_io.cdp specifies telephony protocol behavior for channelized T1 lines configured with loopstart.
/usr/dialogic/cfg/pdk_us_mf_io.cdp pdk_us_mf_io.cdp specifies telephony protocol behavior for channelized T1 lines configured with E&M.

1.3 Apache HTTP Server

The Apache HTTP Server version 1.3.26 and PHP version 4.2.2 provide HTTP services with dynamic-processing and application server capabilities as well as proxy caching capability. The Apache HTTP Server, as configured out-of-the-box, provides access to the web-based configuration interface for the Plum Voice Platform on TCP port 80 and HTTP proxy caching on TCP port 8080.

Executable Files

/usr/local/apache/bin/apachectl { start | stop | restart | graceful | configtest }

The 'start' and 'stop' parameters will, of course, start and stop the httpd process. 'Restart' sends a SIGHUP to the httpd process if it is already running, or simply starts the httpd process if it is not running. 'Graceful' does a graceful restart (waiting for existing HTTP sessions to conclude) by sending a SIGUSR1 to the httpd process if it is already running, or simply starts the httpd process if it is not running. 'Configtest' does a configuration syntax test.
/etc/rc.d/init.d/httpd { start | stop | restart }

The httpd init script calls apachectl with 'start' and 'stop' as arguments. However, if httpd is called with 'restart', it will in turn call apachectl with 'stop', pause two seconds, and then call apachectl again with 'start'.
/etc/rc.d/rc3.d/S99httpd S99httpd is symlinked to httpd.

Logs

/usr/local/apache/logs Two log files are created: access_log and error_log. These will grow unbounded, though their rate of growth is fairly slow. If log rotation is necessary, the logs can be renamed (within the same filesystem) while the httpd process is running. When the httpd process is restarted, a new pair of log files will be created and the old ones can then be compressed, moved, or deleted as necessary.

Configuration Files

/usr/local/apache/conf/httpd.conf The httpd process references httpd.conf for configuration information. More information can be found at http://httpd.apache.org/docs/.


2. Plum Platform Operations

2.1 Plum Voice Platform

The Plum Voice Platform version 2.5 is a VoiceXML 2.0/2.1 interpreter built on Red Hat Linux and Dialogic telephony hardware. All configuration data for the platform is kept in the directory /usr/local/plumvp/config. To reset the platform to its original shipped state, simply stop the platform and delete all files within the configuration directory.

Executable Files

/usr/local/plumvp/bin/plumvp { -console | -verbose | -daemon | -url URL | -config config-file }

The plumvp executable should not normally be executed directly at the command line. However, under certain circumstances it may be necessary to alter the behavior of the plumvp executable by editing the parameters sent it in the plumvpctl control/init script.

'-console' instructs plumvp to spew all log entries to stderr. If the '-verbose' parameter is used, debug-level log entries will be shown and continuous channel logs will be saved in /usr/local/plumvp/logs/ch##.log.Plumvp will run as a daemon if '-daemon' is set. The default URL start page of "config/director.vxml" can be overridden with the '-url' parameter. An alternate configuration file (instead of "config/plumvp.cfg") can be specified with the '-config' parameter.

The plumvp executable listens on TCP port 7587 for incoming TCP connections. It responds to those connections with platform utilization info in the following format:

[(channel,DNIS,ANI,call_length) ... ] open_chans/total_chans
/usr/local/plumvp/bin/plumvpctl { start | stop | restart | status | kill }

The 'start' and 'stop' parameters will start and (gracefully) stop the plumvp process. 'Restart' will stop and then start the plumvp process. The 'status' parameter will return  "Running" or "Stopped" depending on whether the plumvp daemon is running or not. 'Kill' is like 'stop' except that it will immediately terminate any calls in progress. In the event that the plumvp process is unable to terminate, 'killall -9 plumvp' can be used instead. 'killall' should be used with caution as it may leave the telephony interface in an indeterminate state especially on systems with channelized T1 interfaces.
/etc/rc.d/init.d/S99plumvp S99plumvp is symlinked to plumvpctl.

Logs

/usr/local/plumvp/logs Four kinds of log files are created in the logs directory by the plumvp process: access/session logs, the channel event log, error logs, and the global event log. The access/session logs are named access.YYYYMMDD.log and contain an entry for every call session and an entry for every VoiceXML <log> call. The channel event log contains channel-specific entries for error and informational events and debug events should the '-verbose' parameter be set for the plumvp daemon. The error logs are named error.YYYYMMDD and contain all error events from the channel event log. The global event log contains all entries not specific to any channel. The
/usr/local/plumvp/dnislogs The last log for each DNIS is saved in this directory. The DNIS logs contain entries for all events. The last log is overwritten with each new call to a DNIS.
/usr/local/plumvp/snapshot Contains files for each channel actively handling a call. Each file contains the ANI and DNIS for the call.

Configuration Files

/usr/local/plumvp/license.cfg The license.cfg file is provided by Plum and contains hardware configuration information as well as channel activation directives.
/usr/local/plumvp/config/plumvp.cfg The plumvp.cfg is created and modified by the Plum Voice Platform web-based configuration interface and contains global platform configuration directives. It should not be edited by hand.
/usr/local/plumvp/config/director.vxml The director.vxml is created and modified by the Plum Voice Platform web-based configuration interface and is the base VoiceXML document that directs calls based on DNIS. It should not be edited by hand.
/usr/local/plumvp/config/*_*.vxml The other .vxml files in the config directory are the various scratchpads maintained by users via the Plum Voice Platform web-based configuration interface. They can be edited directly, but should not be deleted directly from the command-line.
/usr/local/plumvp/config/*.gdbm All information about user accounts, DNIS settings, and scratchpads are contained within the .gdbm files. These files should not be edited by hand.

2.2 TTS Engine

The Plum Voice Platform's distributable and modular text-to-speech engines receive speech synthesis requests on TCP port 7586. The speech synthesis requests are in the form of a '\0' terminated SSML string. The TTS engines then respond with headerless 8kHz µ-law audio data. The Natural Voices and Theta TTS engines require special licensing. Festival is a free Open Source TTS engine.

Control Scripts

/usr/local/plumvp/bin/ATTtts ATTtts is the AT&T NaturalVoices version of the Plum Voice Platform text-to-speech engine. It runs if the /usr/local/ATTNaturalVoices directory is present.
/usr/local/plumvp/bin/THTtts THTtts is the Cepstral Theta version of the Plum Voice Platform text-to-speech engine. It runs if the /usr/local/ATTNaturalVoices directory is not present and the /usr/local/theta directory is present.
/usr/local/plumvp/bin/FSTtts FSTtts is the University of Edinburgh Festival version of the Plum Voice Platform text-to-speech engine. It runs if the /usr/local/ATTNaturalVoices directory is not present, the /usr/local/theta directory is not present, and the /usr/local/festival directory is present.
/usr/local/plumvp/bin/ttsctl { start | stop | restart | status }

The 'start' and 'stop' parameters will start and stop the TTS engine. 'Restart' will stop and then start the TTS engine. The 'status' parameter will return  "Running" or "Stopped" depending on whether the TTS engine is running or not.
/etc/rc.d/init.d/S99tts S99tts is symlinked to ttsctl.

2.3 ASR Engine

The Plum Voice Platform's distributable and modular automatic speech recognition engines manage speech recognition sessions initiated on TCP port 7585. OpenSpeech Recognizer requires special licensing. Sphinx is a free Open Source ASR engine.

Control Scripts

/usr/local/plumvp/bin/SWIasr SWIasr is the SpeechWorks OpenSpeech Recognizer version of the Plum Voice Platform automatic speech recognition engine. It runs if the /usr/local/Speechworks directory is present.
/usr/local/plumvp/bin/SPHasr SPHasr is the Carnegie-Mellon Univesity Sphinx version of the Plum Voice Platform automatic speech recognition engine. It runs if the /usr/local/Speechworks directory is not present and the /usr/local/plumvp/sphinx directory is present.
/usr/local/plumvp/bin/asrctl { start | stop | restart | status }

The 'start' and 'stop' parameters will start and stop the ASR engine. 'Restart' will stop and then start the ASR engine. The 'status' parameter will return  "Running" or "Stopped" depending on whether the ASR engine is running or not.
/etc/rc.d/init.d/S99asr S99asr is symlinked to asrctl.