Mod fax

From FreeSWITCH Wiki

Contents 1 Status 1.1 Installation and configuration 1.2 Invoking the app from the XML dialplan 1.2.1 For receiving a fax 1.2.2 For transmitting a fax 1.3 Invoking the app from the CLI 1.3.1 For transmitting a fax 1.4 Emailing the fax upon receipt 1.5 Configuring the app 1.6 Controlling the app 1.7 Checking the results 2 Error result codes 3 Tests

Status

We are finishing mod_fax. It requires full field testing now.

Its important that you create the config XML file since the spool directory for faxes can be configured only there.

Things to be done:

• fire out an event on every fax received/sent;
• fire out an event on every page fax received/sent;
• T.38 support;

Installation and configuration

• Enable mod_fax in modules.conf and recompile.
• Make sure to copy and edit fax.conf.xml into your appropriate autoload directory
• Enable mod_fax in Modules.conf.xml

If you receive 'No targets specified and no makefile found' when making mod_fax, then spandsp is probably not configured.

• Ensure that you have libtiff development files installed
  • For Debian/Ubuntu you can type

• For CentOS 5.x

Now it should make mod_fax

Invoking the app from the XML dialplan

You can invoke the rxfax application and use the data option to pass it the TIFF file name. If you do not pass any information in the data option mod_fax will create the file name for you and place the received fax into your spool directory.

(This section need to be completed)

For receiving a fax

<extension name="test_rxfax_stream">
       <condition field="destination_number" expression="^\*90012$">
               <action application="answer" />
               <action application="playback" data="silence_stream://2000"/>
               <action application="rxfax" data="//my_directory//rxfax.tiff"/>
               <action application="hangup"/>
       </condition>
</extension>

For transmitting a fax

A PDF file can be converted to TIFF format using ImageMagick, here is an example:

convert -density 204x98 -resize 1728x1186 -monochrome -compress Fax txfax.pdf txfax.tiff

For a better Quality, you can use Ghostscript for PDF/PS files, here is an example:

gs -q -sDEVICE=tiffg3 -r204x98 -dNOPAUSE -sOutputFile=txfax.tiff -- txfax.pdf

NOTE: Ghostscripts wont put your document in the correct orientation... not really a problem when sending to a remote paper machine, but it nice to have it correctly when receiving a fax on a computer. ImageMagick put the correct orientation BUT the quality is FAR from the quality of ghostscript

You can transmit a Fax using the following dialplan:

<extension name="test_txfax_stream">
       <condition field="destination_number" expression="^\*90012$">
               <action application="txfax" data="txfax.tiff"/>
               <action application="hangup"/>
       </condition>

</extension>

Invoking the app from the CLI

For transmitting a fax

In the CLI, for sending a fax via profile external using gateway 10.10.10.10 and fax machine number 100, you'll have to use this

originate sofia/external/100@10.10.10.10 &txfax(/path_to_fax_file)

Or to specify the gateway to use:

originate sofia/gateway/<gateway name>/<phone number> &txfax(/path_to_fax_file)

Emailing the fax upon receipt

This configuration assumes a debian based system, adapt as necessary:

• apt-get install mailx sharutils
• Using the following dialplan instead of above, replacing USER@DOMAIN as desired:

<extension name="test_rxfax_stream">
       <condition field="destination_number" expression="^\*90012$">
               <action application="answer" />
               <action application="playback" data="silence_stream://2000"/>
               <action application="rxfax" data="/tmp/${uuid}.rxfax.tiff"/>
               <action application="system" data="/opt/freeswitch/scripts/emailfax.sh USER@DOMAIN /tmp/${uuid}.rxfax.tiff"/>
               <action application="hangup"/>
       </condition>
</extension>

• Create the /opt/freeswitch/scripts/emailfax.sh file as follows, changing DOMAIN to your desired DOMAIN:

#!/bin/bash
# Send an email with the fax attachment
# $1 is email
# $2 is filename

(echo "Fax received"; uuencode "$2" "$2") | mail -a "Reply-To:noreply@DOMAIN" -a "From:noreply@DOMAIN" -s "Fax received" "$1"

Here is another example, using a python script called process-rxfax.py, via Dialplan XML:

<extension name="test_rxfax_python"/>
       <condition field="destination_number" expression="^\*90012$">
               <action application="set" data="recipient=YOU@YOURDOMAINHERE.com"/> 
               <action application="python" data="process-rxfax"/> 
               <action application="hangup"/>
       </condition>
</extension>

