PLEASE READ THE HISTORY SECTION AT THE END OF THIS FILE IF YOU'VE
USED THIS PROGRAM BEFORE!!!

NOTE: YOU CANNOT USE THE OLD SOUNDFILES CREATED BY VERSIONS 1.0, 1.1,
and 1.2 OF THIS PROGRAM.

--------------------------------------------------------------------------

DESCRIPTION

This is ZVM 1.6, a voice module that CAN be used with
GPFax2.21+ (GPFax is not required!).  In short, it allows you to use
your ZyXEL modem as an answering machine.  You can retrieve your
messages remotely and locally, play messages through the modem's
internal speaker, through the telephone line, or through the Amiga's
sound system.  It also detects when a fax is calling up and lets GPFax
handle the call.

It has a fully gadgetized user interface.  NOTE -- at this time, the
keyboard shortcuts for the CYCLE gadgets do NOT work.

It has an AREXX port.

REQUIREMENTS

This works on my A3000 running WB2.04 (it won't run on 1.3).  It
should run fine on a 68000 machine.  CELP is the best choice, if you
have one of the plus models.  ADPCM2 is really good enough for most
purposes.

As of this time, there is no CELP decoder.  Therefore, you cannot play
back any files that have been recorded with the CELP compression
method.  I strongly suggest that you stick with ADPCM2 until this is
fixed.

The modem's ROM is 5.02.  Anything higher should work.  Type in ATI in
some terminal to find out what ROM version you have.  As of 5.02 (what
I have), the decoding of the touch tones is not very reliable.  Hence,
you need to press the keys for a long time before the modem recognizes
them.  I've been told that the higher ROM versions work much better.

This version requires the GPFax/11 font, which is included with
permission from GPSoftware.

AUTHOR

This program was written by Al Villarica of BuglesSoft.  I can be reached at:

rvillari@cat.syr.edu

or

Al Villarica
104 Roney Lane, #22
Syracuse, NY 13210

Please send any bug reports or features you would like included to
either address (Email is faster).

ACKNOWLEDGEMENTS

Mike Sinz for SimpleRexx and Enforcer
Jan van den Baard for GadToolsBox 1.4 (The Sequel)
Dr. Greg Perry of GPSoft for GPFax
SAS for SAS/C
David Gay for Emacs port
ZyXEL for their modem and the conversion routines from ADPCM2/3 to something

-------------------------------------------------------------------------------

A.  Setting up

1.  Unarchive the archive.  Assign voice: to the directory which contains
ZVM.  You will need to put this ``assign'' into your user-startup file.

Ex. assign voice: work:zvm

1b.  Make the voices and voicein directories

makedir voice:voices
makedir voice:voicein

2.  Copy over the required font into your font directory.  Type in the
following to accomplish this:

copy gpfax.font fonts:
makedir fonts:gpfax
copy gpfax/11 fonts:gpfax

2b.  Run GPFax and go into the options menu and make sure that it is 
set up to be in SHARED serial mode.  You also need to go into the ENVIRONMENT
window and change the modem initialization string.  It probably currently
reads AAT&FE0...Kill off the &F.  This is because the &F hangs up the modem,
and at the time we issue a RECFAX to GPFax, the modem is already ON-HOOK.
You don't want it to hang up and then pick it up again.

3.  To run the program, get into a CLI shell and type the following
(or put it in a script).  The script cliloadzvm assumes that there is
an assign called gpfax: which points to the directory where the GPFax
executable resides.  There is a script called cliloadzvmnofax which
doesn't load GPFax and also uses the NOFAX option.

cd voice:
run >nil: <nil: gpfax
waitforport REXX_GPFAX
run >nil: <nil: voice:ZVM serial.device 0 FAX 50 16 50 64

OR

cd voice:
execute cliloadzvm

OR

cd voice:
execute cliloadzvmnofax

3b.  Arguments to ZVM

zvm serialdevice unitnumber FAX|NOFAX rec_time silence_threshold silence_time amiga_volume

  - serialdevice is the name of the serial device you want

  - unitnumber is the unit number of the serial device you want

  - The NOFAX option (note the capitals) will disable the fax reception
stuff.  The FAX option will enable the fax reception.

  - rec_time is the maximum recording time when answering a call

  - silence_threshold ranges from 0 to 31.  0 means that you want to disable the
  modem's silence detection.  31 means that you want the modem to treat even
  a noisy line as silent.  1 means that you want the modem to treat a clean
  line as meaning silent.  In other words, the higher the number (except for 0),
  the more likely the modem will treat noise as silence (thus, ending a recording
  session).  If you want the modem to be extra sensitive about what silence is,
  set this to a low value.

  - silence_time is in units of 0.1 second.  That means that a value of 50 here means
  5 seconds.  Anyway, this is the length of time the modem wants to hear silence
  for before telling ZVM that it has detected it.

  - amiga_volume ranges from 1 to 64.  64 is the loudest.

Use the following defaults:
  serialdevice = serial.device
  unitnumber = 0
  FAX
  rec_time = 50
  silence_threshold = 15
  silence_time = 50
  amiga_volume = 64

So, a typical ZVM invocation would look like

ZVM serial.device 0 FAX 50 15 50 64

which means that you want to use the serial.device unit 0, with the FAX
option enabled, a 50 second maximum recording time, a level 15 silence
detection sensitivity, and a 5 second silence detection time.

4.  CUSTOMIZE your program by recording the appropriate outgoing
messages.  You need to click on the Setup gadget to get into the Setup
Window.

-------------------------------------------------------------------------------

B.  Buttons:

Voice Module Window

1.  Calls tells you the number of messages you have waiting.  Faxes tells
you the number of fax attempts.  The CLR gadgets beside each of these clears
the corresponding logs.  You really shouldn't have to use the CLR beside the
Calls information box.  This is because you can delete messages one
at a time when listening to them.  You do need the Fax CLR button
because this only tells you the number of faxes that came in.  You
need to view the faxes through GPFax.

2.  Play Messages - Plays the messages over the telephone line, the
Amiga's sound system, or the modem speaker, one at a time.  Another
window will pop up that allows you to:

	a.  Delete the message
	b.  Play it again
	c.  Quit playing the rest of the messages
	d.  Skip to the next message, saving the previous one

3.  To - Selects whether you want to play the incoming messages over
the modem speaker, the telephone line, or the Amiga's sound system.

4.  Answer Fax - If you have GPFax2.21 or greater, this will let it answer
the call as a fax.

5.  Answer Call - Force the modem to answer the call as an automatic
voice/fax machine.

6.  Quit - Quit.

7.  Status - This status box shows you some status information.

8.  Setup - Click on this to get into the setup window.

Setup Window

1.  Rings - Click on this for the desired number of rings you want before
I will answer the call.  "Toll Saver" will let the modem answer in 2 rings
if there are messages, and 4 rings if there are none.

2.  Comp - Select the compression you desire.  ADPCM2 uses less disk space
and computing resources.  This is the preferred setting, unless you
have CELP.  ADPCM3 won't run on an unaccelerated Amiga.

3.  Password - Enter a 4 digit password (it has to be 4 digits!) for
accessing the messages from another telephone.

4.  Message - This is a cycle gadget which shows the messages you need to
customize before this program can be fully operational.  See the last section.

5.  Record - Records the message named by the Message cycle gadget
through the telephone line or an external mic.

6.  From - Select external mic or telephone line.  On Zyxels, you can
connect a telephone handset to the "Line" input of the modem.  Then,
you can speak into the "EAR" phone and use it like an External Mic.
WARNING: Don't use the External Mic option when the modem is plugged
into the phone line!

When recording over the telephone line, I suggest you press one of the
telephone keys to get rid of the dial tone first!  When you're done
recording, click on the Stop gadget that pops up.  See section
"Messages to customize" at the end of this documentation file.

7.  Play - Plays the message named by the Message cycle gadget
through the telephone line or the modem speaker.

8.  To - Select modem speaker, telephone line, or the Amiga's sound
system.

-------------------------------------------------------------------------------

C.  Calling from the outside:

When a person calls from the outside, ZVM will give instructions on
what to press.  It asks you to press 2 to send a fax.  At this time,
you can also press 9 to retrieve your messages.  It's a hidden option
most callers don't need to know.  Note that if you use the NOFAX
option, it will not accept 2 at this time.

After the caller leaves his message and hangs up, the modem will keep
on recording until it hears "silence" or a busy tone.  If it doesn't
hear any of those, it will record for up to 50 seconds.  You can set
the max. recording time using the parameters described above.

After you press 9, you will be instructed to enter a 4 digit password.
If it matches the Password string gadget in the setup section, you will
be granted access.  Each message will be played.  You will then be asked
to either 1) delete the message, 2) keep it and go onto the next one, or
3) play it again.

