OpenZAP
From FreeSWITCH Wiki
OpenZAP is FreeSWITCH's interface to the Sangoma TDM API and Zaptel TDM API interfaces, which we refer to in this document as the "Zaptel interface" or "Zaptel API." Zaptel provides kernel drivers to interact with hardware, such as TDM boards installed in a PC, and exposes an API to that hardware; OpenZap implements a TDM abstraction library for use by FreeSWITCH of the Zaptel API.
OpenZap supports both analog and PRI cards, various signaling schemes, and can route media streams to and from the hardware.
Overview
Status
- Development is finished and testers are currently wanted.
- So far we have analog (only tested in US so far but we are working on UK too) and q.931 PRI signaling but we should be able to add more things like RBS as time progresses.
- The PRI stack is incomplete
- MFC/R2 support has been added using the OpenR2 signaling library but still needs stress testing.
License
BSD
History
Zaptel is actually a decendant of the original public domain tormenta driver made by Jim Dixon in 2000.
http://www.zapatatelephony.org/zap.c
http://www.zapatatelephony.org/zap.h
Our goal here is to pick up where this left off and keep the important functionality in the driver and the rest in user space. Eventually we hope to make our own platform-agnostic driver interface.
Design
We only use zaptel as a device via the socket opened on the operating system to access the low level features such as open close read write and the rest of the functionality is implemented in our own user space layer.
For clarification -- we simply speak to the zaptel kernel interface. In fact, we don't even use their header files to build. So if you have a card that requires modified drivers, then you would need to use those, but they should work as long as they maintain the same zaptel interface.
Getting started
OpenZAP can be used in two modes. The first mode uses Zaptel and will let you use any card Zaptel supports. The other mode is wanpipe, which will let you interact directly with Sangoma cards without going through Zaptel.
Zaptel Tutorial
A set of step-by-step instructions is available on the Zaptel Tutorial page.
Zaptel mode
You must have the Zaptel API up and running in order to use the OpenZap module.
Zaptel Installation
The hardware you intend to use, e.g., an FXO/FXS card or a PRI card, should be installed first so you can verify the zaptel installation after it's been completed. (Make sure the system has internet connectivity as it downloads some utilities)
At this point we can follow two different paths: general instruction and Debian instructions.
Non-Debian Instructions:
1. Download the zaptel-1.4.2.tar.gz from reliable sources. Untar the source tarball, compile and install it.
# I had to rely on this older zaptel version that works for me, as the newer ones were troubling me. $ tar -zxvf zaptel-1.4.2.tar.gz $ cd zaptel-1.4.2 $ ./configure $ make $ make install $ make config
2. Make sure you have the proper zaptel.conf in your /etc directory
3. Be cautious while configuring country zone in zaptel.conf at /etc. I didn't understand why we have to swap the channel numbers for FXS and FXO. For India, e.g.,
----- @/etc/zaptel.conf ----- loadzone=in defaultzone=in fxsks=4 fxoks=1
4. Add the wctdm and zaptel modules now.
$ modprobe wctdm $ modprobe zaptel
5. Now verify the installation with the ztcfg command
$ ztcfg -vv Zaptel Version: 1.4.2 Echo Canceller: MG2 Configuration ====================== Channel map: Channel 01: FXO Kewlstart (Default) (Slaves: 01) Channel 04: FXS Kewlstart (Default) (Slaves: 04) 2 channels configured.
Debian Instructions:
Debian makes this entire process rather easy.
1. Install the zaptel and zaptel-source package by using your favorite package management tool, e.g., apt-get or aptitude.
2. Build the zaptel-source package and create a deb which contains the Zaptel kernel modules:
$ module-assistant prepare $ module-assistant build zaptel-source
You may wish to example the Debian-specific README files provided by the zaptel (not the zaptel-source) package.
3. Install the deb created in the previous step, which is likely found at /usr/src.
4. Create the /etc/zaptel.conf file. The easiest way to do this is with genzaptelconf:
genzaptelconf -vsdM
(Note: If genzaptelconf cannot "find" the hardware, you may have to use modprobe to load the wctdm or zaptel kernel modules, or perhaps both.)
genzaptelconf may complain about some obscure program named "asterisk" not being present on your system. Regardless, /etc/zaptel.conf will be created.
5. Configure the board:
zapcfg
6. check to see the board's status:
ztscan
Your installation is up and running. At next boot, if you use udev, your hardware will be detected automatically and the system will load the Zaptel modules and configure the hardware from the /etc/zaptel.conf file.
Wanpipe mode
In this mode you do not need to have Zaptel installed. You will a recent version of Wanpipe (3.3.15 works) and compile it in TDM Voice API mode. For an E1 span the openzap.conf file will look like this, where the SPAN is put in Wanpipe mode by specifying span wanpipe
[span wanpipe PRI_1] number => 1 trunk_type => e1 b-channel => 1:1-15 d-channel => 1:16 b-channel => 1:17-31
A T1 span would look more like this:
[span wanpipe PRI_1] number => 1 trunk_type => t1 b-channel => 1:1-23 d-channel => 1:24
/etc/wanpipe/wanpipe1.conf will look like this:
[devices] wanpipe1 = WAN_AFT_TE1, Comment [interfaces] w1g1 = wanpipe1, , TDM_VOICE_API, Comment [wanpipe1] CARD_TYPE = AFT S514CPU = A CommPort = PRI AUTO_PCISLOT = NO PCISLOT = 4 PCIBUS = 13 FE_MEDIA = E1 FE_LCODE = HDB3 FE_FRAME = CRC4 FE_LINE = 1 TE_CLOCK = NORMAL TE_REF_CLOCK = 0 TE_SIG_MODE = CCS TE_HIGHIMPEDANCE = NO LBO = 120OH FE_TXTRISTATE = NO MTU = 1500 UDPPORT = 9000 TTL = 255 IGNORE_FRONT_END = NO TDMV_SPAN = 1 TDMV_DCHAN = 16 TDMV_HW_DTMF = YES [w1g1] ACTIVE_CH = ALL TDMV_ECHO_OFF = NO TDMV_HWEC = YES MTU = 80
Only spans configured as TDM_VOICE_API in wanpipe*.conf can be used together with a SPAN configured as wanpipe in openzap.conf
The autoload_configs/openzap.conf.xml will then look like this:
<configuration name="openzap.conf" description="OpenZAP Configuration">
<settings>
<param name="debug" value="0"/>
<!--<param name="hold-music" value="$${moh_uri}"/>-->
<!--<param name="enable-analog-option" value="call-swap"/>-->
<!--<param name="enable-analog-option" value="3-way"/>-->
</settings>
<pri_spans>
<span name="PRI_1">
<!-- Log Levels: none, alert, crit, err, warning, notice, info, debug -->
<param name="q921loglevel" value="alert"/>
<param name="q931loglevel" value="alert"/>
<param name="mode" value="user"/>
<param name="dialect" value="q931"/>
<param name="dialplan" value="XML"/>
<param name="context" value="pstn"/>
</span>
</pri_spans>
</configuration>
If Wanrouter has been brought up by doing /etc/init.d/wanrouter start and you now start FreeSWITCH the span should come up and you can now hopefully dial out using
<extension name="outgoing-pri">
<condition field="destination_number" expression="^.+$">
<action application="bridge" data="openzap/1/a/${destination_number}"/>
</condition>
</extension>
Make sure you give access rights to /dev/wptdm* for FreeSWITCH user in case you are running as non-root user. You can make it with putting:
SUBSYSTEM=="wptdm", OWNER="freeswitch", GROUP="freeswitch", MODE="0660"
into /etc/udev/rules.d/wanpipe.rules and restarting the udev service.
You may also need to add the following to /etc/udev/rules.d/wanpipe.rules:
SUBSYSTEM=="wanpipe", OWNER="freeswitch", GROUP="freeswitch", MODE="0660"
Wanpipe With Boost PRI
The Boost PRI stack groups together all channels from all spans into a single logical span. You may still dial a specific span by using the group nomenclature.
<STUB, more to come when I get a sec to track it all down...>
Debugging PRI With wanpipemon
Sangoma's wanpipemon utility is handy for generating pcap files on the d-channel of a PRI circuit. Check out Sangoma's wiki entry for more information.
OpenZAP Download
mod_openzap is now included with SVN checkout of FreeSWITCH under libs/open_zap. Therefore, you do not have to download the svn.
However, if you have not checked out FreeSWITCH and would like to look at the OpenZAP code, you can browse the OpenZAP source code here or
Download via subversion:
svn co http://svn.openzap.org/svn/openzap/trunk openzap_trunk
Configuration
See Openzap.conf Examples and Openzap.conf.xml Examples. You will also need a zaptel.conf, since it is tied in with ztcfg into the kernel module configs.
NOTE: The new OpenZAP install process will now put the appropriate conf files in ${prefix}/conf/openzap.conf and will put openzap.conf.xml in ${prefix}/conf/autoload-configs/ This is different from the old process. openzap.conf is now located at ${prefix}/conf/openzap.conf and is no longer needed in /etc/openzap.
You will, of course, need to edit both openzap.conf and openzap.conf.xml. Please see the above links to sample configs.
OpenZAP Installation
1. Make sure while compiling FreeSWITCH source, you have included ../../libs/openzap/mod_openzap in modules.conf (just need to uncomment it)
2. Tones should be configured in OpenZAP and not in zaptel. FreeSWITCH uses its libteletone for tones generation and detection, and does not rely on zaptel tones configuration. Therefore it does not matter which country zone is configured in zaptel. Make sure that you have loaded your country-specific tones at /etc/openzap/tones.conf. Check for your country-specific dial-tone/ring-tone/busy-tone etc in tones.conf because you can't make outbound calls on FXO unless you have proper tones configured.For eg, the tones.conf(India) will look like this tones.conf Example
NOTE: By default, tones.conf for USA is available at ${freeswitch_src}/libs/openzap/conf/ , For the new versions, it's installed under ${prefix}/conf/tones.conf
Adding libpri Support
OpenZAP has its own PRI stack that might do everything you require. However, it is still in development. If you would like to use libpri as the PRI stack within OpenZAP, install libpri and compile OpenZAP to use it.
Download and install libpri:
cd /usr/src wget http://downloads.digium.com/pub/libpri/libpri-1.4-current.tar.gz tar -zxvf libpri-1.4-current.tar.gz cd libpri-1.4.X make && make install
Note: replace 'X' with the correct release number. As of this writing, libpri-1.4.10 is the latest version.
Next, re-configure OpenZAP to use libpri:
./configure --with-libpri make make mod_openzap-install
The examples page shows how to configure PRI spans to use libpri.
Once you are using libpri, to see debug information you can type
oz libpri debug 1 all
Rhino Cards
Rhino cards use Zaptel, however there are some caveats. Please see the Rhino page for details.
R2 Support
Moises Silva has added preliminary support for R2. Please see the OpenZAP_OpenR2 page for details.
Hardware/Driver compatibility
OpenZAP should work with the latest Sangoma TDM API as well as any Zaptel dating back to when there was only Tormenta 2.
The hardware support thus far includes Zaptel and native Sangoma TDM API. The existing codebase includes mod_openzap for FreeSWITCH that is currently functional with analog and Euro or DMS100 PRI.
Setup
Configuration Files
Depending upon your specific hardware there are several configuration files. The two primary files are openzap.conf (located in the conf directory) and openzap.conf.xml (located in conf/autoload_configs directory).
In a typical zaptel-based installation, the openzap.conf file will mirror the contents of the zaptel.conf file. The openzap.conf file has several configuration options:
- name - default caller ID name for this span
- number - default caller ID number for this span
- trunk_type - trunk type, i.e. t1, e1, etc.
- b-channel - specify one or more b-channels (ISDN)
- d-channel - specify one or more d-channels (ISDN)
- fxo-channel - specify one or more FXO channels (analog, RBS)
- fxs-channel - specify one or more FXS channels (analog, RBS)
See the openzap.conf_Examples page for some typical setup examples.
The openzap.conf.xml contains the higher layer configuration information for the span(s) that are described in openzap.conf. The openzap.conf.xml file defines a span as analog or PRI. For PRI spans, the dialect type is also specified here.
See the openzap.conf.xml_Examples page for some typical setup examples.
Start Up FreeSWITCH
1. Once you are done with installing zaptel drivers and fixed the FXS/FXO card on your machine, the green LEDs(Digium TDM400 card in my case) on your card will start glowing. (that's good omen for you :-) )
2. At the time of running FreeSWITCH from /usr/local/freeswitch/bin/, make sure again that <load module ="mod_openzap"/> is included in /usr/local/freeswitch/conf/autoload_configs/modules.conf.xml
3. Make sure you see the OpenZAP FXS and FXO configuration messages on your console when you run FreeSWITCH. For example,
2008-05-01 18:10:32 [INFO] zap_zt.c:170 zt_open_range() configuring device /dev/zap/channel channel 1 as OpenZAP device 1:1 fd:33 2008-05-01 18:10:32 [INFO] zap_zt.c:170 zt_open_range() configuring device /dev/zap/channel channel 4 as OpenZAP device 2:1 fd:34 2008-05-01 18:10:32 [INFO] zap_io.c:1978 load_config() Configured 2 channel(s) 2008-05-01 18:10:32 [CONSOLE] switch_loadable_module.c:749 switch_loadable_module_load_file() Successfully Loaded [mod_openzap] 2008-05-01 18:10:32 [NOTICE] switch_loadable_module.c:139 switch_loadable_module_process() Adding Endpoint 'openzap' 2008-05-01 18:10:32 [NOTICE] switch_loadable_module.c:245 switch_loadable_module_process() Adding API Function 'oz'
For digital channels like PRI's the messages will be similar: 2008-09-26 10:55:26 [INFO] zap_io.c:2213 zap_load_module() Loading IO from /usr/local/freeswitch/mod/ozmod_zt.so 2008-09-26 10:55:26 [INFO] zap_io.c:2006 load_config() auto-loaded 'zt' 2008-09-26 10:55:26 [INFO] ozmod_zt.c:170 zt_open_range() configuring device /dev/zap/channel channel 1 as OpenZAP device 1:1 fd:50 2008-09-26 10:55:26 [INFO] ozmod_zt.c:170 zt_open_range() configuring device /dev/zap/channel channel 2 as OpenZAP device 1:2 fd:51 2008-09-26 10:55:26 [INFO] ozmod_zt.c:170 zt_open_range() configuring device /dev/zap/channel channel 3 as OpenZAP device 1:3 fd:52 . . . 2008-09-26 10:55:26 [INFO] ozmod_zt.c:170 zt_open_range() configuring device /dev/zap/channel channel 96 as OpenZAP device 4:24 fd:144 2008-09-26 10:55:26 [INFO] zap_io.c:2137 load_config() Configured 96 channel(s) 2008-09-26 10:55:27 [INFO] zap_io.c:2230 zap_load_module() Loading SIG from /usr/local/freeswitch/mod/ozmod_isdn.so 2008-09-26 10:55:27 [INFO] zap_io.c:2346 zap_configure_span() auto-loaded 'isdn' 2008-09-26 10:55:27 [CONSOLE] switch_loadable_module.c:789 switch_loadable_module_load_file() Successfully Loaded [mod_openzap]
4. Now you can take a ride on your Ozzzzzzz... zip zap zoom ;)
OpenZAP CLI Commands
To see a list of your configured spans, at the CLI type
oz list
To see detailed information about a specific span type
oz dump <span_id> [<chan_id>]
To save Q931 packets in a *.pcap file for decoding in wireshark
oz q931_pcap <span_id> on|off [pcapfilename without suffix]
Note: Only if you have libpcap and libpcap-devel installed on your system! Also note that you can't use libpri if you want to be able to capture the q931 traffic, it only works with ozmod_isdn.
To see debug messaging if you are using libpri
oz libpri debug <span_id> all
To turn off the debug messaging if you are using libpri
oz libpri debug <span_id> off
Dialplan Configuration
Usage
The syntax of the bridge application data's option is openzap/span/port/phone-number.
To automatically discover of a free port number instead of a number you can use "a" or "A". For example, "openzap/1/a/123456789" will pick up the first available port in span 1 to dial the number 123456789.
Using "A" for the port will find the highest-numbered port available.
Examples
1. To bridge an inbound call to your FXS that is configured on channel 1, for an UA registered as 507@proxy.com configure as below
<extension name="incoming-fxs">
<condition field="destination_number" expression="^(507)$">
<action application="bridge" data="openzap/1/1"/>
</condition>
</extension>
2. To bridge an outbound call onto your FXO card that is configured on channel 4, for any 10-digit destination configure as below
<extension name="outgoing-fxo">
<condition field="destination_number" expression="^(\d{10})$">
<action application="bridge" data="openzap/2/1/${dialed_ext}"/>
</condition>
</extension>
3. To bridge an outbound call to the first available port from a dual-span PRI card, regardless of the span number (will try the 1st span first, then the 2nd span if the 1st one is not available):
<extension name="outgoing-pri">
<condition field="destination_number" expression="^(\d{10})$">
<action application="bridge" data="openzap/1/a/$1|openzap/2/a/$1"/>
</condition>
</extension>
4. To bridge about outbound call to the last available channel on a PRI span:
<extension name="outgoing-pri">
<condition field="destination_number" expression="^(\d{10})$">
<action application="bridge" data="openzap/1/A/$1"/>
</condition>
</extension>
Examples
As an example, let's see configuration for OpenZap module with Digium TDM400P 2FXS/2FXO card. Configuration OpenZAP- DigiumTDM400P Example
Tormenta2: Openzap.conf Examples and Openzap.conf.xml Examples. You will also need a zaptel.conf, since it is tied in with ztcfg into the kernel module configs.
Here's a step-by-step for installing and configuring a Sangoma A101DE card with libpri configured for T1/NI2.
Debugging your OpenZAP set up
Symptom: "Why bother changing state on 1:1 from UP to UP" or "Cannot get a RING_START event on a non-fxo channel"
Resolution: The problem here is that you have your channel that connects to the telco defined as an fxs channel, instead of an fxo channel. Note that the other guys ask you to specify what kind of signalling the channel is expecting at the other end, while FreeSWITCH wants you to specify what type of signalling the FreeSWITCH end is.
To fix this, change your openzap.conf to something similar to
[span zt] name => OpenZAP number => 1 fxo-channel => 1
Your zaptel.conf still requires you to specify what sort of signalling you are expecting to see on the other end so it will look like
fxsks=1 loadzone=us defaultzone=us
Symptom: [ERR] ozmod_wanpipe.c:440 wp_open_range() failure configuring device s*c** using a Sangoma card with FreeSWITCH running as a normal user
Use UDEV to set the right permissions. Create an file called /etc/udev/rules.d/wanpipe.rules with the following line (replace freeswitch with your actual user) :
SUBSYSTEM=="wptdm", OWNER="freeswitch", GROUP="freeswitch", MODE="0660"
Then reload your udev by doing /etc/init.d/udev reload or restarting your system and reload your wanpipe, The permissions should now be correct. CentOs I use start_udev
Symptom: Signalling works but buzzing audio is heard using Wanpipe on a 64 bit system with > 4 GB RAM
Recompile wanpipe with ./Setup install --64bit_4GB
FAQ
Q: OpenZAP vs. mod_wanpipe
OpenZAP replaces mod_wanpipe
Q: OpenZAP vs. libpri
OpenZAP can replace libpri or can be used with libpri. Because OpenZAP is licensed under the BSD it is actually compatible with the GPL-licensed libpri. See OpenZAP#Adding_libpri_Support for setup instructions.
Q: Does OpenZAP support libss7?
Currently we do not have any open source SS7 solutions but commercial options are available.
Q: How do I configure spanmaps?
This can be done in the autoload_configs/openzap.conf.xml file.
Q: Do you need a special tor2.c for using Tormenta2?
You should not need anything special, just zaptel loaded with any plugin tor2, whatever. Any variation of the driver should be fine since zaptel is fairly generic. Tormenta2 clones from pbxhardware.com are reported to work well.
Q: For analog cards (XP100), will I need zaptel kernel drivers?
Yes, for analog cards, OpenZAP communicates w/ the zaptel kernel drivers via sockets, which in turn communicates with the hardware card.
Q: If I want Sangoma with OpenZAP, do I need wanpipe installed?
Yes
Sangoma cards can be used in two ways with OpenZAP depending on the driver set in FS_ROOT_DIR/conf/openzap.conf
- Using the wanpipe driver if the span is configured as TDM_VOICE_API in the Wanrouter setup script.
- Using the zaptel driver if the span is configured as TDM_VOICE in Wanrouter setup script.
AFAIK wanpipe is preferred, but if you need to use things like OSLEC operating in the zaptel driver you will need to use the second option.
Q: Does OpenZAP support ccs, hdb3 with Digium te420?
If those are configured with the drivers, then yes, we support zaptel. OTOH if those are something in userspace, then no.
Q: Does OpenZAP support EuroISDN?
The euro patches are now inside the svn source code, more testers are needed to complete the work.
For EuroISDN support you need to specifiy Q931 as the dialect in openzap.conf.xml.
The following has been tested:
- Caller ID works.
- Calling in and out works.
- Privacy set with the privacy application is not working. The caller presentation is not changed. We have yet to confirm if this is a problem with OpenZAP or the privacy app.
Q: Does OpenZAP support OSLEC?
Yes. OSLEC operates at the Zaptel driver level so no special OpenZAP configuration is needed. Just load OSLEC and go!
Q: How do I configure my TDM400P (FXO & FXS) in FreeSWITCH?
This is how I configured my TDM400P in FreeSWITCH, If anyone wants to move this over to wiki.freeswitch.org go ahead: FreeSWITCH and TDM Hardware (POTS FXO/FXS)
