PBX4Linux

Software based ISDN Private Branch Exchange for Linux






By Andreas Eversberg (Jolly)

(http://isdn.jolly.de)




Documentation for Version 2.5



















































This page is left blank.




Index




  1. Introduction


  1. Hardware Requirements


  1. Download & Installation


  1. Configuration


  1. Using PBX4Linux


  1. Tuning


  1. Debugging


  1. Architecture


  1. Support


  1. References & Relates Projects


Appendix



1


Introduction


1.1 What is PBX4Linux?


PBX4Linux is pure software based ISDN PBX, that connects external lines, internal telephones, and optionally voice over IP. It is designed to run with Linux only because it uses the kernel’s mISDN passive driver by Karsten Keil. It can work together with OpenH323, that is a voice over IP implementation complied to the H.323 ITU-T standard.



1.2 Philosophy behind


At the end of 2001, I found out, that my ISDN card has a chipset capable of connecting telephones to it. This is called the NT-Mode. So my card can be used to transfer information between telephones and my Linux box. Normally ISDN cards transfer information between a computer and the public telephone system. But at this time there was no protocol for Linux kernel that could talk to ISDN telephones.


My first idea was to use a telephone to make voice over IP calls. Instead of messing with headsets, I wanted to just pick up the phone, get a dial tone, and dial the IP number. On the other side, I wanted to have another phone, that rings and shows me the IP number of the caller. I know, that there are IP phone already but they are more expensive than ISDN phones. So I started to expand the Linux kernel to be able to handle telephones connected to my ISDN card. The patch was written for the old ‘HiSax’ driver. I hated that patch because it was another dirty addition. I was glad that Karsten Keil wrote the new modular ISDN driver that gave me a well defined API and real multipoint NT-mode. I added some features to the new driver, so real time cross connections, conferences, DTMF decoding and tone generation is possible.


While writing the expansion of the kernel driver, I designed the PBX4Linux, that is now also capable of connecting calls between connected telephones and external ISDN lines connected to the public telephone system, as well as voice over IP using OpenH323 library.


I wanted to have a PBX, that provides features I am missing in standard products, like letting a call ring on my telephone at home and at the same time on my mobile via external call. The called phone, that picks up first, gets connected, the other gets released. Another idea was callback, which helps me to reduce the costs of mobile calls.


Many features followed: Deletion of digits while dialing after pick-up, an answering machine that records during the announcement to trick the caller, and conferences with no member limit but the resources of available channels.


During this book, you will learn about the features it has, how it works and, how to set up your own software based ISDN PBX.



1.3 Who wrote it?


My name is Andreas Eversberg and I live in the northern part of Germany, called ‘Schleswig-Holstein’. I currently work for a telephone company, called KomTel, which is a full service provider for telephone lines, internet and leased lines in Schleswig-Holstein. I do administration of the network elements like subscriber line cards and ADSL routers. I started writing the PBX and the kernel driver, six months before I got the job at KomTel. I see this job as a start of managing life and getting used to “work” and of course to learn and earn money.


My email address is ‘jolly@jolly.de’. My homepage is ‘http://www.jolly.de’. The PBX4Linux page is ‘http://isdn.jolly.de’.



1.4 How much does it cost?


It costs nothing at all. As long as you use it for non commercial purpose, I will not charge you. Using this PBX in your company to handle the daily business is not a commercial purpose in this context. See the appendix for copyright information.



1.5 Some definitions of terms in this document



Private Branch Exchange (PBX), also called PABX, is a small private telephone system. It features internal calls without getting changed, because calls are routed internally. It has connectivity to the telephone network in most cases. It provides more features than the telephone network provides.




H.323 is a standard for making calls via packet switched IP networks. It specifies, how voice (and call control) is transferred over IP. H.323 is defined by the International Telecommunication Union (ITU). To be able to interconnect two persons using H.323, both must have an IP connection. If one party is reachable via public telephone network, PBX4Linux can be used as H.323 gateway to transfer telephone calls from and to IP networks.




Extensions are telephones connected to a PBX. PBX4Linux supports individual configuration of extension. Each extension is defined by a number. Many telephones can have the same extension’s number. The extension is identified by the outgoing caller ID of the telephone. On incoming calls, the internal port(s) is/are defined by the extension’s configuration, where to route the call to.




A telephone is connected directly via ISDN card to the PBX. The card runs in NT-mode, that is simulating an NT1 with hard and software layers.




An external telephone line (from a local telecommunication provider) is connected to the PBX. Multiple external lines may be used for more channels.




Audio samples are not directly transmitted via B-channel. First a 12 bit sample is sampled from the audio input and then converted into 8 bits. This is done by reducing the dynamics for high amplitude samples, to increase the number of samples available for low amplitude. There are two different ‘laws’, describing the amplitude ranges. The conversion can easily be done by a table of 256 entries (to decode) and 65536 samples (to encode from a 16 bit sample). In Europe, we use “a-law”. In America they use “mu-law”. The mu-law also allows to drop the lowest significant bit. This is used in America for telephone exchanges that provides only 56 bits. To read more about the coding, refer to any “how-ISDN-works” manual.




There are two different types of interfaces:



The Primary Rate Interface has one 64 bit D-channel and 30 B-channel (channel 0 is used for synchronization). The electric interface is also called “s2m” or “PRI” and is defined in the ITU-Standard “G.703”. The bit rate is 2048Kbits/s. The electrical version of a “G.703” interface is limited to several meters of cable length, so a modem must be used. “HDSL” and “SDSL” provide transmission via none insulated twisted pair copper wires over some kilometers. An older standard is called “u2m”. PRI interfaces are also called PMX (Primary Multiplex).


The Basic Rate Interface has one 16 bit D-channel and two B-channel. The electrical interface is also called “S/T” or “S0”. It supports point to multipoint connectivity. Also this interface has only a limited range of cable length, so “uk0” or “up0” is used to transfer the signal over several kilometers.



An ISDN interface has several types of channels. The D-channel is used to transfer signaling information (data channel). The audio data in transferred vi B-channel (binary channel). Also any data transmission like fax or internet is transferred via B-channel. Some interfaces have overhead, monitor and echo channels. These are only relevant between interfaces and do not transfer information between subscribers.



2


Hardware Requirements


2.1 ISDN cards


The first thing needed for the PBX, is of cause at least one ISDN card. At least two cards are required to interconnect internal telephones with external telephone lines. Any card can be used that is supported by the kernel’s mISDN driver (the next generation passive ISDN driver by Karsten Keil):



Please mail your experience with untested cards, when using the kernel’s mISDN driver.


In order to connect telephones directly to an ISDN card, it must support NT-Mode. Then it is possible to use it as internal ISDN port. There currently there are these type of chip sets, that support NT-Mode hardware layer:



All of these chips have a small ‘Dom’ of Cologne on the top:



The following cards do have the required chip set capable of NT-Mode:



Please mail me other cards you know, that have an NT-Mode capable chip sets. The card will look like:


(Figure: Cards with HFC-PCI, thanx to Ulrich for the pics)



2.2 Connect ISDN telephones to your ISDN card.


Normally cards run in TE-Mode, which means ‘Terminal Equipment’. Terminal equipment is e.g. an ISDN telephone, an ISDN card, a fax machine, or any other terminal to places calls, dial into the internet, or send and receive faxes. The NT is the small box where all ISDN terminals are connected, which means ‘Network Termination’. It is the small little box also known as ‘NTBA’ (Germany) or ‘NT1’ (everywhere else:).


What must be done, to connect telephones to an ISDN card? Don’t be shocked when you read the list. It is much easier, as you will find out later in the text. Here is a list of things to do:



In order to bring a HFC card into NT-mode, the following module parameter is used:


$ modprobe hfcpci protocol=0x12 layermask=3


But this will be explained later…


It is not possible to use just a cross-over cable for Ethernet. ISDN is differently connected than Ethernet. Additionally terminals and cards have no termination. ISDN cross connection is done by connecting the inner wires (pin 4 and 5) with the wires around them (pin 3 and 6). Pins 1, 2, 7 and 8 are not used. Some special PBX telephones use these pins for extra power supply. Termination is essential, even if the ISDN cable would have almost zero length. All this can be done by using an old (even broken) NT1 (NTBA). Telephone companies throw them away when they are broken. Most times the power supply still works. If you measure about 40 volts between pin 3 and 4, as well as ping 5 and 6, you know that your NT1 is good enough for using it as a power supply. Be sure that the terminator switches inside are turned on.


An NT1 (NTBA) has three types of connectors. The first connects to the underground wire that is connected to the telephone company. The second connects to the ISDN telephones. The third is connected to the power line. Follow the steps to get an NT1 connected to an ISDN card instead of the telephone network:


The VERY SIMPLE way:


Take an ISDN or Ethernet cable and cut it in the middle. Reconnect the inner pins (4 and 5) of one end with the pins around them (3 and 6) of the other end. Do it vice versa. (Connect 3 with 4, 4 with 3, 5 with 6, 6 with 5) Now you have an ISDN cross over cable, that is different to an Ethernet cable. Just connect the ISDN card with the cross over to one plug of your NT1, and a telephone with a normal cable (not crossed) to the other plug. Connect the power line of your NT1 or telephone and you are done. You will be able to connect only one telephone, because both plugs are used. Don’t use the cross-over cable to directly connect your card to your telephone, unless your card or your cable has termination and your telephone has own power supply.


The COMFORTABLE way:


Step 1: Open the small door to get access to the wire clips. If it has no door, just take a screw driver and open the case. Be aware of high voltage at the switched power supply, even if it is not connected to the power line. Capacitors may hold high voltage for a long time. Inside are 4 clips to connect an ISDN cable directly to it, rather than connecting it to one of the RJ45 plugs. Each NT on the picture has six yellow clips: One pair (to the left) are used to connect the U-Bus (underground wire), the two pairs (to the right) connect to the S-Bus (telephone). The S-Bus is directly connected in parallel to the two rj45 plugs.


(Figure: NT1 with door open)


Step 2: Find out which clip inside the NT1 is connected to which pin on the rj45 plug. Therefore connect an ISDN cable to one of the two ISDN jacks. Take an Ohm-Meter and find out which clip is connected to which pin of the ISDN cable. Use a small peace of wire, to help the meter’s probe get into the hole of the clip. Pin 4 and 5 as well as 3 and 6 of the ISDN cable, is connected through the coil inside the NT1. The coil has low resistance, so your Ohm-Meter will show that they are connected. So you cannot determine between pin 4 and 5 as well as between pin 3 and 6. There are two clips connected to pin 4 and 5 as well as another two to clips connected to 3 and 6. It doesn’t matter which clip is connected to pin 4 and which is connected to pin 5, since the polarity doesn’t matter. (Pin 3 and 6 respectively)


Most NT1 in Europe name the 4 pins: A1 and B1, A2 and B2. Do the following connections:



(Figure: Find clips)


Step 3: Take another ISDN cable or Ethernet cable and cut off one end. Take the inner pair of the cable (pin 4 and 5) and connect them to the clips, that are connected to the outer pins of the ISDN jacks (pin 3 and 6). Do this with the inner pins of the cable respectively. Again, polarity of a cable pair doesn’t matter for the ISDN bus.


9

(Figure: cable connected to the clips)


Step 4: Use the Ohm-Meter again and verify the connection between the cable, that is connected to the clips, and the cable connected to one of the jacks. Pin 4 and 5 should now connect to pin 3 and 6 and vice versa.


(Figure: Verify cross connection)


Step 5: Connect the cable, which is connected to the clips, to the ISDN card, that should run in NT-Mode. Be sure that termination is switched on. Inside the NT1 are two switches, that must be ON. This is the default.


(Figure: cable connected to the ISDN card)


Step 6: Connect an ISDN telephone to the ISDN cable, that is connected to the ISDN jack. Also connect the power cable.


(Figure: complete setup)


Since there is nothing connected to the U-Bus (underground wire), the internal electronics is disabled, because it gets its power from the U-Bus (not from the power line). Only the power supply is connected to the coils (transformer) inside the NT1 providing power for telephones, as well as termination. This is why the NT1 can be broken. Only power supply must work.


NOTE: If you like to connect more than one telephone, you might experience clicks and sound problems. Use 50 ohm instead of 100 ohm termination. This can be done by adding another 100 ohm resistors in parallel with the ones in the NT1. Two 100 ohm resistors become 50 ohm! One resistor must be connected between pin 3 and 6, and the other between 4 and 5. You may figure out yourself how to connect the cable plus the resistors. Maybe you use a soldering iron.



2.3 Interrupt problems


One serious problem of installing HFC cards are interrupts. Some PCI slots share the same IRQ. Be sure that every HFC card has its individual IRQ. When booting the PC, the IRQ is shown of each PCI card installed. If two cards share the same IRQ the HFC-PCI driver may fail. I experienced this as I installed three cards in one PC.


Another problem might occur with older PC main boards using Fritz cards and IDE hard drives. The interrupts of the IDE controller causes loss of frames coming from the ISDN cards. This results in gaps of the audio during hard drive operation. I use a Fritz-Card, which causes losses of interrupts during IDE hard driver access. The HFC-PCI card works fine. This problem doesn’t occur with my PCI Adaptec SCSI controller in the same machine.


If anyone has experience with certain ISDN cards in combination with frame drops, let me know.


2.4 Hard disk


The size of a hard drive doesn’t matter, as long as no audio recording is done. Since the PBX has a call recording feature (and answering machine), smaller hard drives get filled quickly during long calls. A recoding with 8 bit mono causes a recorded file of 8 kilobytes per second or 8000 bytes. The best quality of recoding is 16 bit stereo. This causes 32 kilobytes to be written down during one second. If the call lasts one hour, PBX4Linux would record a file of 115.2 megabytes or 115200000 bytes. Even with 8 bits mono (or law codec) is used, the recording would have still a size of 28.8 megabytes or 28800000 bytes. If the PBX would support the LPC-10 codec to record audio, the size would be 1.44 megabytes for recording one hour. A year of audio data could be compressed down to about 12.6 gigabytes. In this case, don’t worry about size of your hard drive anymore. Any volunteers are welcome to implement the LPC-10 codec… Note that the call recording is just a feature that is not turned on by default.


There are no requirements for hard drive’s speed, since the load will be 800-1600 kilobytes per seconds for 100 calls at a time. Hard drives are much faster these days.



2.5 Memory


Almost every Linux box uses swap memory. PBX4Linux disables swapping of it’s code and data memory. Other programs still use swap. If the PBX allocates new memory, that is not available, the memory of other processes must be written to disk first. This causes a high delay of call processing, which also causes audio jitter. Also if other programs on the Linux box are swapped (like the telnet daemon), the PBX will stop for a short period of time, caused by hard disk traffic. To reduce the risk, you may turn off swap memory when running the PBX. Telephone calls are a real-time task, that don’t like delays of any undefined time. Therefore increase physical memory, so the Linux box would run without swapping memory.


It depends on what’s running on the Linux box. Just boot your Linux, and after starting PBX look how much of memory is left. Turn off swap, and check what’s left:


$ swapoff -a


$ free

total used free shared buffers cached

Mem: 52376 50364 2012 0 868 6064

-/+ buffers/cache: 43432 8944

Swap: 0 0 0


In this example from my Linux box, there is about 2 megabytes of free memory. Note that the cached memory of about 6 megabytes will be available any time. The cached memory holds recent data from hard drive, that will be accessed faster when accessed again. In this case there are 8944 kilobytes (almost 9 megabytes) of memory still available without swapping. After a while, the machine without swap may run out of memory. I experience this sometimes, because I have many other processes running, like web server, PPPoE and proxy.


Note that a PBX without using OpenH323 would have much less memory consumption, as with OpenH323. You better have more than 64 megabytes of memory. But today, memory is no matter of price anymore. It is much better to leave swap turned on, have much memory, and no other programs running (except for some small tools, like ftp, telnet and ssh daemons).



2.6 CPU


I have no experience with CPU usage. Making an external call, the CPU usage (AMD K6-200) is between 0.5% and 3.5%. On one H.323 call to an internal telephone, it is about 10%. If anyone has more experiences, please let me know. I recommend at least 200 megahertz for the PBX.



2.6 PCM


Almost all ISDN controllers support PCM bus to interconnect them. The HFC-4S / HFC-8S / HFC-E1 support a PCM bus of 128 timeslots with two banks. It is possible to connect up to 128 callers on one bus. This makes large PBXs possible, where 128 calls can be made without CPU load for audio transfer. The driver automatically detects these cards and does hardware crossconnections and conferencing. There are boards available for PBX4Linux. Mail to isdn@jolly.de for more infos.



3


Download & Installation


3.1. Install mISDN driver


Why mISDN driver and not HiSax driver:



You may choose a binary version or install the source as described here. In case of a binary release, you need only one tar archive to download. It will have all modules, libraries and files needed for PBX4Linux. It is compiled for Intel 586 IBM compatible PC with Linux 2.6.0 or higher. To install the binary archiv, download it, untar and install:


$ tar xvzf pbx4linux-binary-xxxx.tar.gz


$ cd pbx-binary


$ make install


There executables will be installed at “/usr/local/bin/”. All support files will be installed at “/usr/local/pbx”. Also the kernel modules will be installed at “/usr/local/pbx/modules”. To load these modules, you need to specify the path when using “genrc”. “genrc” is described later and is used to load and unload kernel modules.


Alternatively the source version can be installed. In order to run the PBX, the kernel with mISDN is needed, as well as the “mISDNuser” package. Download the latest sources from ‘http://isdn.jolly.de/’, the following packages are needed:



You may use an existing kernel and patch it with mISDN driver or install a complete new kernel. For a new kernel remove the old link “/usr/src/linux”. If there is no link, rename or move the “linux” directory, that may be located under “/usr/src”. Otherwise you might overwrite your current kernel. Unpack the source:


$ cd /usr/src/


$ tar -xvzf linux-x.x.xx_mISDN.tar.gz


$ ln -s linux-xx.xx.xx_mISDN linux


$ cd linux


Instead of downloading the complete patched kernel, you may also download the patch of the mISDN driver. Install as shown:


$ cd mISDN


$ ./std2kern [-h]


This tool will copy the mISDN source from the current directory to the kernel source. Give “h” option to get a list of options. By default the driver will be installed in “/usr/src/linux/” .


Then configure your Kernel:


$ cd /usr/src/linux


$ make mrproper


$ make menuconfig


You may copy the “.config” file from your previous kernel source directory, to keep your setting. Copy the file after “make mrproper” and before “make menuconfig”:


$ cp ../linux-your.old.versrion/.config .


WARNING: Don’t just copy the config file, if the kernel version changes too much (e.g. 2.4 to 2.6). Always check the kernel features. Features may have different names in the config file, so they will be disabled in newer versions.


Enable the following kernel features, using “make menuconfig”:



A card, that supports NT-Mode, you may want to use. Otherwise you will not be able to connect telephones. If your card is an HFC-S PCI, say yes to the following:



Also say yes to any card you may want to use for external line.


Save and exit kernel configuration, and continue to build the kernel source:


$ make dep (not needed for kernel 2.6)


$ make bzlilo


$ make modules


$ make modules_install


If everything compiles without errors, Reboot! Warnings about unused variables and wrong prototypes can be ignored of course. After reboot, run “depmod”, in order to create dependencies, so the ISDN modules will be found. In newer kernels the “depmod” is done when installing the modules.


To be able to use the “/dev/mISDN” device, it must be created:


$ mknod /dev/mISDN c 46 0


It is a character device with major number 46 and minor 0. But before the device exists, the modules must be loaded. Read on, on how to create an rc-script to load and unload the modules.



3.2. mISDNuser


In order to access mISDN device driver and use the NT-mode, install mISDNuser package.


$ tar -xvzf mISDNuser-x.xx.tar.gz


$ cd mISDNuser


$ make


Two libraries will be created:



Also some other utils will be part of the package. Just ignore them. Be sure to uncompress mISDNuser the same source directory where you will uncompress the PBX. The paths to the libraries are relative in the Makefile of the PBX. If you choose different locations, you must edit the Makefile.


The libmISDN.a provides direct access to the mISDN device. It will be used to communicated directly with the protocol stacks of mISDN.


The libisdnnet.a provides NT-mode protocol. The TE-mode is already part of the kernel.



3.3. PBX4Linux


Download the PBX4Linux at http://isdn.jolly.de/download. Uncompress it:


$ tar -xvzf pbx4linux_xxxx.tar.gz


$ cd pbx4linux


Edit the “Makefile”. At the line "WITH-H323", write “#” in front of it to comment it out. You will need it later when you like to add H.323 support. But first get the PBX running without H.323.


Compile and install the PBX:


$ make


$ make install


Configuration files, documents and data files will be installed by default at: “/usr/local/pbx”. Edit the “Makefile” in order to choose a different location. Don't worry about your old configuration files, you might already have from older version. They will only be copied, if they don't exist already. If they don’t exist, default configuration files will be installed. The binaries are installed at “/usr/local/bin” by default.


To see a list of start options of PBX4Linux, just enter:


$ pbx


To run PBX4Linux as background task, enter:


$ pbx fork


A daemon fork will be done, so closing the shell will not interrupt the PBX. Also use this for startup, if the PBX should be started at boot time.


Note: In order to run PBX4Linux, the mISDN driver must be loaded. Follow the next chapter on how to configure the driver, and creating a start and stop script.



3.4 OpenH323


First visit the OpenH323 project homepage at ‘http://www.openh323.org’. OpenH323 comes with two packages:



OpenH323 consists of object orientated classes to build H.323 connections. It must have “pwlib” installed in order to compile and run. Be sure to get the latest version from the download area, even if you have them already installed with your distribution. Follow the installation instruction for each package. Here is a short instruction on what to do. If you have trouble, get help from the OpenH323 page. In this instruction we use “/usr/src/” to install all packages to. Be sure that the source tree of PBX4Linux is also located in “/usr/src/”. The PBX uses relative links to the source tree of OpenH323.


NOTE: You may skip this part if you do not want to use the PBX with H.323 support. Try the PBX without H.323 support first, and do not experience all problems at once.


If you have H.323 already installed with your distribution, you must change the following variables in the “Makefile”:


H323_INCLUDE = -I../openh323/include

H323_LIB = -L../openh323/lib

PWLIB_INCLUDE = -I../pwlib/include/ptlib/unix -I../pwlib/include

PWLIB_LIB = -L../pwlib/lib


They must point to the correct location, where “pwlib” and OpenH323 is installed. Otherwise you might get compile errors.


Uncompress “pwlib”. Use the same directory where you uncompressed the PBX source:


$ cd /usr/src


$ tar -xvzf pwlib.tar.gz


Compile “pwlib”:


$ cd pwlib


$ make both


This will take a while, so drink a cup of coffee or visit your children again .


If no error occurred, proceed with installation:


$ make install


$ ldconfig


$ cd ..


Uncompress “openh323”. Use the same directory where you uncompressed “pwlib” and the PBX source:


$ cd /usr/src


$ tar -xvzf openh323*.tar.gz


$ cd openh323


Compile:


$ make opt


Take another cup of coffee, since this will take really longer. Be sure to have allot of memory, in order to handle all the include files during compilation. Use a minimum of 128k swap space, or you might run out of memory. It helps to have lots of system memory, to increase compile speed. If you have less than 64k, it may take a whole day, caused by massive swapping. If you have trouble, read “ReadMe.txt” and follow the installation instruction there.


If no error occurred, proceed with installation:


$ make install


$ ldconfig


$ cd ..


In order to compile the PBX with H.323 support, edit the file "main.h", and uncomment the "WITH-H323" define. Remove the ‘#’ in front, and the PBX will compile using OpenH323:


$ make


$ make install


The following error may occur during compilation, if the paths to the include files of “pwlib” are not correctly set:


…

from /usr/local/include/ptlib/timer.h:355,

from /usr/local/include/ptlib/timer.h:355,

from /usr/local/include/ptlib/timer.h:355,

from /usr/local/include/ptlib/timer.h:355,

from /usr/local/include/ptlib/timer.h:355,

from /usr/local/include/ptlib/timer.h:355,

from /usr/local/include/ptlib.h:154,

from main.h:52,

from main.c:26:

/usr/local/include/ptlib/timer.h:147: macro or `#include' recursion too deep

/usr/local/include/ptlib/timer.h:355: macro or `#include' recursion too deep

make: *** [main.o] Unterbrechung


In this case, the include variables in the “Makefile” do not point to the correct location. The file “timer.h”, that should be found in the UNIX specific include directory (pwlib/include/ptlib/unix), is included from the file “timer.h”, that is located in the main “ptlib” directory (pwlib/include). In this example above, the compiler finds the wrong file, becaue the UNIX specific include directory is not given or doesn’t exist. This causes a recursion in this case, because the compiler doesn’t know about the UNIX specific directory. It is necessary to have the correct order specified in the “Makefile”:


PWLIB_INCLUDE = -I/path/to/pwlib/include/ptlib/unix –I/path/to/pwlib/include



4


Configuration


4.1. Start and stop mISDN


The following example will assume that your have a HFC-PCI card and a Fritz-Card installed. The Fritz-Card is connected to a normal multipoint ISDN line. Multipoint lines are used in most places. It is possible to connect up to eight telephones to it; the PBX may be connected parallel with other telephones. The HFC-PCI card is connected to a telephone, as described above. With this setup, your PBX will be able to forward calls between external lines and internal telephones.


Many things must be done to setup ISDN4Linux. Therefore I wrote a small tool, that creates a shell scrip to start and stop kernel’s mISDN driver. It comes with the PBX4linux package and will be installed with it. Run it with:


$ genrc


This program generates a script, which is used to start/stop/restart mISDN

driver. All configuration of cards is done for using with the PBX.


Enter mode of your ISDN card #1. Should it run in NT-mode (for internal

phones), or in TE-mode (for external lines)? If you do not like to add more

