Super Technologies

1. What is spandsp

Spandsp is a library for Digital Signal Processing(DSP). DSP is used to turn images into audio and back. In Asterisk, spandsp, is required for sending and receiving faxes.

The main web site of spandsp is http://soft-switch.org/. There you can find the latest version.

 

2. Packages required by spandsp

1) Libtiff – This is the only package, required by spandsp. This package provides support for the Tag Image File Format(TIFF). This is a format, used for storing image data. If you need more information about the TIFF format, you can follow the link in our references.

Libtiff contains the library, used for the reading and writing of TIFF files, on UNIX-based systems.

To install the libtiff package, go to the main website of libtiff, which is http://www.libtiff.org/. Go to the download section – http://dl.maptools.org/dl/libtiff/ and download the desired package. According to the information from the spandsp web site, the libtiff version 3.5.7, 3.6.0 or 3.7.1 works OK.

NOTE: For this tutorial we will use the libtiff version 3.7.1.

Now, go to the directory where you downloaded the file and unzip it.

Enter the directory, where the unzipped files are- cd tiff-version.

Execute the following commands, one by one:

./configure
make clean
make
make install
ldconfig

Check your /etc/ld.so.conf file.

It has to be in the /etc/ directory.

If you do not have such file – make one. In the file you need to add the path to the spandsp library. By default the directory is /usr/local/lib. So if you do not have such line in your file, you have to add it manually.

run ldconfig after u add it. 

3. How to install spandsp

Once, you have finished with the libtiff package, it is time to install the spandsp package.

STEP 1) Download the spandsp package. You can do this from the main web site http://soft-switch.org/downloads/spandsp/. Also, you need to download 3 more files from here. They are: app_rxfax.c, app_txfax.c and apps_makefile.patch.

NOTE: For this tutorial we will use the spandsp version 0.0.2pre21

STEP 2) The installation.

Unzip the spandsp package by using the command: tar -xvzf spandsp-version.tar.gz

Go to the directory of the spandsp and type the following commands, one by one.

./configure
make clean
make
make install

STEP 3) Put the app_rxfax.c, app_txfax.c and apps_makefile.patch files in the Asterisk application directory. Usually it is /usr/src/asterisk/apps

STEP 4) Patch the Makefile. You can achieve this by typing the following command:

patch <apps_makefile.patch

Remember, that you have to be in the Asterisk application directory(usually /usr/src/asterisk/apps), when you are executing the command.

STEP 6) Rebuild your Asterisk. Go to the asterisk directory (usually /usr/src/asterisk) and type the following commands:

make clean
make
make install

At the end, if everything is OK you will have two more applications added – rx_fax and fx_fax. You can check this by starting the Asterisk and using the show applications command.

 

4. Sending faxes through SIP using spanDSP

Prerequisites

You need a working Asterisk PBX with registered user in the sip.conf file and made extensions. Also, you need a fax machine and an ATA device.

NOTE:We will use Asterisk CVS HEAD version. Our fax machine is Brother FAX-T94. The ATA device is Grandstream HandyTone-486 – the firmware is 1.0.6.2. To learn more about the configuration of this ATA device please take a look at our tutorial

Asterisk PBX configurations

sip.conf Configurations

We need one registered user in the sip.conf file.

So, we have registered the user sip_fax.

Type=friend means that this user can make and receive calls. Host=dynamic means that the IP is not static but dynamic through a DHCP server. Allow=all means that the line which this user will use, could support all audio codecs. Context=test1 – this shows that this user is working with the extensions in this context of the configuration file extensions.conf.

IMPORTANT: You can send and receive faxes with spandsp only through the G.711(alaw or ulaw) codecs.

extensions.conf Configurations

Now lets take a look at the extensions.conf file.

On the picture above you can see our extensions.conf file.

We have an extension 300. This will be the extension on which we will receive faxes. As you can see the first application is Answer. If you want to receive faxes, you have always to answer the channel by using this application. In this way the Asterisk will hear for a fax signal.

It seems that there is a problem with the hanging up after the sending of fax. So, if you try to execute the Hangup application in the extension 300 with priority 5, nothing will happen. So, the solution is to use the AbsoluteTimeout application. As argument in its brackets we have set 35, which means that after 35 seconds the execution will continue with the extension with letter T. This one will execute the Hangup application, which will hang up the channel.

Then we have the Set application. It will set the path and the name of the file, where we would like the fax to be stored. They will be set to a variable, named FAXFILE.

The name of the file is test.tif. The directory where it will be stored is /tmp/.

NOTE: Please pay attention, that you will have to allow the reading and writing in this directory.

Finally we have the extension with the RxFax application. It will allow us to send a fax from the fax machine to the Asterisk and to store it in a file. As argument in the brackets we have set only the variable ${FAXFILE}, which we have used in the Set application, to set the location and the name of the file.

Now, when somebody dials the number 300 from its fax machine and then press the start button for sending faxes. The Asterisk will answer the channel, hear the fax signal and execute the RxFax application. The fax will be stored in the file test.tif in the /tmp directory.

Grandstream HandyTone-486 configurations