This python script gets put into your FreeSWITCH's Mod_Python path, and will launch mod_fax to receive the fax and then convert it to a PDF and email it. The script requires that you have the ps2pdf utility (from ghostscript) and tiff2ps installed. In FreeBSD these are in Ports and are also available under most Linux distributions via package management (apt-get, yum, rpm etc). This python script also requires a working mod_python and mod_fax installation. More information here.

Configuring the app

App can be controlled globally using fax.conf.xml

<configuration name="fax.conf" description="FAX application configuration">
   <settings>
       <param name="use-ecm"       value="true"/>
       <param name="verbose"       value="true"/>
       <param name="disable-v17"   value="false"/>
       <param name="ident"         value="SpanDSP Fax Ident"/>
       <param name="header"        value="SpanDSP Fax Header"/>
       <param name="spool-dir"     value="/tmp"/>
       <param name="file-prefix"   value="faxrx"/>
   </settings>
</configuration>

Controlling the app

You can set the following channel's varialbles to control the behavior of the mod application:

• fax_force_caller - Force to act as caller or receiver; Mode: Tx=1 or Rx=0
• fax_ident
• fax_header
• fax_start_page - Saved document will start at specified page
• fax_end_page - Saved document will end at specified page
• fax_prefix
• fax_use_ecm - Forces the use of ECM if globally disabled, on a per call basis
• fax_disable_v17 - Disable V17 modem that is: use lower speed modems (lower speeds are auto-negotiated with the remote party and cannot be forced. That's a work that the spandsp modem handles on its own.)
• fax_verbose - Be verbose when printing logs (per call basis)

Checking the results

Rx/Tx fax will set the following channel varilables when it terminates:

• fax_success - 0 on error, 1 on success;
• fax_result_code - 0 on error otherwise >= 1;
• fax_result_text - fax error string, provide info where an error has happened;
• fax_ecm_used - "on" or "off";
• fax_local_station_id
• fax_remote_station_id
• fax_document_transferred_pages
• fax_document_total_pages
• fax_image_resolution - XxY
• fax_image_size
• fax_bad_rows
• fax_transfer_rate - speed expressed in bauds (bit per seconds) like 14.400, 9.600, etc.;
• fax_v17_disabled - 0/1
• fax_ecm_requested - 0/1
• fax_filename

Error result codes

When receiving a "Fax processing not successful", you should also receive one of the following result codes:

• 2 - Timed out waiting for initial communication.
• 3 - Timed out waiting for the first message.
• 5 - The HDLC carrier did not stop in a timely manner.
• 11 - Far end cannot receive at the resolution of the image.
• 12 - Far end cannot receive at the size of image.
• 13 - Unexpected message received.
• 14 - Received bad response to DCS or training.
• 17 - Received a DCN while waiting for a DIS.
• 18 - Invalid response after sending a page.
• 20 - Received no response to DCS or TCF.
• 21 - No response after sending a page.
• 37 - Unexpected DCN while waiting for EOM, EOP or MPS.
• 41 - TIFF/F file cannot be opened.
• 43 - TIFF/F format is not compatible.
• 48 - Disconnected after permitted retries.
• 49 - The call dropped prematurely.

***Please help complete the list***

Tests

• Linksys PAP2T via SIP with G.711 - sending to RxFax is OK

• Asterisk + spanDSP - asterisk has problem with CNG so you need to patch mod_fax.c at the moment and comment out the "continue" under the CNG detection - this is a temporary hack just to do tests until mod_fax is finished - i was able to receive a 120 pages fax without problems

• Receiving faxes with a single port FXO (*cough* clone *cough*) works. I've only tried a couple of 1 page faxes but they were received successfully. Great work!

• FreeSWITCH originating the fax via txfax, sending to rxfax on another channel on the same FreeSWITCH works with no issues, even when multiple faxes are being processed at the same time. Was able to put a load on FreeSWITCH by originating a bunch of test faxes from fs_cli, and they all went through properly. Codec = uLaw/G.711 8000

• Receiving from analog fax machines connected to PSTN, routed via SIP trunk to FreeSWITCH seems to work very reliably. Tests done with SIP trunks from an OpenSER server with PRIs connected to it directly, so little to no VoIP latency is occurring. Received faxes from several senders via this method of 1-10 pages at various resolutions from different fax machines/lines of various quality with no rejections yet. Also tested receiving from FaxZero.com (free web faxing gateway) and it has worked several times.

Have fun with fax, Antonio Gallo (AGX)