EasyPal Full Guide - updated 7/20/07

EasyPal Full is the work of Erik VK4AES.  Do not bother him with emails
about the program.  If you need help, someone on the DIGSSTV newsgroup
may be able to help you.  Be sure to include the version number in any
report of a problem.  Also keep up to date and use the latest version.

This software uses the DRM (Digital Radio Mondiale) encoding to allow
the sending of image files over an HF voice channel.  This is known as
Digital SSTV.

The GUI was written with Delphi and compiled on a Windows Vista system.
It works best when run on a two GHz or faster CPU with Windows Vista.
Although less stable, it should run on most fast PC's with Windows XP.
Keep in mind that it is still in beta testing.

The download is a 2.7 MB ZIP file that contains only one file:
"EasyPal_Full.exe".  This file should be placed into it's own
folder and a shortcut to it should be put on the desktop.

Links for downloading the latest version are available at this URL:
http://kb4yz.ham.org

Help from other users is available from the Yahoo Groups newsgroup
"DIGSSTV":
http://groups.yahoo.com/group/digsstv

=============================== Setup ===================================

Setup:  Initial Setup - Enter/change Callsign, Soundcard, and CommPort.
                        Click the "OK" or "Apply" button to update/exit.

                        The setup for CommPort includes options for
                        "FAC Green".  Using an external circuit this
                        option could be used to mute the speaker while
                        receiving the digital signal.

                        It is recommended that you close the program
                        and re-start after setting up or making changes
                        to the soundcard settings.

RX Input -
     Allows quick access to Recording Control.
     Select the input where the received audio comes into the soundcard.

TX Volume -
     Allows quick access to Master Volume for soundcard.
     All inputs should be Muted except for the Master Volume and Wave.
                         
     RX Input and TX Volume are not shown when running under Vista.

BSR Mode Automatic (recommended) -
     Will automatically switch the DRM transmit mode required by the BSR.

BSR Mode User Select (advanced)
     Allows the user to force the DRM transmit mode to a mode other than
     that requested by the BSR.

Expanded GUI -
     EasyPal Full runs in a window that is 925x570.
     The user may optionally select the "Expanded GUI" which will
     resize the window to fill out the available space on screen.
     Generally, this will be a 4x3 aspect ratio but the actual
     number of pixels would be determined by the screen resolution.

W/Fall Color -
     Allows the user to select the color of the waterfall.
     Using "negative" will display black on white line drawings more
     effectively provided that the image is made negative prior to
     being sent. When the received is viewed in the "negative"
     waterfall, it will appear with the proper contrast.

Very Light Encode -
     Selects the Encode1 level of RS encoding - ".rs1" file extension.
     Transmission time will be increased by 13%.
     At least 89% of the segments transmitted must be received.

Light Encode -
     Selects the Encode2 level of RS encoding - ".rs2" file extension.
     Transmission time will be increased by 31%.
     At least 76% of the segments transmitted must be received.

Medium Encode -
     Selects the Encode3 level of RS encoding - ".rs3" file extension.
     Transmission time will be increased by 54%.
     At least 64% of the segments transmitted must be received.

Heavy Encode -
     Selects the Encode4 level of RS encoding - ".rs4" file extension.
     Transmission time will be increased by 86%.
     At least 51% of the segments transmitted must be received.

     Encoded files will have interleaved redundancy using Reed-Solomon
     error correction.  The encoded file with redundant data is
     sent so that the original file may be created even though not all
     segments were received.

     There is no progressive receive in this mode.  The received file
     will decode after a sufficient number of segments are copied and
     the image will appear as soon as the decoding is finished.  This
     may happen even before the transmission is complete.  Receiving
     RS encoded files is automatic - no need to select for receive.

     Use of Encode may reduce the need for BSR's and FIX'es.
     Compatable only with others running EasyPal.
     A stand alone decode program is available that will allow those
     not using EasyPal to decode the .rs files manually.  See:
     http://www.tima.com/~djones/rsdecoder.htm

Default (resolution) -
     Will resize down a large image to fit within 640 x 480 pixels.
     Small images that are PASTED will be resized larger to fit
     within 640 x 480 pixels.

