

	 #########	   #	   # ######### #
		#	    #	  #  #	       #
	      ##   #	 #   #	 #   #	       #
	     #	   #	 #    ###    #######   #
	   ##	   #	 #   #	 #   #	       #
	  #	   #	 #  #	  #  #	       #
	 #########  ###### #	   # ######### #########
			 #
			 #
		    #####


	A control program for the ZyXEL U-1496 series MODEMs for use with the
	Linux operating system (and other UNIX-like systems)

	This program manages the use of the ZyXEL MODEM for:

	- dial-in, for use by "uucp" and other programs started from
	  a login

	- dial-in security (checking username and password)

	- dial-back security

	- dial-out, e.g. using "cu", "uucp" or "seyon"

	- receiving FAXes

	- sending FAXes

	- polling for FAXes

	- answering machine (voice mailbox)

	Everything is done in a single program, to keep things simple
	and fast.  Multi-program solutions are available from others.
	(e.g. modgetty)

	Copyright 1993 by Rob Janssen, PE1CHL

	This program uses parts of "getty_ps", written by Paul Sutcliffe:
	Copyright 1989,1990 by Paul Sutcliffe Jr.

	Permission is hereby granted to copy, reproduce, redistribute,
	or otherwise use this software as long as: there is no monetary
	profit gained specifically from the use or reproduction or this
	software, it is not sold, rented, traded or otherwise marketed,
	and this copyright notice is included prominently in any copy
	made.

	The author make no claims as to the fitness or correctness of
	this software for any use whatsoever, and it is provided as is.
	Any use of this software is at the user's own risk.

==========
Note:  This version has the configuration file under /etc/zyxel.conf or
/etc/zyxel.conf.ttyS1, etc., and the library under /usr/lib/zyxel.
==========

Installation
------------

Installation should be most straightforward by unpacking everything from
the distribution tar file:

cd /
tar xvzf (path-to-your-tarfile)

This will install the program as /etc/ZyXEL, and creates a defaults file
in /etc/defaults/ZyXEL.
Also a directory /usr/ZyXEL is created, which will hold the files used
by the program.  Another location for this directory could be selected in
the /etc/defaults/ZyXEL file.


After loading the files the following setup files can be edited:

/etc/default/ZyXEL:

This file defines the behaviour of the program, and where it is to find
the files it needs.  An example of such a file:

INIT="" AT&F&D3&S1&T4E0S2=255S6=5S40=120S42.6=1P\r OK
MUTE=M0
READY=[1750,0,1]
STATEFILE=/usr/ZyXEL/state.%s
FIFO=/usr/ZyXEL/fifo.%s
DEBUG=170
#LOCKPOLL=YES
#
# DATA mode stuff
#
VERSION=/etc/issue
ISSUE=/etc/issue.modem
TIMEOUT=60
LOGIN=/etc/login
LOGINENV=NO
LOGINFLAGS=-f
PROTECT=/etc/protect.usr
#
# FAX mode stuff
#
FAXID= +00 00 00000000
FAXDIR=/usr/ZyXEL/fax
FAXFILE=%y%m%d-%H%M
#
# VOICE mode stuff
#
PLAYDIR=/usr/ZyXEL/play
RECDIR=/usr/ZyXEL/record
RECFILE=%y%m%d-%H%M
RECMODE=0
SILENCE=20,70
DROPMSG=5
SHOWMSG=AA
VOICECMD=/usr/ZyXEL/commands
ARCHIVE=/usr/ZyXEL/archive
APIUSERLEVEL=7
#
# VOICE mode beeps
# avoid freqs 440 Hz, 1200 Hz, 1300 Hz and 1800 Hz
#
RECATTN=[933,0,4]
RECDONE=[1866,0,1][0,0,1][1866,0,1]
PROMPT1=[933,0,1]
PROMPT2=[1866,0,1][933,0,1]
ERROR=[500,0,3][0,0,1][500,0,3][0,0,5]