cards, say 'done'.

[nt | te | done]: te


The ‘te’ keyword tells ‘genrc’, that the first card (Fritz-Card) should run in TE-Mode. It will be connected to an ISDN line. Therefore the card must be configured as a “terminal endpoint”.


Is your card #1 connected to point-to-multipoint line, which supports multiple telephones on one line (Mehrgeräteanschluss) OR is it a point-to-point line which is used for PBX and supports extension dialing (Anlagenanschluss)?

[ptp | ptm]: ptm


The type of line we will use, is multipoint. This is the standard type of ISDN lines all over the world.


Select driver of ISDN card #1.


(1) HFC PCI (Cologne Chip)

(2) AVM Fritz PCI

(3) Seldbaur FAX

(4) Winbond 6692 PCI


Select card number[1-n]: 2


Enter ‘2’ to select Fritz-Card. If your card is not in that list, there is no driver for it or ‘genrc’ may be out of date.


Summary: Card #1 of type AVM Fritz PCI will run in TE-mode and point-to-multipoint-mode.


Enter mode of your ISDN card #2. Should it run in NT-mode (for internal

phones), or in TE-mode (for external lines)? If you do not like to add more

cards, say 'done'.

[nt | te | done]: nt


The next card we use is the HFC-PCI running in NT-Mode. We want to connect a telephone to it. NT means “network terminator”. In this case our Linux box is the network where the telephone is connected to.