HiRES (Downsize if > 1280*1024) -
     Will resize down a large image to fit within 1280 x 1024 pixels.
     Small images that are PASTED will be resized larger to fit
     within 1280 x 1024 pixels.

HiRES (Best)
     Will not resize image.
     This is the best setting to use when an external program such as
     "sstvPics" is used to resize the image prior to pasting into
     EasyPal.

     The HiRES setting will not affect the image when "LoadAny" is used.

Show RX Screen -
     Selects the RX tab to view the RX Screen and RX information line.
   Gamma -
     Allows for the adjustment of the brightness of the received image.
   RX Filename -
     The filename of the received image.  Note this when selecting
     the proper file to select for the "Send Selected Request" BSR.

     Click on image to display full screen.
     Animated GIF files will not be displayed full screen.

Show TX Screen -
     Selects the TX tab to view the TX Screen and TX information line.
   Secs -
     This is the number of seconds it would take to transmit this image.
   K -
     This is the file size for the image to transmit.  Does not apply
     to images loaded using LoadAny.
   Slider -
     The setting of this slider changes the level of the JPEG-2000
     compression that determines the file size.
   SET -
     If the slider has changed position after the image has been loaded,
     it will be necessary to click the SET button so that the JPEG-2000
     compression can be reapplied.
   TX Filename -
     The name of the file to be transmitted.  The filename will change
     when the transmission starts.

TX mode = RX mode -
     This provides a way to quickly change the TX mode to match the
     DRM mode just received.

Define Additional Save Directory -
     Received files will be saved into a user selected folder in addition
     to being saved in the "Autosave" folder.
     (Not working)

=============================== Action ===================================

Action:

Send Text -
     Turns the TX window into a text editor for the sending of text.
     Text may be typed, pasted, and edited prior to transmitting.

Session Log -
     Logs the calls and time for current session only.

QuickTxMode -
     This screen serves as a quick reminder for what DRM modes are
     suitable for different conditions.

USE Repeater -
     Show Repeater Commands - Check to enable "Repeater" menu.

============================== Repeater =================================

Show Last Received Repeater Directory -
     Displays the "Repeater Directory" window.
     The filenames and file sizes are listed.
     Select a file by clicking the filename, then use the "Replay Selected File"
     or "Delete Selected File" button.  The repeater command will then be sent.

File is saved to external "\Repeater\" (retick each time) -
     Allows the sending of a file to be saved to the "Repeater" folder on a
     remote repeater.  The "USER Info" allows you to enter a callsign for a
     recipient.  Click "OK" to send loaded file to remote repeater.
     Either sender or recipient may delete this file from the remote repeater.

Start WebCam -
     Activates the webcam.
     All FTP Settings should be unchecked.  "Run should be checked.

     Clicking any of the repeater access options from the "Repeater"
     menu will immediately start transmitting that command to
     any active HamPAL or EasyPal repeater on frequency.

     The DRM mode used to send a repeater command will also be the DRM mode used
     by the remote repeater to send any digital file.

Interrogate Repeater -
     Sends the file "a.r##.
     Repeater sends out the "reply.wav" file.
     Default is "REPEATER".
     If the "reply.wav" file in not in the correct folder,
     the repeater will not respond.
     A repeater that has been shutdown can still respond.

Replay last received File -
     Sends the file "b.r#".
     Repeater sends out the "replay.wav" file.
     Default is "REPLAY".
     Repeater replays the last received file.

View Repeater Directory -
     Sends the file "f.r##.
     Repeater sends out the "dir.wav" file.  Default is "DIRECTORY".
     Repeater sends an .rs2 encoded file providing a list of files
     found in the "Repeater" folder.  When this file is received,
     The "REPEATER DIRECTORY" window will appear.  If you wish to
     view later, use "Show Last Received Repeater Directory".
     After files have been added or deleted from the "Repeater"
     folder on the remote repeater, the order of filenames will
     be changed.  For this reason, the "View Repeater Directory"
     command should be sent again to get the updated listing prior
     to sending any "Selected File" command.

