
                            H A M V I E W
                            -------------
 Current release 2.10                            By:  Alberto di Bene    I2PHD
                                                      Vittorio de Tomasi IK2CZL


                                                        V2.05  July 14th, 1998
                                                        V2.06  Aug.  1st, 1998
                                                        V2.10  Nov. 28th, 1998


                       **** W A R N I N G ****

   If upgrading from a previous version, delete the HAMVIEW.INI file.
   The new INI file has a different format, and it will be recreated
   by the program. You will have to reset your station coordinates, though.

                       ***********************


DISCLAIMERS
-----------

If you are eager to read all the disclaimers and legalese stuff, go to the end
of this document. Most important things first.


WHAT IS HAMVIEW ?
-----------------

To say it in a few words, HAMVIEW is a program that:

- gets an audio signal either from a Sound Blaster(TM) compatible card or
  from a .WAV file
- performs a windowed spectral analysis on the incoming signal
- displays the signal spectrum on the video screen using a carefully matched
  color scheme
- performs some enhancement on the signal using signal processing methods
- plays the filtered signal at the output of the audio card
- and last but not least, all these goodies are done in real time! (well, to
  be honest with about one second of delay from the input to the output,
  due to the data windows used for signal analysis and processing).

The program was especially developed for radio amateurs interested into all
those communication techniques where signals very close to (or more often
below) the receiver noise floor are used, like EME, VLF, and so on.
However we believe that Hamview will be of value also for HF and VHF CW lovers
(try it... we never found a point-and-click CW filter on a commercial
receiver!!!).

All the hardware needed is:

 - a Pentium computer with MS-DOS or PC-DOS 6.xx or greater
   (a W95 DOS session is OK). Windows NT is not supported, as the program
   needs to talk directly to the hardware, bypassing any driver, and this
   is not allowed under NT.
 - a Creative SB16 sound card or better. Compatible cards should work, provided
   that 100% hardware compatibility is assured, and the card is full-duplex
   compatible.