Select driver of ISDN card #2.


(1) HFC PCI (Cologne Chip)


Your card will run in NT-mode. The shown cards are capable of providing

hardware layer for NT-mode.

Select card number[1-n]: 1


We are not asked for multipoint, because only multipoint mode is supported for NT-mode. The selected card is HFC-PCI.


Summary: Card #2 of type HFC PCI (Cologne Chip) will run in NT-mode and point-to-multipoint-mode.


Enter mode of your ISDN card #3. Should it run in NT-mode (for internal

phones), or in TE-mode (for external lines)? If you do not like to add more

cards, say 'done'.

[nt | te | done]: done


There is no third card, so we use the keyword ‘done’. Now we are asked to enter dsp-module’s options and debugging values. Just enter ‘0’ for every value.


Enter options of mISDN_dsp module. For a-LAW, just enter 0.

For u-LAW enter 1.

[0..n | 0xn]: 0


Enter debugging flags mISDN core. For no debug, just enter 0.

[0..n | 0xn]: 0


Enter debugging flags mISDN core. For no debug, just enter 0.

[0..n | 0xn]: 0


Enter debugging flags of cards. For no debug, just enter 0.

[0..n | 0xn]: 0


Enter l1 debugging flags of driver. For no debug, just enter 0.

[0..n | 0xn]: 0