Repeat Text in Repeater Waterfall -
     You are prompted to enter a text message.
     The file "k.r" is sent.
     The content of this file is the text message.
     The Repeater responds with the text message in the Waterfall.

Request WebCam Picture -
     Sends the file "i.r##".
     Repeater sends out the "webcam.wav" file.
     Default is "WEBCAM".
     Repeater sends the current webcam picture if available.
     Note that the file is standard JPEG: "070710041023-WebCamImage.jpg".

Request Repeater resend BSR Request -
     Sends the file "c.r##".
     Repeater sends out the "filefail.wav" file.
     Default is "BSR de RPTR".
     Repeater sends the BSR.

Shutdown ALL Repeaters -
     Shutdown all repeaters within range.
     Sends the file "d.r".
     Repeater sends out the "paused.wav" file.
     Default is "STOPPED".

Restart ALL Repeaters -
     Restarts all repeaters within range.
     Sends the file "e.r".
     Repeater sends out the "restart.wav" file.
     Default is "RESTARTED".

Shutdown Specific Repeater -
     Shutdown specific repeater of user selected callsign.
     Sends the file "l.rCALL".  (lower case "L")
     "CALL" repeater sends out the "paused.wav" file.
     Default is "STOPPED".

Restart Specific Repeater -
     Restarts specific repeater of user selected callsign.
     Sends the file "m.rCALL".
     "CALL" repeater sends out the "restart.wav" file.
     Default is "RESTARTED".

Activate Repeater Beacon -
     Repeater sends out the "beacon.wav" file.  Default is "BEACON".
     Not available on distribution versions.

Activate as Base Repeater -
     Manually activates repeater mode.
     Not available on distribution versions.

Repeater BSR
     An active repeater will automatically send BSR's if needed.
     Repeater sends out the "filefail.wav" file.
     Default is "BSR de RPTR".
     Repeater sends the BSR.

Repeater Acknowledgment
     An active repeater will automatically send an acknowledgment
     when it successfully receives a file.
     Repeater sends out the "fileok.wav" file.
     Default is "FILE OK".

Repeater FIX

     An active repeater will automatically send a FIX in responce
     to an BSR when it has a FIX available.
     Repeater sends out the "repfix.wav" file.
     Default is "FIX de RPTR".
     Repeater sends the FIX.
     A repeater is able to FIX a file if it first received the file OK
     and the BSR used was a "Send Selected Request" for this file.
     A repeater is able to FIX a file that it has just replayed using
     any type of BSR.

Other Repeater wave files:

     Repeater sends out the "toobig.wav" file.
     Default is "REFUSED TX > 10mins".

     Repeater sends out the "timeout.wav" file.
     Default is "10min TIME OUT".

