Chapter 1. Getting Started

Table of Contents

Requirements and installation of CapiSuite
Requirements
Installation
Updating from previous versions
How CapiSuite works, how it is configured and started
How does CapiSuite work?
Configuration of CapiSuite
Startup of CapiSuite
Features and configuration of the default scripts
Script features
How the scripts work
Script configuration
Deleting old files
Using CapiSuite together with the default scripts
Receiving calls
Doing a remote inquiry
Sending fax jobs

Requirements and installation of CapiSuite

Requirements

Hardware and drivers

As CapiSuite uses the CAPI (Common ISDN Application Programming Interface) for accessing your ISDN-hardware, you'll need a card for which a CAPI compatible driver is available.

Currently these are all cards manufactured by AVM and some Eicon cards. If you have one of the passive cards of AVM, you'll have to download and install their CAPI drivers.

There are also some distributions (e.g. current versions of SUSE) which include the Capi4Linux drivers from AVM already - you'll only have to activate them (use YaST2 in SUSE Linux). If you own an active card of AVM (e.g. the B1, C2 or C4), then you'll have everything you need already installed.

No, there's no way to get it working with the old ISDN4Linux interface. Perhaps there never will be one as the ISDN4Linux project meanwhile provides a CAPI compatible interface in the mISDN project - CapiSuite certainly also works with it.

CapiSuite has mainly been tested on AVM ISDN cards, esp. the Fritz!PCI, the Fritz!USB and the B1 on the i386 platform but there should be no problem with other CAPI-compatible drivers for other cards or on other platforms. Nevertheless, some features aren't mandatory for all CAPI-compatible cards, so perhaps you may not be able to fax or to switch from voice to fax mode with all cards.

Software

CapiSuite depends on some packages which must be installed before CapiSuite can be used.

I will list them here with a short information why this packages are needed and where to find further information on how to install them. It may be always a good idea to check the installation tool of your favourite distribution first and see if they're included with it before trying to download and install them from the net. Don't be afraid, because there are so many - most of them are included in nearly every distribution and perhaps are already installed on your system.

Python >= 2.2

CapiSuite uses an embedded Python interpreter to interpret the given scripts - so you'll need an installed and working version of Python. This should be included in mostly every up-to-date Linux distribution. For further infos on Python, a nice tutorial and much more, please go to http://www.python.org

sox >= 12.17.3

This is the swiss-knife for converting audio formats. It's not required by the CapiSuite core, but will be very helpful if you want to hear or record the voice files used for calls on your machine. It's also required if you want to use the default scripts of CapiSuite. I'll bet this is included in your distribution and most likely already installed on your system. Just try to start sox to get sure. As Helmut Gruber pointed out, you need at least version 12.17.3, as this version started to handle inverse A-Law files. You'll find more details on http://sox.sourceforge.net

sfftobmp

CapiSuite will save fax files in the CAPI specific format Structured Fax File (SFF). sfftobmp is a small but useful converter to convert this files to more common formats like JPEG, TIFF or BMP. Get it on http://sfftools.sourceforge.net/sfftobmp.html. It's again not needed by the CapiSuite core, but by the default scripts.

sffview

This tool is a simple but useful SFF viewer. It's not needed by any CapiSuite component, but very useful if you just want to see a fax file without the need to convert it first. You can get it from http://sfftools.sourceforge.net/sffview.html.

tiff2ps

A small utility to convert TIFF files to the Postscript format. It's needed by the default script to convert faxes to PDF files (SFF->TIFF->PS->PDF :-} ). It's often included in a package called tiff or tifftools. Details on http://www.libtiff.org

ps2pdf

Again a small utility for the SFF->PDF chain - this time for the conversion of Adobe PostScript to Adobe PDF. It's part of Ghostscript, so you most likely have it already. (http://www.gnu.org/software/ghostscript/ghostscript.html)

current Ghostscript with cfax patch

Current Ghostscript versions will include a device to create the above mentioned SFF files. If you have an older version, you'll need the patch from http://sfftools.sourceforge.net/ghostscript.html. To see if your GhostScript version already has this patch, please call gs --help and see if you can find the device cfax in the long list of supported devices.

jpeg2ps

The jpeg2ps command is used to convert color fax files to the PostScript format for mail delivery. It's not so important, unless you want to be able to receive color faxes. Unfortunately, there's currently no way to disable the reception of color faxes with AVM cards due to a bug in the AVM CAPI driver. So if someone sends you a color fax (which seems to be a very rare case), you'll need this package - unless you'll get a mail stating this error. If your distribution doesn't have this packages, you can download it from http://www.pdflib.com/jpeg2ps/.

