Search

Tuesday, September 28, 2010

How to use Fax for Asterisk - Part 2

How to use Fax for Asterisk - Part 2

We send and receive faxes via the dialplan function FAXOPT and SendFax/ReceiveFax asterisk applications.

 

*CLI> core show application sendfax

  -= Info about application 'SendFAX' =-

[Synopsis]

Sends a specified TIFF/F file as a FAX.

[Description]

SendFAX(filename[&filename[&filename]][,options]):

 The SendFAX() application sends the specified TIFF/F file(s) as a FAX.

 The application arguments are:

    'd' - enables FAX debugging

    'f' - allow audio fallback FAX transfer on T.38 capable channels

    'z' - initiate a T.38 reinvite on the channel if the remote end does not

    's' - send progress Manager events (overrides statusevents setting in res_fa                                              x.conf)

 Use the FAXOPT function to specify session arguments prior to calling SendFAX()

 and use FAXOPT after SendFAX completes to query result status for the session.

 The SendFAX() application is provided by res_fax, which is a FAX technology agn                                              ostic module

 that utilizes FAX technology resource modules to complete a FAX transmission.

[Syntax]

Not available

[Arguments]

Not available

[See Also]

Not available

The FAXOPT dialplan function is used to set options to be used by SendFax or ReceiveFax and obtain the fax results afterwards.

To faxout, we can use callfile to dial the destination fax number and call SendFax in dialplan.

Sample.call

Channel:SIP/t38gateway/12345678

Callerid:"Test"<1111>

Maxretries:0

Waittime:45

Context:fax_context

Extension:ffa_faxout

Priority:1

Set:TIFF_2_SEND=sample.tiff

Set:TAGLINE=header_sample

Set:RECEIVER=12345678

Extensions.conf

[fax_context]

exten => ffa_faxout,1,NoOp(**** SENDING FAX ****)

exten => ffa_faxout,n,Wait(6)

exten => ffa_faxout,n,Set(FAXFILE=${TIFF_2_SEND})

; Set FAXOPTs

exten => ffa_faxout,n,NoOp(**** SETTING FAXOPT ****)

exten => ffa_faxout,n,Set(FAXOPT(ecm)=yes)

exten => ffa_faxout,n,Set(FAXOPT(headerinfo)=${TAGLINE})

exten => ffa_faxout,n,Set(FAXOPT(maxrate)=14400)

exten => ffa_faxout,n,Set(FAXOPT(minrate)=2400)

; Send the fax

exten => ffa_faxout,n,NoOp(**** SENDING FAX : ${FAXFILE} ****)

exten => ffa_faxout,n,SendFAX(/tmp/${FAXFILE},dfzs)

; Hangup! Print FAXOPTs

exten => h,1,NoOp(FAXOPT(ecm) : ${FAXOPT(ecm)})

exten => h,n,NoOp(FAXOPT(filename) : ${FAXOPT(filename)})

exten => h,n,NoOp(FAXOPT(headerinfo) : ${FAXOPT(headerinfo)})

exten => h,n,NoOp(FAXOPT(localstationid) : ${FAXOPT(localstationid)})

exten => h,n,NoOp(FAXOPT(maxrate) : ${FAXOPT(maxrate)})

exten => h,n,NoOp(FAXOPT(minrate) : ${FAXOPT(minrate)})

exten => h,n,NoOp(FAXOPT(pages) : ${FAXOPT(pages)})

exten => h,n,NoOp(FAXOPT(rate) : ${FAXOPT(rate)})

exten => h,n,NoOp(FAXOPT(remotestationid) : ${FAXOPT(remotestationid)})

exten => h,n,NoOp(FAXOPT(resolution) : ${FAXOPT(resolution)})

exten => h,n,NoOp(FAXOPT(status) : ${FAXOPT(status)})

exten => h,n,NoOp(FAXOPT(statusstr) : ${FAXOPT(statusstr)})

exten => h,n,NoOp(FAXOPT(error) : ${FAXOPT(error)})

exten => h,n,NoOp(DNIS: ${RECEIVER})

exten => h,n,System(write_log.sh ${RECEIVER} ${FAXOPT(filename)} ${FAXOPT(status)} ${FAXOPT(statusstr)}  ${FAXOPT(error)})

Points to note.

It is not recommended to edit the callfile in /var/spool/asterisk/outgoing as it might be processed by asterisk in the middle of creation.  A better approach is to create the callfile somewhere else and 'mv' to the outgoing directory.

The resolution of tiff is important.  We can enforce the correct values by specifying them in the gs command.

gs -q -dNOPAUSE -dBATCH -sDEVICE=tiffg4 -sPAPERSIZE=a4 -g1680x2285 -sOutputFile=sample.tiff sample.pdf