Enter l2 debugging flags of driver. For no debug, just enter 0.

[0..n | 0xn]: 0


Enter l3 debugging flags of driver. For no debug, just enter 0.

[0..n | 0xn]: 0


Enter dsp debugging flags of driver. For no debug, just enter 0.

[0..n | 0xn]: 0


Debugging is explained later in this book. Just enter ‘0’ for the first time. If you experience crashes, read on, on how to use these values.


Enter location of the mISDN modules. Enter '0' for kernel's default location. Enter '1' for binary distribution's location '/usr/local/pbx/modules' or enter full path to the modules dir.

[0 | 1 | <path>]: 0


Depending on the location of the modules, give '0' or '1' here. '0' for default location (source distribution) or '1' for location of the binary distribution.


File 'mISDN' is written to the current directory.

$


Now the following shell script is written in the current directory with the name “mISDN”:


# rc script for mISDN driver


case "$1" in

start|--start)

modprobe mISDN_core debug=0x0

modprobe mISDN_dsp debug=0x0

modprobe mISDN_l1 debug=0x0

modprobe mISDN_l2 debug=0x0

modprobe l3udss1 debug=0x0

modprobe hfcpci protocol=0x12 layermask=0x3 debug=0x0

modprobe fritzpci protocol=0x2 layermask=0xf debug=0x0


