Asterisk: ISDN PRI support with a Sangoma A108 PCI Express card

One of the most reliable ways to connect Asterisk, or any Private Branch Exchange (PBX), to the Public Switched Telephone Network (PSTN) is with ISDN: Integrated Services Digital Network. In Europe, this service is available in two main flavors: ISDN-30/PRI (Primary Rate Interface) and ISDN-2/BRI (Basic Rate Interface). PRI connections are widely used for office PBX connections, while BRI is more affordable and often considered a good choice for SoHo use.

Euro-ISDN PRI connections have thirty 64 kbps B- (Bearer/data) channels for voice or data connections and one 64 kbps D- (Delta/control) channel for the transmission of signaling information: to connect/disconnect calls and negotiate special calling parameters, such as caller-ID, call waiting and data protocol.

The Sangoma A108 Four-Port T1/E1/J1 card can support up to eight PRI spans (physical connections) for a total of 240 ISDN B-channels. Although is has only four RJ-45 ports, it can accommodate eight physical connections when a set of Y-cables are used that are included with the card. These make use of the fact that ISDN cables need only four wires, while RJ-45 connectors have eight contacts. The Sangoma support wiki includes a diagram of these Y-cables.

A Sangoma A108 PCI card.

Also called the A108 Octal Voice and Data Card, this is an active ISDN card, capable of handling most of the ISDN connection protocols, such as dialing and accepting calls, through the use of dedicated microprocessors and firmware, which is efficient when many channels see heavy use. With passive ISDN cards, these tasks are instead performed by PC software.

As can be seen in the image, the A108 consists of two printed circuit boards. The lower half, with the PCI edge connectors, is referred to by Sangoma as the base card, while they call the upper half the main board. The A108 shares its base card with the A104, but has a different main board. Of the A108, both PCI and PCI Express versions are available.

This article describes how to configure Debian 5.0 (lenny) and Asterisk with a Sangoma A108 card for use with a single ISDN PRI connection in the Netherlands, while explaining a bit about the technology from this point of view. It builds on a previous article, Asterisk: minimal SIP configuration, in which Asterisk 1.4.21, Zaptel 1.4.11 and the zaptel-modules package were installed and configured. The installation procedures below assume that an A108 card has already been installed and that both the operating system and Asterisk are up and running.

This card is supported by a proprietary Sangoma package, called Wanpipe. This is the software used for their AFT (Advanced Flexible Telecommunications) and legacy S-series product lines. The software must be downloaded from the Sangoma site and installed separately, but it does have a few software requirments of its own. These can be met in advance by installing four Debian packages:

~# apt-get install libncurses5-dev bison libtool flex

A total of six packages are installed as a result, including two dependencies:

autotools-dev              20080123.1                      Update infrastructure for config.{guess,sub} files
bison                      1:2.3.dfsg-5                    A parser generator that is compatible with YACC
flex                       2.5.35-6                        A fast lexical analyzer generator.
libltdl3-dev               1.5.26-4+lenny1                 A system independent dlopen wrapper for GNU libtool
libncurses5-dev            5.7+20081213-1                  developer's libraries and docs for ncurses
libtool                    1.5.26-4+lenny1                 Generic library support script

Next, download the latest version of the Wanpipe software, in this case v3.5.11 (dated 2010-04-19), and save it in the /usr/src directory. Unpack it and run the Wanpipe setup script:

~# cd /usr/src
~# wget -q ftp://ftp.sangoma.com/linux/current_wanpipe/wanpipe-3.5.11.tgz
~# tar -xzf wanpipe-3.5.11.tgz
~# cd wanpipe-3.5.11
~# ./Setup install --with-zaptel=/usr/src/modules/zaptel/

When the Setup script is run, a series of questions are asked, most of which can all be answered with either an affirmative, or a confirmation of a default setting. There are, however, some important selections to be made. First, regarding the Compilation Mode, choose:

2. TDM Voice (Dahdi/Zaptel) Support 
       Protocols: TDMV (Dahid/Zaptel), TDM API on AFT adatpers.
       Default for: Asterisk & CallWeaver

Towards the end of the installation script, the option is offered to "create wanpipe devices for ZAPTEL." Accept this offer, as well as to generate a new version of /etc/asterisk/zapata.conf, which is the configuration file for Asterisk Zaptel channels. Once this option has been selected, answer the next questions regarding the specifications of the ISDN PRI connection as follows:

Select media type for AFT-A108 on port 1 E1
Configuring port 1 on 108 as E1, line coding:HDB3, framing:CRC4 NO  - Configure line coding and framing
Select line coding for port 1 on 108 HDB3
Select framing for port 1 on 108 NCRC4
Select clock for AFT-A108 on port 1 NORMAL
Select signalling type for AFT-A108 on port 1 Zaptel/Dahdi - PRI CPE
Select switchtype for AFT-A108 on port 1 EuroISDN
Configuring port 1 on AFT-A108 as a full E1 YES - Use all channels
Select dialplan context for AFT-AA108 on port 1 from-pstn
Select dialplan context for AFT-AA108 on port 1 Custom: use "incoming"
Input the group for this port 1
Select media type for AFT-A108 on port 2 Unused

