Fax Transfer Module

Latest revision as of 12:09, 4 November 2013

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.

[edit] Send a fax

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

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

[edit] Receive a fax

To receive a fax you can use this:

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

[edit] 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

[edit] Sample setup

[edit] 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.)

[edit] yate.conf

[modules]
faxchan.yate=true

You need to enable the faxchan manually, if you set modload=disable in the [general] section

[edit] faxchan.conf

There is no such file - no configuration needed / possible

[edit] Questions & Answers

[edit] 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.

[edit] How can I configure the faxchan module?

No configuration file exists for this module - no configuration needs to be done.

[edit] Debugging

[edit] 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

[edit] 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

• Why T.38 makes sense, and Fax over VoIP without it fails
• Modules