On the first line, the INIT string is defined which is sent to the
MODEM.  You may want to remove the P just before the first \r if your
telephone system allows the use of DTMF dialing.  (P = Pulse dialing)
You may also want to insert or modify settings like S6=5 (extending wait
for dialtone) and S40=120 (enable distinctive ring detection) in the
INIT string.  Leave the other initialization options as they are shown,
at least until you fully understand their meaning and the implications
of changing them.

The command after MUTE= is sent to the MODEM before answering calls in
DATA or FAX mode.  You can use M0, M1, M2 or M3 to control the behaviour
of the MODEM internal speaker.  Check the ZyXEL MODEM manual.

The tone after READY= is sent when ZyXEL has started and successfully
initialized the MODEM.  It will sound a short beep from the internal
speaker.  comment-out this line when you don't like that.

The number after DEBUG= turns on some debugging output (will be written
to the file /tmp/ZyXEL:line), it can be commented-out as soon as
everything appears to be operating ok.  More debugging output can also
be enabled, the number after DEBUG= is an octal number indicating
classes of debug output:

	D_OPT		0001	/* option settings */
	D_DEF		0002	/* defaults file processing */
	D_UTMP		0004	/* utmp/wtmp processing */
	D_CHAT		0010	/* MODEM chat (send/expect/waitfor) */
	D_GETL		0040	/* get login name routine */
	D_RUN		0100	/* other runtime diagnostics */
	D_LOCK		0200	/* lockfile processing */


When you use only clean programs like Taylor-UUCP and Seyon, you can
omit the line LOCKPOLL=YES.  It causes the program to wake up every 15
seconds to check for a lockfile, which is usually not necessary.  Use
LOCKPOLL=YES only when you find that ZyXEL does not detect that certain
programs have been using the port.

Add your phone number after the FAXID=, it is used when answering FAX
calls.  This string can be up to 25 characters.

RECMODE= defines the recording mode used for incoming messages.  known
modes are:

	CELP		0	(only on PLUS models)
	ADPCM2		1
	ADPCM3		2

Selecting mode 0 on a non-PLUS modem will cause recording in ADPCM2 mode.

DROPMSG= defines a minimum recording time (in seconds) for an incoming
voice message to be kept.  Messages shorter than this will be deleted
immediately after the recording.  This is used to prevent recordings of
only the BUSY tone being kept.  5 seconds seems to be a good value.

SHOWMSG=AA enables the "incoming messages available" indication on the
"AA" LED on the MODEM.  Note that the "AA" LED is normally OFF, even
when the program is in a mode where it will be answering the phone.
This is because the decision to answer the phone is made based on the
incoming RING indication, and the mode in which the program is at that
time.
When SHOWMSG=AA is in the file, the "AA" LED will be ON when a VOICE
message is present in the voice messages recording directory.  This
allows you to see at a glance whether a message is waiting, without
having to check on the computer screen (which may be blanked or OFF).

APIUSERLEVEL= defines the userlevel that a user entering via the API
FIFO will automatically get.  The API FIFO is the interface used by
local programs, to let ZyXEL playback VOICE messages etc.  When the
APIUSERLEVEL is suitably set, a local user can playback messages without
first entering the password that would be required when doing this from
the phone.


/usr/ZyXEL/commands.example:

copy this file to /usr/ZyXEL/commands, and edit the numbers used as
'passwords' (123456 and 654321 in the example file) so that the
passwords you use are not so easy to guess by others :-)


/etc/inittab:

replace the line you may be currently using for the port (e.g. using
getty or uugetty) with something like the following:

	s1:4:respawn:/etc/ZyXEL ttyS1 57600

The baudrate "57600" may be too high when you use a '386 machine and
have no 16550A UART installed.  You can decrease it to 38400 without
much penalty.  Going down to 19200 or even 9600 will kill some of the
voice mailbox capabilities...


/etc/issue.modem:

The contents of this file are shown when a caller connects in DATA mode.
The @letter sequence is used to insert system-dependent data.
You can edit this file to direct callers towards public services
available on your system (e.g. "bbs" and "nuucp")


/etc/protect.usr:

This file defines the users that can login via the MODEM, and the
password they have to use.  It can also define a telephone number to
dial back to the calling user, for enhanced security.
Because of this file, you can have restricted access via the modem,
without having to set passwords on all your accounts.  Of course, you
should only allow access to restricted applications (uucp, bbs) in that
case, because a user getting a shell can simply "su" to any other user
which does not have a password...

The layout of the /etc/protect.usr file is:

username:*
username:password
locationname:password:telephone_number

The first form allows access for users logging in as "username", without
asking for a password.  The second form will cause a Password: prompt to
appear, and the entered password will be checked.
When the telephone_number is also present (third form), the line is
disconnected and the specified number is then dialled.  When it answers,
a connection is set up, and the user will be presented with the normal
login: prompt of the operating system, so that he can login as any user
whose password he knows.

Note that the passwords appear in plaintext, and have to be maintained
by the system administrator using a text editor.  The file should
therefore be owned by "root", and have mode 600 (-rw-------).


/usr/ZyXEL/state.<linename>

This file (e.g. /usr/ZyXEL/state.ttyS1) defines the operating mode of
the program for a certain line.  It consists of one to five lines with
multiple space-separated tokens.  The following tokens are used:

	<mode> <number_of_rings> [<alt_number_of_rings>]

The <mode> defines the mode in which calls are answered.  The following
values are defined:

	DATA	answer in DATA/FAX mode, switch to VOICE when NO CARRIER
	VOICE	answer in VOICE mode, switch to DATA/FAX after silence
	FAX	answer only in FAX mode

The <number_of_rings> sets the moment at which the program answers the
phone.  In DATA mode this will usually be 1 or 2, but in VOICE mode you
may prefer to select a higher number to give some time to manually
pickup the phone when you are nearby.

For VOICE mode, an optional second <number_of_rings> may be specified.
When messages are present in the voice messages recording directory, the
phone is picked up after this second number of rings.
This can be used as a toll saver feature: specify a lower number of rings
in the second number, and when you want to check remotely if messages
are waiting, only let the phone ring as many times as specified here.
You will save the costs of a call when no messages are waiting.
Example:

VOICE 4 2


When you are using the "distinctive ring detection" option of the ZyXEL
MODEM, the file should have five lines (or at least one more than the
highest ring type expected from the MODEM).  In this case, the program
will use the n+1'th line of the file when RINGn is received from the
modem.  Example:

VOICE 4
VOICE 4
DATA 2

MODEM will pickup in VOICE mode after 4 rings when RING or RING1 is
received, and will pickup in DATA mode after 2 rings when RING2 is
received.


crontab of user root:

In this crontab you can put commands to switch the mode of the program
at specified times of day.  E.g. to run in DATA mode during the night,
and switch to VOICE mode during the day.  Example:

	0 23 * * *	echo "DATA 2" >/usr/ZyXEL/state.ttyS1
	30 7 * * *	echo "VOICE 4" >/usr/ZyXEL/state.ttyS1

This will put the program in DATA mode for the period 23:00-07:30 each
day (I am using this setup for my BBS)


Firing it up
------------

After the above changes have been made, and the MODEM has been connected
and switched ON, use "telinit 4" to set the INIT runlevel to 4, which
causes the /etc/ZyXEL program to be respawned.  (use "telinit q" when the
runlevel already was at 4)
Now, you should see a quick dialogue on the MODEM TXD and RXD LEDs, and
you should hear a short BEEP from the modem to indicate successful
intialization.   After this, the LEDs HS, DTR, CTS and EC should be ON,
the others should be OFF.
When this fails, the is probably a problem with the COM port or the cable
used to connect the MODEM.  Checkout using a terminal program.

When you now press the DATA/VOICE button on the MODEM, it will react as
if a call came in.  Depending on the STATE file contents, it will be
in VOICE or in DATA mode.
However, to be operating in VOICE mode you will need pre-recorded messages,
which you first need to record now.


Recording messages
------------------

To record your own outgoing messages proceed as follows:

