Product: CAPI4Linux, module: CAPI4HylaFAX
Operating System: Linux
Version: 01.03.00
Build: 05.08.12
This document contains information and instructions on:
1 General Information about Fax G3 over the CAPI 2.0 Interface with AVM ISDN-Controllers
1.1 HylaFAX and Connecting to ISDN Using CAPI 2.0
1.2 Important Information for the Installation of the HylaFAX Interface for CAPI 2.0
2 Installing the HylaFAX Interface for CAPI 2.0 in SUSE
2.4 Sending Faxes with HylaFAX
3 Installing the HylaFAX Interface for CAPI 2.0 in Other Distributions
4 Instructions about the File Format and on Converting Existing Files
5 Instructions for Operation with Multiple AVM ISDN-Controllers
6 Instructions for Fax Polling
7 Additional Information Sources
Analog Fax G3 service over the digital ISDN network requires that the data transmitted be transformed from analog to digital or from digital to analog (A/D or D/A transformation), as well as signaling conform to the Fax G3 standard (such as ITU-T.30).
As part of the CAPI 2.0 standard, this protocol mechanism is subject to compulsory standardization (TB.30 modem for Group 3 fax). The implementation of this protocol by the manufacturer of the ISDN-Controller is optional. If Fax G3 is implemented in CAPI 2.0 drivers, software developed for the CAPI 2.0 interface can access the ISDN-Controller directly and thus quite easily. All AVM ISDN-Controllers for ISDN basic access currently supported by CAPI4Linux offer Fax G3 support over the CAPI 2.0 interface.
Note that when passive ISDN-Controllers like the AVM FRITZ!Card are used, all calculations for A/D or D/A transformation must be carried by the CPU of your computer system. This can result in a relatively high system load, especially when Fax G3 documents are received. Active controllers such as those from the AVM ISDN-Controller Family B1 all include their own chip, thus reducing the system's load.
The current version of HylaFAX unfortunately does not offer direct CAPI 2.0 binding; only a binding for analog modems. Until now only active ISDN-Controllers like the AVM ISDN-Controller B1 could be connected to HylaFAX by patch.
This "CAPI4Linux" package allows the use of practically any ISDN-Controller equipped with a fax-capable CAPI 2.0 driver compliant with the LINUX CAPI 2.0 specification. See also the CAPI 2.0 Specification at:
http://www.capi.org
Thus it is possible to fax with the popular passive ISDN-Controllers even in Linux. Thanks to CAPI 2.0, multiple ISDN services can be used at the same time, such as Fax G3 reception and a connection to the Internet via pppd. The ISDN B channels are assigned automatically by the CAPI 2.0 driver.
Up to four active AVM ISDN-Controllers with CAPI4Linux drivers can be installed on each system. Even mixed configurations are possible (for instance, one AVM ISDN-Controller B1 ISA plus two ISDN-Controllers C2). The CAPI4HylaFAX module then has to be modified for operation with multiple ISDN-Controllers. Please see the additional information in section 3.
In any system, only one passive ISDN-Controller (e.g. FRITZ!Card PCI) can be installed using a CAPI4Linux driver.
The latest version of HylaFAX and more information are available at
http://www.hylafax.org.
From the current HylaFAX version on (included on the SUSE 8.1 CDs), HylaFAX always transfers seven parameters to HylaFAX faxrcvd. SUSE Linux versions 8.0 or below or original HylaFAX versions expect fewer parameters. The difference from the original HylaFAX lies in the restricted analog model of the former, which does not include the important interpretation of the ISDN feature MSN or DDI for e-mail forwarding.
The new CAPI4HylaFAX installation script automatically changes an existing faxrcvd script so that older faxrcvd scripts can continue working with the current CAPI4HylaFAX version.
In line 33, for example, the script looks like this:
# faxrcvd file devID commID error-msg CIDNumber CIDName destination
#
if [ $# -lt 7 ]; then
echo "Usage: $0 file devID commID error-msg CIDNumber CIDName destination"
fi
The following table specifies the faxrcvd parameters in brief:
| Parameter | Event Type |
| file | indicates the received TIFF or SFF fax file |
| devid | relates to the virtual modem device needed by CAPI to send a fax (faxCAPI, for example) |
| commid | continuous identification number for incoming calls (faxes) |
| error-msg | includes an entry indicating that problems occurred during fax reception |
| cidnumber | fax number of the sender; if no number is transferred, the caller ID is shown here |
| cidname | name of the sender's fax device. |
| destination | extension number of the recipient (MSN or DDI)*. |
*If you want to use the current CAPI4HylaFAX version in one of the SUSE versions between 7.2 and 8.0, and if you would like to forward faxes from a certain MSN or DDI, you have to adapt the the faxrcvd script manually, since the order of parameters varies depending on the HylaFAX and SUSE versions used.
Further information about faxrcvd can be found in the corresponding manual page, displayed by entering the command "man faxrcvd" at a console.
| NOTE | If you are using "GlobalCall", please note the following: "GlobalCall", especially popular in Austria, does not transmit your main number, thus deactivating the parameter "IncomingMSN" in the "config.faxCAPI" file. Therefore all voice and fax calls coming in at the main number are accepted. If you want to deactivate the automatic call acceptance, you have to set the parameter "AcceptGlobalCalls" to "0". In all other cases the pre-set value "1" is correct. |
More information about HylaFAX and how to use of the "faxrcvd" script is available at
www.hylafax.org.
Please note that the following prerequisites have to be met before starting installation:
| NOTE | AVM supplies pre-compiled patches for SUSE which permit an especially simple installation for these distributions. If you use a different distribution, see the corresponding information in the section "Installing the HylaFAX Interface for CAPI 2.0 in Other Distributions". |
| NOTE | Please remove any old version of CAPI4HylaFAX before installing a new version! |
| NOTE | If you would like to send or receive a fax without HylaFAX support, simply install stand-alone operation without automatic HylaFAX configuration by entering "./install -s". With "./install -h" you get an overview of parameters with extended installation options. |
| Parameter | Effect |
| OutgoingMSN | Defines the outgoing MSN to be used at the ISDN basic rate interface. In this way you can indicate a specific MSN from the block of numbers for outgoing connections to perform MSN-specific accounting. For some PBXs with internal S0 bus you must indicate the MSN of the extension used. |
| IncomingMSNs | Defines the outgoing MSN to be used at the ISDN basic rate interface. If several ISDN devices with the same ISDN service indicator are used at the basic rate interface, each of these devices must be unambiguously addressed via a specific MSN. If this parameter is NOT defined, all incoming calls with the service indicator "Group 2/3 Fax" and "Telephony (analog)" will be accepted. If several MSNs are to be used, they must be separated by commas. |
| DDIParams | Defines parameters for operation at a PBX ISDN point-to-point line with direct dial-in (DDI). "DDIOffset": indicates the number of digits which precede the extension number. Example: 39976-0 => DDIOffset=39976 (base number) "DDILength": indicates the number of digits of the extension number. Example: 4711 => DDILength=4 "IncomingDDIs": List of extension numbers that should be accepted. |
| FaxNumber | Defines the fax number which appears in the fax header at the recipient. ATTENTION: HylaFAX cannot process empty spaces. Use the entry "." instead. This entry is automatically converted into a blank. |
| FaxIdentifier | Defines the local name (station ID) shown in the fax header at the recipient. |
| NumberPrefix | Defines the digit required to get an outside line when operating at a PBX (generally "0"). |
| ATTENTION | To change the settings of the CAPI4HylaFAX module after installation, or to configure more than one active AVM ISDN-Controller for fax operation with HylaFAX, you MUST perform the respective settings manually in the config.faxCAPI file. This file is used by HylaFAX as well as by the applications "c2faxsend" and "c2faxrecv": /etc/config.faxCAPI (in SUSE Linux) /var/spool/HylaFAX/etc/config.faxCAPI (HylaFAX 4.1.x) |
| Sending | c2faxsend -f TIFF -d [TelNo] [TIFF file] c2faxsend -f SFF -d [TelNo] [SFF file] |
| Receiving | c2faxrecv -f TIFF c2faxrecv -f SFF |
c2faxsend -vf TIFF -d [TelNo] fritz_pic.tifThe section "Instructions about the File Format and on Converting Existing Files" presents more information about the TIFF format used.
To work with HylaFAX, a number of preparatory steps are performed automatically by the installation script during installation (see the section "Installation", step 5).
If HylaFAX is to be used, note the following:
To send, just enter "sendfax -d [TelNo] file". The file can have almost any format. The programs "file" or "a2ps" must be able to read the format so that the file can be converted correctly first into PS format and then into TIFF format. Graphic frontends are also available to make working with HylaFAX somewhat easier. For more information, see the documentation at:
If faxes are to be sent directly from an application, the printer configuration must be adapted in the application. Usually a command for printing can be entered in the application, usually just "lpr". Replace this with "sendfax -d [TelNo]". These functions are program-dependent and should be documented in the application Help file.
Once a fax is received via HylaFAX, "root" receives a mail sent by the script "faxrcvd" reporting that a fax has been received.
When using the fax module "c2faxrecv" in stand-alone operation, you can achieve analog fax reception by using the supplied script "sample_faxrcvd".
Once a fax has been received, the script specified in the configuration file ("faxrcvd" in HylaFAX) can be run with the following parameters:
| Stand-alone operation | [Result Code] [CAPI Disconnect Reason] [Sender ID] [Called Number or DDI] [No of Pages] [File(s)] |
| HylaFAX mode | [faxrcvd file] [devID] [commID] [error-msg] [CIDNumber] [CIDName] [destination] |
More details about fax reception with HylaFAX are provided in the HylaFAX documentation.
Even if you use any distributions or kernel versions other then SUSE, it is usually no problem to use CAPI4HylaFAX. Only if the installation routine of CAPI4HylaFAX reports missing (program) libraries is it necessary to compile the sources supplied in the directory "/src". To simplify this process, AVM supplies complete "makefiles". For more details about compiling sources, see the file "README.src".
TIFF (Tagged Image File Format) files must correspond to the specification "Class F for facsimile (TIFF Class F)", based on the TIFF 6.0 specification. In addition, the file must contain one-dimensional Huffmann coding. This format was specified in "Group 3" by the CCITT (International Telegraph and Telephone Consultative Committee). For more information about TIFF format, see the "Developer" division of Adobe Systems Incorporated at: http://www.adobe.com
To convert a postscript file into a TIFF file conform to the fax application, the following command can be used to activate Ghostscript:
More information about the SSF format is documented in the CAPI 2.0 specification at http://www.capi.org.gs -dBATCH -dNOPAUSE -sDEVICE=tiffg3 -sOutputFile=[Name of tiff file] [Name of postscript file]
Up to four active AVM ISDN-Controllers can be addressed via the CAPI 2.0 interface. It is also possible to install controllers for different bus systems such as PCI, ISA and PCMCIA. For details about the controller installation, please refer to the documentation of the driver module Linux CAPI 2.0.
The module CAPI4HylaFAX simultaneously supports the operation of multiple active AVM ISDN-Controllers sending and receiving in HylaFAX. After installing the module CAPI4HylaFAX, some modifications are necessary in the configuration file "/etc/config.faxCAPI". This is necessary because the graphic installation routine described above is designed for one controller only. Other parameters for the operation of several AVM ISDN-Controllers in the configuration file "config.faxCAPI" are documented in the file itself. After modifying the configuration file the module "c2faxrecv" must be stopped and restarted in order to activate the modification.
A pre-configured sample script is enclosed for the operation with the AVM ISDN-Controller C4 or the AVM ISDN-Controller C2. The script is called "sample_AVMC4_config.faxCAPI". This script simplifies the configuration of multiple-channel controllers for CAPI4HylaFAX: just modify the script according to your individual technical surroundings (MSNs etc.).
Fax polling is now supported with this version of HylaFAX. Operation in client mode is possible, i.e., CAPI4HylaFAX can be used to poll fax documents. It is not yet possible to provide callers with fax documents to poll (Server Mode).
Execute the following file to start fax polling in stand-alone mode:
c2faxsend -vf TIFF -d [TELNo] -P [e-mail address]
Execute the following file to start fax polling in HylaFAX mode:
sendfax -d [TELNo] -p
In either case, a script is started after the fax is received and the e-mail address and the corresponding fax document is provided. The script is defined in the configuration file "config.faxCAPI" under the following parameter:
PollRcvdCmd
The applications interface CAPI 2.0 can be downloaded free of charge from the following Internet site:
Additional questions about the CAPI 2.0 Specification should be asked in the Usenet at the following URL:
Discussions of ISDN and Linux issues can be found at:
news:de.comp.os.unix.linux.isdn
Information about an already existing CAPI 2.0-based program for receiving faxes (G3) and voice calls is provided at the URL:
http://capircvd.berlios.de/index_eng.php3
For more information on using AVM products with Linux, see the AVM web site at:
Because there are so many different kernels and distributions, e-mail support is limited to the operating systems and kernel versions described in the section "Installation Requirements". This support is limited to the actual installation up to the successful completion of the test connection or the test fax over CAPI drivers and the CAPI4HylaFAX module in combination with AVM DSL/ISDN-Controllers using the provided installation programs. For questions about network configuration, integrated functions of the operating system Linux and applications from other manufacturers, please contact the relevant manufacturer or the support service of the distribution used. Please address your questions concerning configuration and operation of HylaFAX to:
www.hylafax.org
The AVM web site offers detailed information and updates free of charge. Visit the site at:
www.avm.de/en
All programs and drivers available on AVM's Internet site can also be downloaded from the AVM Data Call Center (ADC).
Please try all of the information sources described above before contacting AVM support.
If these instructions and the various information sources have not helped to resolve your problem, contact AVM Support for additional technical assistance. You may send your support requests to AVM by e-mail. Support inquiries can be sent to AVM using the e-mail form provided at the Internet address:
www.avm.de/en
Fill out the form and mail it to AVM Support by clicking the "Send" button.
EOF
SAS; SR; 08/2005