sleep 1

;;


stop|--stop)

rmmod hfcpci

rmmod fritzpci

rmmod mISDN_isar

rmmod l3udss1

rmmod mISDN_l2

rmmod mISDN_l1

rmmod mISDN_core

;;


restart|--restart)

sh $0 stop

sleep 2 # some phones will release tei when layer 1 is down

sh $0 start

;;


help|--help)

echo "Usage: $0 {start|stop|restart|help}"

exit 0

;;


*)

echo "Usage: $0 {start|stop|restart|help}"

exit 2

;;


esac


To load ISDN4Linux, just enter:


$ sh mISDN start


To unload the modules just enter:


$ sh mISDN stop


I will now explain what the script does, if the start option is given:


“modprobe mISDN_core debug=0x0” will load the kernel mISDN driver core.


“modprobe mISDN_dsp debug=0x0” will load the real time audio processor.


“modprobe mISDN_l1 debug=0x0” will load the layer-1 protocol for TE-mode.


“modprobe mISDN_l2 debug=0x0” will load the layer-2 protocol for TE-mode.


“modprobe l3udss1 debug=0x0” will load the layer-3 protocol for TE-mode.


“modprobe hfcpci protocol=0x12 layermask=0x3 debug=0x0” will load the card driver for all HFC cards. Protocol type of 0x12 means NT-mode (0x10) and DSS1 (0x02). Layermask of 0x3 means layer-0 (bit 0, card) and layer-1 (bit 1). Layer-2 and layer-3 are realized via libisdnnet library.


