|
This documentation applies to version 0.01-alpha.
|
|
The dssctrl software package may be broken down into three distinct pieces: the dssctrld daemon, the dssctrl client
and the libdssctrl library.
The dssctrld daemon performs the actual management of one or more DSS receivers (or eventually other similar
devices) and can optionally use time information reported by the receiver to periodically monitor and adjust the
system's clock.
The dssctrl client allows commands to be issued to a dssctrld daemon, either on the same machine, or on remote
machines over a TCP/IP stack. The dssctrl client program is a command line tool suitable for
use with home multimedia software/PVR software such as MythTV.
The libdssctrl library may be used by programs to easily issue commands to the dssctrld daemon. For details on
using the libdssctrl please look at the header file libdssctrl.h in the libdssctrl subdirectory in the source.
|
|
Typically the dssctrld daemon is started during the System V initialization procedure using a script placed in
/etc/init.d. Optionally, the dssctrld daemon may be started directly from /etc/rc.sysinit (or similar).
The script dssctrld in the extras subfolder may be placed into your may be placed into your /etc/init.d directory.
Also be sure to place the dssctrld.conf file into your /etc directory.
For reference, the dssctrld script (as of December 17, 2004) is shown below:
#!/bin/bash
#
# Shell script to install the dssctrld daemon on system boot. Do so with as
# little reliance on system specific features as possible.
#
# Syntax of the configuration file is to include options on each line (with
# optional spaces). Device options may be specified multiple times.
#
# Options are:
# Force - Force time on system startup.
# Offset <value in seconds> - Sets the time offset (signed) to apply.
# Verbose - Enables verbose output.
# VeryVerbose - Enables very verbose output.
# Port <port> - Port to monitor for activity.
# Logfile <filename> - Location to place logfile.
# Source: <type>:<device> - Device acting as clock source.
# Device: <type>:<device> - Device acting as clock source.
#
#
# Define necessary environment settings (change these if needed)
#
CONFIGURATION_FILE="/etc/dssctrld.conf"
DSSCTRLD="/usr/sbin/dssctrld"
#
# Command functions:
#
function Start() {
if [ ! -f $CONFIGURATION_FILE ];
then
echo "Configuration file not found at \"$CONFIGURATION_FILE\""
exit 1
fi
OFFSET=
OFFSET_SPECIFIED="no"
PORT=
PORT_SPECIFIED="no"
LOGFILE=
LOGFILE_SPECIFIED="no"
DEVICES=
CLOCK_SOURCE=0
SOURCE_SPECIFIED="no"
FORCE="no"
NO_CLOCK_SOURCE="no"
VERBOSE="no"
VERY_VERBOSE="no"
LAST_KEYWORD="x"
CURRENT_DEVICE=0
for KEYWORD in `cat <$CONFIGURATION_FILE | sed -e "s/#.*$//"`;
do
case "$LAST_KEYWORD" in
offset | Offset)
if [ "$OFFSET_SPECIFIED" != "no" ];
then
echo "*** Only one time offset may be defined."
exit 1
fi
OFFSET_SPECIFIED="yes"
OFFSET="$KEYWORD"
KEYWORD="x"
;;
port | Port)
if [ "$PORT_SPECIFIED" != "no" ];
then
echo "*** Only one port may be defined."
exit 1
fi
PORT_SPECIFIED="yes"
PORT="$KEYWORD"
KEYWORD="x"
;;
logfile | Logfile)
if [ "$LOGFILE_SPECIFIED" != "no" ];
then
echo "*** Only one logfile may be defined."
exit 1
fi
LOGFILE_SPECIFIED="yes"
LOGFILE="$KEYWORD"
KEYWORD="x"
;;
source | Source)
if [ "$SOURCE_SPECIFIED" != "no" -o "$NO_CLOCK_SOURCE" != "no" ];
then
echo "*** Only one clock source may exist."
exit 1
fi
SOURCE_SPECIFIED="yes"
CLOCK_SOURCE=$CURRENT_DEVICE
let CURRENT_DEVICE=CURRENT_DEVICE+1
DEVICES="$DEVICES $KEYWORD"
KEYWORD="x"
;;
device | Device)
let CURRENT_DEVICE=CURRENT_DEVICE+1
DEVICES="$DEVICES $KEYWORD"
KEYWORD="x"
;;
esac
LAST_KEYWORD="$KEYWORD"
case "$KEYWORD" in
noclocksource | NoClockSource)
if [ "$NO_CLOCK_SOURCE" != "no" -o "$SOURCE_SPECIFIED" != "no" ];
then
echo "*** Force specified multiple times."
exit 1
fi
FORCE="yes"
;;
force | Force)
if [ "$FORCE" != "no" ];
then
echo "*** Force specified multiple times."
exit 1
fi
FORCE="yes"
;;
verbose | Verbose)
if [ "$VERBOSE" != "no" -o "$VERY_VERBOSE" != "no" ];
then
echo "*** Verbosity specified multiple times."
exit 1
fi
VERBOSE="yes"
;;
veryverbose | VeryVerbose)
if [ "$VERBOSE" != "no" -o "$VERY_VERBOSE" != "no" ];
then
echo "*** Verbosity specified multiple times."
exit 1
fi
VERY_VERBOSE="yes"
;;
esac
done
if [ "$OFFSET_SPECIFIED" != "no" ];
then
PARAMETERS="$PARAMETERS --offset $OFFSET"
fi
if [ "$PORT_SPECIFIED" != "no" ];
then
PARAMETERS="$PARAMETERS --port $PORT"
fi
if [ "$LOGFILE_SPECIFIED" != "no" ];
then
PARAMETERS="$PARAMETERS --logfile $LOGFILE"
fi
if [ "$SOURCE_SPECIFIED" != "no" ];
then
PARAMETERS="$PARAMETERS --clock-source $CLOCK_SOURCE"
fi
if [ "$NO_CLOCK_SOURCE" != "no" ];
then
PARAMETERS="$PARAMETERS --no-clock-source"
fi
if [ "$FORCE" != "no" ];
then
PARAMETERS="$PARAMETERS --force"
fi
if [ "$VERBOSE" != "no" ];
then
PARAMETERS="$PARAMETERS --verbose"
fi
if [ "$VERY_VERBOSE" != "no" ];
then
PARAMETERS="$PARAMETERS --very-verbose"
fi
$DSSCTRLD $PARAMETERS $DEVICES &
}
function Stop() {
killall dssctrld
}
#
# Go make things happen:
#
case "$1" in
start)
echo -n "Starting dssctrld...."
Start
echo "Done"
;;
stop)
echo -n "Stopping dssctrld...."
Stop
echo "Done"
;;
restart)
$0 stop
$0 start
;;
reload)
$0 stop
$0 start
;;
*)
echo "Usage: $0 {start|stop|restart}"
exit 1
esac
exit 0
And the /etc/dssctrld.conf file (as of December 17, 2004) is shown below:
#
# This is the configuration file for the dssctrl SysV initialization script.
#
# Options may be specified in lower case or proper case only.
#
# Uncomment the "Force" option to tell dssctrld to force the system clock on
# start-up.
Force
# The offset option allows a signed time offset (in seconds) to be applied to
# the time reported by the DSS receiver. A positive offset advances the clock.
#
# Offset 3600
# Uncomment the "Verbose" option to tell dssctrld to report information to the
# logs verbosely.
# Verbose
# Uncomment the "VeryVerbose" option to tell dssctrld to report information to
# the logs very verbosely.
# VeryVerbose
# Uncomment the "Port" option to change the default TCP/IP port.
# Port 1103
# Uncomment the "Logfile" option to change the default logfile.
# Logfile /var/log/dssctrld.log
# Uncomment to disable all devices as possible clock sources.
# NoClockSource
# Add "Source" and "Device" options below to specify the devices the daemon
# should manage.
#
# Example:
# Device rca:/dev/ttyS2
# Source rca:/dev/ttyUSB0
# Device rca:/dev/ttyS1
#
# The device marked with the "Source" option will be used as the source for
# time information. Zero or one "Source" option may be specified.
Device rca:/dev/ttyUSB0
Be sure to add symbolic links to this script from the appropriate /etc/rd.d directory for the desired run levels
(typically 3 and 5). Commands to do this are typically:
# ln -s /etc/init.d/dssctrld /etc/rc3.d/S99dssctrld
# ln -s /etc/init.d/dssctrld /etc/rc5.d/S99dssctrld
Edit the file /etc/dssctrld.conf that you placed into your /etc subdirectory. Follow the embedded comments for an
explanation of what each option does.
|
|
The dssctrld daemon is must be allowed to run continuously and is therefore not suited for use in conjunction with
the inetd or xinetd daemons. Under normal circumstances, the overhead required by the dssctrld daemon is low so the
advantage to using the xinetd daemon to run the dssctrld daemon is minimal. Also, the dssctrld must be run suid
root.
The dssctrld daemon accepts a number of command line switches that may be used to modify/control it's behaviour and
all configuration settings are passed to it directly on the command line. The daemon does not require a
configuration file.
Besides the usual help switch (-h, --help, or -?), the dssctrld daemon accepts a number of other switches. These
switches are:
| -v | --verbose |
Enables verbose logging of the daemons activity.
|
| -V | --very-verbose |
Enables extremely verbose logging of the daemons
activity.
|
| -p <port> | --port <port> |
Changes the default port used to interact with the dssctrl client or the libdssctrl library. Default value is
1103.
|
| -c <device> | --clock-source <device> |
By default the first device listed on the command line is used as the source for time information. On systems
controlling multiple DSS receivers, this switch allows the second or third device on the command line to be used
as the clock source. The first device is device 0, the second device is device 1, etc.
|
| -n | --no-clock-source |
This switch tells dssctrld not to monitor or adjust the system clock.
|
| -o <time offset> | --offset <time offset> |
The offset (signed) in seconds to be applied to the time reported by the DSS receiver. May be used to introduce
correction to the DSS receiver's time.
|
| -f | --force |
Force the system clock to be set to the time reported by the DSS receiver. Useful to set the system clock on
start-up.
|
| -C | --console |
Direct all messages to stdout instead of /var/log/dssctrl.log.
|
| -l <filename> | --logfile <filename> |
Changes the logfile from /var/log/dssctrl.log to <filename>.
|
Each device that dssctrld controls must be specified on the command line. Unless specified on the command line
using the
--clock-source switch, the first device specified on the command line is used as the clock source used to
monitor/adjust the system clock.
Each device is specified using a device description of the form <device type>:<interface>.
Currently only RCA DSS receivers are supported. For an RCA DSS receiver connected on /dev/ttyS0, the device
description would be "rca:/dev/ttyS0".
For a system controlling two RCA DSS receivers, with one on the first serial port and one on a USB to serial
adapter, the command line might be:
# dssctrld -f -c 1 rca:/dev/ttyS0 rca:/dev/ttyUSB0
In the example above, the system clock is forced when the daemon is run. Also, the RCA DSS receiver at
/dev/ttyUSB0 is used as the source of time information.
|
|
The dssctrl client is a small program that provides a command line interface that issues commands to a dssctrld
daemon using facilities provided by the libdssctrl library.
The dssctrl client accepts a number of switches and one command (possibly with a parameter). Switches and the
command may be intermixed (the command is treated just like a switch, except that one and only one command can be
specified on the command line).
There are three ways to specify the location (and port) of the dssctrld daemon. By default, the client will look
for the server at localhost:1103. If the environment variable DSSCTRL_SERVER is defined, then the dssctrl client
will look for the server at the location specified by the DSSCTRL_SERVER environment variable. Lastly, the server
may be specified using the -r (--server) command line switch. The format for the server is <server name>:port
where the :port suffix is optional. For example, if the dssctrld daemon is running on a system named
"mythtv" and the port on the server has been changed to 10000 (using the --port switch on the dssctrld server), the
DSSCTRL_SERVER environment variable may be set to:
$ export DSSCTRL_SERVER="mythtv:1000"
Note that the -r/--server switch overrides the DSSCTRL_SERVER environment variable.
The dssctrl client accepts the following switches:
| -h | --help |
Displays a list of command line options and gives some basic information that might be useful in making use of
the dssctrl client.
|
| -r <server> | --server <server> |
Overrides the DSSCTRL_SERVER environment variable (if defined). May be used to set the server and port number
of the dssctrld server. The format of the server string should be of the form server:port (the :port value is
optional. If not included, the port 1103 is assumed).
|
| -d <device> | --device <device> |
If the dssctrld server controls multiple DSS receivers, this switch may be used to specify which device should
be controlled. By default, device 0 is controlled.
|
| -w <timeout> | --timeout <timeout> |
Specifies the maximum time to wait (in mSec) for the dssctrld server to respond to a command. The default
timeout is set to 30000 (30 seconds).
|
In addition to the switches above, a number of commands are supported:
| -s | --state | state |
Requests the current state of a DSS receiver. Returns either "on" or "off". This command is currently not
implemented for RCA DSS receivers. Provided for support of future product.
|
| -o | --off | on |
Powers on the remote DSS receiver.
|
| -f | --off | off |
Powers off the remote DSS receiver.
|
| -c | --channel | channel |
Returns the channel number of the DSS receiver is currently tuned to.
|
| -t <channel> | --tune <channel> | tune <channel> |
Changes the current channel on a remote DSS receiver to <channel>.
|
| -T | --time | time |
Reports the time as reported by the DSS receiver.
|
| -S | --signal | signal |
Returns the signal strength reported by the DSS receiver as a percentage.
|
| -m <message> | --message <channel> | message <message> |
Tells the remote DSS receiver to display a message on the bottom of the TV screen. To remove a previously
displayed message, send an empty message. Typically the message is surrounded in quotes to allow spaces and
special characters to be included.
|
Note that as support is added for additional devices, some of the commands above may not be supported (based on the
capabilities of the device).
Below are some example command lines that will hopefully illustrate how to use dssctrl:
$ dssctrl -r localhost:10000 tune 244
$ dssctrl --timeout 2000 tune 5
$ dssctrl -r mythtv.home.net -c
$ dssctrl -r htpc -d 1 off
$ dssctrl message "Hi"
$ dssctrl message ""
# dssctrl time
|