We can verify our fax document using 'tiffinfo sample.tiff'

If we receive 'res_fax_digium.c: FAX handle 0: failed to queue document', it is likely due to mis-formatted tiff.

Utf8 tagline is currently not supported.

We can pass certain variables from callfile to our dialplan, eg the destination number, for generating fax status reports.  The fax status is obtained from ${FAXOPT(status)}

The write_log.sh is a simple shell script that merely logs whatever number we faxed with the fax status.  Alternatively, we could use AGI to insert the data to database for billing purpose.

To enable t38 fax, we have to set 't38pt_udptl=yes' in sip.conf 

If we receive error 'Audio FAX not allowed on channel', it is likely an issue with the t38_udptl value.

To monitor fax progress, we can set debug on as below.

*CLI> fax set debug on

To send faxes simultaneously (assuming that we purchased enough channels from Digium), we could put multiple callfiles in /var/spool/asterisk/outgoing and monitor this folder to add more callfiles when appropriate. 

 

In following parts, I would show how to control the maximum number of concurrent fax calls and automate fax retry.  

 

How to use Fax for Asterisk - Part 1

How to use Fax for Asterisk - Part 1

Recently, we evaluated fax for asterisk in the process to find a stable fax solution under asterisk.

Ffa is selected because it supports both DAHDI TDM fax and T38 Voip fax.  Note that t38 termination is only available when using asterisk 1.6 and above.  In asterisk 1.4, we can only use g711 faxing with ffa, a solution which is more vulnerable to network jitters and delays.  

We setup an environment as below for evaluating ffa.

Fc9

Asterisk 1.6.2.14

Dahdi with 2-port Digium card

Then we download the free Fax for Asterisk (1-channel) from http://www.digium.com/en/products/software/faxforasterisk.php.

Ffa installation involves below steps.

Create account with Digium

In the first place, we create an account with digium and order free FFA on digium store which would send us a license string afterwards.

Register free fax for asterisk

Cd /usr/src

wget http://downloads.digium.com/pub/register/x86-32/register

Chmod 500 register

./register

This program prompt us to enter the license string obtained from digium.

Determine the build

wget http://downloads.digium.com/pub/telephony/fax/benchfax/x86-32/benchfax-1.1.0-x86_32 -O benchfax

Chmod 500 benchfax

./benchfax

This process examines our system to determine an optimal build and it could take over 10 minutes to complete.

Fax selector

Next, we visit http://www.digium.com/en/docs/FAX/faa-download.php and input the o/s, asterisk version and the 'build' as suggested from benchfax.  The fax selector will respond with the corresponding urls of res_fax and res_fax_digium.

Install the required components

wget http://downloads.digium.com/pub/telephony/fax/res_fax/asterisk-1.6.2.0/x86-32/res_fax-1.6.2.0_1.2.1-x86_32.tar.gz

wget http://downloads.digium.com/pub/telephony/fax/res_fax_digium/asterisk-1.6.2.0/x86-32/res_fax_digium-1.6.2.0_1.2.1-

i686_32.tar.gz

tar xzvf res_fax-1.6.2.0_1.2.1-x86_32.tar.gz

cp res_fax-1.6.2.0_1.2.1-x86_32/res_fax.so /usr/lib/asterisk/modules

tar xzvf res_fax_digium-1.6.2.0_1.2.1-i686_32.tar.gz

cp res_fax_digium-1.6.2.0_1.2.1-i686_32/res_fax_digium.so /usr/lib/asterisk/modules

Load res_fax and res_fax_digium in asterisk

Then we can load the two modules in asterisk.

*CLI> module load res_fax.so

*CLI> module load res_fax_digium.so

To verify ffa installation, we can :

*CLI> fax show stats

FAX Statistics:

---------------

Current Sessions     : 0

Transmit Attempts    : 0

Receive Attempts     : 0

Completed FAXes      : 0

Failed FAXes         : 0

Digium G.711

Licensed Channels    : 1

Max Concurrent       : 1

Success              : 0

Switched to T.38     : 0

Canceled             : 0

No FAX               : 0

Partial              : 0

Negotiation Failed   : 0

Train Failure        : 0

Protocol Error       : 0

IO Partial           : 0

IO Fail              : 0

Digium T.38

Licensed Channels    : 1

Max Concurrent       : 1

Success              : 0

Canceled             : 0

No FAX               : 0

Partial              : 0

Negotiation Failed   : 0

Train Failure        : 0

Protocol Error       : 0

IO Partial           : 0

IO Fail              : 0

From the output, we should see that ffa now supports both g711 and t38 faxing.

 

Note that it is not recommended to specify 'load=>' in modules.conf as long as we have autoload=yes.

 

In next parts, I would demonstrate how to place fax calls and monitor results.