“modprobe fritzpci protocol=0x2 layermask=0xf debug=0x0” will load the card driver for all Fritz cards. Protocol type of 0x2 means TE-mode (0x00) and DSS1 (0x02). Layermask of 0x7 means layer-0 (bit 0, card), layer-1 (bit 1), layer-2 (bit 2) and layer-3 (bit 3).


“sleep 1” will wait some time until all cards are registered.


Look into the system log. You will see some information while loading the modules. Also errors will show up there. In order to see the current configuration, start the PBX with the query option:


$ pbx query


** PBX4Linux ** Version X.x (XXX 200x)


Port 1: NT-mode BRI S/T interface port (for phones)


Port 2: TE-mode BRI S/T interface line (for phone lines)


$


Connect an ISDN telephone as described above, and pick up the phone. You will not get a dial tone from the kernel. In order to get a dial tone, the application PBX4Linux must be running. But before running the PBX, you must configure interfaces and “extensions”.


4.2 PBX lines


A PBX line, also known as point-to-point line, is only capable to connect one PBX (or a special telephone) to it. But it provides dialing of extensions. The PBX, connected to this type of ISDN line, is able receive incoming calls, after the first digit behind the main number is dialed. It is controlled by the PBX, when the number is complete. It depends on the provider, how much digits can be dialed after the main number. The international convention of the maximum length of a phone number is 13 digits. If the county code has two digits (49 in Germany) and the area code has three digits (212 for the city Solingen), and the main number has six digits, then there are two more digits that will be routed to the PBX line. Of course the PBX can define by itself when the number is complete. Inside Germany, more digits are allowed. The ‘German Telekom’ for example forwards up to 17 digits. The company, I work for, forwards up to 24 digits after the area code. The PBX will signal, when the number is complete. This is supported by the PBX4Linux.


