In almost every country and territory telecoms equipment must be formally approved before it is used with the public telephone network. The penalties for attaching non-approved equipment vary greatly. In some places they are quite severe. The approvals process - what needs approving, and how you do it - also varies greatly. The software described in this document has not passed through any approvals process. The author of this software takes no responsibility for how it is used. OK, now on to the fun stuff........
This is a first attempt at documenting this procedure, so the document might well contain errors. Soory about that. Report them, and I will try to improve things.
The zaptel signal chain is usually something like:
MFC/R2 works with a new abstration library, called libunicall. This provides a unified call handling interface (hence unicall) suitable for most telephony signalling protocols. The signal chain is:PSTN - telephony card - zaptel driver - libpri - chan_zap - asterisk
PSTN - telephony card - zaptel driver - libmfcr2 - libunicall - chan_unicall - asterisk
If you need an explanation of what the MFC/R2 signalling protocol is, and how it works, look here. If you have problems debugging an installation, this information may help.
First you need to install the zaptel drivers, as you would for any other use of the Digium cards. Then you need to configure the /etc/zaptel.conf file to put the channels into the appropriate mode. For a TE405P/TE410P running 4 E1s of MFC/R2 you will want something like this:
# MFC/R2 does not normally use CRC4 span=1,1,0,cas,hdb3 span=2,0,0,cas,hdb3 span=3,0,0,cas,hdb3 span=4,0,0,cas,hdb3 # cas=1-15:1101 cas=17-31:1101 # cas=32-46:1101 cas=48-62:1101 # cas=63-77:1101 cas=79-93:1101 # cas=94-108:1101 cas=110-124:1101
The 4 characters after the colon in the cas statements define the idle pattern for the signalling bits. For China and Thailand you should use 1111 instead of 1101. 1101 should be correct for all other countries using MFC/R2. This pattern puts the trunk in the blocked state, so when no application software is using the trunk it behaves in a sensible way.
After running ztcfg with the above zaptel.conf file you should have 4 working E1s. If you have an active MFC/R2 E1, connect it to one of the ports on the TE405P card. You should get a green light. If you make calls into the E1 you find the E1 is blocked. This is the correct state before asterisk is started.
Now you need to build and install spandsp, libsupertone, libmfcr2 and libunicall from the tarballs. These may be downloaded from http://www.soft-switch.org/downloads
spandsp is a library of DSP functions for telephony. It includes a number of call processing and modem functions. For MFC/R2 signalling we use it to generate and detect the signalling tones. Untar the spandsp tarball. Use cd to move to the spandsp directory, and use the following commands to build and install it:
./configure make make install
This will install the library in /usr/local. In this case make sure your /etc/ld.so.conf file has an entry for /usr/local/lib. If you wish the software to be installed in /usr, you should build it with the commands.
./configure --prefix=/usr make make install
Whichever directory you choose to use, be consistent and use the same one for all the modules.
libsupertone implements supervisory tones for almost every country in the world. It is used by libunicall. Untar the libsupertone tarball. Use the cd command to move to the libsupertone directory, and use the following commands to build and install it:
./configure <add --prefix=/usr if you wish> make make install
libunicall is the signalling abstraction layer. Untar the libunicall tarball. Rename the directory as "libunicall" (I need to clean up some points in the build process, but this works for now) Then use the following commands to build and install it:
./configure <add --prefix=/usr if you wish> make make install
libmfcr2 implements the MFC/R2 signalling protocol, and interfaces to Digium's E1 cards. It is a protocol module for use by libunicall. Untar the libmfcr2 tarball. Use the cd command to move to the libmfcr2 directory, and use the following commands to build and install it:
./configure <add --prefix=/usr if you wish> make make install
As well as installing the MFC/R2 software as a library, it is also installed in /usr/lib/unicall/protocols as a shared object module, which can be dynamically loaded by libunicall. libunicall always looks for protocol modules in this directory.
If you have got this far, and have an MFC/R2 signalled E1 line connected to a Digium E1 card on your machine, you should now be able to test it. There is a test program in the libunicall directory, called testcall. This is able to make and receive calls. You will need to edit the source code a little to match your needs, and then compile the program. At the start of testcall.c there are several lines defining the exact protocol, phone numbers and trunks to be used for testing.
The protocol class should be "mfcr2". The protocol variant depends on the country. Many countries use MFC/R2 signalling. Although it is specified in ITU specifications, each country actually uses its own variant of what the ITU has specified. The following variants have been implemented so far. If you have the information necessary to add further variants to the software, other variants can be added fairly easily. The short UN codes shown on the right are the codes you should use to specify the variant you wish to use.
Note that Indonesia has two protocols, which they call R2. One is a real digital R2 variant. The other is more like the old analogue R2 systems. Only the real digital R2 variant is currently supported.Algeria "dz", Argentina "ar" Bahrain "bh" Bolivia "bo" Brazil "br" Chile "cl" China "cn" Colombia landlines "co-land" Colombia cellular "co-cell" Czech "cz" Democratic Republic of Congo "cd" Egypt "eg", Ghana "gh" Honduras "hn" India "in" Indonesia "id" Iraq "iq" Korea "kr" Kuwait "kw" Malaysia "my" Mexico "mx" Nigeria "ng" Panama "pa" Philipinnes "ph" Romania "ro" Saudi Arabia "sa" Singapore "sg" Thailand "th" Venezuela "ve" Vietnam "vn"
A complete protocol variant code is as follows:
"<country code>,<maximum ANI digits>,<DNIS digits>[,<options>]"
The optional options field allows some of the less commonly used options to be selected. It is a bit mask, as follows:
For example:
"cn,20,7"
means use China MFC/R2. Expect up to 20 ANI (caller number) digits. Expect 7 DNIS (dialed number) digits. Most variants can handle less than the specified number of DNIS digits, but some only handle this through fairly long timeouts. Getting the DNIS length right can be important for good performance.
The protocol end should be set to UC_MODE_CPE (customer premises end) or UC_MODE_CO (central office end). MFC/R2 is a peer-to-peer protocol, so this parameter is ignored. For other protocols (e.g. ISDN) it can be important.
The base ANI is the caller ID which will be used for outgoing calls. The base DNIS is the number which will be dialed on the first trunk. It is incremented for each additional trunk.
FIRST_TRUNK_CIRCUIT should be set to the first zaptel circuit number of the first MFC/R2 E1 line. NUM_TRUNKS should be set the number of trunks to be used. So, if you have two E1s to be used for MFC/R2, and they are the second and third E1s in your system, you probably want "#define FIRST_TRUNK_CIRCUIT 32" amd "#define NUM TRUNKS 60".
If you want the trunks to just wait for incoming calls set FIRST_OG_TRUNK to -1. If you want some of the trunks to make test calls, set FIRST_OG_TRUNK to the sequence number of the first trunk, counting from zero. Set NUM_OG_TRUNKS to the number of contiguous trunks. So, to make calls on the first 5 trunks of the setup in the last paragraph you would use "#define FIRST_OG_TRINK 0" and "#define NUM_OG_TRUNKS 5".
If you edit and compile testcall, you can run it by just typing "./testcall". If will then listen for calls on all the configured circuits.
Get chan_unicall.c, unicall.conf.sample and channels_makefile.patch from http://www.soft-switch.org/downloads/unicall. Copy chan_unicall.c and channels_makefile.patch to the channels directory of your Asterisk source tree. Patch the Makefile in that directory with the command:
patch <channels_makefile.patch
Now, if you run "make" and "make install" for Asterisk it should build a new channel driver - chan_unicall. Copy unicall.conf.sample to /etc/asterisk/unicall.conf. Edit this file to match your trunks. Its structure is similar to chan_zap. You will need to sepcify the protocol variant in the same way as for the testcall program.Now when you run Asterisk you should have MFC/R2 support.
There are a large number of variants of MFC/R2 around the world. Even within a single country there can be several slight variations. The following list is of reported successes. There is no way for the software developer to confirm these. Success has been reported in a number of other countries, and with other Telcos. However, the details needed to add them to this list are not available.
If you have success, please provide the Telco's name and any special tuning details needed to make your installation work properly. Let's try to make this a comprehensive list.
Numerous users have success by specifying the configuration as follows:
protocolvariant=ar,10,4
A number of installations in Brazil require a timeout for clearing a call. This is to prevent them from clearing when the telco sends metering pulses. To enable this, look for the following line:
and change it to:mfcr2->clear_back_persistence_check = 0;
and recompile the software. This timeout is in milliseconds. If you still have trouble, trying increasing it to 500. Future versions of Unicall will make this timeout selectable without recompiling.mfcr2->clear_back_persistence_check = 300;
protocolvariant=br,20,4,8
protocolvariant=br,20,4
protocolvariant=br,20,20
protocolvariant=br,20,20
Colombia has two versions of MFC/R2 - one for land lines and one for cellular. Some (unspecified) providers are known to work with the Columbian Land Line protocol. However, it seems some lines use the Argentinian protocol.
ETB is reported to work with the Argentinian protocol, using:
protocolvariant = ar,20,4
protocolvariant=mx,10,4
protocolvariant=mx,10,4
protocolvariant=ph,12,18,1
protocolvariant=ph,12,18,1