There are a few settings which you have to do in the ATA. Using the web interface go to the Advanced Settings.

Set the SIP Proxy Server. This is the IP address of your Asterisk Server. In our case the IP is 10.3.3.34, but in your case it could be different. For the Outbound Proxy set the same IP address (The IP address of your Asterisk).

For the SIP User ID, write the name of the user, as it is set in your sip.conf file. In our case this is sip_fax. In your case it could be different. Authenticate ID – write the same username as in the previous option. In our case again sip_fax. Authenticate Password is related with the secret setting in the sip.conf file. So here you have to write the same as you have written in the secret option for the user which you are going to use. In our example we have set for the user sip_fax, a secret=sip_fax. So for Authenticate Password, we will write again sip_fax. In your case could be different.

Do not forget, that you can send faxes through the spandsp only by using the G.711 (ulaw or alaw) codec. So, it is very important to set the preferred codecs for the Grandstream HandyTone-486 to either PCMA(alaw) or PCMU(ulaw). In our case the codecs are set to PCMU(ulaw).

The most import option which you have to set is the FaxMode. It is set to T.38(Auto Detect) by default. You have to change it to Pass-Through.

More about the configuration of the Grandstream HandyTone-486 you can learn from our tutorial

 

Screenshot of what you can see on the CLI of the Asterisk PBX

 

Additional information

For more information about extensions.conf you can check here.
For more information about sip.conf you can check here.

This application is tested with Brother FAX-T94 fax machine and Asterisk CVS HEAD version. They are connected through Grandstream HandyTone-486 ATA (firmware 1.0.6.2).

 

Uploaded files

extensions.conf
sip.conf

 

5. Receiving faxes through SIP using spanDSP

 

6. Troubleshooting

1) If you have problems with the patching of the Makefile. If you receive like the following:

patching file Makefile
Hunk #1 FAILED at 55.
Hunk #2 FAILED at 93.
2 out of 2 hunks FAILED — saving rejects to file Makefile.rej

Then you have to change the Makefile file manually.

Open the apps_makefile.patch. Find the lines which started with "+". These are the lines which you have to add to the Makefile file. In our case these lines are:

+APPS+=$(shell if [ -f /usr/include/spandsp.h ]; then echo "app_rxfax.so app_txfax.so" ; fi)
+APPS+=$(shell if [ -f /usr/local/include/spandsp.h ]; then echo "app_rxfax.so app_txfax.so" ; fi)

and

+app_rxfax.so : app_rxfax.o
+ $(CC) $(SOLINK) -o $@ $< -lspandsp -ltiff
+
+app_txfax.so : app_txfax.o
+ $(CC) $(SOLINK) -o $@ $< -lspandsp -ltiff

You have to add the lines in the following places:

The first two lines have to be added after the following line:

ifneq ($(wildcard $(CROSS_COMPILE_TARGET)/usr/local/include/osp/osp.h $(CROSS_COMPILE_TARGET)/usr/include/osp/osp.h),)
APPS+=app_osplookup.so
endif

and the next two lines after:

app_sql_odbc.so: app_sql_odbc.o
$(CC) $(SOLINK) -o $@ $< -lodbc

NOTE: The "+" signs at the beginning of the lines does not have to be included in the Makefile. So, omit them.

2) If you receive a message like the following:

[app_txfax.so]Oct 5 12:05:24 WARNING[14665]: loader.c:314 __load_resource: /usr/lib/asterisk/modules/app_txfax.so: undefined symbol: fax_set_header_info
Oct 5 12:05:24 WARNING[14665]: loader.c:543 load_modules: Loading module app_txfax.so failed!
Ouch … error while writing audio data: : Broken pipe

When you execute the asterisk -vvvvvvvc command and the Asterisk crashes when you try to execute the safe_asterisk command, then very probably you have the following problem:

The previously installed version of spandsp has been 0.0.3, but now you have installed version 0.0.2. The problem is that the installation of version 0.0.3 creates a symlink, which is not replaced by installation of version 0.0.2. So the symlink points to the library of version 0.0.3, which actually does not exist.

The solution is to find the location of this symlink and to delete it manually. Usually it is in the /usr/lib/ directory. Go through the steps from section 3. How to install spandsp.

3)The system executes the RxFax application. The fax machine seems to start the sending, but unexpectedly the Asterisk hangs up the line.

The solution. The problem could be in the directory, where you would like to store the faxes. Check whether it is created. Also check whether do you have rights to read and write into this directory.

4)If you receive a message like this one:

Jun 3 10:20:05 WARNING[14277]: chan_sip.c:3063 process_sdp: Unknown SDP media type in offer: image 49170 udptl t38

Then probably your ATA is configured to use T.38. Go through the web interface to the Advanced Settings and switch the FAX Mode to Pass-Through

 

7. Packages

This are the software and the packages, we are using. You can download them by clicking the links.

The RxFax and TxFax applications
Spandsp-0.0.2pre21
Libtiff-3.7.1
Libpri
Zaptel
Asterisk

 

8. References

The spandsp on ScottStuff
A forum post with example about spandsp extension
E-fax on AsteriskBrasil
The TIFF graphics format on wikipedia