-------------------------------------------------------------------------------

D. AREXX port:

The AREXX port is called VOICEMAIL1.

Commands:

1.  UNLISTEN - Make the program not listen to the serial port.  This is
useful if you want to run a term program but don't want to quit ZVM.

2.  LISTEN - Only valid when the program is UNLISTEN'ed.

3.  QUIT - Quit.

4.  ANSWERFAX - Force ZVM to answer the call as a fax.

5.  ANSWERCALL - Force ZVM to answer the call as an automatic voice/fax machine.

6.  PLAY - Same as clicking on the Play gadget in the Voice Module window.

I use dnet a lot, so I have this simple script that works well:

failat 20
sys:rexxc/rx >nil: <nil: "address voicemail1 unlisten"
dnet >nil: nil: -X -Z2      <---put your dnet parameters here
wait >nil: <nil: 5
sys:rexxc/rx >nil: <nil: "address voicemail1 listen"

-------------------------------------------------------------------------------

E.  Messages you have to customize:

Here are the things you need to say when recording these messages in
the Setup Window.

1.  Wait for Beep = "This is ???-????.  Press 2 to send a fax or wait for
	the beep then leave your message"

or, if you used the NOFAX option,

    "This is ???-????.  Wait for the beep then leave your message."

2.  Retrieve or Fax = "Press 2 to send a fax or 9 to retrieve your messages."

