Fax Transfer Module
This module can be used either to send or receive a fax from a local file.
The module is sending and receiving faxes by using any other telephony capable channels like wpchan or zapchan. Faxing over VoIP using the G.711 A-law or mu-law codecs is possible but unreliable. You can provide tiff files or you can receive faxes in tiff files.
Since the spandsp library evolves and the API changes you are advised to download and use version 0.0.6 pre 3, also available here. Other versions may not be detected during configuration or may fail to build or run properly.
Contents |
Send a fax
In regexroute.conf you can set this to transmit a fax:
^1$=fax/transmit/path/to/tx-file.tiff
Receive a fax
To receive a fax you can use this:
^2$=fax/receive/path/to/rx-file.tiff
How to use faxchan module
The best way to use this module is an external module written in php (maybe) that can handle the name of the tiff file and maybe a forwarding to a mail.
To create an outgoing fax call send a call.execute message with:
* callto=fax/transmit/path/to/tx-file.tiff * caller=our number either of * direct=callto for outgoing call leg or * target=called party number
From rmanager you can send a fax like this:
call fax/transmit/path/to/tx-file.tiff called-number
This module has no configuration file. All parameters are taken from the call message:
- faxident - sets the ID as reported to the remote fax - default is taken from the caller parameter
- faxcaller - forces operating as originator (true) or answerer (false) - default uses direction of call
- faxecm - enables the error correcting mode (default true)
The chan.hangup message will carry the information about the fax sent or received:
- faxpages - number of pages transferred, only if not zero
- faxident_local - textual fax machine ID that was sent to the remote fax
- faxident_remote - textual fax machine ID that was received from remote
- faxcaller - true if operated as originator, false if or answerer
- faxecm - true if ECM was used for all pages, false otherwise
Logging of spandsp messages at DEBUG and FLOW levels is disabled by default. It can be controlled at runtime from rmanager by issuing one of the commands:
- debug spandsp - to show the current detailed logging status
- debug spandsp on - to enable detailed logging
- debug spandsp off - to disable detailed logging
Alternatively you can put in yate.conf:
[debug] spandsp=on
You will still need to set the debugging level on the fax channels to 9 or 10 to see spandsp FLOW or DEBUG.
IMPORTANT: The spandsp library logs only to file. You will not see any output in rmanager. Always copy the output from the log file, not from rmanager session.
Please note that the old fax channel in Yate 0.8 had an extra element. This has been replaced with the faxcaller message parameter which is safer and more flexible.
Also note that the faxecm default was false before SVN Revision 2413
Sample setup
regexroute.conf
^1234$=fax/receive//telephony/fax/${called}/incoming/rx-$(message,time).tiff
note that ${called} has curly brackets, whereas $(message,time) has round brackets.
- The number 1234, when matched in regexroute.conf (check your routing!), will receive a fax
- The fax will be stored in a dynamically generated location
- /telephony/fax/ (notice the two slashes in the line fax/receive//telephony - one is for dividing fax/receive/ and the parameter to it, the other means "root directory")
- ${called} - a directory for each called number will be generated
- Please note, that faxchan will not create directories for you - faxes to non-existent directories will be silently dropped. Create the directories for your receivers manually, or edit the setup to include the parameter in the filename itself.
- In our example this directory would be simply 1234 (the destination we match to be routed)
- /incoming/ - optional, maybe you also want to have an outgoing directory for certain numbers / cases.
- rx-$(message,time).tiff - this will create a tiff (multipage if several pages are received!), with the Unix timestamp since the Unix epoch. (This is known to work on YATE 4.2, not sure about earlier versions - 2 / 3 , though.)
yate.conf
[modules] faxchan.yate=true
You need to enable the faxchan manually, if you set modload=disable in the [general] section
faxchan.conf
There is no such file - no configuration needed / possible
Questions & Answers
How do I enable T.38?
I did not have to do anything to enable T.38 - it is supported by my upstream provider (which uses Dialogic-SIP). The connection for incoming faxes will start in 'classic' SIP mode and switch to T.38.
How can I configure the faxchan module?
No configuration file exists for this module - no configuration needs to be done.
Debugging
Log
Enable verbose logging (-vvvvvvvvvvv) when starting YATE.
The log should contain the following:
<ALL> Plugin::Plugin("fax",false) [0x7fdc1b38a3a0]
Loaded module Fax
indicating that the fax module was loaded. If not, check your yate.conf / modules directory (do you have it in a compiled state already?)
The fax channel depends on spandsp ( http://soft-switch.org/ ) - some versions of YATE will not compile this module with some versions of spandsp
Network Traffic Capture
Capture the traffic on your server using
tcpdump -s 65535 -w /tmp/capture.cap
(start before sending a Fax, stop after it has been received by pressing Ctrl + C).
Analyse the capture file using WireShark.
(If your upstream provider supports T.38) it should contain T.38 UDPTLPacket packets, i.e. with hdlc-data. (The "protocol" tab will be T.38)
The first part of the capture will be "classical" UDP SIP Traffic, the switch to T.38 will be done later.
There should be a SIP/SDP invite message containing Media Attributes in its Message Body, i.e. T38FaxVersion, T38MaxBitRate, T38FaxMaxBuffer, etc.
See also