See below for an explanation of these settings. As for the last answer, the same one − Unused − is also given for ports 3 through 8, since they will not be used either.

The Wanpipe setup script, when run as described above, creates a number of configuration files, including /etc/wanpipe/wanpipe1.conf, /etc/zaptel.conf and /etc/asterisk/zapata.conf. The first of these contains the parameters that are required for Wanpipe to establish the ISDN PRI connection:

[devices]
wanpipe1 = WAN_AFT_TE1, Comment

[interfaces]
w1g1 = wanpipe1, , TDM_VOICE, Comment

[wanpipe1]
CARD_TYPE       = AFT
S514CPU         = A
CommPort        = PRI
AUTO_PCISLOT    = NO
PCISLOT         = 4
PCIBUS          = 13
FE_MEDIA        = E1
FE_LCODE        = HDB3
FE_FRAME        = NCRC4
FE_LINE         = 1
TE_CLOCK        = NORMAL
TE_REF_CLOCK    = 0
TE_SIG_MODE     = CCS
TE_HIGHIMPEDANCE        = NO
TE_RX_SLEVEL    = 430
LBO             = 120OH
FE_TXTRISTATE   = NO
MTU             = 1500
UDPPORT         = 9000
TTL             = 255
IGNORE_FRONT_END = NO
TDMV_SPAN       = 1
TDMV_DCHAN      = 16
TDMV_HW_DTMF    = NO
TDMV_HW_FAX_DETECT = NO

[w1g1]
ACTIVE_CH       = ALL
TDMV_HWEC       = NO
MTU             = 8

Partial explanation:

FE_MEDIA = E1

Front End Media type. In this case, E1 has been selected for Euro-ISDN. Depends on what is used by the telco. T1 is used in North America.

FE_LCODE = HDB3

Front End Line Code type for the transmission of voice information over the ISDN B-channels. Depends on what is used by the telco. In this case HDB3 (High Density Bipolar of order 3) is used, which is a modified AMI code. Typically, E1 connections use either HDB3 or AMI (Alternate Mark Inversion), while T1 connections use B8ZS (Bipolar with 8-Zero Substitution) or AMI.

FE_FRAME = NCRC4

Front End Frame type, or format. This is for the data link layer (OSI layer 2), with the correct setting depending on the specifications of the equipment used by the telco. Since different frame types have different lengths, this allows the Sangoma card to determine which bits are associated with each channel. In North America, T1 connections use either the ESF (Extended Super Frame), or the older SF (Super Frame) frame types. The SF type is also known as D4 (Digital 4). In Europe, E1 connections use either the CRC4 frame type, or the original version without CRC checking, NCRC4 (no-CRC4), which is used in this case.

FE_LINE = 1

Front End Line number. This value is used by the A108 driver to determine the physical port to associate with this connection. For the A108 card, valid values are 1-8.

TE_CLOCK = NORMAL

T1/E1 Clock source. Valid options are NORMAL, which indicates a slave clock, receiving timing from the telco, and MASTER to use an internal oscillator. The latter is only used in back-to-back mode, or when specified by the telco. The default is NORMAL.

TE_REF_CLOCK = 0

T1/E1 Reference Clock source. This allows a different port number (2, 3 or 4 in this scenario) to be used as the clock source for this port, in which case the setting TE_CLOCK=MASTER is also required. The default for this setting is 0 (disabled).

TE_SIG_MODE = CCS

T1/E1 Signalling Mode in which the ISDN connection control protocol (OSI layer 3) is sent. The mode may be either CAS or CCS. Whenever possible, Common Channel Signaling (CCS) is used for the out-of-band transmission of signalling information over the ISDN D-channel. Its in-band counterpart, Channel Associated Signaling (CAS), is only used when no D-channel is present, but this is rare. For CCS, the actual network protocol used is specified in ITU-T recommendations Q.930 (I.450) and Q.931 (I.451).

LBO = 120OH

Line Build-Out (waveform transmit) value. Wanpipe uses this value to match the waveforms of different carrier technologies: T1 or E1. For T1 connections, a number of extra values are included to compensate for signal attenuation due to the length of the cable between the card to the first repeater in the circuit. For E1, one value is included for 75Ω unbalanced (coaxial) and another for 120Ω balanced (twisted pair) connections. The A108 has a separate framer chip: a dedicated microprocessor responsible for both line coding and the assembly/disassembly of ISDN frames. It is thanks to this IC that the card is also able to support coaxial connections, although in that case additional coax to RJ-45 adapters (example) are required that are not supplied by Sangoma.

The Wanpipe setup script compiles its modules against the Zaptel source. This is because it is the Zaptel telephony infrastructure that provides the virtual TDM bus through which Asterisk communicates with any telephony cards. For this reason, all such cards must be mentioned in the Zaptel configuration file, /etc/zaptel.conf. In this case, the task of adding the correct entry to this file − an entry that must agree with the settings in wanpipe1.conf − has already been performed by the Wanpipe setup script:

loadzone=nl
defaultzone=nl

span=1,1,0,ccs,hdb3
bchan=1-15,17-31
hardhdlc=16

Explanation:

loadzone=nl

Loads the indication tones (dial tone, etc.) that are used in a particular country. Multiple entries like this can be included, each for a different tonezone. The default is us.

defaultzone=nl

Sets the default tonezone to specify which country's indication tones should be used if nothing else is defined. The default is us.

span=1,1,0,ccs,hdb3

This is the Zaptel span configuration statement, the format for which is:

span=(spannum),(timing),(LBO),(framing),(coding)

spannum=1	−	Sets the span number. Spans are identified by incrementing numbers starting with 1. A span is a logical unit that represents a group of channels. With digital telephony a span usually represents a physical port on the card. This system has one 4-port card; the first port is in use, so it is referred to as span 1.
timing=1	−	Sets the synchronization source for timing purposes. The first span is numbered "1" to make it the primary timing source on the system, accepting timing from the telco. Each additional span is given an incrementally higher value.
LBO=0	−	Line Build-Out (waveform transmit) value. Used with T1 connections to compensate for signal attenuation due to the length of the cable that connects the ISDN card to the first repeater in the circuit. A number of possible values, representing increasingly attenuated waveforms, are found in the table below. Many ISDN PRI cards have registers to control LBO values, including programmable waveforms for both transmit and receive. This is also useful for matching the waveforms of different carrier technologies, e.g. T1 or E1. However, since none of the values in the table below apply to European scenarios, it is probably best to always set this LBO value to zero, regardless of the LBO setting in /etc/wanpipe/wanpipe1.conf.
		Value     CSU (dB)     DSX-1 (feet)     DSX-1 (meters)   0 0 0−133 0−40.54 1 133−266 40.54−81.08 2 266−399 81.08−121.62 3 399−533 121.62−162.46 4 533−655 162.46−199.64 5 -7.5 6 -15.0 7 -22.5
		The column titles in the table above refer to T1 trunk lines with either a channel service unit (CSU) interface, or a DSX-1 interface. The latter is named after the central office cross-connection point at which DS1 (T1) signals are interconnected. With a CSU interface, the length of the cable is unknown, so an attenuation value in decibels (dB) is used that must either be measured, or supplied by the telco. ISDN cards with integrated CSUs are common in the United States where telcos do not provide the DCE due to industry deregulation, but such cards are more expensive. So, customers may instead choose to purchase their own T1 CSU/DSU to provide a DSX-1 interface. When an ISDN card is attached to this interface, the length of the cable can be measured (or at least estimated) and the DSX-1 column (in feet or in meters) is used. However, correctly determining any of the values greater than 0 in advance is often difficult because other factors, such as bad cabling, or a device on the other end that is not transmitting at the assumed level, can easily influence the matter. Therefore, the only solution is often just to experiment and see which setting works best.
framing=ccs	−	The type of information specified here depends on the telco and the equipment used. For T1 connections it is the (OSI layer 2) frame type: esf or d4 (Extended Super Frame or Digital 4 a.k.a. Super Frame). For E1 and BRI it is the (OSI layer 3) signalling type, cas or ccs (CAS or CCS), for the ISDN connection control protocol.
coding=hdb3	−	Line code type used for the transmission of voice information over the ISDN B-channels. Depends on what is used by the telco, which in this case is HDB3 (High Density Bipolar of order 3). A modified AMI code, HDB3 is commonly used for E1 connections at all levels. Other possible line codes for PRI include AMI (Alternate Mark Inversion) and B8ZS (Bipolar with 8-Zero Substitution). The latter is used mostly in North America.

bchan=1-15,17-31

Sets two ranges for the ISDN B-channels.

hardhdlc=16

Sets the number for the ISDN D-channel.

All Zap channels must be defined in the /etc/asterisk/zapata.conf configuration file before they can be used by Asterisk. If one does not yet exist, the Wanpipe setup script also creates this file:

[trunkgroups]

[channels]
context=incoming
usecallerid=yes
hidecallerid=no
callwaiting=yes
usecallingpres=yes
callwaitingcallerid=yes
threewaycalling=yes
transfer=yes
canpark=yes
cancallforward=yes
callreturn=yes
echocancel=yes
echocancelwhenbridged=yes
relaxdtmf=yes
rxgain=0.0
txgain=0.0
group=1
callgroup=1
pickupgroup=1
immediate=no

;Sangoma A108 port 1 [slot:4 bus:13 span:1] <wanpipe1>
switchtype=euroisdn
context=incoming
group=1
signalling=pri_cpe
channel =>1-15,17-31

Explanation (in the exact same order as above):

[trunkgroups]

Empty section. Used to create logical connections that consist of multiple physical ones, so it is irrelevant in this case.

[channels]

Relevant section title. It may contain many channel definitions, although only one is included here.