The program was developed in an effort to improve the capabilities of amateur
radio communications using the power of digital signal processing, and is
continuously evolving.
Check the Hamview web page ( http://www.freeyellow.com/members/padan ) for
further news.
If you find some interest in the program, please send an E-mail or a QSL
to one of the authors, saying (if possible):

- where you discovered this program
- how did you use it
- if it was of some use to you
- what kind of computer and operating system you use
- what addition would you like to see in the next version of Hamview

This information will not be delivered to anybody except the authors of
Hamview, and will not be used for commercial purposes. They will be treated
according to current laws for privacy, and have the sole purpose of helping us
to improve the next version of Hamview.

PREREQUISITES
-------------

To run HAMVIEW, you need the following:

     - A Pentium CPU (minimum 90 MHz). The program has been tested also
       with a 100 MHz DX2 486 CPU. It runs, but the percentage of CPU
       used is dangerously near to 100%, with all the filters off.
       If you want to use the 'Fast' setting, you need at least a 200 MHz
       Pentium.

     - Native DOS or a full-screen DOS session of Win 95.

     - A Sound Blaster 16 card. A fully compatible card can also be used,
       but the compatibility must be at the hardware level. This means
       that if you need to load drivers to achieve such compatibility,
       this card won't work with HAMVIEW. The SB AWE-32 and AWE-64 cards
       are hardware compatible with the SB 16.
       The sound card must have both the DMA channels defined, and they
       must not use the same number. If you use Win 95, this can be checked
       by opening ControlPanel->System->DeviceManager and verifying
       which resources the sound card is using. Both DMA channels must be
       present, with the second DMA channel set either to 5, 6 or 7.

       If using native DOS, if your card is *not* PnP (Plug-and-Play),
       just check if the jumpers are set correctly. If your card is PnP,
       as it will probably be, you must use a PnP Configuration Manager to
       set the card. If you have an original Creative Labs, this Config.
       Manager should have been installed by the card setup procedure.
       If not, consult the documentation for the card.

     - A SVGA video card capable of at least one of the following video modes:

             640 x 480 x 256 colors (8-bit mode)
             800 x 600 x 256 colors (8-bit mode)
            1024 x 768 x 256 colors (8-bit mode)

       The card must be VESA-compliant, either by itself, or by using a
       driver, like the Display Doctor by Scitech.

       Almost all the video cards on the market today meet these
       requirements (what?!? Are you still using an HGC card ?!?).
       HAMVIEW supports all three resolutions, but, of course,
       the best quality is achieved when working at 1024 x 768.


GETTING STARTED
---------------

Unpack the HAMVIEW.ZIP file to a directory of your choice on your hard disk.

Connect the input audio to the line-input jack of the sound card. Don't use
the microphone input, HAMVIEW disables it to prevent stray ambient noise
pick-ups. If you want to hear the filtered audio you need of course at least
one speaker connected to the sound card output (left or right it doesn't matter,
the same signal is routed to both channels).

Make sure that you have an environment variable BLASTER, set as follows:

  BLASTER=Annn Ix Dy Hz  (other values can follow)

where:    Annn is the I/O port address (usually A220 or A240)
          Ix   is the IRQ used by the sound card (usually I5 or I7)
          Dy   is the low DMA channel (usually D0 or D1)
          Hz   is the High DMA channel (can only be H5 or H6 or H7)

  other values can be present (e.g. T6 E620 P330). They are not needed nor
  used by Hamview.


To invoke HAMVIEW use the following syntax from the DOS command line:

                HAMVIEW [filename] [-v0 | -v1 | -v2] [-m | -f]


 where:  filename, if present, indicates the name of the file to be used
         for the playback mode. If absent, real-time mode is assumed.

         -v0 sets the resolution at  640 x 480 x 256
         -v1 sets the resolution at  800 x 600 x 256
         -v2 sets the resolution at 1024 x 768 x 256 (this is the default)

         -m  sets the speed to medium
         -f  sets the speed to fast   (more on this later)
         if this parameter is omitted, it defaults to normal.

The program searches the current directory for a file named HAMVIEW.INI which is
used to set the station coordinates, in order to have a correct display of the
moon azimuth and elevation (this program is especially targeted to EME users).
If the file is not present, a default one is generated, with the station
coordinates of I2PHD. If you need to have the moon data displayed correctly,
you can change it with a standard text editor. The format is self-explanatory.

Upon starting, you will be presented with the program main (and only) screen.
The vertical axis is the frequency scale. The program's range is from 20 Hz
to 4094 Hz in normal mode, 20 - 8188 Hz in medium mode and 20 - 12282 in fast
mode.

Only a part of this range can be shown on the screen. You can
scroll up and down with the PgUp and PgDown keys. Near the bottom-left corner
there is an input level indicator. Adjust input level to keep the level in the
green part, with only occasional excursions in the red zone.
The mouse pointer (a small cross) can be moved, and the frequency corresponding
to its vertical position is displayed on the status line.

On the extreme left part of the screen a real-time spectrum-analyzer-like
display is shown, updated every half second in normal mode, 4 times a second
in medium mode, and six times a second in fast mode.

On the central part of the screen a moving bar will paint behind itself the
color corresponding to the magnitude of each frequency bin. The higher the
amplitude of the incoming signal at a given frequency, the brighter the color
of the point shown.
Each point corresponds to a bandwidth of 2, 4 or 6 Hz (depending on the speed),
and the bar moves with steps of half, one fourth or one sixth of a second,
again depending on the speed setting.
These values are the consequence of the sampling rate chosen (8192, 16384 or
24576 samples/sec), and the buffer size (two flip-flop buffers,
4096 entries each).

On the right part of the screen there are 9 mouse-selectable large buttons, used
to set or reset various functions or parameters. Their color toggles from
Red (function active) to Green (function not active) when single-clicked.

The settings are remembered fron one execution to the next, so you don't have
to reset your favorite mode.

  From the top:

  - ESTIMATOR   selectable from Blackmann/Tukey or FFT. Default Blackmann/Tukey.
                This selects which kind of spectral estimator the program must
                use. BT gives a better signal-to-noise ratio, but has the
                tendency to mask very weak signals when more than a signal is
                present. FFT is the usual Fourier Transform estimator.

  - SMOOTH      computes a moving average of the spectrum. Default OFF.
                Can be used to smooth out the noise. The integration is done
                on the nine past values.

  - SCALE       can be set to LOG or LIN. Default is LOG. Selects whether the
                mapping between magnitude and colors is linear or
                logarithmic. LOG works best with the Blackmann/Tukey estimator.
                The program has an interlock such that when you select the
                FFT estimator, the scale is also changed to LIN, if not already
                set.

  - DENOISER    selects the LMS denoiser. Default OFF. The LMS denoiser is of
                the Widrow type, and works best when the signal amplitude is
                above a given minimum level.

  - BANDPASS    selects the FIR bandpass filter. Defaults to OFF. This filter
                has very steep skirts and a flat passband. This passband is
                indicated by a red portion on the moving bar. To set the
                low cut and high cut frequencies, use the mouse. The left
                button sets the low cut, and the right one the high cut.
                This can be done only when the CW filter is not active.

  - FILTER      activates the CW filter. Its center frequency is indicated
                by a yellow spot on the moving bar. This frequency can be
                set with the left mouse button. Its value is saved by the
                program, and recalled when the program is restarted.

  - TRACK       selects the automatic tracking of both the bandpass and the
                CW filter. The filters are automatically centered on the
                strongest signal. It is suggested to disable this feature
                as soon as the desired center frequency is acquired, to
                avoid having the filters jumping back and forth, when the
                signal-to-noise ratio is very low.  Default OFF.

  - MARKER      when ON, the moving bar leaves tiny marks behind itself spaced
                100 Hz. Default OFF.

  - GAIN        sets the mapping gain between signal magnitude and color.
                Default HIGH. When receiving CW signals strong enough to
                be normally heard, as is the case on the HF bands, the
                best results can be obtained by setting the gain to LOW.

                                =================

When the program runs, the following keys are active:

  -   R         recording. Activates the recording of the incoming audio
                into the file HVddhhmm.WAV, where dd is the day, hh and mm
                are the hours and minutes when Hamview started.
                If pressed again, the recording pauses until a new pressure.
                When rerecording after a pause, the file is appended.

  -   Ctl       Passthrough mode. The incoming audio is simply rerouted to
                the output, with no processing. Very useful when tuning, as
                the processing delay of one second is suppressed when in
                passtrough mode. The activation of the passthrough mode is
                signalled on the up left corner of the screen by a prominent
                upper case P, white on red background.
                The visual (on screen) processing of the input signal is
                unaffected.

  -   Cursor UP and DOWN
                The cursor UP and DOWN keys adjust the output volume, from
                zero to the maximum. Useful when listening with headsets.

  -   PLUS and MINUS keys
                The PLUS key increases the speed from normal to medium to fast,
                while the MINUS key does the opposite. When changing speed
                the vertical axis is redrawn accordingly.

  -   Z         The Z key clears the screen.


  -   PgUp and PgDown
                The PgUp and PgDown keys move up and down the frequency range
                displayed on the screen. The scrolling amount is indicated in
                the INI file. The default is 200 Hz.


  -   ESC       terminates the program, after resetting the sound card
                mixer to the state found at program initialization.


All of the mouse-selectable buttons can also be toggled by typing the first
letter of the command itself (i.e. 'E' for Estimator, 'F' for Filter), with
the exception of Scale, which is toggled with the 'L' key.
Case is immaterial.

The status line reports the percentage of CPU used by the program. As an
example, with a 225 MHz Pentium this value ranges between 19.8 % with all
the functions off and 29.4 % with all the functions on, in normal speed.

For EME operations, a real time clock shows to the operator the two minute
periods used for trasmission exchange between east and west stations.
To properly set the clock, you must set the environmental variable "TZ",
using the DOS command:

SET TZ=<string>

This string is composed of:

- three characters denoting the name of the time zone (i.e. GMT, CET, PST,
  and so on),
- a number showing the difference between GMT and local time
- an optional string denoting that daylight saving time is currently used.

Here is an example for Italy, where local time is GMT-1

SET TZ=CET-1

and if we are in daylight saving time this becomes

SET TZ=CET-1DST

Remember: the only important parts of the variable are the number giving the
difference between GMT and local time and the daylight-saving-time indicator!

Every two minutes you will notice that the clock background changes, and a
letter "E" or "W" close to the clock reminds to the operator which period
("east" or "west") is current. At the base of the spectrum display the
same color is used to trace a thin line, to ease the identification
of the stations.


Any remarks, suggestions, praises, complaints, whatever you may have on this
program are welcome. Please feel free to contact the authors at the email
addresses below.


DISCLAIMERS
-----------

Here they are.


The authors will not be liable for any direct, indirect, consequential or
incidental damages to other pieces of software, equipment, goods,
or persons, arising from the use of this software.

The authors are not liable for any possible illegal use of this software,
and for any other act arising from the results obtained from the software.

Although the use of the software HAMVIEW is free for the purposes
described in the present document, it is *not* a public domain software.
The authors retain the full copyright on the software binaries, the source
code, and the user interface.


HAMVIEW is a Copyrighted property of:

Alberto di Bene, I2PHD      dibene@usa.net
via Albignano 28
I-24040 Casirate d'Adda (BG)
Italy

Vittorio De Tomasi, IK2CZL  ik2czl@amsat.org
Via Melzi d'Eril 10
I-20154 Milano
Italy

(c) 1998

The use of this software is free for hobby and research purposes.
If used for commercial or industrial purposes, you must obtain a licence
agreement from the authors.

The program can be freely distributed, provided that you don't charge
money for this, except for the cost of the transfer media, and that
this text document is distributed as well.

The commercial distribution of the software without the permission of the
authors is strictly forbidden.

Thanks to Ethan Brodsky for his full duplex Sound Blaster routine.

                      ============================
