readme-sm+-0.1

使用3Com USR Modem进行录音和放音

README for SM+ version 0.1 - Sportster Message Plus
===================================================

This is the README file for version 0.1 of sm+, and it is the only
documentation available for this version. It provides information on
what sm+ is meant to be, how it is to be installed and how it is to
be used, as well as limitaions and bugs.

See the file COPYING for licensing terms (GPL). 
See the file INSTALL for generic installation instructions
(configure), but see also the sm+-specific installation notes below
(section "Installing sm+").


What is sm+?
============

SM+ is a program to manipulate the settings for the independent mode
of a modem of the type "3Com USRobotics Sportster Message Plus" aka
"U.S. Robotics 56K Message" (or compatible).


Installing sm+
==============

Prerequisites
-------------

The "expect" package by Don Libes must be installed, version 5.12.0 or
better.

Getting sm+
-----------

Get sm+ by ftp from sunsite.unc.edu (or mirrors) in the directory
/pub/Linux/apps/serialcomm/modem. E.g. for version 0.1 (this version),
get
	ftp://sunsite.unc.edu/pub/Linux/apps/serialcomm/modem/sm+-0.1.tar.gz


Actual installation
-------------------

Run "configure" and use the resulting executable expect-script, "sm+",
in any directory of your choice.

You can then use "make" to install it where additional software usually
goes on your computer (typically /usr/local/bin/).

Don't forget to check the access-rights of your modem device (also see
"Security concerns" in the section "Bugs and Limitations", below).

Using sm+
=========

Minimal usage is something like

	$ sm+ /dev/modem

which virtually does nothing, as you may have expected (except for
verifying that the modem really is a Sportster Message Plus). 

There are action commands and switch directives: Switch directives
manipulate the settings for the independent mode. Actions have
immediate impact. Action commands and switch directives may be
intermixed in the command-line, the last command-line argument has to
be the modem device.


Actions
-------

Actions are performed in the order they are specified in.


Meta-Actions:

  -h, --help
        print usage help
  -V, --verbose [arg]
        increase verbosity (to level ARG, if given)
        if given, ARG must match "^[0-9]+$"


STATUS:

Report the status information of the SM+ Flash Memory and Stored
Messages in a computer friendly format.

  -s, --status
        show status report


RECORD and PLAY:

Record the specified SM+ outgoing message through the internal
microphone and store it in the SM+ Memory. The recording is terminated
either by a key press abort, or if the size of the recorded SM+
message exceeds the space available for its storage in the SM+ Memory.

  -r, --record
        record outgoing message
  -R, --recordFull
        record outgoing message for "memory full"

Play back the specified voice message through the external speaker.

  -p, --play [arg]
        play message number ARG (0 for outgoing)
        if given, ARG must match "^[0-9]+$"
  -P, --playFull, -p 255
        play outgoing message for "memory full"

The record and play actions currently only use the intern microphone
and the external speaker connector (headphone) of the modem.


Switches
--------

Many switches are boolean; they can be enabled ("+"-form) and disabled
("-"-form). Others take arguments. Order of switches is not
significant (except when a switch is specified more than only; than
the last value given will be used).


ACTIVATE:

  +, --activate
        activate self-mode

	This makes the modem take off the hook, answer, receive
	and store automatically.

  -, --deactivate
        deactivate self-mode

	This makes the modem behave like a normal modem.


WRITE:

Store the current settings of the SM+ Feature in a nonvolatile
memory. Then, if a power cycle occurs, the SM+ Feature stays enabled
and the stored settings are used.

  -w, --write
        write settings to non-volatile memory

	If modem is power-cycled, it will remember the settings for
	self-mode.


CLOCK:

The SM+ has a clock which time-stampes incoming messages. Initially
and after a power-cycle, the clock is not running.

Reset SM+ clock to 0 days, 0 hours, 0 minutes, 0 seconds. The SM+
Clock measures time up to 255 days. After modem's power up, the SM+
clock is set to 255 days, 255 hours, 255 minutes, 255 seconds. The SM+
Clock does not roll over, it saturates at 254 days, 24 hours, 0
minutes, 0 seconds instead. The SM+ clock has to be reset in order to
start running.

  +c, --startClock
        start clock


RING:

Set up the number of incoming RINGs before answering in the SM+ Mode.

  -n, --ring arg
        set number of rings (>2)
        ARG must match "^[0-9]+$"

	
FAXRECEPTION and FAXID: 

Enable/disable fax reception and storage in SM+ Mode.

  +f, --enableFaxReception
        enable fax reception
  -f, --disableFaxReception
        disable fax reception

Set up and store the T.30 compliant SM+ Fax ID String for fax
reception in SM+ Mode. The SM+ Fax ID String consists of up to 20
ASCII characters from 020h (space) to 060h ('), and from 07Bh ({) to
07Eh (~).

  -i, --faxid arg
        set fax id to ARG


VOICERECEPTION and VOICEDURATION:

Enable/disable voice reception and storage in SM+ Mode.

  +v, --enableVoiceReception
        enable voice reception
  -v, --disableVoiceReception
        disable voice reception

Specify the duration in seconds of the received voice messages.

  -d, --voiceDuration arg
        set maximal duration for incoming voice messages
        ARG must match "^[0-9]+$"


MONITOR:

If the SM+ Call Monitor Option is enabled, then all audio signals
present on the phone line during an answer session in the SM+ Mode are
routed to the external speaker connector in addition to all standard
signal routing.

  +m, --enableMonitor
        enable speaker monitor
  -m, --disableMonitor
        disable speaker monitor


LOCAL: 

Enable/disable the SM+ Local Mode. In this mode the modem will do no
further communication with the computer. It will not report incoming
RINGs. Only smart programs (like this one) can reanimate the modem.

  +l, --enableLocal
        enable local mode
  -l, --disableLocal
        disable local mode


optionsFrom:

Read more options from a file and insert them into the command-line.

  -o, --optionsFrom arg
        read options from file ARG


DIALUPRETRIEVAL and PASSWORD:

If the SM+ Dialup Retrieval Option is enabled, the user can remotely
retrieve the stored voice messages through a dialup connection. A user
configurable four digits password called the SM+ Dialup Retrieval
Password, that has to be entered during a dialup retrieval session
using the DTMF tones, protect the access. Sending appropriate DTMF
signals as control commands controls the progress of a dialup
retrieval session.

Enable/disable SM+ Dialup Retrieval Option.

  +t, --enableDialupRetrieval
        enable dialup retrieval
  -t, --disableDialupRetrieval
        disable dialup retrieval

Set up and store the SM+ Dialup Password. The SM+ Dialup Password
consists of 4 digits.

  -c, --code [arg]
        set password for dialup retrieval ("code")
        if given, ARG must match "^[0-9][0-9][0-9][0-9]$"

Note about using the Dialup Retrieval Option: 
	Voice retrieval is entered through the call selection,
	discussed in the reception mode. Once a DTMF digit is detected
	during call selection, the SM+ Dialup Password verification is
	started. The user has three chances to enter the correct SM+
	Dialup Password. If he fails to enter the correct SM+ Dialup
	Password, the call is aborted and the modem goes back on
	hook. If the correct SM+ Dialup Password is entered, the modem
	acoustically indicates the number of present Unchecked
	Messages (new) including the case of no new messages. The user
	may then enter the DTMF digit 0 to repeat the acoustic
	indication of new messages count. The DTMF digit 1 will start
	playback of all Unchecked Messages. The DTMF digit 2 will
	start playback of all Stored Messages. While playing back
	messages , the DTMF digit 1 restarts the playback of currently
	played voice message. The DTMF digit 2 aborts current
	playback, marks the aborted message as checked, and start
	playing the next selected message. When there are no more
	voice messages selected for playback, the modem acoustically
	indicates the end of currently played message and waits for
	more DTMF tones for a predefined amount of time. The user can
	either hang up the SM+ Modem by DTMF digit * or the SM+ Modem
	hangs up automatically after a certain period of time has
	expired.

Example usage
-------------

I use it like this (password changed):

	$ sm+ + -n 3 -i "++49+228+210503 MSF" +f -d 90 +v +m +l +c -c 9999 +t -w /dev/modem

To be more honest, I use it like this:

	$ sm+ -o ~/sm+.options

And the file ~/sm+.options contains:

	+ -n 3 -i "++49+228+210503 MSF" +f -d 90 +v +m +l +c -c 9999 +t -w /dev/modem

This means:
	- activate SM+ mode (+)
	- answer after 3 RINGs (-n 3)
	- set receiving fax-Id to "++49+228+210503 MSF" (-i "++49+228+210503 MSF")
	- enable fax reception (+f)
	- limit incomint voice messages to 90 seconds (-d 90)
	- enable voice reception (+v)
	- enable answer monitor option (+m)
	- enable local mode (+l)
	- start the clock (+c)
	- set a dialup retrieval password (-c 9999, code changed)
	- enable dialup retrieval (+t)
	- write these settings into non-volatile memory (-w)
	- use my modem (/dev/modem)

If I was less into showing off what a guru I am, the following would do the same:

	--activate --ring 3 --faxid "++49+228+210503 MSF" --enableFaxReception --voiceDuration 90 --enableVoiceReception --enableMonitor --enableLocal --startClock --code 9999 --enableDialupRetrieval --write /dev/modem


Bugs and Limitations
====================

Tested configurations
---------------------

Only tested in the following configurations:
	- Linux 2.0.0, expect 5.12.0, modem firmware rev. 11.1.18 (as bought)
	- Linux 2.0.0, expect 5.12.0, modem firmware rev. 12.1.14 (V90 upgraded)

Security concerns
-----------------

Every user who has access to the modem device can retrieve and display
any of the following data (using this program or any general-purpose
application for serial-line communication):
      - the password stored in the modem (also see below)
      - messages (be it voice or fax)
      - sender fax IDs of stored fax messages
      - other meta-data like time of reception and duration of
        stored messages
And every user who has access to the modem device can also delete stored
messages or change the setup.

This means that you should read- and write-protect the modem device properly.

You may set a "Dialup Password" for dialup retrieval of stored
messages with a MF-dialtone device.

If the password to be set is given as a command-line option argument,
any user of the system may see it in a process status report of the
OS. Instead of specifying the password in the command-line directly,
better store the password option and argument in a file that is
properly read- and write-protected, and use the "-o"-option to read
from that file.


Known Issues (term by courtesy of some big software company)
------------------------------------------------------------

- Sometimes the modem hangs during initiation of communication. This
  was a normal experience also in the days when I had to use the
  "Modem Manager" software. So I don't blame this software (Tell me if
  I'm wrong!). If this happens to you, just power-cycle the modem
  (losing clock information).

- There is no built-in facility for locking and unlocking the modem
  device. This means that sm+ would talk to e.g. an mgetty process
  listening on the line instead of the actual modem.

- There is no facility for deleting messages from the modem's memory.

- The status report command (STATUS, "-s") leaves the user alone with
  interpretation of the "SM+ Information Screen in a user friendly
  format" (citation from SMP_SDK.pdf).

- The start clock command (START, "+c") blindly starts the clock, no
  matter if necessary or not. The time of this action is not stored
  anywhere and thus is not used later.

- Messages are not downloadable (be it voice or fax).

- The record and play actions currently only use the intern microphone
  and the external speaker connector of the modem. And there is no way to
  modify the input gain or the output gain levels.

- Trying to play a fax message on the intern speaker yields a modem
  error.

- The verbosity levels of messages seem to be inconsistent.

- (intern: There is no timeout active while playing a message.)

- There could be some mgetty-like (or compatible)
  /var/spool/fax/incoming behaviour.


To do
-----

- Status-report and clock-start should update and use a timestamp
  stored outside of the modem.

- Provide for device locking during operation.

- Implement message deletion.

- Status-report and others should request and process
  (i.e. "understand") the computer-readable form of report and than
  output in a nice format (maybe according to a user-defined
  format-string?).

- Messages should be downloadable (be it voice or fax).

- The record and play actions should also be able to use voice files.

- Input and output gain of the intern microphone and the intern
  headphone speaker should be adjustable.

- Only voice messages should be tried to play.

- The verbosity levels of messages are not sophisticated enough (or
  too sophisticated?).

- (intern: Timeout correctly while playing a message.)

- (intern: Only start clock if it is not running already?)


Future plans and priorities
---------------------------

Maybe I will only implement those to-dos I'm most interested in:

- download fax messages

- delete messages