Another advantage of a PBX line is the ability to have more than one ISDN line for the same main number. One ISDN line can handle two calls only at a time. The number of simultaneous calls can be increased by heaving more than one line. PBX4Linux also supports this. There is no know limit, except for the number of cards, that fit into your Linux box.


Note that PBX lines might get monitored by the telephone company, because they are more expensive and more important than normal ISDN lines. In this case, talk to your telephone company to ignore alarms because every reboot, crash or ever restarting of the mISDN driver will cause alarms.


To tell mISDN to use a PBX line, you must set the card into point-to-point mode. This will automatically done when using “genrc”. The protocol for the card driver would be 0x22. (0x20 for PTP-mode, 0x02 for DSS1)


$ modproble fritzpci protocol=0x22 layermask=0xf debug=0x0


This will be included in the “mISDN” shell script, if the option “ptp” is selected when running the “genrc” tool.


PBX lines may also be multipoint. You will be able to connect normal telephones to it. In cast of PBX4Linux it makes no difference. If telephones would be connected parallel to the PBX line, dialing of extension digits will not work when one phone on the bus is ringing.


Another type of PBX line is the PMX line or “primary rate multiplex” line. This type of line provides 30 B-channels in Europe and 22 B-channels in the USA. It is used for really big PBXs. It is also possible to cascade multiple PMX lines to one PBX. I already implemented a driver, to support the European PMX chipset “HFC-E1”.



4.3 CLIP No Screening


“CLIP No Screening” or “No Screening CLIP” is a special agreement with your telephone company. Normally caller IDs sent on outgoing calls, are checked against the numbers that are assigned to your ISDN line. If you send a caller ID, for which you have a number assigned, the telephone company will forward it to the called user. If the caller ID you specify doesn’t match with any of your assigned numbers, the main number assigned to you, is used. So it is not possible to fake caller IDs, and pretend that you are your ex-girlfriends new boyfriend, or the boss of your neighbor. But sometimes you may want to pretend that you are the boss of your neighbor, especially when she calls your PBX, and it forwards the call to your mobile telephone using a second line. On the second line to your mobile, the caller ID of the caller of the first line (the boss) is used. You will see when your mobile telephone rings, that the boss calls and not just your stupid main number of your telephone line.


Another way to use this, is when you connect two PBXs. Lets assume you make an H.323 call to another PBX, that transfers the call for you to the public telephone system. In this case you want to send the caller ID of the PBX, you are calling from, and not of the other PBX, that transfers the call.


There are lots of things to use it for. Some of them are not very nice, but most of them are quite funny. I have this feature on my PBX line, for the reasons described above. Ask your local telephone company for the agreement. Note, that this feature is part of the basic ISDN standard ITU-T Q.931, so it is conform, to make this feature available to you. If your telephone company tells you, that this feature is not legal, tell them about the standard.


The caller ID, sent on a normal ISDN line, is normally the local telephone number of type “unknown”. The telephone company will add the national and international prefix in front. When using “CLIP No Screening”, the caller ID must be sent by the PBX including all prefixes. There are three common types of caller IDs that can be sent: Type “subscriber” will just send the caller ID without any prefix. The called party that receives this caller ID will just see that number, as you specified, everywhere in the world. Type “national” must be sent with area code and number. The called party’s Telephone will automatically add the national long distance prefix in front, so it must be omitted. Type “international” must be sent with country code, area code and number. The called party’s Telephone will automatically add the international access code in front, so it must be omitted. Because PBX doesn’t know what access code the called party must dial, it just sends the type “international”, and the prefix is added by the called party’s telephone.


It the connected ID is transmitted without checking, it is called “COLP No Screening”.



4.4 CLIR Ignore


