tk5 0.6-6.2 / usr / share / tk5 / README

                           tk5

             Copyright 2001 - 2004, Bob Parnass
                      2350 Douglas Rd
                 Oswego, IL 60543-9794 USA
                      http://parnass.org

tk5 is open source software designed for the ICOM IC-R5
receiver.

I implemented tk5 in the Tcl/Tk scripting language which
enables it to run on a variety of operating systems,
including Linux, MacOS X, BSD, Solaris, Unix, Microsoft
Windows (95 and later), etc.

The free Tcl/Tk interpreter software, version 8.4 or later,
must be installed on your computer prior to using tk5.

If you are running Windows, upgrading your Tcl/Tk software
from an earlier version, and using my other tk radio programs,
you may have to update them to use the new Tcl/Tk version.
The update is a simple one line change to a .bat file.

If you use tk3, for example, look at the C:\tk3\tk3.bat file.
Change the last line of that file from:
"C:\tcl\bin\wish83.exe"  "C:\tk3\tk3.tcl" 
to
"C:\tcl\bin\wish.exe"  "C:\tk3\tk3.tcl"
 

tk5 and Tcl/Tk installation instructions may be found on the web at
http://parnass.org

Please become familiar with the IC-R5 and ICOM's instruction
manual before using tk5.

                          Notes


The Linux version of tk5 presumes the wish windowing shell
is in your PATH.



                          License

tk5 is neither shareware nor in the public domain.  It is
a copyrighted work; you can redistribute it and/or modify it
under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

tk5 is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
the GNU General Public License for more details.

You should have received a file named "COPYING" which
contains a copy of the GNU General Public License along with
tk5; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307  USA


			Acknowledgments

Some of the Tcl/Tk procedures used in tk5 were devised by
other authors and their contributions are marked accordingly
within the source code.


                     Bob Parnass, AJ9S
                        May 25, 2003



USAGE NOTES

Obtain the proper TTL-to-RS232 level shifter adapter for mating the
computer to the receiver.  Do not use a direct connect
cable.  I use the RT Systems (http://rtsars.com) CT-29A and
the Purple Computing PL35S adapters.

In general, it's a good idea to connect the computer and radio
while the power to both is off.  It's inconvenient to turn the PC
off and on just to disconnect the radio so I use a serial port
switch box which connects my PC's serial port to one of four
devices and merely switch the radio in and out of the line.

If you are running Windows, you must reboot your PC
after downloading and installing the software on your computer,

When you first start the program, you will asked to identify
which serial port is connected to the radio. (If you ever
relocate the radio to a different serial port,
you should remove the tk5.ini file and restart tk5.
tk5 will recreate the tk5.ini file for you).

Once you've identified the proper serial port,
tk5 will open a couple of windows and display what
looks like a few forms.

I have received reports that tk5 works with the USA, Japanese, and
European version radios.

Important: Before trying to reprogram your radio, you should first
read the image from your radio using the
Radio --> Read from radio...
menus and save it in a file using the
File --> Save As...
menus.  You can name is something like "original.tr5".
Back up this file.

You can view memory channel settings in a scrolled window.
This version of tk5 permits you to view, but not change,
the memory settings. You can edit the memory channel data
outside tk5 by exporting the data to a .csv file.

Once data has been read from the radio,
you can then export the memory channel information to
a .csv file, using the File --> Export memory channels menu.
Exit tk5.

You can use a text editor or spreadsheet
program to change or pretty-print the data in the .csv file.
Just be sure to write the data out in .csv format again.

You can restart tk5 and read the memory image file
(original.tr5 or whatever you named it) you created earlier,
using the File --> Open menus.

You can then view and change any of the settings.
If you have changed any of the memory channel data
in the .csv file, import it into tk5 using the
File --> Import memory channels menu.

You can check for errors in the data by using the
Data --> Validate menu.

If there are no errors, you should write the information
to a new image file (file name ends in .tr5) using the
File --> Save As menu.

You can now program your radio using the
Radio --> Write to radio menu.

Note:  You cannot both read from and write to the radio
during the same tk5 session.



IMPORTING A FREQUENCY LIST FROM A .CSV FILE

Start the program.

Read in an image file (.tr5 extension) using

File -> Open

Import the memory channel information from
your .csv file using:

File -->  Import Memory Channels


Save the updated image in a new .tr5 file using
File --> Save As ...

Write the new image to the radio using

Radio --> Write to radio

After the cloning is complete, you should power off the IC-R5.

OTHER NOTES

Before writing a memory image to the radio, tk5 validates
the data, encodes the image, then writes the data. 
You can validate the data and encode the image without
writing to the radio using the Data pulldown menu, though
that's unnecessary and useful chiefly for debugging tk5.

All memory channel labels will be cleared when reading a memory
image from the radio.

Due to a quirk in ICOM's IC-R5 firmware design, only the
lower and upper frequency fields are used when starting
a limit search. The following fields in the Limit Search banks are
not used when starting a limit search: mode, step, tone squelch,
CTCSS, duplex, skip.

Instead, the IC-R5 uses the settings from the relevant bandstacking
register (VFO).  A popular workaround is to recall a Search Limit bank
to the VFO before starting a search.  That operation copies all
the Limit Search settings to the bandstacking register.

You may store non-television frequencies in the TV channels,
but they will be coerced to the nearest 5 kHz step.
I have not found a way to force the IC-R5 to employ NFM mode
for TV channels, only WFM or AM.