Asterisk MFC R2

This page explains how to install MFC/R2 support for Asterisk

Disclaimer

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. Sorry about that. Report them, and I will try to improve
things.

New MFC/R2 Library

There is now an alternative to using Unicall if you need MFC/R2 support, it is libopenr2. It is a lot easier to install than Unicall and it has been already integrated in Asterisk 1.6.2 by default into chan_dahdi/chan_zap, no patching needed, there is also patches and svn branches available for previous Asterisk versions. This is the official way to install R2 support for Asterisk.

The asterisk-r2 mailing list has been created for the MFC-R2 users community to ask questions and share information.


Architecture

The zaptel signal chain is usually:
PSTN - zaptel card - zaptel driver - libpri - chan-zap - asterisk

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 - zaptel card - zaptel driver - libmfcr2 - libunicall - chan-unicall - asterisk

Getting zaptel set up to use an E1 card for MFC/R2

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

Getting the libraries installed

Up-to-date version of unicall for Asterisk 1.4 can be found at http://www.moythreads.com/astunicall/downloads/

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.html

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 *) see the note below>
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.

Note (version 0.0.3): --prefix must be specified even if you want to install in default location /usr/local. reference


Testing your MFC/R2 signalling installation

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.
Argentina             "ar"
Bahrain               "bh"
Bolivia               "bo"
Brazil                "br"
Chile                 "cl"
China                 "cn"
Colombia landlines    "co-land"
Colombia cellular     "co-cell"
Czech                 "cz"
Honduras              "hn"
India                 "in"
Indonesia             "id"
Korea                 "kr"
Malaysia              "my"
Mexico                "mx"
Panama                "pa"
Philipinnes           "ph"
Singapore             "sg"
Thailand              "th"
  

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.

A complete protocol variant code is as follows:
"<country code>,<maximum ANI digits>,<DNIS digits>;"

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.

NOTE: a document describing how to test libmfcr2 with testcall and some other
usefull tips about it can be found at:

http://www.moythreads.com/unicall/mfcr2-asterisk-unicall-0.2-english.pdf


Getting Asterisk to work with your MFC/R2 setup

Get chan_unicall.c, unicall.conf.sample and channels_makefile.patch from
ftp://ftp.soft-switch.org/pub/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

Check that chan_unicall.so is in the CHANNEL_LIBS list
in the makefile
CHANNEL_LIBS=chan_modem.so chan_sip.so \
chan_modem_aopen.so \
chan_modem_bestdata.so chan_modem_i4l.so \
chan_agent.so chan_mgcp.so chan_iax2.so \
chan_local.so chan_skinny.so chan_unicall.so

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. Now when
you run Asterisk you should have MFC/R2 support.

Country and carrier specific protocol variants

Sometimes the protocol variant depends not only on the country but also on the carriers. It would be interesting to have a complete list of protocol variants, including the different carriers that may exist in each country. The list that is provided here is still very incomplete, so if you have any additional information or correction, please feel free to add it. The information that is provided for each country/carrier combination should be placed in the protocolvariant field of the unicall.conf file.

Argentina

Telecom E1

protocolvariant=ar,10,4

Brazil

Embratel

protocolvariant=br,20,4,8

Brasil Telecom

protocolvariant=br,20,4

Telefonica Brasil

protocolvariant=br,20,20

GVT

protocolvariant=br,20,20

Telemar

protocolvariant=br,20,20

Colombia

ETB

protocolvariant = ar,20,4

Telefónica Telecom

protocolvariant = br,10,7,7

Mexico

Telmex and Avantel

protocolvariant=mx,10,4

Phillippines

Nextel

protocolvariant=ph,12,18,1



This page explains how to install MFC/R2 support for Asterisk

Disclaimer

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. Sorry about that. Report them, and I will try to improve
things.

New MFC/R2 Library

There is now an alternative to using Unicall if you need MFC/R2 support, it is libopenr2. It is a lot easier to install than Unicall and it has been already integrated in Asterisk 1.6.2 by default into chan_dahdi/chan_zap, no patching needed, there is also patches and svn branches available for previous Asterisk versions. This is the official way to install R2 support for Asterisk.

The asterisk-r2 mailing list has been created for the MFC-R2 users community to ask questions and share information.


Architecture

The zaptel signal chain is usually:
PSTN - zaptel card - zaptel driver - libpri - chan-zap - asterisk

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 - zaptel card - zaptel driver - libmfcr2 - libunicall - chan-unicall - asterisk

Getting zaptel set up to use an E1 card for MFC/R2

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

Getting the libraries installed

Up-to-date version of unicall for Asterisk 1.4 can be found at http://www.moythreads.com/astunicall/downloads/

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.html

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 *) see the note below>
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.

Note (version 0.0.3): --prefix must be specified even if you want to install in default location /usr/local. reference


Testing your MFC/R2 signalling installation

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.
Argentina             "ar"
Bahrain               "bh"
Bolivia               "bo"
Brazil                "br"
Chile                 "cl"
China                 "cn"
Colombia landlines    "co-land"
Colombia cellular     "co-cell"
Czech                 "cz"
Honduras              "hn"
India                 "in"
Indonesia             "id"
Korea                 "kr"
Malaysia              "my"
Mexico                "mx"
Panama                "pa"
Philipinnes           "ph"
Singapore             "sg"
Thailand              "th"
  

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.

A complete protocol variant code is as follows:
"<country code>,<maximum ANI digits>,<DNIS digits>;"

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.

NOTE: a document describing how to test libmfcr2 with testcall and some other
usefull tips about it can be found at:

http://www.moythreads.com/unicall/mfcr2-asterisk-unicall-0.2-english.pdf


Getting Asterisk to work with your MFC/R2 setup

Get chan_unicall.c, unicall.conf.sample and channels_makefile.patch from
ftp://ftp.soft-switch.org/pub/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

Check that chan_unicall.so is in the CHANNEL_LIBS list
in the makefile
CHANNEL_LIBS=chan_modem.so chan_sip.so \
chan_modem_aopen.so \
chan_modem_bestdata.so chan_modem_i4l.so \
chan_agent.so chan_mgcp.so chan_iax2.so \
chan_local.so chan_skinny.so chan_unicall.so

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. Now when
you run Asterisk you should have MFC/R2 support.

Country and carrier specific protocol variants

Sometimes the protocol variant depends not only on the country but also on the carriers. It would be interesting to have a complete list of protocol variants, including the different carriers that may exist in each country. The list that is provided here is still very incomplete, so if you have any additional information or correction, please feel free to add it. The information that is provided for each country/carrier combination should be placed in the protocolvariant field of the unicall.conf file.

Argentina

Telecom E1

protocolvariant=ar,10,4

Brazil

Embratel

protocolvariant=br,20,4,8

Brasil Telecom

protocolvariant=br,20,4

Telefonica Brasil

protocolvariant=br,20,20

GVT

protocolvariant=br,20,20

Telemar

protocolvariant=br,20,20

Colombia

ETB

protocolvariant = ar,20,4

Telefónica Telecom

protocolvariant = br,10,7,7

Mexico

Telmex and Avantel

protocolvariant=mx,10,4

Phillippines

Nextel

protocolvariant=ph,12,18,1



Created by: lvazquez, Last modification: Fri 10 of Jul, 2009 (18:04 UTC) by moy
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+