ft991/ft991utility/Readme
ff1ca398
 Module: ft991utility.py
 
 Introduction
 ------------
 The ft991 utility is an interactive tool for backing up and restoring both
 the memory settings and menu settings of the Yaesu FT991 transceiver.
 Individual memory locations store information about frequency, repeater
 offset, signaling, tags, modulation, and clarifier.  Menu settings store
 configuration information about current menu options and parameters.  The
 utility also has a pass through mode for sending CAT commands directly to
 the transceiver.  This feature is useful for future code development and
 debugging.
 
 The ft991.py module encapsulates the FT991 CAT commands and handles low
 level serial communication to and from the FT991 usb port.  CAT commands
 are encapsulated according to object oriented methodology, that is, 'set'
 to send parameters and settings to the FT991, and 'get' to receive status
 information back from the FT991. Additionally ft991.py contains helper
 functions for parsing data read from backup files. The 'set' functions
 also handle formatting of CAT commands and their associated parameters,
 while 'get' functions handle parsing of data returned from CAT commands
 that return status information.
 
616f4281
 Email bug reports and comments to: ka7jlo@gmail.com
75d24721
 
ff1ca398
 Notes
 -----
 1. The files ft991utility.py and ft991.py should be downloaded from the
75d24721
    github repository and placed in the same folder.
e4975c9b
 2. *IMPORTANT* Before running the utility you may need to edit line 39 or
    line 40 in the "environment setup" section of the file "ft991utility.py".
    Be sure the com port is correct.  This will depend on whether you are
    running Linux or Windows and on the default serial port assigned to the FT991.
 3. *IMPORTANT*  Edit line 41 to match the baud rate setting in your FT991.  From
    the FT991 front panel select "Menu" and scroll to item #031 "CAT RATE".
    The baud rate should be the same as line 41.
 4. To run the utility, open a terminal session in directory containing
ff1ca398
    the ft991utility.py and ft991.py files.  Then simply type the utility
    file name after the command line prompt, e.g.,
        ~$ ./ft991utility.py
    If necessary, change the permissions on ft991utility.py to allow the file
616f4281
    to be run as an executable.  To change the permissions on Linux run the
    command
        ~$ chmod +x ft991utility.py
e4975c9b
 5. Windows users will need to have the python 3.8 framework installed.
ff1ca398
    Probably, the easiest way to get the framework is to install the
    Windows Subsystem for Linux Ubuntu platform.  Note that the utility
616f4281
    has not been tested on Windows and the developer makes no guarantees.
e4975c9b
 6. While it is possible to run the utility completely from the command
616f4281
    line using command line options, beginning users are encouraged to use
    the interactive mode.  To use the interactive mode simply type the file
ff1ca398
    name of the utility with no command line arguments, e.g.,
            ./ft991utility.py
e4975c9b
 7. The utility saves memory settings in a comma-delimited file that
75d24721
    can be imported into a spreadsheet application for ease in viewing
616f4281
    and editing.
e4975c9b
 8. The verbose mode, available both as a command line option and in
ff1ca398
    interactive mode, echos raw commands sent to the FT991, as well as
    raw status returned by the FT991.  This feature is useful for development
    and debugging purposes.
e4975c9b
 9. If you already have repeater frequencies and such programmed
ff1ca398
    in memory, you should first run the 'bm' command in interactive mode
    to back up your current memory settings.  Unless you change the default
    file name, this file should appear in your current working directory as
    'ft991mem.csv'.  Change this file name to something else such as
75d24721
    'ft991mem_todaysDate.csv so that you can restore from this file at a
ff1ca398
    later date if necessary.
e4975c9b
 10. By the same token you should immediately back up your menu settings using
     the 'bu' command in interactive mode.  The default file name is
     'ft991menu.cfg'.  Likewise change this file name to something else.
 11. The example file 'example.csv' shows how a memory settings file should
616f4281
     appear.  To load these settings in your FT991, run the 'rm' command in
     interactive mode.  When prompted to enter a file name type 'example.csv'. 
     For example,
         Enter file name or <CR> for default: example.csv
e4975c9b
 12. Backup and restore of VHF/UHF split frequency repeater settings is not
616f4281
     supported by the FT991.
e4975c9b
 13. Please do not edit the menu settings file unless you absolutely know
ff1ca398
     what you are doing.  There should rarely be a need to edit this file.
     Menu changes should be made on the FT991, itself, and then backed up.