Introducing CAPI 4 BSD
by Jan Stocker <Jan.Stocker@t-online.de>
Abstract
This article describes what CAPI is and how it is integrated in the FreeBSD system. Furthermore, it will show you how to setup an ISDN FAX server using CAPI 4 BSD and HylaFax.
Introduction
CAPI is a shortcut for Common-ISDN-API and defines an abstraction layer for different ISDN protocols, so an application can be coded independent of the used hardware. The interface, created by three ISDN hardware companies (AVM, Stollmann, Systec) in the year 1989, supported German ISDN (1TR6) and was called CAPI 1.1.
In 1994, ETSI (European Telecommunication Standardisation Institut) defined a new standard for D-Channel protocols. The outcome was CAPI 2.0. This version now allows the use of all common D-channel: Euro-ISDN, DSS1, AT&T ISDN (5ESS) etc., as well as different B-channel protocols: HDLC, T.30, T.30(Fax), Speech, X.25 with only one interface.
The functionality of CAPI 2.0 includes basic call control (connect/disconnect,send/receive data), DTMF detection/generation, multiple application support, multiple controller support, support for most supplementary services (Terminal Portability, Hold/Retrieve, Suspend/Resume, Explicit Call Transfer).
FreeBSD currently contains only a subsystem called ISDN 4 BSD. This module gives you access to the ISDN hardware using a proprietary protocol. The module's highest value is its ability to use the I4B devices for network connections. It also has some limited support for answering machine applications. But ISDN has one more big feature apart from voice and plain data connections: FAX. Nearly all FAX solutions require a CAPI 2.0 compatible interface, so FreeBSD users had to use their old analog modems for this job.
Thomas Wintergerst, who has been working on CAPI solutions for more than 10 years, implemented a complete CAPI 2.0 compatible interface for FreeBSD, which I present in this article with a focus on FAX.
CAPI 4 BSD
CAPI 4 BSD - short C4B - implements all API functions specified by CAPI 2.0. Aside from the application interface, C4B has drivers for AVM (B1,...), active ISDN hardware controllers. The author is also working on drivers for Digi Europe (ITK) and Eicon cards.
As for now, C4B is limited to active controllers only, because for passive controllers you need to implement all access and data control functions in nearly real time. For FAX connections in particular, this is a hard task (FAX G3 is made up of analog telephony and not plain data connection). Active controllers work mostly with DSPs doing the "analog" stuff and give you a fine interface. Today you can get a cheap AVM B1 ISA for 20 Euro and the PCI version for about 80 Euro on eBay.
First C4B alpha Version was thrown to the public in the year 2003 on July, 14th. The development for FreeBSD 4.x stops with V0.6 on 2003-03-10 and continues to V0.91 only for the FreeBSD version 5.x. The source files are mostly up to date with -current and can be altered for new versions very easily. Perhaps at the time that you read this, you can find C4B integrated in the base system.
C4B is based on following modules/programs:
- capidev - Creates the pseudo device /dev/capi20 building the bridge between kernel and user land.
- kcapimgr - This is the kernel module handling all transfer between CAPI and the hardware.
- avmaicctl - You need this tool to upload the AVM firmware to a specific AVM controller.
- libcapi20.so - This is a shared library for creating own CAPI applications.
- i4bcapimgr - It attaches a virtual controller for each ISDN controller for I4B. So, I4B is using C4B for accessing the active ISDN cards.
- capitest - This program is for test purposes only. You can send fax/voice data from a specific MSN/DDI to a number of your choice. There is also a full function test using both b-channels in a loop-back.
- capitrace - With capitrace, you can create a complete trace of both controller and application side. This is a helpful debug tool for finding connection problems.
C4B Installation
You need the C4B distribution files for patching the FreeBSD base system. The latest version can be downloaded directly from the author's homepage:
http://www.nord-com.net/thomas.wintergerst
Please download and extract the contents of the archive to a directory of your choice (not /usr/src).
$ cd /root && gunzip -c /mydownload/c4b-0.92.tar.gz | tar xvf -
The file "c4b/Readme" contains detailed installation instructions. For the impatient user: read here what to do:
First install all new files and patch some existing ones. You need to change to the directory matching your FreeBSD system version. Do not use the directory FreeBSD-Current; it only contains template files. For a recent -current use a directory with the nearest date, call the script "do-patches.sh" and have a look for error messages.
$ cd c4b/patches/FreeBSD-Current-040530 && ./do-patches.sh
Newer FreeBSD-5.2-current and FreeBSD-5.3 systems can not compile C4B anymore, you need to have a newer C4B than 0.92 or change two lines in usr/src/usr.sbin/c4b/capitrace/trace_message_print.cc on line 846 and 971. Replace
<< (char *) &(C_GET_BYTE (pTraceMsg->info.appl_get_serial_number.abBuffer [0]))
with
<< (char *) &(pTraceMsg->info.appl_get_serial_number.abBuffer [0])
After a successful run, your /usr/src directory contains now all required files for C4B. Because C4B normally is used as kernel module you do not need to edit your kernel configuration file. But there is one exception: If you are using I4B you need to disable - yes "disable" - all active controller devices now handled by C4B p.e. the AVM B1 (please read section "C4B & I4B"). Now build and install a kernel as you normally do:
$ cd /sys/i386/conf $ config GENERIC $ cd ../../compile/GENERIC $ make depend && make all && make install
There are some userland executables that you need to build. You can build each by hand (described by detail in the installation file comes with C4B) or by simply making a complete world.
$ cd /usr/src $ make buildworld && make installworld
C4B Configuration
If you are using an ISA controller, you need to tell the C4B subsystem what type of card you are using and what its configuration data is. FreeBSD 5.x supports device hardware configuration with a file /boot/device.hints. All PnP compatible PCI devices do not need to be configured by hand. The file /sys/i386/conf/NOTES contains all necessary information. The following lines must be added to /boot/device.hints for a standard AVM B1 installation. Please also make sure that your BIOS has allocated IRQ 5 for ISA devices, so it will not be used by other peripherals.
--- # AVM-B1 ISA hint.avmaic.0.at="isa" hint.avmaic.0.port="0x150" hint.avmaic.0.irq="5 ---
The AVM B1 has a small jumper on it. You need to set it to a free I/O port and this must match your line in device.hints. Furthermore, C4B needs to be initialized and the active ISDN controllers need to be fed with the firmware to work properly. Thomas worked out a rc-script doing this for you if the information is written to /etc/rc.conf. As usual, all possible variables are documented in /etc/defaults/rc.conf.
Enable C4B and set the driver to "avmaic" for AVM based cards
--- capi_enable="YES" capi_load_ctlr_driver="avmaic" ---
For the firmware download - or upload :) - there is a combination of 3 commands: First you need to define a unique name for your download command, in this example "b1" and two more assignments capi_<name>_cmd and capi_<name>_flags. avmaicctl needs to know which CAPI controller to use. In this case I use CAPI controller number 1 (because CAPI starts with 1 and not 0 like I4B). The firmware is located at /usr/share/capi/<vendor>, there is a special firmware for USA purposes. Please use this if you are located in the United States and have difficulties with the standard b1.t4 firmware.
--- capi_download_commands="b1" capi_b1_cmd="/usr/sbin/avmaicctl" capi_b1_flags="-d 1 /usr/share/capi/avmaic/b1.t4" ---
C4B uses syslog facilities to write messages in the logfile. The detail grade can be set in the file /boot/loader.conf with the line.
--- capi.capidev.loglevel = n ---
where n can be 0 for few messages, 1 for errors, 2 for information, 3 for trace and 4 for many debug messages. The loglevel can also be set with sysctl and an equally named variable. You can read all about this in the manpage for capidev
$ man 4 capidev
There are three more entries for setting up the capi device:
--- capi.capidev.devowner= <user id> capi.capidev.devgroup= <group id> capi.capidev.devmode = <mode> ---
However, I recommend using /etc/devfs.conf for such things, because functions with the same context should stay in the same position.
C4B Test & Debug
To get C4B up & running you must reboot your server after setting up C4B correctly. Boot messages and dmesg output must be something similar like this:
--- capidev: CAPI device created avmaic0: <AVM B1 ISA> at port 0x150-0x16f irq 5 on isa0 avmaic0: "AVMB1-1" successfully attached as CAPI controller 1 ---
If it does not work, look in the /var/log/messages file. FreeBSD cannot probe the IRQ because the IRQ was not allocated in BIOS for ISA devices and the given I/O port does not match the jumper settings, and so on. The program "capitest" has some functionality to make outcalls and accept incoming calls for fax and voice communications. Capitest needs a file to send. This is raw PCM a-law bit invers for voice calls (ask your favorite search engine for a converting tool); for FAX calls it sends raw SFF files, which are similar to TIFF-G3 but not the same.
Capitest can give you information about your installed ISDN card and the current C4B state. Just call
$ capitest -l -v
---
1 controller installed:
Controller 1
Name: AVMB1-1
Manufacturer: AVM Berlin GmbH
Type of controller: AVM B1 ISA
Driver name: avmaic
Driver unit number: 0
BSD driver version: 0.8
Manuf. firmware version: 49.2
Serial number: 2012394
Number of B-channels: 2
Global options: 0x00000039
Internal controller support
DTMF support
Supplementary services support
Channel allocation support
B1 protocol support: 0x4000001f
64 kbit/s with HDLC framing
64 kbit/s bit-transparent operation with byte framing
V.110 asynchronous operation with start/stop byte framing
V.110 synchronous operation with HDLC framing
T.30 modem for Group 3 fax
Unknown B1 protocol bit #30
B2 protocol support: 0x00000b1b
ISO 7776 (X.75 SLP)
Transparent
LAPD in accordance with Q.921 for D-channel X.25 (SAPI 16)
T.30 for Group 3 fax
ISO 7776 (X.75 SLP) modified to support V.42bis compression
V.120 asynchronous mode
V.120 bit-transparent mode
B3 protocol support: 0x8000003f
Transparent
T.90NL with compatibility to T.70NL, in accordance with T.90 Appendix II
ISO 8208 (X.25 DTE-DTE)
X.25 DCE
T.30 for Group 3 fax
T.30 for Group 3 fax with extensions
Unknown B3 protocol bit #31
---
The next thing you should try is to call a phone next to you. Do not worry about the missing PCM file--just send some noise over the line:
$ capitest -o /root/.cshrc -tv 0477775886
A complete self test is done by using X.75 protocol for data transfer:
$ capitest -s -tx 04777775886
While playing with capitest please note: All AVM B1 ISA cards can not send and receive fax documents at the same time--only PCI cards can manage that! Furthermore, capitest has some more nice features, such as a batch service. This is useful when making stress tests on your hardware. Please look to the man page for info (man capitest).
The application "capitrace" can create a complete dump of messages sent from and to the controller over the capi20 device. This does not include libcapi20, but it does not matter because the functions are nearly thin glue. Some parameters define the detail of the output, if you want everything just use
$ capitrace -a -bl2048 -td+ -tb+ application.bin
for a complete trace on the application layer, including all 2048 bytes for each package. The controller layer can be accessed by using "-c <controller nr>" instead of "-a" and you can specify both options in one call:
$ capitrace -a [options..] application.bin -c 1 [options..] controller.bin
The created files contain the trace as binary data and need to be converted for human reading with:
$ capitrace -i application.bin
For a detailed trace file the conversion may take several minutes, so please be patient.
C4B & I4B
If you are using I4B for network access with your active ISDN card, some things change. You must disable the AVM B1 device in your kernel configuration file for I4B, because I4B and C4B can not access the ISDN card on hardware level. (If my mind does not play tricks on me, I think you have to leave at least one passive device in the kernel to get I4B compiled, but that may be old stuff.)
So how is I4B creating a ISDN connection? C4B comes with a module called i4bcapimgr. This piece of code adds a virtual controller to I4B for each real controller C4B knows. As for now, I4B acts like a CAPI application talking to the ISDN line over C4B and - as CAPI defines - any other CAPI application can use the ISDN card, too. The rc script for C4B takes loads the i4bcapimgr depending on a running I4B subsytem, so no more changes are needed.
ISDN FaxServer
Now, after having a running C4B system, let us give a FAX server. Hylafax is a complete client/server fax solution providing ISDN access with an additional capi4hylafax package.
Hylafax
Hylafax is found in the ports system ports/comms/hylafax, and does everything you need: client connection, spooling, document converting and so on. It does not have a dependency on ghostscript, but you need it if your clients do not create TIFF-G3 documents, like Pyla. So first install ghostscript. I prefer not using X11 extensions for a server:
$ cd /usr/ports/print/ghostscript-gnu-nox11 && make install clean
Now you are ready to install hylafax itself:
$ cd /usr/ports/comms/hylafax && make install clean
Do not enter anything special when asked. Just use the defaults, except choosing paper format when living in Europe (Press 13, write "A4", <Enter>). I do not know why the server application for HylaFax is not being installed correctly, but doing it like this needs only a few hand strikes:
$ chown uucp /usr/local/sbin/hfaxd $ chmod 4555 /usr/local/sbin/hfaxd
This gives hfaxd the correct rights to communicate with the module faxqd and read access to the spool directory. You also need to create a startup script for hylafax in /usr/local/etc/rc.d to get it up at boot time. There is a sample file called hylafax.sh.sample but it leaks hfaxd, so you must add hfaxd start and shutdown lines. The following script (/usr/local/etc/rc.d/hylyfax.sh) is complete and can be used as is:
---
#! /bin/sh
# hylafax startup example.
# be sure to initialize the followings:
# server: /usr/local/sbin/faxsetup
# modems: /usr/local/sbin/faxaddmodem
# incoming calls: /etc/ttys
case "$1" in
start)
if [ -x /usr/local/sbin/faxq ]; then
/usr/local/sbin/faxq && echo -n ' faxq'
fi
if [ -x /usr/local/sbin/hfaxd ]; then
/usr/local/sbin/hfaxd -i hylafax -o fax && echo -n ' hfaxd'
fi
;;
stop)
killall hfaxd && echo -n ' hfaxd'
killall faxq && echo -n ' faxq'
;;
*)
echo "Usage: `basename $0` {start|stop}" >&2
exit 64
;;
esac
exit 0
---
Do not forget to set execute rights on this file
$ chmod a+x /usr/local/etc/rc.d/hylyfax.sh
Continuing with the hylafax general setup. The setup is nearly self explaining. You can enter your dialing configuration, but please answer the question "Do you want to run faxaddmodem to configure a modem [yes]?" with NO, because we will later create a configuration file for a special CAPI modem.
$ /usr/local/sbin/faxsetup
Capi4Hylafax
Capi4Hylafax is the add-on for Hylafax concerning CAPI support. This FreeBSD is not in the ports system at the time I write this article, but will be in near future and the following patches may be out-of-date. But for now, you need to download and patch capi4hylafax like this:
Download http://www.shellbang.org/files/port-comms-capi4hylafax-20030809-01.tbz and unpack it to /usr/ports. Now you have a port for capi4hylafax in your local ports tree. Capi4Hylafax needs automake and the dependecy tracking in current ports system is buggy, so you may install automake by yourself, if it is not installed anyway.
$ cd /usr/ports/automake && make install clean
AVM, creator of the capi4hylafax source codes, assumes that the CAPI implementation has a buffer for eight data packets, but CAPI only defines that the minimum must be seven. FreeBSD implementation really has only seven. You can manage that dynamically in your CAPI application but AVM has not implemented such a data flow mechanism. Therefore, we need to change the define CAPI_MAX_OUTSTANDING_FRAMES from eight to seven. The next version of C4B may support eight buffers, because AVM cards can internally handle that, too.
$ cd /usr/ports/comms/capi4hylafax $ make extract $ make patch
Edit work/capi4hylafax-20030809/src/capi/capi2def.h and change the line
--- #define CAPI_MAX_OUTSTANDING_FRAMES 8 ---
to
--- #define CAPI_MAX_OUTSTANDING_FRAMES 7 ---
Now you can install cypi4hylafax.
$ make install clean
After the successful installation, we must write the configuration for the CAPI pseudo modem. There is a short script to give you a text ui for that:
$/usr/local/sbin/c2faxconfig
The output is written to the file /var/spool/hylafax/etc/config.faxCAPI. Please edit this file for further information, p.e. DDI setup and replace all "/var/spool/fax" entries with "/var/spool/hylafax". You also must add a line for the new CAPI sendfax programm to the main hylafax configuration at /var/spool/hylafax/etc/config:
--- SendFaxCmd: /usr/local/bin/c2faxsend ---
Hylafax needs the program c2faxrecv running for using the CAPI. This is no typo: c2faxrecv is not only for receiving fax pages over CAPI--it also adds the pseudo CAPI modem to hylafax on the fly, which is needed to send a fax. So if c2faxrecv is not started, hylafax does not know the CAPI fax modem and can not send a fax. To start c2faxrecv at boot time at the following line to /etc/rc.conf
--- capi4hylafax_c2faxrecv_enable="YES" ---
Clients
You are now ready to use hylafax on the local host, but a client/server system wants to be used remotely. So add a user to the configuration file /var/spool/hylafax/etc/hosts.hfaxd. An entry is something similar like passwd file, but different :) Login names max contain regular expressions and the passwords are crypted. A line
--- faxuser ---
adds a user "faxuser" with no password and access from any computer. That¿s enough for the start. You also can use "faxadduser" for adding remote user to hylafax.
There are so many clients out there, so I do not want to make a list here. On the Hylafax home page you will find a list with commercial and free software products that talk to the hylafax server. There are also applications that do not need the hfaxd server, i.e. one solution uses a special printer setup on the server and a web gui for entering numbers to dial; others extract the number from the PostScript file.
One application not linked that I want to mention here is Pyla. Pyla is a non-commercial solution written in Python and can be used on different plattforms. For MS Windows clients http://www.teamsw.it/pyla/pylasetup.html gives you a detailed instruction how to setup your client.
Conclusion
C4B evolved to a complete and stable CAPI implementation for FreeBSD. We now have the possibility to port standard CAPI based programs to our favorite OS in an easy way. Hylafax with Capi4Hylafax is the first and easiest solution using C4B, making FreeBSD into a good ISDN fax machine.
Links
C4B - http://www.nord-com.net/thomas.wintergerst/
CAPI4Hylafax (FreeBSD Port) - http://www.shellbang.org/freebsd/portsandpatches.html
HylaFax - http://www.hylafax.org
CAPI4Hylafax - http://www.avm.de
Pyla - http://www.teamsw.it/pyla/
Copyright
(C) 2004 Jan Stocker
Redistribution of this text is permitted as long as the copyright is retained and all text altering is marked by author and date.
Version 1.0 - 2004-04-28
Version 1.1 - 2004-06-27 CAPI4Hylafax FreeBSD port moved to my site
Version 1.2 - 2004-09-19 Update to C4B 0.92 / Bugnotice CapiTrace