1. put the program in VOICE mode (echo "VOICE 4" >/usr/ZyXEL/state.ttyS1)

2. use one of three methods to get connected to the VOICE mailbox:

- connect a microphone to the MODEM (see manual), run the "zvmb" program,
  and press V to connect to the VOICE mailbox.  you will use the
  machine's keyboard to enter numbers in this case, and you should not
  type the * and #  (use ENTER instead).  enter 55 to switch the modem to
  use the microphone for input.

- or call the MODEM from another phone (e.g. when you have a PBX), and after
  you get a connection and the existing message has been played press '9'.

- or connect a microphone to the MODEM (see manual), and press the DATA/VOICE
  button on the MODEM.  Use a 'pocket tone dialer' (DTMF keypad with
  loudspeaker) to generate DTMF tones in this case.
  After the message has been played, press '9'.
  Then type *55#, and the mailbox should answer with a short BEEP.
  This phase may be a little tough as the MODEM was in 'telephone line'
  mode and is not very sensitive.  After the *55# is accepted the
  'microphone' mode has been selected and everything should be fine.

3. enter *51# to record in CELP mode, *52# to record in ADPCM2 mode or
   *53# to record in ADPCM3 mode (these give different quality and data rate)

4. wait for the BEEP, and start recording your message.  The silence detection
   interval is quite short now, so you should continue talking...  You
   can adjust the silence detection interval in the commands file, but
   keep in mind that the period of silence in your recorded message will
   slow down the procedure each time it is played...
   When finished the BEEP-BEEP sound indicates the recording is stopped.

5. enter *54# to replay your message, and repeat the recording if not
   satisfied.

6. now your message is saved in /tmp/record.zvd, and you can move that file
   to the proper file in the /usr/ZyXEL/play directory.  the greeting to
   be played when answering in VOICE mode is called "greeting.zvd".

Repeat this for all the messages you want to record or replace.

You can also use .zvd files created by any other software that adheres
to the .zvd standard file format.  (e.g ZFAX under DOS)


Remote Control
--------------

In general, the MODEM DTMF detection feature seems to be a little
insensitive just after the start of the recording.  Wait a short while
after the BEEP to get better results, or first press *.


DTMF functions in VOICE mode:

1	- play announcement message (again)

2	- replay your own recorded message

3	- record a new message over previous one

4	- erase your own recorded message

6	- goto DATA mode

7	- goto FAX mode

9	- expert mode

0	- hangup

*	- ignored because * has to be pressed on many phones to enable DTMF

#	- stop (message, recording), end number


All codes shown as *digits# below are numeric entries, for which the
decimal value of the digits between * and # selects the function.  So,
*00# is equivalent to *0#.
The * key merely erases all entries made before, effectivily clearing
the number as a startoff.   It can therefore also be used when an entry
error has been made.  (e.g. *52*51# gets processed as '51')

Functions in expert mode:

*0#	- back to VOICE mode

*33#	- recorded message playback

*34#	- archived message playback

*51#	- record new message (CELP)

*52#	- record new message (ADPCM2)

*53#	- record new message (ADPCM3)

*54#	- play new message

*55#	- switch to microphone input

*56#	- switch to telephone line input

*61#	- enter number for callback

*62#	- callback selected number

others	- see /usr/ZyXEL/commands


Functions in message playback mode:

0	- leave playback

1	- playback help

2	- tell message date/time

3	- next message

4	- delete message & step to next

5	- archive message & step to next

7	- first message, step forward

8	- play same message again

9	- last message, step backward




Using "zvmb"
------------

"zvmb" is a very simple program, which was mainly developed to test
the API FIFO interface of the program.  A more friendly program has
to be developed for user interaction.
However, zvmb is now usable to do some interaction with the VOICE
mailbox, and it is more comfortable that the earlier method, which
worked by connecting a microphone and using a DTMF keypad to issue
commands...

When "zvmb" has been started, it tells you how to quit from it:

ZyXEL VoiceMailBox user interface - Hit RETURN for MENU
Use ^C to quit

Please remember this :-)  (it is the INTR key defined for your terminal,
when ^? appears, the DEL key is meant)
You can press ENTER to get a menu of available commands:

ZyXEL 1.0 (Sep  5 1993 10:58:19)   (c) 1993 by Rob Janssen, PE1CHL

Commands are:
S: use SPEAKER for playback (default)
L: use LINE for playback
V: access VoiceMailBox
F: Send a FAX <number> <filename>
Q: Poll for FAX <number>
R: Link status report

Pressing one of these letters will immediately perform the indicated
action.
S and L are used to set the output device for VOICE mailbox message
playback.  Messages can be played back through the MODEM internal
speaker, or to a speaker or telephone handset connected to the LINE
terminal of the MODEM (see MODEM manual, end of chapter 14).
The internal speaker is attractive because it requires no plugging or
switching of the line, but the quality of playback is awful.  Use the
LINE option for HI-FI playback :-)

V is used to access the VOICE mailbox.  You will be dropped into the
mailbox at the point where you normally are after listening to the
announcement message, and pressing 9 to enter expert mode.
Your userlevel will have been set according to the APIUSERLEVEL=
line in the /etc/default/ZyXEL file, so that you will not have to
enter the password code in personal-use environments. (APIUSERLEVEL=7)
Now, you can enter any code defined in the /usr/ZyXEL/commands file,
and enter 0 to exit from the VOICE mailbox.
When the default commands file is in place, 33 will enter the message
playback mode, where you can handle messages that have arrived.

F is used to send a FAX.  First, you need to prepare the outgoing FAX
file using ZFAX under DOS or "dosemu", the format of this file is
(unfortunately) different from that generated by other fax programs.
Then send the FAX by typing: F number faxfile [ENTER], e.g.:
F 030715610 /tmp/fax1.fax
The result of sending the FAX is reported, you will have to re-try
when it fails.

Q is used to poll for an incoming FAX.  Type Q number <ENTER> to call
the specified number and ask for a FAX.  When it is available, it will
be received and stored in the incoming FAX directory.

==========
The ability to fork an external fax program (such as efax) has been added.
Just set the "FAXPROG" variable in the /etc/zyxel.conf file to the program
(plus any parameters) to be executed to receive the fax.
==========

R will print the ZyXEL LINK STATUS REPORT, reporting the statistics
for the last DATA-mode CONNECT.  Just for the curious... :-)


Calling out
-----------

To use the modem to place an outgoing call, you will have to use the
/dev/ttySx device, i.e. the same device as the ZyXEL program is also
using to access the modem.  You may have been using /dev/cuax until now,
to let the system arbitrate between incoming and outgoing calls on the
modemline.  However, this arbitration is based on the availability of
the DCD signal to indicate an incoming call, and the ZyXEL modem does
not provide this signal in VOICE mode.
Therefore, the program has to operate the serial port in a different
mode than getty does, and you cannot make use of the /dev/cuax device.
Other programs that allow the use of the ZyXEL modem with Linux have the
same characteristic.

To prevent problems when another program opens the serial port while the
ZyXEL program is busy chatting with the modem, or vice-versa, a lock
file has to be created in a pre-defined place.  The presence of this
file indicates that the line is in use.
This lockfile is correctly created by programs like uucico, cu, seyon.
Your favorite terminal program may need to be configured to create (and
check) the lockfile.  Check this out when you notice that the ZyXEL
program interferes with your use of the modem.

The directory, name and contents of the lockfile can be configured
while compiling the program.  On a Linux system, these files usually
live in /usr/spool/uucp, and are named LCK..ttySx (to match the name
of the line the modem is on).  The contents of the file are the PID
of the program that is actively using the MODEM at that time, as an
ASCII string.  Alternatively, the PID may be written in the file in
binary (4 bytes).
On UNIX system 5 release 4, the lock files are in /usr/spool/locks,
are named LK.dev.major.minor (to match the device, major and minor
numbers of the tty node), and the contents are also the ASCII PID.
This behaviour can be selected at compile time using the symbol
SVR4LOCKS in the source.