Delete selected user file -
     Deletes user selected file from directory if authorized.
     Sends the file "h.r#".  (#=number of file)
     Repeater sends out the "deleted.wav" file.
     Default is "DELETED".
     The repeater could also respond with the "notexist.wav" file.
     Default is "NOT EXIST".
     The repeater could also respond with the "notdel.wav" file.
     Default is "REFUSED".

Request Webcam Picture from ??? Repeater - (not available)
     User specifies the CALL for the repeater to send the webcam image.
     Sends the file "j.rCALL".
     Repeater sends out the "webcam.wav" file.
     Default is "WEBCAM".
     Repeater sends the current webcam picture if available.
     Note that the file is standard JPEG: "070710041023-WebCamImage.jpg".

Send Back Specified File  -
     Replays user selected file from the directory.
     Sends the file "g.r#".   (#=number of file)
     Repeater sends out the "selected.wav" file.
     Default is "SELECTED".
     Repeater sends out the specified file.

============================== LoadPic ==================================

LoadPic:
     Brings up Window for selecting an image file to load, resize,
     and convert into JPEG-2000 (JP2) format.  When transmitted,
     the filename is changed to "############-originalfilename.JP2".
     The "############" is a 12 digit number representing the
     current year/month/day/hour/minute/seconds.

=============================== LoadAny =================================

LoadAny:
     Allows for the loading of most any file type to be transmitted.
     The file will be renamed but will keep the original extension.
     This is useful when sending animated GIF files where
     conversion to JPEG-2000 is not desired.

=============================== Copy ===================================

Copy:
     Standard image copy to clipboard from the RX or TX screen.

=============================== Paste ===================================

Paste:
     Standard image paste from clipboard to the RX or TX screen.
     Paste to the TX screen will compress and convert the image
     to JPEG-2000 format.  The image may be resized based on the
     setting for HiRES.

=============================== FIX ===================================

FIX:
     Brings up Last FIX Request.  Use when the receiving station
     requires the same FIX sent again.

     After receiving a BSR, you will have a message on the title bar:

     it may be a message like this:
     "-W9VMT-Requests-63/92 segments for-070707122834-cat1.jp2"
     Just click "FIX NOW" to send the FIX.

     or it may be a message like this:
     "You can repair 63/92 segments in 070707122834-cat1.jp2 for W9VMT"
     Just click "FIX NOW" to send the FIX.

     or it may be a message like this:
     "This BSR is not for you"
     You do not have this file.
     This BSR request is for another station.
     In this case, you will have to get the file repaired
     before you will be able to send any fixes.

     or it may be a message like this:
     'You do not have this file for "K9NP ERIC" to Repair'
     You do not have this file.
     This BSR request is for another station.
     In this case, you will have to get the file repaired
     before you will be able to send any fixes.

     If there is no message in the title bar and you think that
     you received the BSR request OK, and you should be able to
     send the FIX, go ahead and send the FIX anyway.  It may work!

     The FIX sends "FIX" in the waterfall before the data.

     Any station running EasyPal that successfully receives an image,
     can send the fix for any other station that sends an BSR for that
     same image from EasyPal.  (The original image may be sent from any
     program using a compatable DRM mode.)  If the original image was
     transmitted with a filename that had spaces within the filename,
     it may require the original sender to do the FIX.

     There is no need to reload an image to fix someone.

     The "Last FIX Request" includes the Call from the station that
     sent the BSR, mode, segments, and filename.  If the mode details
     are in any way different from the mode the file was sent, then the
     FIX will not work.  Ask for an "Old Type" BSR instead.

=============================== WAV ===================================

WAV:
     Brings up the "Play Wave File" list.  Selecting a WAV file
     and clicking "TX Now" will immediatelly play the audio from this
     WAV file.  Create the wav files using "WFPic",
     "WFTxt" or an external program such as HamPAL or DIGTRX.

     These special wave files must be in the main EasyPal folder:
     BEACON.wav - repeater sends at preset intervals when "Beacon" is checked.
     BEGIN.wav - sent before each DRM file transmission.
     BSR.wav - sent before each user initiated BSR transmission.
     DELETED.wav - repeater sends this when selected file is deleted.
     DIR.wav - repeater sends before the RS Encoded file (repeaterdir.txt.rs2)
               in responce to "View Repeater Directory".
     FILEFAIL.wav - repeater sends before the BSR.
     FILEOK.wav - repeater sends when it successfully receives a file.
     FIX.wav - sent before each FIX transmission.
     NOTDEL.wav - repeater sends this when selected file is not allowed to be deleted.
     NOTEXIST.wav - repeater sends this when selected file is not available for deletion.
     PAUSED.wav - repeater sends in responce to "Shutdown ALL/Specific Repeater".
     REPFIX.wav - repeater sends before the FIX transmission.
     REPLAY.wav - sent before repeater sends out the last received file.
     REPLY.wav - repeater sends in responce to "Interrogate Repeater".
     RESTART.wav - repeater sends in responce to "Restart ALL Repeaters".
     SELECTED.wav - repeater sends in responce to "Send Back Specified File".
     TIMEOUT.wav - repeater sends this when selected file is too large to send.
     TOOBIG.wav - repeater sends this when selected file is too large to send.
     WEBCAM.wav - repeater sends before the current webcam picture.

=============================== WFPic ===================================

WFPic: (Waterfall picture)
     Transforms the image on screen into a grey scale image that
     becomes analog encoded audio to produce a like image in the
     waterfall.

=============================== WFTxt ===================================

WFTxt: (Waterfall text)
     Transforms a user provided text message with the choice of
     various sizes and fonts into analog encoded audio to produce
     the text as an image in the waterfall.

     To make a waterfall ID click "WFTxt".  Type your call into the
     Waterfall Text window using all caps.  You may want to add a space
     between each character.  Select a plain bold font to make it
     easier to read when displayed in the waterfall.  Click Save and
     use your call as the filename.  To send this, click WAV and
     select the file, then click "Tx Now".

=============================== Clear ===================================

Clear:
     Clears the selected (RX/TX) screen.

=============================== About ===================================

About:
     Credits.

=============================== Info Area ===============================

Callsign -
     The callsign of a transmitting station will appear in the upper
     left corner while receiving an DRM transmission.

RX audio level bar graph.
     (Higher incoming audio produces more green.)

% -
     RX signal quality level bar graph - equivalent to
     SNR (Signal to Noise Ratio).  There will be more green area with
     increased signal quality.

TX -
     DRM submode selected for transmit.
     Right click mode parameter to toggle through settings.
     Any changes to the mode are saved for future sessions
     when the program is closed.

     Default DRM Mode should be Mode B, Width
     2.5 khz, Error HI, QAM 16, and LeadIn 24.
     Interleave is always Long and cannot be changed.
     These settings are the best choices for general use
     on the HF bands.

     LeadIn 12 will reduce transmit time by reducing
     the number of redundant segments.  For very short
     transmissions such as Text messages, LeadIn 12
     may be too short a time for all stations to
     achieve MSC sync before the transmission is
     finished.  In this case, select LeadIn 24.

RX -
     DRM submode received.
     FAC must be green before the mode can be detected and the
     callsign decoded.  In addition to those mode settings that
     may be changed on transmit, the RX will also reveal the
     interleave setting.  Lng for long and Sht for short.  The
     receive mode settings are automatic and do not require the
     operator to make any changes for receiving any DRM mode.

RX mode display: (red/green bars)
     MSC - Green light indicates MSC (Main Service Channel) lock.
     FAC - Green light indicates FAC (Fast Access Channel) lock.
     Frame - Green light indicates Frame Sync.
     Time  - Green light indicates Time Sync.
     IO - Green light indicates Soundcard is active.

     Data cannot be decoded until the MSC has a lock.  So the MSC
     must be green before you will be able to copy anything.

Total -
     "Total" is the number of segments in the image file being received.

OK Segs -
     "OK Segs" is the number of segments successfully decoded so far.

Position -
     "Position" is the segment number that was last decoded.

not processed -
     This is the number of segments that still need to be received.

Transmit progress bar indicates the % transmitted.
(Visable only during transmit).

=============================== Buttons ===================================

TRANSMIT -
     Starts the transmission of the file.

Tune -
     Immediatelly sends the three tone tuning tone for 7 seconds.
     Green markers in waterfall should match the "Tune" signal
     or pilot carriers.

Replay RX -
     Replays last received image file.  It may be renamed but it
     will have the exact same content.

ABORT -
     Allows for stopping a picture, WAV, BSR, or FIX transmission.

Encode -
     Left click to toggle RS encoding for transmitted files.
     Right click to toggle through the four levels of encoding.

ProgRX - Progressive RX
     Check to enable viewing image as it is coming in.
     Using Progressive RX may slow other processes
     such as the waterfall display.

BSR Requests -
     Brings up the BSR Requests window.
     For those transmissions that have a partial file stored,
     there will be a file name listed.  The sender's call is
     listed first.  Click a file name from the list to display
     a partial image (if available) and other information.
     There may be more than one file for the same image.
     If this is the case, you should select the one that has
     the fewest number of missing segments.  Selecting the
     file first is only necessary when using the
     "Send Selected Request".

"Send Selected Request" -
     CAUTION - TRANSMITTING THIS TYPE OF BSR MAY LOCKUP
     NON-COMPATABLE SYSTEMS.  (DIGTRX and HamPal)
     This type of BSR is available even after EasyPal has been
     closed and restarted.  Use when you require a third party
     FIX from another station running EasyPal.  You must select
     the file from the list to be fixed before clicking the
     "Send Selected Request" button.

"Old Type BSR (compatable all)"
     Use this type BSR when requesting segments from non-compatable
     systems.  Only the original sender or one that replayed the
     file will be able to fix you with this type of BSR.

"Old Type Fast BSR (not compatable)"
     This is the normal type of BSR to use when requesting segments
     from the original sender that is also running EasyPal.
     This type of BSR is a bit different from the BSR format used
     in the past.  It is called a "Fast BSR" because it uses a form of
     shorthand to indicate contiguous segments.  This new "Fast BSR"
     will send faster because the text file listing the missing
     segments is smaller.  One drawback to the use of the new
     "Fast BSR" is that older programs such as HamPal may not
     recognize all the segments required and if there are many,
     HamPal may only be able to send fixes for two or three
     segments at a time.  This is only a problem when pictures are
     sent from HamPal to EasyPal.

     "Old Type" BSR's do NOT require that you select the filename.

     "Old Type" BSR may not be available.  You will get the message,
     "nothing to fix".  This is most likely the case where you have
     received a BSR from another station but not copied any of the FIX.
     In this case, have the original station send part of the file
     and abort.  The "Old Type" BSR should now be available.

"Bad Segment Report"
     Each type of BSR starts the transmission of a short text file
     that lists the segment numbers that were missing on the last
     received file (or selected file).
     During this transmission, many instances will be sent to ensure
     that the information gets through.  When many segments are
     required, the transmission time for the BSR may be much longer.

=============================== TABS ===================================

RX tab -
     Click to view RX screen and RX information line.

TX tab -
     Click to view TX screen and TX information line.

View tab -
     Click to view thumbnails of Last RX Pictures.
     Click to view thumbnails of Last TX Pictures.

Send to TX -
     This allows for a replay of the thumbnail image.
     Transfers selected thumbnail to TX window.  JPEG-2000
     compression is applied and filename is changed when
     transmitted.  Quality is reduced each time this type
     of replay is used.

Full Screen -
     Displays selected thumbnail to full screen.
     Image displayed will always be the original size.
     The image is displayed againgt a black background.
     Animated GIF files might not be displayed.
     To return to the program screen, click the mouse
     or hit the "Esc" key.

Delete to Recycle Bin -
     Selected thumbnail will be deleted.
     Since not all selected thumbnails will actually be
     deleted, it may be necessary to open the "RxFiles"
     or the "TxFiles" folder to manually delete these
     files.  Selecting the very last thumbnail to
     delete for the second time may actually delete the
     first.

Send to Repeater Directory - ("USE Repeater" checked)
     Transfers selected thumbnail to "Repeater" folder.
     Additional JPEG-2000 compression is applied based on
     setting of slider on the TX window.  If "Encode" is
     checked, then this level of RS Encoding will be
     applied and the filename extension will be changed
     to the one for that level of RS Encoding.  Quality
     may be reduced for this type of conversion.

     Thumbnails are standard JPEG (.jpg) images that are
     re-compressed copies of the files received and sent.
     Image files in the "LastRX" folder may not have the
     quality and characteristics as the original files sent.

     The original files received are stored in the
     "Autosave" folder.  These files should be identical to
     the quality and characteristics of the original files sent.

=============================== NOTES ===================================

The waterfall may be paused - just left click to pause/restart.

When EasyPal is closed, the contents of the "Transient" folder is deleted.
Temp files in other folders are also deleted.

Partially received files (ones with missing segments) will be saved
into the "Corrupt" folder.  They are stored here until they are repaired
or manually deleted by the user.

Hints will appear after mouse pointer is placed over selected buttons
and areas.

=============================== Updates ===================================

The latest version of this file is available here:
http://www.tima.com/~djones/easypalfull.txt

Please notify Dave - KB4YZ of updates and corrections:  djones@tima.