Asterisk FAX works on SPAN DSP which can be obtained from http://soft-switch.org/
((Installation of spandsp))
((Asterisk Fax))
((Email to Fax))
((Fax to Email))
!Asterisk and fax calls
!!Fax over IP
__In short:__
Across the Internet even a G.711 codec fax transmission is unpredictable. However, people often get perfectly good results on lightly loaded LANs. It still isn’t perfect, as a burst of data on the LAN can still upset things, but some people get results they can live with.
__In detail:__
There are two conceptual methods of carrying virtually real-time fax-machine-to-fax-machine communication across packet networks:
* Fax relay, in which the T.30 fax from the PSTN is demodulated at the sending gateway. The demodulated fax content is enveloped into packets, sent over the network, and remodulated into T.30 fax at the receiving end.
* Fax pass-through, in which modulated fax information from the PSTN is passed in-band end-to-end over a voice speech path in an IP network. The following two pass-through techniques are possible:
** The configured voice codec is used for the fax transmission. This technique works only when the configured codec is G.711 with no voice activity detection (VAD) and no echo cancellation (EC), or when the configured codec is a clear-channel codec or G.726/32. Low bit-rate codecs cannot be used for fax transmissions.
** The gateway dynamically changes the codec from the codec configured for voice to G.711 with no VAD and no EC for the duration of the fax session. This method is specifically referred to as codec upspeed or fax pass-through with upspeed.
In addition to the methods for real-time fax transmission, a method called store-and-forward fax breaks the fax process into distinct sending and receiving processes and allows fax messages to be stored between those processes. store-and-forward fax is based on the ITU-T T.37 standard, and it also enables fax transmissions to be received from or delivered to computers rather than fax machines.
__T.38 relay:__
In fax relay mode, gateways terminate T.30 fax signaling by spoofing a virtual fax machine to the locally attached fax machine. Unlike in-band faxing or fax pass-through, fax relay breaks down the T.30 fax tones into their specific HDLC frames (demodulation), sends the information across the voice network using the fax relay protocol, and then converts the bits back into tones at the far side (modulation). The fax machines on either end are sending and receiving tones and are not aware that a demodulation/modulation fax relay process is occurring.
__Summary:__
Fax pass-through is the simplest technique for sending fax over IP networks, but it is not the default, nor is it the most desirable method of supporting fax over IP. T.38 fax relay provides a more reliable and error-free method of sending faxes over an IP network
!!Can I fax over a call with GSM codec compression?
You’re not going to get that working because ((GSM codec|GSM)) is a lossy ((codecs|codec)). It is able to get extreme savings in size, because it optimizes out parts of the sound that most humans don’t hear. However, that same bandwidth that humans don’t hear is exactly the bandwidth that the fax application uses to transmit valuable portions of the image.
Therefore, the GSM codec is never going to be appropriate for sending faxes. Besides, if you need low bitrates for your IP connection, you’re likely to experience delays in the fax negotiation — which will probably result in a failed fax attempt. If you want to be able to send faxes in this way, then negotiate the fax at one end, and email the resulting ((TIFF)) graphics file to the other end.
!!ECM – error correction mode
High-end (?) fax machines with the memory to store page data often are able to use Error Correction Mode (ECM) for error-free page transmission. When ECM is enabled, a fax page is transmitted in a series of blocks that contain frames with packets of data. After receiving the data for a complete page, a receiving fax machine notifies the transmitting fax machine of any frames with errors. The transmitting fax machine then retransmits the specified frames. This process is repeated until all frames are received without errors. If the receiving fax machine is unable to receive an error-free page, the fax transmission may fail and one of the fax machines may disconnect. On networks that have a packet loss rate greater than 2 per cent, fax transmissions routinely fail when ECM is enabled because of ECM’s low tolerance for packet loss.
!! Virtual Fax
* ((Fax over IP)) – T.38 anyone?
** CVS as of Oct. 2005 now has very limited and experimental T.38 pass-through support for SIP (bug/patch [http://bugs.digium.com/view.php?id=5090|5090]).
** [http://thread.gmane.org/gmane.comp.telephony.pbx.asterisk.devel/12453|ionidea T.38 code] for Asterisk 1.0.7. Be aware that it is trying to do something that is of little value to most Asterisk users. Most people want either passthrough for use with ATAs or a PSTN gateway. This offers neither, instead it provides a TKPT link between a TIFF file on an Asterisk machine, and a remote machine. Very few remote machine support TPKT, and as far as I (steveu) know not a single ATA does.
** The closest source of information so far is this post [http://lists.digium.com/pipermail/asterisk-users/2003-July/015303.html]. Please add more details if you have a positive experience with setting up a virtual fax for Asterisk.
!!From the field
__Q__: Just wondering for anyone using T.38 (with any equipment), how well does it work as compared to a FAX PSTN call?
__A__: Our experience is that it’s only as good as the T.30 implementation in your T.38 gateway, softswitch etc. Since it’s really them having a conversation with the remote device, you’re relying on their implementation of the fax protocol. We recently had a problem with a customer’s T.38 termination service … they had disabled ECM (Error Correction Mode) as a general policy across their devices, and as a result a lot of our customer’ faxes were of degraded quality. The provider claimed that when their network started to drop packets, ECM caused the faxes to take too long to send because of all image data retransmits. Our response – fix your network!
__One thing to be aware of when deciding between T.38 and the PSTN is that V.34 fax (speeds above 14,400) aren’t possible__, so you’ll want to make sure that the money you save from (presumably cheaper) T.38 termination is greater than the money you save from spending less time on the wire. The speed boost from V.34 is larger for multi-page faxes than single-pagers, and penetration of V.34-capable machines varies from country to country and vertical market to vertical market.
__ATAs with T.38__: So far this biggest time consumption of my development time has been trying to deal with the poor T.38 hardware implementations which are currently available to test with (Apr 2005).
__SHAW & LINKSYS__
I had a customer enable the SHAW QoS option for his cable modem. We were able to fax using a LinkSys ATA using G.729.
!!Sending and Receiving Faxes with Asterisk
That means when Asterisk is the endpoint of a fax transimition. In these cases Asterisk has to simulate a fax machine and either do something with thi just received image or have received an image in some way that is latter faxed.
To achieve this there are two ((Asterisk)) applications: ((app_rxfax and app_txfax)) which work on top of a library called ((spandsp)).
The ast_fax application (atand alone app) provides email-asterisk integration. To make life a lot easier, use the mail2fax and fax2mail bash scripts available from [www.generationd.com]. These 2 scripts make it easy to send and receive email (based on app_rxfax. app_txfax, and ast_fax).
Another choice is [http://wpkg.org/email2fax] – it only needs spandsp/app_txfax to send faxes, and accepst e-mails with PDF and TIFF attachments.
!!HylaFax and Asterisk
Another solution is the ((Hylafax)) software. capi4hylafax and chan_capi will gladly coexist. You just tell asterisk to ignore the DIDs that are used for fax. A maximum of 1 passive card and 4 active cards are supported. RedHat users: Some useful RPM can be found [http://mungo.homelinux.org/|here].
[http://www.hylafax.org/archive/2004-07/msg00096.html|hylafax-users Hylafax and Asterisk – Configuration report]
!!!IAXmodem
(Oct. 2005): You can get reliable fax performance with Asterisk by simply using the Asterisk PBX as a T1 PRI "bridge"… meaning you bring your T1 into your multi-port T1 card on your Asterisk server, and then you send all fax calls back out through a different port which terminates on a T1 faxmodem in your HylaFAX server or on a T1 channel bank that is connected to analog faxmodems.
However, if you don’t use fax very often, don’t want to use an on-line fax service, don’t want to pay for a dedicated fax line, and aren’t using T1 lines that the options above aren’t really options at all. So for that purpose (and *still* not wanting to use txfax/rxfax) I’ve created ((Asterisk IAXmodem|IAXmodem)).
!!Asterisk as a fax/voice switch
The answer is simple: Yes, it can. If you Answer() the call before you Dial() an extension, Asterisk will listen for fax beeping. If the call is an fax, it will automatically jump into the ~np~fax~/np~ extension IF your fax call comes in thru a ZAP channel (i.e. not a CAPI channel).
__Background info__: It’s not the card that detects the fax. Its the builtin code in asterisk that does it (dsp.c). chan_zap.c is currently the only channel driver that uses the faxdetection but in theory it could be enabled/used in other channel drivers as well.
Sample code to receive a fax:
^
~np~[default]~/np~
; Answer the line and listen
exten => s,1,Answer
; Dial an extension, let asterisk give a ringtone
exten => s,2,Dial(IAX2/3987,40,r)
; Hangup if nobody picked up within 40 seconds
exten => s,3,Hangup
; Did we get a fax?
exten => fax,1,SetVar(FAXFILE=/var/spool/asterisk-fax/${UNIQUEID}.tif)
exten => fax,2,rxfax(${FAXFILE})
^
Downside of this solution: The moment that somebody calls you, Asterisk picks up and it will cost him, like with any other fax/voice switch.
Sample code to send a fax:
^
Channel:ZAP/G1/1234567
MaxRetries: 0
WaitTime: 20
Application:txfax
Data:/tmp/faximage.tif|caller
^
save the above into a call file then move this file to /var/spool/asterisk/outgoing
!!Zap fax detection
If you’re having trouble getting fax detection on a Zap channels to work it might be because the faxdetect option in ((Asterisk config zapata.conf|zapata.conf)) defaults to off. These are the valid options for faxdetect:
faxdetect=both
faxdetect=incoming
faxdetect=outgoing
faxdetect=no
!!Sending a fax to a SIP device
You can send faxes to SIP extensions, too. Make sure you are using g.711 (Alaw or ulaw) as your codec! Be aware that user reports show mixed results for fax machines connected to ATA devices, for some folks it works, for others it works only 50% of the time. One important aspect is to have an ATA that is able to recognize a fax and immediately turns off its internal echo cancellation routine. Next to that you might have to reduce fax speed from 9600 bit/s to 4800 bit/s in order to produce reliable results. Finally do note that Digium does not claim that Asterisk plays along well with fax transmissions…
Something like this will detect the fax and send it to your SIP device:
^
exten => s,1,Answer
exten => s,2,Dial(SIP/201&SIP/202)
exten => fax,1,Dial(SIP/203,30)
exten => fax,2,Congestion
exten => fax,102,Congestion
^
First it answers the line to allow Asterisk to listen for fax tones, then it rings our normal phones. If, however, fax tones were detected, it will go to the "fax" extention which dials our SIP device with the fax machine on it. Finally, if the fax extension is in use or doesn’t answer in 30 seconds, play the congestion tone.
!!!Success stories with SIP and IAX (Sep. ’05, Germany)
We have a lot of clients reporting that faxing through our asterisk gateway works very well. Our clients are VoIP providers, thus the typical setup is:
fax <-analog-> ATAbox <-SIP-> asterisk1 <-IAX-> asterisk2 <-PSTN-> remotefax
or
asterisk1_with_spandsp <-IAX-> asterisk2 <-PSTN-> remotefax
asterisk1 is the machine of the providers, which use our termination service. asterisk2 is our gateway.
We have one customer, whose customers are SOHOs with typical small PBXs, supporting 2 or 4 lines. He now puts the FritzboxFon between PSTN and their PBXs, in order to take the outbound phone traffic via VoIP, including fax. He is using as internet connectivity KabelBW, a regional cable TV provider. His setups are success stories.
!!Emailing a fax based on DID
For an incoming fax you can lookup the email address to send to based on the DID. Although it is possible to do a mysql lookup or even a DBGet the following example queries Active Directory for the email address via the [http://www.voip-info.org/tiki-index.php?page=Asterisk+cmd+LDAPget|LDAPGet] Asterisk application.
^
Extensions.conf
~np~[incoming-pstn]~/np~
exten => _123495XX,1,SetVar(NumberCalled=${EXTEN})
exten => _123495XX,2,Answer
exten => _123495XX,3,Ringing
exten => _123495XX,4,Wait(3)
exten => _123495XX,5,Macro(StdExten,${EXTEN:4})
exten => fax,1,Goto(fax,666,1)
~np~[fax]~/np~
exten => 666,1,Macro(faxreceive)
exten => h,1,system(/usr/sbin/mailfax ${FAXFILE} ${EMAILADDR} ${CALLERIDNUM})
~np~[macro-faxreceive]~/np~
exten => s,1,SetVar(FAXFILE=/var/spool/asterisk-fax/${UNIQUEID}.tif)
exten => s,2,LDAPGet(EMAILADDR=cidmail/${NumberCalled})
exten => s,3,rxfax(${FAXFILE})
exten => s,103,SetVar([email protected])
exten => s,104,rxfax(${FAXFILE})
^
What happens here is that we set the variable NumberCalled to the DID so that we can look it up in AD in macro-faxreceive. We then answer the line, generate a ringing tone and wait 3 seconds for a fax tone. If a fax is detected then we jump to the fax extension and goto the fax context. In the ~np~[fax]~/np~ context we call macro-faxreceive where we use the Asterisk LDAPGet application to search for an email address associated with the DID. If there is no email address then we set a default email address although we could forward it to a hardfax with a little bit more work. Once we exit macro-faxreceive we now need to actually send our fax to the email recipient and for this we use the hangup extension exten -> h to call a shellscript. Our change of contexts ensures that the shellscript only runs after receiving a fax and not after every call.
In order for LDAPGet to do its work we need to define our query in ldap.conf:
^
~np~[cidmail]~/np~
host = ldap.somecompany.com
user = cn=asterisk ldap,ou=services,ou=logins,dc=somecompany,dc=com
pass = secret
base = ou=users,ou=logins,dc=somecompany,dc=com
filter = (&(objectClass=person)(otherFacsimileTelephoneNumber=%s))
attribute = mail
^
And finally the shell script used to convert the tiff to PDF and email it to our user:
If you live in an A4 country then edit /usr/bin/ps2pdfwr to add ‘-sPAPERSIZE=a4’ to the ghostscript command line, else your received faxes will have extra whitespace added to the top and be cut short at the bottom of each page.
^
#!/bin/sh
FAXFILE=$1
RECIPIENT=$2
FAXSENDER=$3
tiff2ps -2eaz -w 8.3 -h 11.7 $FAXFILE |
ps2pdf – |
mime-construct –to $RECIPIENT –subject "Fax from $FAXSENDER" \
–attachment fax.pdf –type application/pdf –file –
^
Thanks to Scott Laird at [http://scottstuff.net/scott/archives/000152.html] for the majority of the stuff here that is not LDAP related.
!!Fax for chan_capi with CAPI cards with DSP
__by Carl Sempla__
For those of you who have a CAPI card with an on-board DSP (like some Eicon Diva Server), this patch allows you to receive faxes. If you want to answer a channel in fax mode, use capiAnswerFax() instead of Answer() If you use Answer(), you will be in voice mode. If the hardware DSP detects a fax tone, you can switch from voice to fax mode by calling capiAnswerFax().
__Example of use:__
line number 123, play something, if a fax tone is detected, handle it
line number 124, answer directly in fax mode
^
~np~[incoming]~/np~
exten => 123,1,Answer()
exten => 123,2,BackGround(jpop)
exten => 124,1,Goto(handle_fax,s,1)
exten => fax,1,Goto(handle_fax,s,1)
~np~[handle_fax]~/np~
exten => s,1,capiAnswerFax(/tmp/${UNIQUEID})
exten => s,2,Hangup()
exten => h,1,deadagi,fax.php // Run sfftobmp and mail it.
^
The output of capiAnswerFax is a SFF file. Use sfftobmp to convert it. With a Diva Server, theses features are allowed : fax up to 33600, high resolution. Color Fax /JPEG Compression is disabled (I can’t test it).
You can download the patch at :
[http://www.mlkj.net/asterisk/]
A fix for a dead lock issue is also included (Oct 22 18:06:00 WARNING[11275]: channel.c:472 ast_channel_walk_locked: Avoided initial deadlock for ‘CAPI[contr1/173720007]/7’, 10 retries!)
!!SIP/IAX fax detection
If you are trying to detect faxes over IAX, SIP, or for that matter any type of channels, ((Newman Telecom)) has created ((NVFaxDetect)) and updated ((BackgroundDetect)) as ((NVBackgroundDetect)) for that purpose. We have had near perfect results on decent IAX connections using ULAW/ALAW. Fax detection utilizes Asterisk DSP and works in the same way. Once detected, faxes are sent to the fax extension — look at Zap fax detection above.
!!Sending faxes via e-mail
If you want to be able to send an email to a phone number without generating a call file, or logging into your Asterisk server, check out [http://www.inter7.com/astfax|Asterisk Fax] for a package which accepts e-mails with attached fax images to phone number addresses.
Even better choice is [http://wpkg.org/email2fax|email2fax], which accepts e-mails with attached PDF or TIFF files, and faxes them to fax numbers specified in the e-mail’s subject.
!!AsterFax
And better again 🙂 [http://asterfax.sourceforge.net|asterfax], which accepts plain email or email with an attachment and faxes it to the fax number in the ‘to’ address. e.g. [email protected]
Asterfax supports tiff, pdf, postscript, MS-Word and OpenOffice Writer attachments.
The set of supported files can also be easily extended via a simple configuration file and appropriate third party software.
The great thing about AsterFax is that you can send a fax directly from MS-Word without installing any client software.
!!Sending Faxes with Windows GUI
A program allowing a user to print to a windows printer and then fax the document through Asterisk (optionally AstFax listed above) [http://www2.stealthdigitalservice.com:8080/download/Print2File/print2file.html|Click Here for more details]
!!Faxing over the Internet Success using Zap + IAX2
We are successfully faxing inbound and outbound using g726 with 20ms – 60ms ping times over the internet!
I am using Asterisk 1.2.0 as a gateway to carry voice traffic and faxes over the internet to the PSTN
{fax machines} –> {pbx} –> Zap(pri) –> IAX2(Internet) –> Zap(pri) –> PSTN
I have only been able to achieve this with g726. It works and it works well.
!!See also
* ((Asterisk Fax to email))
* ((Asterisk spandsp)): Sending and receiving fax directly with Asterisk
* ((Asterisk IAXmodem)): Software modem uses an IAX channel (use e.g. with HylaFax)
* [http://www.soft-switch.org/foip.html|Faxing over IP networks] by Steve Underwood
* ((Hylafax))
* ((T.38))
* [http://www.voxgratia.net/blog/archives/2005/08/fax_facts.html|T.30 and T.38]: Some fax facts explained
* ((NVBackgroundDetect)): Detects fax on SIP/IAX/ZAP while playing a file
* ((NVFaxDetect)): Detects fax on SIP/IAX/ZAP
* [http://www.tpc.int/| Old and venerable collaborative fax delivery service]]
—
* ((Asterisk and faxes))
* __((Asterisk))__ | ((Asterisk FAQ))