The most wonderful feature that an ISDN line can ever have is “CLIR Ignore”. CLIR stands for “Caller Line Identification Restriction”. The caller is able to hide the caller ID. If a call with an restricted ID is received, the telecommunication system will delete the number. Only the information, that the ID is restricted, is transferred. In Germany most telephone lines restrict caller IDs. It is regulated by the “Regulierungsbehörde RegTP”, that a call which is made anonymously, should not presented to the called party. The law says, that the called party has a right to know who is calling. This is quite strange.


If “CLIR Ignore” is provided to your ISDN line, the caller ID is transmitted even if the caller doesn’t want it. You could see every caller’s ID in your log file. You could always reply a call if you were absent. This feature is used by the police and emergency phones in order to call back, if the caller hangs up. The number will be transmitted with the information, that it should not be displayed. Normally the telephone company deletes the number if it should not be displayed.


Once I enabled the “CLIR Ignore” feature on my telephone line for one minute, to see how the caller ID is transmitted. In fact, a restricted caller ID is transmitted with the information, that it should not be presented. The PBX4Linux also supports suppression of the restricted caller IDs, if your have the “CLIR Ignore”-feature on your ISDN line. Of course the PBX4Linux also has the “CLIR Ignore” feature, that is called “anon-ignore”. It displays anonymous external calls (if the “CLIR Ignore” feature is provided on your ISDN line) as well as anonymous internal calls.



4.5 Previous through-connect


Whenever you make a call, you get tones and patterns from your external line: You hear the dial tone of the local exchange, the ringing of the remote exchange and sometimes announcements. All this happens before and after the called party answers. Also you don’t get charged for it.


It is possible to send own tones during ringing or any stage of call setup, instead of the standard tones of your local exchange. A caller will not get a plain ringing tone, he will hear your ‘music’ or whatever you send him. There are three things required to send own tones before you answer a call:


  1. You must have a PBX line, because during call setup there cannot be multiple telephones sending their tones. A PBX line only talks to one PBX and so an audio channel can be assigned before answering of a call.

  2. You must have the special feature enabled on your local exchange (telephone company). On Siemens switches (EWSD), the feature is called “PTRUCON” and is available at Version 15 of the APS (firmware). You may ask your telephone company to enable it for your, but don’t expect them to do it in Germany. Tell me if you are successful.

  3. You need to enable the ‘inbandpattern” option in ‘options.conf’. See below for configuration. This options will indicate that tones are available at any state of the call.


The procedure of sending own tones is supported by the PBX, and is specified in the ISDN standard Q.931 Annex K. Note that only the audio path to the caller may be connected through, not the path from the caller to the PBX, so this is no ticket to make free calls.


The feature is mainly used for call forwarding through the PBX. If a forwarded gets answered, it will take a while until the connect message is received and forwarded by the PBX. This can cause the first second of the answered call to be lost. In case of previous through-connect, the audio path is connected to the forwarded party prior answer, and so the caller will hear as soon as the party answers.


What do you think about an answering machine that makes you charge only after the beep?



4.6 Leased lines


There exist three types of ISDN basic access leased lines:



Both ends of a leased line are terminated by an NT1 (NTBA). On each side, one ISDN card may be connected, both running in TE-Mode. Since leased lines are statically connected, no call setup must be done. The data can be just transferred between both ISDN cards.


It is possible to connect a card, running in TE-Mode (hardware layer), to one end of the leased line, where the NT-Mode protocol (software layer) is used. On the other end, telephones can be connected. A 144Kb leased line is required, because the D-channel must also be transmitted. It is then possible to use the leased line to connect telephones far, far away from the PBX. I have never tested this setup, but it should work. Any card can be used of course, since the hardware layer of this card is running in TE-Mode. For this case, contact me, so I can add this feature to the PBX4Linux.



4.7 General options


The first thing that is done, when the PBX4Linux is started, it loads the file “options.conf”. The default file is located at “/usr/local/pbx/options.conf”, if the default installation path is used. The file contains allot of keywords and comments. Comments start with “#”. Here is a description for every keyword used in this file:



Use this keyword to specify the debug flags. This can be:



The flags can be given decimal or hexadecimal using the “0x” prefix. Possible flags are defined in “main.h” header file. The definitions begin with “DEBUG_*”.


Default: Debugging is tuned off by default.


Example: “debug 0x8000” turns graphical call state debugging on by default.



A PBX transfers signaling information as well as audio data. For the audio data it is essential that the PBX responds as fast as possible. Therefore the Linux OS provides a scheduling algorithm to provide real time processing. “SCHED_RR” (round robin) is used which allows one task with the highest priority to be processed until it waits for an action. Be sure to have the highest priority, so no other program will use CPU if PBX4Linux needs to. The priority must be between 0 and 99. If no priority is given, the scheduler is not changed, real time processing is disabled. This is useful for debugging, because software faults, causing endless loops would cause locking of all processes, the shells, the telnet daemon, even the console.


Default: By default the scheduler has priority 0.


Example: “schedule 99” set PBX4Linux process in SCHED_RR with priority 99.




Specify the coding of samples, which are used in your country. It affects the internal processing of the PBX. Note that all tones and announcements are encoded “alaw”.


Default: By default “alaw” is used.




Tones and announcements are used to tell the telephone user when to dial, when the call is ringing, why did this call disconnect… All tones are a-law encoded samples. There are two default sets of tones, located at “/usr/local/pbx”, if the PBX data is installed in the default location:



Both are located at “/usr/local/pbx/,” if the default installation directory was u