or, if you used the NOFAX option,

     "Press 9 to retrieve your messages."

NOTE:  This message gets played if the caller presses a key that doesn't
activate any function.  You may choose to not mention the "9" key (put
in something funny like "What do you think this is, a voicemail system?).
Do what you like.

3.  Enter Password = "Enter your 4 digit password."

4.  Bad Password = "You entered a bad password."

5.  Play or Delete = "Enter 1 to delete this message, 2 to keep it, or 3 to play
it again."

6.  Timed Out = "You exceeded the time limit for entering your choice."

7.  Bad Choice = "You entered a bad choice."

8.  No Message = "There are no more messages."

9.  Goodbye = "Bye now!"

----------------------------------------------------------------------------------

To Do
	- Caller ID
partly	- User selectable max. recording time
partly	- User selectable silence detection time and silence detection level
	- Better UI for accessing the messages (use a ListView gadget)
partly	- Decoder for ADPCM2 and Encoder
	- Figure out what's wrong with ADPCM3
	- Work with other FAX programs
	- Work better with workbench and tooltypes
	- Add '*' as an option to end a call -- maybe we can also ask
		for the caller's phone number at that time!
	- Automatic delivery of messages
	- Maintenance mode from outside
	- Allow DTMF keys to run AREXX scripts
	- Archive messages
	- Import/Export IFF files
	- Record conversation
	- If someone picks up the phone before ZVM does, it should also pick
		it up and see if the caller wants a fax, etc.  In other words,
		it should support some kind of remote transfer
	- Distinctive ring
	- Use AREXX to allow heavy customization of answerCall()
	- Allow caller to enter his phone number and time of desired return call (aside
		from CID)
	- Blocking of messages via CID (if you don't want to receive messages from
		particular callers, or area codes, etc.)
	- VOICEMAIL
	- AREXX command when there are messages/faxes waiting (instead of just beeping)
	- Beep only if there is a new call (i.e. stop beeping when the person presses
		Play messages)
	- Possibly add a comment field for messages (especially useful when
		we put in the archiving facility)
	- silent modem

HISTORY

V1.6	- Added back ADPCM3
	- You can play ADPCM3 over the Amiga's speaker
	- Fixed the bug that didn't allow you to record a message right after
		playing it over the Amiga's speaker
	- ZVM uses different serial port speeds depending on the compression
		ratio.  I'm not sure if this will make ADPCM3 or CELP work better.
	- Uses different block sizes for different compressions also

V1.5	- Changed the interface to GPFax.  It now just uses ARexx instead of
		trying to do the AT+FCLASS=2, blah blah blah.  This requires
		two changes to the GPFax settings though.  You need to remove
		the &F part of the modem initialization string.  This is the first
		step towards making the program OTHER-FAX-friendly.
	- Added cliloadzvmnofax
	- Added back ADPCM3.  You can record in it and play it back through the
		Amiga sound system.  I still can't figure out how to make it play
		back reliably over the modem speaker or telephone line.

V1.4	- Added amiga volume parameter
	- Hopefully more robust than 1.3
	- Watch the status line of the main window for some error messages

V1.3	- Added playback through the Amiga's sound system
	- Added adjustable silence sensitivity and interval.  This is through
		the CLI arguments.  It's only a stopgap measure until I work
		it into the GUI.
	- Added adjustable recording time.  Also a stopgap measure until I work
		it into the GUI.
	- Had to make all the arguments to the program REQUIRED because I was
		too lazy to have to parse it.

V1.2	- Fixed some bugs and made serial routines faster
	- I declare ADPCM3 to not be working.  Don't use it.
	- Changed the way callers are handled.  Should be friendlier to the caller
		now.
	- Puts up a window if it can't open the timers or the serial port
		instead of writing to stdout
	- Now displays the version number on the main window
	- Basically a name change to ZVM instead of VM

V1.1
	- Added a different window for Unlisten mode
	- You can now quit in unlisten mode -- you're not stuck there anymore
	- New arguments for starting the program:
		zvm [NOFAX] [devicename unitnumber]
		
		If you start the program with NOFAX (note the capitals),
		the program will not answer faxes.  The caller cannot select
		'2' from the initial menu to force a fax.  In other words,
		the handling of faxes will be disabled by this argument.
	- Added zoom gadget and moved some stuff around in the UI -- when
		you click in the zoom gadget, you get a semi-iconized
		form (actually, it just shrinks the window) which shows
		you the # of incoming calls and faxes.  Note that this is
		just a resized window, so you can type in keys to access
		the functionality without zooming out.  For example, you
		can press the 's' key to access the setup window.
	- GPFax needs to be set on SHARED serial for this combo to work.