Fax Transfer Module

Revision as of 15:08, 6 November 2012

Fax 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.

In regexroute.conf you can set this to transmit a fax:

^1$=fax/transmit/path/to/tx-file.tiff

To receive a fax you can use this:

^2$=fax/receive/path/to/rx-file.tiff

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 ramanager. 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.
  • /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

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?)

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.