As the color fax protocol uses concatenated JPEG files for transferring multiple pages, you should also download and apply my multipleJPEG patch from http://www.hillier.de/linux/jpeg2ps-multi.php3

Installation

First of all, I would suggest to check if your CAPI-driver is setup correctly. To do this, simply run capiinfo on a root shell.

If you get many lines of output, your CAPI driver works. If you just get an error message, you'll have to install CAPI-compatible drivers. Refer to the documentation of your ISDN card vendor, your Linux distribution and/or some ISDN mailing lists for this, please. If you really can't find anyone to support you in doing this, you may ask on the CapiSuite mailing lists for support as last resort.

The rest of the installation depends on wether you use binary or source packages for installing CapiSuite. If you don't want to change the CapiSuite sources, I would recommend you to use the binary packages when available for your distribution and platform.

You can download both binary packages and sources from the download section on http://www.capisuite.de/download. If you built packages for other distributions not yet available, please send me your link and I'll happily include it there...

Installation from binary packages

If you can get binary packages for your distribution and platform, I would advise to use them. There are many binary packages of CapiSuite available for different distributions maintained by different people. It's also part of current versions of SUSE, Debian and Gentoo.

If you managed to install CapiSuite on a system not mentioned below, please tell me and I'll include the instructions here. If you have created binary packages for other distributions, I'll be also happy to point to your download section or make them available on my page.

Now everything should be setup ready to run. So please read on in the section called “How CapiSuite works, how it is configured and started”.

Installation from RPM packages (SUSE, Fedora, Mandrake & Co.)

To install the CapiSuite RPM packages you can either use your favorite setup tool - either provided by your distributor or the community - or you can do manually (as root):

rpm -Uvh capisuite-version.rpm
Installation from other packages

Please refer to the documentation of your distribution and the information given in the packages or on the homepage of the maintainers. If someone wants to write a section about these packages, please contact me.

Installation from the source packages

If there are no binary packages you can use or if you like to do everything on your own, you can get the sources from the download section.

Download the newest source tarball (capisuite-X.Y.tar.gz) from the CapiSuite homepage and copy it to some location. Go there and issue the following commands:

./configure
make
su # get root now
make install

This will install CapiSuite completely in the /usr/local-tree. If you want it to stay in other directories, please see the commandline-help printed by

./configure --help

for options to customize the installation directories.

Installation from Subversion

If you want to live on the bleeding edge and always test the newest features, you may also checkout the current sources of CapiSuite from the repository.

This is not recommended unless you want to test the newest features or want to help in developing CapiSuite! The development sources may do anything, may not work or not even compile. Do this on your own risk!

You'll need installed and working versions of the usual development tools like GNU make, gcc/g++ and also the components described above (esp. development packages of Python).

If you want to build the documentation out of the sources, you'll also need Doxygen and correctly installed Docbook/XML tools.

For instructions on where to find the repository and how to checkout the sources, please refer to the download section on the CapiSuite homepage on http://www.capisuite.de.

After you checked out the sources to some directory, please do

make -f Makefile.cvs

Now, you can continue with the normal installation process as described in the section called “Installation from the source packages”.

Updating from previous versions

This section will give you an overview of how to update CapiSuite from earlier versions.

In general, the usual update mechanism depending on your installation method should be used - that means the update features of your package managers if you installed from binary packages. If you installed from sources, you should save your configuration files before doing make install. As this is done like for any other software package you use, we won't go into further detail about that here.

What this section should mainly cover are the changes in the configuration files and requirements to other tools between different versions, so that you'll be able to update your configuration quickly. For a more complete list of new features and important changes, please refer to the file NEWS distributed with the CapiSuite packages. In addition, all single changes in the different source code files can be found in the ChangeLog, which, however, will only be interesting for developers, I suppose.

From 0.4.4 to 0.4.5

The default scripts now use an SMTP connection to localhost instead of calling the sendmail command manually as previous versions did. This was changed because the other mechanism had many stability problems in the past. This means, you now have to have a running SMTP daemon listening on your localhost. As this is the default configuration of most distributions, this should be no problem.

In answering_machine.conf and fax.conf, two new options have been added: fax_email_from and voice_email_from allow the configuration of the from address CapiSuite uses when sending mails to the user. These new entries are optional - if you don't set them, the user name is used as from address as in previous versions.