context=incoming

The name specified here, which is arbitrary, determines the point at which incoming calls enter the dial plan when they arrive on this channel definition.

usecallerid=yes

If enabled, it causes Asterisk to look for the caller-ID (CID) on incoming calls and send it to the intended extension for display. The default is yes.

hidecallerid=no

If enabled, this prevents the CID from being sent on outgoing calls. The CID may also be enabled or disabled by initially dialing *82 or *67 respectively; this results in a dialrecall tone after which the intended number can be dialled. The default is no.

callwaiting=yes

If enabled, Asterisk will generate "call waiting pips" for incoming calls when the line is busy. If enabled by default, call waiting can temporarily be disabled by dialing *70, which results in a dialrecall tone after which the intended number can be dialled. The reserse is not possible: to temporarily enable call waiting if it is disabled by default. The default is no.

usecallingpres=yes

Whether or not use the CID presentation for the outgoing call that the calling switch is sending.

callwaitingcallerid=yes

If enabled, CID data will be sent to the handset during call waiting indication. Requires callwaiting=yes. The default is no.

threewaycalling=yes

If enabled, it allows calls to be placed on hold by pressing a hook flash. This results in a dialrecall tone after which a number can be dialled. The default is no.

transfer=yes

This option is only relevant when threewaycalling=yes. If enabled, once a call has been placed on hold with a hook flash, it can be transfered to another extension by dialling and hanging up. The default is no. Overrides the canpark setting.

canpark=yes

Allows call parking if enabled. Overridden by transfer=yes.

cancallforward=yes

If enabled, call forwarding immediate may be activated by dialling *72; this results in a dialrecall tone after which a forwarding number can be dialled. Any incoming calls will then be redirected to the forwarding number. The forwarding can be disabled by dialing *73. The default is no.

callreturn=yes

If enabled, *69 may be dialled to have Asterisk read the CID of the last incoming call. The dialrecall tone will be heard if there is no record of a last caller. The default is no.

echocancel=yes

Echo cancellation option. May be set to yes (128 taps), no (0 taps), or a power of two between 32 and 256 for a specific number of taps of cancellation. Each tap is one sample from the data stream. If set to an invalid value, the setting falls back to the default. Disabling this option is not recommended. The default is yes.

echocancelwhenbridged=yes

Enables echo cancellation during bridged TDM calls. In principle, such calls should not require it, but it often improves audio performance. The default is no.

relaxdtmf=yes

Allows the detection parameters to be relaxed in case there is a problem detecting DTMF tones. However, this will sooner lead to a phenomenon known as talk-off, in which certain kinds of voices that can produce sounds similar to DTMF tones are interpreted as such. The system will then assume that a key has been pressed and process it accordingly, which may result in the call being lost. The default is no.

rxgain=0.0

Adjusts the gain in dB for the audio signal recieved by Asterisk from a device. This may be, for example, to compensate for differences in hardware. Specified by a decimal number from -100 to 100 and recommended to be changed by only a few dB at a time. The default value is 0.0.

txgain=0.0

Adjusts the gain in dB for the audio signal transmitted by Asterisk to a device. This may be, for example, to compensate for differences in hardware. Specified by a decimal number from -100 to 100 and recommended to be changed by only a few dB at a time. The default value is 0.0.

group=1

Allows multiple channels to be treated as one for outgoing calls, in which case the first available channel will always be used. The value used here is arbitrary, but must be matched in the dial plan.

callgroup=1

Any channel (phone) may belong to zero or more callgroups, specified by numbers ranging from 0 to 31. Users with phones that belong to a matching pickupgroup number may remotely answer ringing phones by dialing *8#. This feature is supported by Zap, SIP, Skinny and MGCP channels and only works within each of those technologies, i.e. a Zap phone cannot be used to answer a ringing SIP phone. There is no default value.

pickupgroup=1

Any channel (phone) may belong to zero or more pickupgroups, specified by numbers ranging from 0 to 31. Users with phones that belong to a matching callgroup number may have their ringing phones answered remotely by someone by dialing *8#. This feature is supported by Zap, SIP, Skinny and MGCP channels and only works within each of these technologies, i.e. a Zap phone cannot be used to answer a ringing SIP phone. There is no default value.

immediate=no

When disabled, which is the default, and a phone is taken off-hook, the Zaptel driver provides a dial tone and listens for digits that are dialled, passing them on to Asterisk. It waits until the number that is dialled matches an extension and then begins executing the first command on that extension. When enabled, however, Asterisk instructs the Zaptel driver not to generate a dial tone and instead passes control immediately on to Asterisk, upon which it starts executing the commands for the channel's s extension. This is sometimes called batphone mode.

switchtype=euroisdn

Sets the ISDN switch type, in this case to euroisdn. The default is national (National ISDN type2), which is common in the US.

context=incoming

An unnecessary repetition of the same option already mentioned above.

group=1

An unnecessary repetition of the same option already mentioned above.

signalling=pri_cpe

