El Cheapo Fax ************** This file documents El Cheapo Fax V24.10.93. Copyright (C) 1993 by Olaf 'Rhialto' Seibert. Permission is granted to copy the whole package, in accordance with the GNU General Public License. The primary documentation form is the AmigaGuide file. The other available documents, derived from the same source file, may therefore look a bit odd in some places. Synopsis ******** Usage: all2fax.rexx [-o output file] [-r (raw)] [-a (append)] [-x/y x/y-offset (50)] [-v] [-i (invert)] [-f name.font] [-s fontsize] script-files Usage: iff2fax [-o fax-file (ilbm.g3)] [-r (raw)] [-a (append)] [-sN skip N BODYs] [-x/y x/y-offset (50)] [-v] [-i (invert)] iff-files Usage: asc2fax [-o fax-file (ascii.g3)] [-r raw faxfile] [-a (append)] [-x/y x/y-offset (50)] [-v] [-i (invert)] [-f name.font] [-s fontsize] ascii-files Usage: append [-o fax-file] fax-files Usage: Viewing [-o iff-file (fax.iff)] [-v] [-i (invert)] [-1] [-b0/1 (bitorder)] fax-files Usage: Sending [-f faxdevice] [-l loglevel] [-v] [-b bitorder] phone [files..] Usage: Receiving [-d queuedir/] [-f faxdevice] [-l loglevel] [-v] [-i] [-b bitorder] Overiew ******* El Cheapo Fax is a very cheap and simple package to send and receive faxes using your Amiga and a suitable (Class 2) Fax modem. It is not particulary user-friendly, nor is it blazingly fast. It just does everything I need. In fact, as you and I don't need facsimile at all, it does a lot more. The basic way of using El Cheapo Fax is that you first create a fax data file from text or IFF ILBM source files, and later send this file to the receiving fax. Each fax page will be in a separate file. In the other direction, you receive a fax file first, and afterwards you can convert it to a viewable IFF ILBM file. The necessary software has partly been scraped together from various sources. See the section on copyright for full details. All original code is (C) Copyright 1993 by Olaf Seibert, and All Rights are Reserved. The GNU General Public License applies to this software. The text of the GPL can be found in the file COPYING. Requirements ************ Besides El Cheapo Fax, you need - A Class 2/group 3 fax modem. - A 7 to 10 wire cable that connects TXD (2), RXD (3), RTS (4), CTS (5), DSR (6), GND (7) and DTR (20) and optionally Shield GND (1), DCD (8) and RI (22). - Large fonts. Suggested are 30+ high pixels for fixed-width fonts, 50+ for proportional fonts. - An IFF ILBM file viewer. Limitations *********** Bit order problems ================== For conversion of bit-oriented codes to byte-oriented files, there are two obvious ways of packing the bits in bytes: succeeding bits can be packed from right to left (least significant bit to most significant bit, or bit 0 to bit 7), or left to right (msb to lsb, bit 7 to 0). The first method is called "direct" by the ITU (the former CCITT), the other is called "reversed". Most programs however like the bits in reversed order, because that is better readable if you print the bytes as binary or even as hex. ElCheapoFax creates its fax files in reversed bitorder, and faxsend expects them that way. This means that if you have a fax file that you can only view with -b0 (direct bit order) that you cannot re-send it; you must convert it to IFF and back again, thereby correcting the bit order. Note that the bit order options for faxsend and faxrecv do not pertain to the bit order in the fax file but only to the bit order between the computer and the modem. It informs the modem beforehand, using the +FBOR= command. This implies that faxsend must reverse the bits if it uses direct bit order, and refrain from doing that when using reversed bit order. Because of the +FBOR command, this does not mean that you can send fax files with the wrong bit order! We don't need no steenkin' parameters... ======================================== Currently, no parameters can be chosen. Everything is fixed as 1728 pixels wide (in 215 mm), vertical resolution is fine (7.7 lines/mm), compression is 1-D Huffmann, no error correction mode, no binary file transfer. This, however, is purely a software matter, and thus fixable. RTS/CTS required. ================= Currently, faxsend relies on RTS/CTS handshaking between the modem and the computer. It seems that this is not standard, but is at least supported by the Supra V32bis FAX modem, ROM version 1.200H. This is harder to remedy, as Commodore's serial.device can only do XON/XOFF in both inward and outward direction at the same time, or not at all. The fax protocol however officially requires that you use no flow control in one direction (the computer to modem if sending, modem to computer if receiving), and XON/XOFF in the other. Usage ***** Creating Fax Files ================== It is probably easiest to start at the Rexx script that glues together the functionality of the other programs. Basically you write a text file interspersed with simple formatting parameter sets. Every block of text between parameters is processed to fax data. No text-fitting is currently done; you must make sure yourself that everything fits on the paper. You must have specific provisions for directing output for each page to a separate fax file. Several options apply to more than one of the subprograms. It is therefore best to discuss them now. Generally, all options must be given before the input files. -o fax-file You must always select an output file. -a Append to output file, instead of overwriting it. Set by all2fax.rexx for all fileparts but the first. -x x-offset -y y-offset Normally, all fax data is offset by 50 pixels both horizontally and vertically. The x offset is needed to prevent any data to fall off the left edge of the paper. The y offset is only needed for the first part of a fax page, if at all. Therefore, all2fax.rexx resets the -y option to 0 for every part after the first. -v Verbose. Some subprograms act on this, some don't. -i Invert pixels before conversion. Probably only useful for converting ILBM images. -r Raw. Don't append an end-of-page marker to the output. This option is set initially, but reset for the very last part (this is detected by the end of file condition when reading its text). all2fax.rexx ------------ The commands supported by all2fax are: .args args Process the preceeding file part by running it though asc2iff, and set the given arguments (in addition to those given earlier) for the next part. Most options will be left untouched and remain in effect for succeeding parts (exceptions are -a, -r, -y). Binary options (switches) can be reset with a double dash (as in --a). .doit args Set the given arguments, just as .args would, and process the preceeding file part with asc2iff. .iff args Process the given arguments, and run iff2fax with the relevant parameters. .raw args Run append with the relevant parameters plus those given here. Note that these are not processed in the usual fashion - these arguments are purely one-shot. Append is used to append a previously created (raw) fax file to the output. This is useful for including output of FaxPrinter. .rexx cmd Execute the given rexx command. .shell cmd Execute the given shell command. asc2fax ------- -f any.font -s size Select the font and size to be used. Remember that because of the resolution of a fax, you need quite large fonts. Suggested mininum sizes are 30+ pixels for fixed-width fonts, 50+ for proportional fonts. These will allow approximately 80 characters of text per line. iff2fax ------- Iff2fax is for including ILBMs verbatim (or inverted). No scaling of any kind is done. To get scaled (and possibly dithered) pictures of appropriate size it is probably best to use the FaxPrinter. This program would actually be more accurately named ilbm2fax, but perhaps more general iff support will be provided in the future (though I doubt it). But in any case, iff2fax delves into complex IFF files and converts all FORM ILBMs that it finds, each on a separate page, respecting the -x/-y offsets. Because faxsend doesn't support multiple-page fax files yet, you must use -r to suppress the page terminators in the case of IFFs with multiple ILBMs. This simply glues all pages underneath each other. append ------ Append is used to catenate some existing fax file to your output, for instance as created by FaxPrinter. FaxPrinter ---------- This is not a stand-alone program, but is a standard Preferences printer driver instead. This enables you to create fax graphics from your favourite graphics or printing program (for example, DeluxePaint, ADPro, Post, Ghostscript). Colour graphics can be dithered this way, but please note that the fax data "compression" algorithm behaves very badly on dithered graphics (a single white or black pixel is encoded in a 6 or 3 bit sequence, respectively). You are advised to use black & white graphics whenever possible, unless you don't mind an enormous phone bill. FaxPrinter is the only part of El Cheapo Fax that can generate low-density (i.e. non-fine) fax data. Therefore you should select a printer density of 4 or higher. The -r (raw) switch is implemented by the "SPECIAL_NOFORMFEED" printer flag. Your printing program should enable you to set this, usually with an option like "no formfeed" or "don't eject paper". Support for text output is completely absent from FaxPrinter. You can use a wordprocessor that prints text as grapics, or asc2fax. When running on 2.0+, FaxPrinter uses an ASL file requester to get the name of the file to write in. When ASL is not available, the filename used will be FAX:faxrastportdump. Alternative ways of generating fax files ---------------------------------------- Of course, if you have any other way to generate group 3 fax files, you can use that as well. For instance, Ghostscript has a g3 printer driver. Other programs may have something similar. Viewing Fax Files ================= You can view a fax file by converting it to an IFF ILBM file (using fax2iff) and viewing it with your favourite picture viewer. It is recommended that it is capable of displaying very large pictures, and that you select a high resolution display mode (at least hires interlace). Mostra performs great for this. Fax2iff can optionally invert the fax for you (-i), if your viewer program uses black as background and white as foreground color. -o must be specified to name the output file. Normally, the output file is an IFF CAT file when there are multiple input files, and a plain IFF ILBM file when there is only one input file. A CAT file is just a concatenation of several other IFF files, but many programs can't handle them, stupidly enough. To invert the default output file type, specify -1. When a non-CAT output file is forced, only the first input file will be converted, and the others ignored. To always force a non-CAT file, even with unknown arguments (as in a script) you can add NIL: as an extra input file, i.e. fax2iff -o test.iff -1 NIL:. A PAL hires/interlace display mode has approximately the same aspect ratio as a fine mode fax. My monitor displays approximately 2.4 pixels/mm horizontally and 2.66 pixels/mm vertically, while a fine fax is 8 pixels/mm horizontally and 7.7 pixels/mm vertically. A fax will thus appear a bit too wide. An NTSC mode would be 2.4/2.01 and make the fax a bit too tall. In both cases, the fax will be over 3 times enlarged on screen. fax2iff will add a CAMG chunk indicating HIRES and INTERLACE, and a colormap in which color 0 is white and color 1 is black. For some reason, the bit order in files received from some faxes is not the order that is "correct". This happens at least with my modem (Supra V32bis, revision 1.200H). Therefore, fax2iff attempts to determine the bit order in the present file, by attempting to decode the first 10 lines using both bit orders. The one that produces the least errors is used. Sometimes this could be the wrong choice; in that case you have to give a -b0 (direct bit order) or -b1 (reversed bit order) option. Sending Fax Files ================= You send a prepared series of fax files with faxsend. The parameters are simply the phone number to be called and the names of the files to send. Remember, only one page per file. The phone number is given as a Hayes modem style dial string. It is simply appended to an ATDT command. Valid dial characters are (depending on your modem): 0-9 Numeric Digits * # A-D Auxiliary Digits T Tone Dialing P Pulse Dialing , Pause for (S8) seconds, default is 2 seconds / Pause 1/8 second in dialing sequence W Wait for second Dial Tone The -l option allows you to select the verboseness of progress reporting. Values are from 1 to 8, 8 being most verbose. Default logging level is 5, which reports warnings and all more serious messages. Specifying a level in the range 11-18 has the same effect as a level of 10 lower but also logs the resulting messages in the file "faxlog". The serial device to be used for the faxmodem can be specified with -f unit/nameof.device. Default is -f 0/serial.device. Both parts of the string can be omitted. Normally, the bits are sent to the modem in "direct" order (bitorder code 0). Some faxmodems however seem to work better if the data is sent in "reversed" order (bitorder code 1). Theoretically this should not make any difference at all, but in practice it seems that it does. Don't you love this fax "standard"? If you send a fax and you receive an hangup error code of 54 (the log file shows +FHNG: 54), or the the first page is sent a few times and then faxsend gives up, then you should try the option -b1. The default is -b0. Technically, this is the value for the +FBOR= command (1). ---------- Footnotes ---------- (1) Only use 0 or 1; 2 and 3 are not supported. Receiving Faxes =============== To receive faxes, you should start faxrecv. When it detects any input from the modem (presumably a RING message) it will attempt to answer the call in fax mode. There is no need (and in fact, you should not) set your modem to autoanswer mode. Incoming faxes are written into subdirectories of a spool directory (-d option), with each page in a separate file, plus a LOG file containing session information. The given directory must end in a : or /. The default incoming directory is FAX:incoming/. To immediately answer the phone (if it is already ringing) specify the -i option. In this case, faxrecv answers the phone immediately after initialisation. If you insist on auto-answer, and have some front-door program that can detect fax calls, double the -i option. In this case, the modem is not initialised, the phone not answered (because it already has been), and fax commands are issued immediately. This is experimental. For information, this would work with some faxes as follows: Give the commands AT +FCLASS=0 +FAA=1 S0=(1-255). The fax will then eventually reply with FAX or CONNECT speed. faxrecv can be given a phone number as argument. It will poll that number for a fax, then exit. This does not currently work, at least with the Supra modem. The -b option is also implemented in faxrecv. Perhaps you may need it. Copyrights ********** The code I wrote myself is Copyright (C) 1993 by Olaf Seibert. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the COPYING/GNU General Public License, as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. Significant parts of this package have been lifted from other packages. The following copyrights apply: For tofax.c (derived from Ghostscript 2.2's file gdevdfax.c): /* * Copyright 1992 DigiBoard, Inc. All rights reserved * * Permission to use, copy, modify, and distribute this software and its * documentation for any purpose and without fee is hereby granted. * This software is provided "as is" without express or implied warranty. */ /* gdevdfax.c */ /* DigiBoard, Inc. DigiFAX driver for Ghostscript. */ and /************************************************************************* The rest of this file is a FAX encoding algorithm derived from pbmplus. It is not the normal DigiFAX algorithm. The following copyright applies. ** ** Copyright (C) 1989 by Paul Haeberli . ** ** Permission to use, copy, modify, and distribute this software and its ** documentation for any purpose and without fee is hereby granted, provided ** that the above copyright notice appear in all copies and that both that ** copyright notice and this permission notice appear in supporting ** documentation. This software is provided "as is" without express or ** implied warranty. *************************************************************************/ For fromfax.c (derived from pbmplus' file g3topbm.c): /* g3topbm.c - read a Group 3 FAX file and produce a portable bitmap ** ** Copyright (C) 1989 by Paul Haeberli . ** ** Permission to use, copy, modify, and distribute this software and its ** documentation for any purpose and without fee is hereby granted, provided ** that the above copyright notice appear in all copies and that both that ** copyright notice and this permission notice appear in supporting ** documentation. This software is provided "as is" without express or ** implied warranty. */ For the printer driver, part of the code is a stripped-down version of Commodore's example printer driver for the HP Laserjet. Index ***** Concepts ======== +FHNG: 54 Sending -1 (toggle CAT ILBM) Viewing -a (append) Creating -b (bit order between computer and modem)Sending -b (bitorder in the fax file) Viewing -d (directory) Receiving -f (fax device) Sending -f (font name) asc2fax -i (immediate answer) Receiving -i (invert) Creating -l (logging level) Sending -o (output) Creating -r (raw) Creating -s (font size) asc2fax -v (verbose) Creating -x (offset) Creating -y (offset) Creating .args all2fax.rexx .doit all2fax.rexx .iff all2fax.rexx .raw all2fax.rexx .rexx all2fax.rexx .shell all2fax.rexx Alternative ways of generating fax filesalternatives Bit order problems Limitations Copyrights Copyrights Creating Fax Files Creating fax files, Alternative ways of generatingalternatives generating fax files, Alternative ways ofalternatives Incoming Faxes Receiving Index Index Outgoing Faxes Sending Overiew Overview Receiving Faxes Receiving Repeated failed transmission Sending Requirements Requirements Sending Fax Files Sending Usage Usage Viewing Fax Files Viewing Programs ======== all2fax.rexx all2fax.rexx append append asc2fax asc2fax fax2iff Viewing FaxPrinter FaxPrinter faxrecv Receiving faxsend Sending iff2fax iff2fax