.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH ISEG2DIM 1 "OCTOBER 2012" "iseg2dim" "User Commands"
.SH NAME
iseg2dim - DIM server to control Iseg high voltage supplies
.SH SYNOPSIS
.B iseg2dim
.I <options>
.B ...


.SH DESCRIPTION
\fBiseg2dim\fR is a server to control Iseg HV supplies using the DIM protocol.



.SH OPTIONS
.TP
\fB\-c\fR, \fB\-\-configfile\fR=\fIFILENAME\fR
read configuration file \fIFILENAME\fR instead of /etc/iseg2dim.cfg
.TP
\fB\-f\fR, \fB\-\-foreground\fR
do not detach from the controlling terminal


.SH CONFIGURATION FILE
.TP
\fBSERVERNAME\fR
the name that the server will register at the DIM name service. The default is "iseg2dim"

.SH SERVICE NAMES

\fBiseg2dim\fR uses a systematic naming scheme to organize information
about buses, crates, modules and channels in a tree. Different levels
in the tree are separated by '.', with the root of the tree at the
left. The root of the tree is the servername, by default 'iseg2dim'.
The available CAN buses are the immediate children of the top node,
i.e. 'iseg2dim.bus0', 'iseg2dim.bus1' etc. Currently, only a single
crate per bus is supported and will always be assigned the
name 'crate0', for a full name of e.g. 'iseg2dim.bus0.crate0'. Modules
are also direct children of a bus and are named 'modXX', where XX is
the 2-digit decimal address of the module on the bus. Note that
modules are not the children of a crate, as the CAN protocol used by
Iseg addresses modules by bus and not my crate as well. Each module
has one child per channel, named 'chXX', with XX being the 2-digit
decimal number of the channel.


.SH ALIASES

Aliases can be used to change the naming of DIM services described in
the section \fBSERVICE NAMES\fR. This can be used to give meaningful,
funtional names to these services. They can also be used to generate
names that are compatible with previos versions of iseg2dim that were
only able to handle a single CAN bus with a single crate.

Aliases are defined in the configuration file. The aliases in the file
are processed in the order in which they appear. The processing will
stop after the first match.

The aliases are defined in lines with three fields: first the word
ALIAS in capital letters, second a perl-compatible regular expression
and third a format string to define the alias name for the matched
service. The Boost::Regex library is used to perform the regular
expression matching and replacement, please refer to its documentation.

The regular expression has to match the complete name of a service. To
match arbitrary text at the beginning or end of the name, prepend or
append ".*" to the regular expression. The regular expression can
contain submatch groups, contained in parentheses, that can be
referred to by \\1, \\2 ...

The new service name will be formatted according to the second
argument to the alias command. References to the submatch groups
(\\1 ...) in the regular expression will be replaced with the
respective submatch. Afterwards, all occurences of $[...] will be
arithmetically evaluated and replaced with the result of the
evaluation. The evaluation supports integer arithmetics: addition (+),
subtraction (-), multiplication (*), division (/) and modulo (%) with
the usual operator priorities. The priority of the evaluation can be
changed with parentheses. 

.SH BACKLOG

\fBiseg2dim\fR can keep a backlog of the last messages that were sent
or received over a CAN bus. This can be dumped to a file after a crash
or when a SIGUSR2 is sent to the iseg2dim process. The number of
messages that will be stored in the the backlog can be configured with
the \fBBACKLOG_SIZE\fR option in the configuration file, the directory
where the backlogs will be dumped with the option \fBBACKLOG_DIR\fR. A
size of 0 will disable the backlog.

.SH FILES
.TP
.I /etc/iseg2dim.cfg
The system wide configuration file.

.SH BUGS
iseg2dim does not yet support multiple crates on a single CANBUS.

iseg2dim does not log off the modules at program termination. The
modules will not send announcements for a few minutes and will only
appear after that time.

So far, only device class 21 is implemented. Other device classes
should be straigtforward to implement once the need arises. 

.SH AUTHORS
Tom Dietel