Sets the signalling type to use with the interface. Here, it is set to Primary Rate Interface, Customer-Premises Equipment side. In the United States, the option pri_net is sometimes used, for if no CSU/DSU is present and the ISDN PRI card uses an integrated CSU.

channel => 1-15,17-31

Defines the channel, or range of channels. Each channel definition inherits all of the options stated above it in the configuration file. There must also be a matching channel or range of channels defined in /etc/zaptel.conf.

The output from the lspci -vv command is misleading:

0d:04.0 Network controller: Sangoma Technologies Corp. A104d QUAD T1/E1 AFT card
        Subsystem: Unknown device a114:4113
        Control: I/O- Mem+ BusMaster+ SpecCycle- MemWINV- VGASnoop- ParErr+ Stepping- SERR+ FastB2B-
        Status: Cap- 66MHz- UDF- FastB2B- ParErr- DEVSEL=medium >TAbort- <TAbort- <MAbort- >SERR- <PERR-
        Latency: 255 (1250ns min, 3750ns max)
        Interrupt: pin A routed to IRQ 169
        Region 0: Memory at fc4e0000 (32-bit, non-prefetchable) [size=128K]

This shows the presence of a Sangoma A104 instead of an A108. The reason for this is because the A108 and the A104 share the same base card. According to Sangoma technical support, when using the A108 this information can be ignored and they recommend using lspci only to check for the presence of the card and for conducting a card count.

The Wanpipe setup script compiles a number of modules for the running kernel. The ones currently loaded in memory are revealed with the following command and are (excluding the last two):

~# lsmod
Module                  Size  Used by
wanec                 328088  0 
af_wanpipe             41664  0 
wanpipe               716896  32 
wanrouter              49512  12 wanec,af_wanpipe,wanpipe
sdladrv               206580  4 wanec,af_wanpipe,wanpipe,wanrouter
zaptel                190980  65 wanpipe
crc_ccitt               6337  1 zaptel
...

The modinfo utility gives the following descriptions for these modules:

The Wanpipe software also allows the card to be used for routing data. Not that it is used for this purpose here, but towards this end it does create a network interface that should appear:

# ifconfig w1g1
w1g1      Link encap:Point-to-Point Protocol  
          UP POINTOPOINT RUNNING NOARP  MTU:8  Metric:1
          RX packets:87600513 errors:0 dropped:0 overruns:0 frame:0
          TX packets:87600532 errors:0 dropped:0 overruns:1 carrier:7
          collisions:0 txqueuelen:100 
          RX bytes:0 (0.0 b)  TX bytes:0 (0.0 b)
          Interrupt:169 Memory:f8bc0000-f8bc1fff 

# _

Check the version of the software:

~# wanrouter version

WANPIPE Release: 3.5.11

# _

If the software is working properly, the following command will load all Wanpipe and Zaptel modules and then print a list of all Sangoma hardware installed on the system:

~# wanrouter hwprobe verbose

-----------------------------------------
| Wanpipe Hardware Probe Info (verbose) |
-----------------------------------------
1 . AFT-A108-SH : SLOT=4 : BUS=13 : IRQ=6 : CPU=A : PORT=1 : HWEC=0 : V=41
+01:DS26528: PCIe: PLX1
2 . AFT-A108-SH : SLOT=4 : BUS=13 : IRQ=6 : CPU=A : PORT=2 : HWEC=0 : V=41
+02:DS26528: PCIe: PLX1
3 . AFT-A108-SH : SLOT=4 : BUS=13 : IRQ=6 : CPU=A : PORT=3 : HWEC=0 : V=41
+03:DS26528: PCIe: PLX1
4 . AFT-A108-SH : SLOT=4 : BUS=13 : IRQ=6 : CPU=A : PORT=4 : HWEC=0 : V=41
+04:DS26528: PCIe: PLX1
5 . AFT-A108-SH : SLOT=4 : BUS=13 : IRQ=6 : CPU=A : PORT=5 : HWEC=0 : V=41
+05:DS26528: PCIe: PLX1
6 . AFT-A108-SH : SLOT=4 : BUS=13 : IRQ=6 : CPU=A : PORT=6 : HWEC=0 : V=41
+06:DS26528: PCIe: PLX1
7 . AFT-A108-SH : SLOT=4 : BUS=13 : IRQ=6 : CPU=A : PORT=7 : HWEC=0 : V=41
+07:DS26528: PCIe: PLX1
8 . AFT-A108-SH : SLOT=4 : BUS=13 : IRQ=6 : CPU=A : PORT=8 : HWEC=0 : V=41
+08:DS26528: PCIe: PLX1

Card Cnt: A108=1 

~# _

Among other things, this shows that the software detects the PCI Express (PCIe) version of a Sangoma A108 card with all eight PRI spans available. A PCI version of the A108 is also available.

Show the status of the card:

~# wanrouter status

Devices currently active:
        wanpipe1


Wanpipe Config:

Device name | Protocol Map | Adapter  | IRQ | Slot/IO | If's | CLK | Baud rate |
wanpipe1    | N/A          | A101/1D/A102/2D/4/4D/8| 169 | 4       | 1    | N/A | 0         |

Wanrouter Status:

Device name | Protocol | Station | Status        |
wanpipe1    | AFT TE1  | N/A     | Connected     |

~# _

The most important item displayed here is the status, which should be Connected.

Read E1/T1 alarms:

~# wanpipemon -i w1g1 -c Ta

***** w1g1: E1 Alarms (Framer) *****

ALOS:	OFF	| LOS:	OFF
RED:	OFF	| AIS:	OFF
LOF:	OFF	| RAI:	OFF

***** w1g1: E1 Alarms (LIU) *****

Short Circuit:	OFF
Open Circuit:	OFF
Loss of Signal:	OFF


***** w1g1: E1 Performance Monitoring Counters *****

Line Code Violation	: 244
Far End Block Errors	: 0
CRC4 Errors		: 0
FAS Errors		: 0


Rx Level	: > -2.5db


~# _

This is the Wanpipe AFT Hardware Level Debugging Utility. The options used above are to specify the name of the interface, followed by a command: Ta. The T is for T1/E1 Configuration/Statistics, while the a is to Read T1/E1 alarms. In this case there are no alarms and the number of Line Code Violation errors is small (these should not be seen to increase).

Read all files in the /proc/zaptel/ directory structure:

~# cat /proc/zaptel/*
Span 1: WPE1/0 "wanpipe1 card 0" (MASTER) HDB3/CCS 

	   1 WPE1/0/1 Clear (In use) 
	   2 WPE1/0/2 Clear (In use) 
	   3 WPE1/0/3 Clear (In use) 
	   4 WPE1/0/4 Clear (In use) 
	   5 WPE1/0/5 Clear (In use) 
	   6 WPE1/0/6 Clear (In use) 
	   7 WPE1/0/7 Clear (In use) 
	   8 WPE1/0/8 Clear (In use) 
	   9 WPE1/0/9 Clear (In use) 
	  10 WPE1/0/10 Clear (In use) 
	  11 WPE1/0/11 Clear (In use) 
	  12 WPE1/0/12 Clear (In use) 
	  13 WPE1/0/13 Clear (In use) 
	  14 WPE1/0/14 Clear (In use) 
	  15 WPE1/0/15 Clear (In use) 
	  16 WPE1/0/16 Hardware-assisted HDLC (In use) 
	  17 WPE1/0/17 Clear (In use) 
	  18 WPE1/0/18 Clear (In use) 
	  19 WPE1/0/19 Clear (In use) 
	  20 WPE1/0/20 Clear (In use) 
	  21 WPE1/0/21 Clear (In use) 
	  22 WPE1/0/22 Clear (In use) 
	  23 WPE1/0/23 Clear (In use) 
	  24 WPE1/0/24 Clear (In use) 
	  25 WPE1/0/25 Clear (In use) 
	  26 WPE1/0/26 Clear (In use) 
	  27 WPE1/0/27 Clear (In use) 
	  28 WPE1/0/28 Clear (In use) 
	  29 WPE1/0/29 Clear (In use) 
	  30 WPE1/0/30 Clear (In use) 
	  31 WPE1/0/31 Clear (In use) 
~# _

• This shows a single ISDN PRI span with 31 channels. The same card can support up to four such spans, but other cards may have only one span with a single channel, such as with analog. The first span is Span 1, the second Span 2, etc.
• The Zaptel module names the first Wanpipe span WPE1, the second WPE1, etc. The cards are numbered card 0, card 1, etc.
• This card is described as MASTER, because it is the primary timing source for the system, although it actually receives its timing information from the telco. Additional cards are given no such description.
• HDB3/CCS: the line coding method (HDB3) and a signalling type (CCS) that are used together for ISDN PRI services in the Netherlands.
• This span has 31 channels. They are all described as "(In use)," in this case because Asterisk is running and configured to use them.
• The channels described as Clear are B-channels, because they carry no signaling or anything; the data they carry can be read "as is" by the software layers above.
• The channel described as Hardware-assisted HDLC is the D-channel.

At the data link layer (OSI layer 2), ISDN uses two variants of the Link Access Procedure (LAP): LAP D-channel (LAPD, defined in ITU-T Q.920 and Q.921) for the D-channel, and LAP Balanced (LAPB) for data connections over the B-channels. Actually, LAP was the original data link protocol for X.25 before it was replaced by LAPB. Because LAP is derived from HDLC (High-level Data Link Control), the Sangoma A108 processes both LAPB and LAPD using HDLC controllers implemented in hardware. LAPB, however, is irrelevant for Asterisk, because when the B-channels are used for voice they carry no signaling at all: they are clear. With Asterisk, this is why it is necessary to specify a line coding scheme for the B-channels.

Display general status information on all PRI spans:

~# asterisk -rx "pri show spans"
PRI span 1/0: Provisioned, Up, Active
~# _

Display more detailed information regarding a specific PRI span:

~# asterisk -rx "pri show span 1"
Primary D-channel: 16
Status: Provisioned, Up, Active
Switchtype: EuroISDN
Type: CPE
Window Length: 0/7
Sentrej: 0
SolicitFbit: 0
Retrans: 0
Busy: 0
Overlap Dial: 0
T200 Timer: 1000
T203 Timer: 10000
T305 Timer: 30000
T308 Timer: 4000
T309 Timer: -1
T313 Timer: 4000
N200 Counter: 3

~# _

Show the status of all Zaptel cards:

~# asterisk -rx "zap show status"
Description                              Alarms     IRQ        bpviol     CRC4      
wanpipe1 card 0                          OK         0          0          0         
~# _

Show the status of all Zaptel channels:

~# asterisk -rx "zap show channels"
   Chan Extension  Context         Language   MOH Interpret
 pseudo            incoming                   default
      1            incoming                   default
      2            incoming                   default
      3            incoming                   default
      4            incoming                   default
      5            incoming                   default
      6            incoming                   default
      7            incoming                   default
      8            incoming                   default
      9            incoming                   default
     10            incoming                   default
     11            incoming                   default
     12            incoming                   default
     13            incoming                   default
     14            incoming                   default
     15            incoming                   default
     17            incoming                   default
     18            incoming                   default
     19            incoming                   default
     20            incoming                   default
     21            incoming                   default
     22            incoming                   default
     23            incoming                   default
     24            incoming                   default
     25            incoming                   default
     26            incoming                   default
     27            incoming                   default
     28            incoming                   default
     29            incoming                   default
     30            incoming                   default
     31            incoming                   default
~# _

Show the status of one specific Zaptel channel:

~# asterisk -rx "zap show channel 1"
Channel: 1
File Descriptor: 15
Span: 1
Extension: 
Dialing: no
Context: incoming
Caller ID: 
Calling TON: 0
Caller ID name: 
Destroy: 0
InAlarm: 0
Signalling Type: ISDN PRI
Radio: 0
Owner: <None>
Real: <None>
Callwait: <None>
Threeway: <None>
Confno: -1
Propagated Conference: -1
Real in conference: 0
DSP: no
Relax DTMF: yes
Dialing/CallwaitCAS: 0/0
Default law: alaw
Fax Handled: no
Pulse phone: no
Echo Cancellation: 128 taps, currently OFF
PRI Flags: 
PRI Logical Span: Implicit
Hookstate (FXS only): Onhook
~# _

Assuming the ISDN line is associated with phone number 0715557890, modify the existing Asterisk dial plan, /etc/asterisk/extensions.conf, as follows:

[incoming]
exten => 0715551234,1,Goto(sp,1)
exten => 0715557890,1,Goto(sp,1)

exten => sp,1,Dial(SIP/sip-phone,60)
exten => sp,n,Hangup()

[outgoing]
exten => 0653123456,1,Dial(ZAP/g1/0653123456)
exten => 0653123456,n,Hangup()

exten => _X.,1,Dial(SIP/${EXTEN}@provider)
exten => _X.,n,Hangup()

Explanation:

[incoming]

Just as with incoming calls from the SIP channel, those from the ZAP channel range "1-2" are also inserted at this point, because the title of this section matches the context=incoming statement in /etc/asterisk/zapata.conf for that channel range. Otherwise, the name of this section is arbitrary.

exten => 0715551234,1,Goto(sp,1)

When an incoming call reaches this rule and matches extension number 0715551234, the Goto() application sends control of the current channel to extension sp with priority 1. The name of that extension is arbitrary.

exten => 0715557890,1,Goto(sp,1)

Idem, except for extension number 0715551234. This is for the SIP channel that was configured in the previous article, Asterisk: minimal SIP configuration.

exten => sp,1,Dial(SIP/sip-phone,60)

When an incoming call reaches this rule and matches extension sp, a sequence of two events is triggered, starting with the Dial() application, which is used to connect together all of the various channel types in Asterisk. Here, it connects the incoming SIP or ZAP channel to a SIP channel, called sip-phone, which is represented by a section called [sip-phone] in sip.conf, using a ring-timeout of 60 seconds.

exten => sp,n,Hangup()

After the call has ended, or if the ring-timeout has expired, the priority 2 (n=n+1) rule for this extension is reached. This is the Hangup() application, which simply hangs up the current channel unconditionally.

exten => 0653123456,1,Dial(ZAP/g1/0653123456)

This event is only triggered by calls that reach this point and if the dialled number matches "0653123456." The Dial() application then connects the call to the ZAP channel associated with group 1 and dials "0653123456." Notice that this rule and the next one have been inserted before the "_X." catch-all rule below it − if they had been inserted after, they would never be reached.

exten => 0653123456,n,Hangup()

After the call has ended, the priority 2 (n=n+1) rule for this extension is reached and the Hangup() application hangs up the current channel unconditionally.

Once the new dial plan has been saved, submit the changes to the running Asterisk process with this command:

~# asterisk -rx "dialplan reload"
Dialplan reloaded.
~# _

It should now be possible to receive ISDN calls for extension 0715557890 through Asterisk. This is in addition to SIP calls for extension 0715551234. In both cases, the calls will be connected on to the channel for the previously configured SIP phone.

For outgoing calls, a choice must be made in the dial plan regarding which channel to use. In this example, the ZAP channel is only used for outgoing calls if extension 0653123456 is dialled. For all other numbers the catch-all rule will apply and the SIP channel will be used.

• Asterisk: minimal SIP configuration
• Asterisk: ISDN BRI support with a Cologne Chip HFC-S PCI card

• ITU-T. 2001. Series G: Transmission Systems and Media. ITU-T Recommendation G.703: Digital Systems and Networks. Digital Terminal Equipments, General. Physical/electrical characteristics of hierarchical digital interfaces. PDF at the ITU-T.
• ITU-T 1993. Series Q: Switching and Signalling. ITU-T Recommendation Q.920: Digital subscriber Signalling System No. 1 (DSS1), ISDN User-Network Interface Data Link Layer, General Aspects. PDF at the ITU-T.
• ITU-T 2000. Series Q: Switching and Signalling. ITU-T Recommendation Q.920 (1993): Digital subscriber Signalling System No. 1 (DSS1), ISDN User-Network Interface Data Link Layer, General Aspects. Amendment 1. PDF at the ITU-T.
• ITU-T 1997. Series Q: Switching and Signalling. ITU-T Recommendation Q.921: Digital subscriber Signalling System No. 1 (DSS1), ISDN User-Network Interface, Data Link Layer Specification. PDF at the ITU-T.
• ITU-T 2000. Series Q: Switching and Signalling. ITU-T Recommendation Q.921 (1997): Digital subscriber Signalling System No. 1 (DSS1), ISDN User-Network Interface, Data Link Layer Specification. Amendment 1. PDF at the ITU-T.
• ITU-T. 1993. Series Q: Switching and Signalling. ITU-T Recommendation Q.930 (I.450): Digital subscriber Signalling System No. 1 (DSS1), ISDN User-Network Interface Layer 3, General Aspects. PDF at the ITU-T.
• ITU-T 1998. Series Q: Switching and Signalling. ITU-T Recommendation Q.931 (I.451): Digital subscriber Signalling System No. 1 (DSS1), ISDN User-Network Interface Layer 3 Specification for Basic Call Control. PDF at the ITU-T.
• ITU-T 2002. Series Q: Switching and Signalling. ITU-T Recommendation Q.931 (1998): Digital subscriber Signalling System No. 1 (DSS1), ISDN User-Network Interface Layer 3 Specification for Basic Call Control. Amendment 1: Extentions for the Support of Digital Multiplexing Equipment. PDF at the ITU-T.
• ITU-T 2003. Series Q: Switching and Signalling. ITU-T Recommendation Q.931 (1998): Digital subscriber Signalling System No. 1 (DSS1), Erratum 1. PDF at the ITU-T.
• TechFest. 2007. ISDN Overview. HTML at TechFest.

• Cisco Systems, Inc. 1992-2010. Integrated Services Digital Network (ISDN) Overview. HTML at Cisco Systems.
• Digium. Zapata.conf. PDF at Digium.
• Digium. 2002. Zaptel.conf: How to configure the low-level Zapata Interface Library for your hardware. Linux Support Services Inc. PDF at RJ Systems.
• Dunsmore B, Skandier T. 2002. Integrated Services Digital Network Primer: BRI. Cisco Press. HTML at Cisco Press.
• Grinsing K. 2009. ISDN PRI. HTML at Network And Security.
• Haden R. 1996-2010. ISDN. HTML at Data Network Resource.
• Madsen L, Smith J, Sokol S. 2003. The Hitchhiker's Guide to Asterisk. HTML at MicroAlcarria, PDF at DynX Services.
• Meggelen van J, Madsen L, Smith J. 2007. Asterisk, The Future of Telephony. Second Edition. O'Reilly & Associates, Inc. ISBN-13: 978-0-596-51048-0. 574 pp. HTML at the Asterisk Documentation Project, PDF at O'Reilly Media, Inc.
• Sangoma Technologies Inc. 2006. WANPIPE1 Configuration File. HTML at Sangoma.
• Sangoma Technologies Inc. 2010. Wiki: Wanpipe / Zaptel / Asterisk. HTML at Sangoma.
• Sangoma Technologies Inc. 2010. Wiki: Wanpipe Asterisk Configuration File. HTML at Sangoma.
• TLS Corp. 2001. ISDN Glossary. HTML at Telos Systems.
• Voip-Info.org. 2003-2009. Asterisk config zapata.conf. HTML at Voip-Info.org.
• Voip-Info.org. 2005-2008. Zaptel.conf span syntax. HTML at Voip-Info.org.

• Marc Celsie at Sangoma.
• Rob van der Putten at Superput.
• Joerg Ciesielski at Cologne Chip.