new file mode 100755

@@ -0,0 +1,442 @@

+#!/usr/bin/python -u

+# The -u option turns off block buffering of python output. This assures

+# that output streams to stdout when output happens.

+#

+# Module: ft991.py

+#

+# Description:  This module contains tables for translating common transceiver

+#               settings to FT991 CAT parameters.  Low level serial

+#               communication functions are also handled by this module.  In

+#               particular this module handles:

+#                   1. Instantiating a serial connection object

+#                   2. Sending character strings to the serial port

+#                   3. Reading characters from the serial port

+#                   4. Parsing and formatting of FT991 commands

+#                   5. Translating radio operating parameters to CAT

+#                      commands, i.e., CTCSS tones.  

+#

+# Copyright 2019 by Jeff Owrey, Intravisions.com

+#    This program is free software: 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 3 of the License, or

+#    (at your option) any later version.

+#

+#    This program 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 copy of the GNU General Public Licensef

+#    along with this program.  If not, see http://www.gnu.org/license.

+#

+# Revision History

+#   * v10 24 Nov 2019 by J L Owrey; first release

+#

+# This script has been tested with the following

+#

+#     Python 2.7.15rc1 (default, Nov 12 2018, 14:31:15) 

+#     [GCC 7.3.0] on linux2

+#2345678901234567890123456789012345678901234567890123456789012345678901234567890

+

+import sys, serial, time

+

+# General constant defines

+_INTERFACE_TIMEOUT = 0.1 # seconds

+_SERIAL_READ_TIMEOUT = 0.1 # seconds

+_SERIAL_READ_BUFFER_LENGTH = 1024 # characters

+

+# Define globals

+verbose = False

+debug = False

+ptrDevice = None

+

+# Define lookup tables for common transceiver settings.  Common settings

+# such as modulation mode, repeater offset direction, DCS/CTCSS mode,

+# CTCSS tone, and DCS code are translated to the repective FT991 parameter

+# value.

+

+# Modulation modes

+dMode = { 'LSB':'1', 'USB':'2', 'CW':'3', 'FM':'4', 'AM':'5',

+          'RTTY-LSB':'6', 'CW-R':'7', 'DATA-LSB':'8', 'RTTY-USB':'9',

+          'DATA-FM':'A', 'FM-N':'B', 'DATA-USB':'C', 'AM-N':'D',

+          'C4FM':'E' }

+

+# Repeater shift direction

+dShift = { 'OFF':'0', '+RPT':'1', '-RPT':'2' }

+

+# Power settings

+dPower = { 'LOW':5, 'MID':020, 'HIGH':50, 'MAX':100 }

+

+# Repeater signaling modes

+dEncode = { 'OFF':'0', 'ENC/DEC':'1', 'TONE ENC':'2',

+            'DCS ENC/DEC':'4', 'DCS':'3' }

+

+# CTCSS Tones

+dTones = { '67.0 Hz':'000', '69.3 Hz':'001', '71.9 Hz':'002',

+           '74.4 Hz':'003', '77.0 Hz':'004', '79.7 Hz':'005',

+           '82.5 Hz':'006', '85.4 Hz':'007', '88.5 Hz':'008',

+           '91.5 Hz':'009', '94.8 Hz':'010', '97.4 Hz':'011',

+           '100.0 Hz':'012', '103.5 Hz':'013', '107.2 Hz':'014',

+           '110.9 Hz':'015', '114.8 Hz':'016', '118.8 Hz':'017',

+           '123.0 Hz':'018', '127.3 Hz':'019', '131.8 Hz':'020',

+           '136.5 Hz':'021', '141.3 Hz':'022', '146.2 Hz':'023',

+           '151.4 Hz':'024', '156.7 Hz':'025', '159.8 Hz':'026',

+           '162.2 Hz':'027', '165.5 Hz':'028', '167.9 Hz':'029',

+           '171.3 Hz':'030', '173.8 Hz':'031', '177.3 Hz':'032',

+           '179.9 Hz':'033', '183.5 Hz':'034', '186.2 Hz':'035',

+           '189.9 Hz':'036', '192.8 Hz':'037', '196.6 Hz':'038',

+           '199.5 Hz':'039', '203.5 Hz':'040', '206.5 Hz':'041',

+           '210.7 Hz':'042', '218.1 Hz':'043', '225.7 Hz':'044',

+           '229.1 Hz':'045', '233.6 Hz':'046', '241.8 Hz':'047',

+           '250.3 Hz':'048', '254.1 Hz':'049' } 

+

+# DCS Tones

+dDcs = { '23':'000', '25':'001', '26':'002', '31':'003', '32':'004',

+         '36':'005', '43':'006', '47':'007', '51':'008', '53':'009',

+         '54':'010', '65':'011', '71':'012', '72':'013', '73':'014',

+         '74':'015', '114':'016', '115':'017', '116':'018', '122':'019',

+         '125':'020', '131':'021', '132':'022', '134':'023', '143':'024',

+         '145':'025', '152':'026', '155':'027', '156':'028', '162':'029',

+         '165':'030', '172':'031', '174':'032', '205':'033', '212':'034',

+         '223':'035', '225':'036', '226':'037', '243':'038', '244':'039',

+         '245':'040', '246':'041', '251':'042', '252':'043', '255':'044',

+         '261':'045', '263':'046', '265':'047', '266':'048', '271':'049',

+         '274':'050', '306':'051', '311':'052', '315':'053', '325':'054',

+         '331':'055', '332':'056', '343':'057', '346':'058', '351':'059',

+         '356':'060', '364':'061', '365':'062', '371':'063', '411':'064',

+         '412':'065', '413':'066', '423':'067', '431':'068', '432':'069',

+         '445':'070', '446':'071', '452':'072', '454':'073', '455':'074',

+         '462':'075', '464':'076', '465':'077', '466':'078', '503':'079',

+         '506':'080', '516':'081', '523':'082', '526':'083', '532':'084',

+         '546':'085', '565':'086', '606':'087', '612':'088', '624':'089',

+         '627':'090', '631':'091', '632':'092', '654':'093', '662':'094',

+         '664':'095', '703':'096', '712':'097', '723':'098', '731':'099',

+         '732':'100', '734':'101', '743':'102', '754':'103' }

+

+# Clarifier state

+dRxClar = { 'OFF':'0', 'ON':'1' }

+dTxClar = { 'OFF':'0', 'ON':'1' }

+

+# Define 'set' functions to encapsulate the various FT991 CAT commands.

+

+def setMemory(dMem):

+    """

+    Description: Returns a formatted MT command to the calling function.

+    Parameters: dMem - a dictionary objected with the following keys

+                       defined:

+

+                       memloc - the memory location to be written

+                       rxfreq - the receive frequency of VFO-A in MHz

+                       mode - the modulation mode

+                       encode - the tone or DCS encoding mode

+                       shift - the direction of the repeater shift

+                       tag - a label for the memory location

+

+    Returns: a string containing the formatted command

+    """

+    sCmd = 'MC%0.3d;' % int(dMem['memloc'])

+    sResult = sendCommand(sCmd)

+

+    # While the 'MW' and 'MT' commands can be used to turn the Rx

+    # and Tx clarifiers on, the clarifier states can only be turned

+    # off by sending the 'RT0' and 'XT0' commands.  This situation is

+    # probably due to a potential bug in the CAT interface.

+    sResult = sendCommand('RC;RT0;XT0;')

+

+    sCmd = 'MT%0.3d' % int(dMem['memloc'])

+    sCmd += '%d' % int(float(dMem['rxfreq']) * 1E6)

+    sCmd += '%+0.4d' % int(dMem['clarfreq'])

+    sCmd += dRxClar[dMem['rxclar']]

+    sCmd += dTxClar[dMem['txclar']]

+    sCmd += dMode[dMem['mode']]

+    sCmd += '0'

+    sCmd += dEncode[dMem['encode']]

+    sCmd += '00'

+    sCmd += dShift[dMem['shift']]

+    sCmd += '0'

+    sCmd += '%-12s' % dMem['tag']

+    sCmd += ';'

+    sResult = sendCommand(sCmd)

+    return sResult

+## end def

+

+def getMemory(memLoc):

+    """

+    Description: 

+    Parameters: 

+    Returns: 

+    """

+    dMem = {}

+

+    # Set memory location pointer in FT991.  This is done

+    # by sending the memory location select (MC) command.

+    sCmd = 'MC%0.3d;' % (memLoc)

+    sResult = sendCommand(sCmd)

+    # Skip blank memory locations, which return '?;'.

+    if sResult == '?;':

+        return None

+

+    # Send the get memory settings string to the FT991.

+    sCmd = 'MT%0.3d;' % (memLoc)

+    sResult = sendCommand(sCmd)

+

+    # Parse memory settings string returned by the FT991

+    memloc = sResult[2:5]

+    rxfreq = sResult[5:14]

+    clarfreq = sResult[14:19]

+    rxclar = sResult[19]

+    txclar = sResult[20]

+    mode = sResult[21]

+    encode = sResult[23]

+    shift = sResult[26]

+    tag = sResult[28:40]

+

+    # Store the memory settings in a dictionary object.

+    dMem['memloc'] = str(int(memloc))

+    dMem['rxfreq'] = str(float(rxfreq) / 10**6)

+    dMem['clarfreq'] = str(int(clarfreq))

+    dMem['rxclar'] = dRxClar.keys()[dRxClar.values().index(rxclar)]

+    dMem['txclar'] = dTxClar.keys()[dTxClar.values().index(txclar)]

+    dMem['mode'] = dMode.keys()[dMode.values().index(mode)]

+    dMem['encode'] = dEncode.keys()[dEncode.values().index(encode)]

+    dMem['shift'] = dShift.keys()[dShift.values().index(shift)]

+    dMem['tag'] = tag.strip()

+

+    return dMem

+## end def

+

+def getCTCSS():

+    """

+    Description: 

+    Parameters: 

+    Returns: 

+    """

+    # Get result CTCSS tone

+    sResult = sendCommand('CN00;')

+    tone = sResult[4:7]

+    return dTones.keys()[dTones.values().index(tone)]

+## end def

+

+def getDCS():

+    """

+    Description: 

+    Parameters: 

+    Returns: 

+    """

+    # Get result of CN01 command

+    sResult = sendCommand('CN01;')

+    dcs = sResult[4:7]

+    return dDcs.keys()[dDcs.values().index(dcs)]

+## end def

+

+def setCTCSS(tone):

+    """

+    Description:  returns a formatted CN command that sets the desired

+                  CTCSS tone.

+    Parameters:   tone - a string containing the CTCSS tone in Hz, e.g.,

+                         '100 Hz'

+    Returns: a string containing the formatted command

+    """

+    sCmd = 'CN00%s;' % dTones[tone]

+    return sendCommand(sCmd)

+## end def

+

+def setDCS(code):

+    """

+    Description:  returns a formatted CN command that sets the desired

+                  DCS code.

+    Parameters:   code - a string containing the DCS code, e.g., '23'

+    Returns: a string containing the formatted command

+    """

+    sCmd = 'CN01%s;' % dDcs[code]

+    return sendCommand(sCmd)

+## end def

+

+def setPower(power):

+    """

+    Description:  returns a formatted PC command that sets the desired

+                  RF transmit power level.

+    Parameters:   power - Watts, an integer between 5 and 100

+    Returns: a string containing the formatted command

+    """

+    sCmd = 'PC'

+    sCmd += '%03.d;' % power 

+    return sendCommand(sCmd)

+## end def

+

+def parseCsvData(sline):

+    """

+    Description:  stores each item in the comma delimited line in a single

+                  dictionary object using a key appropriate for that item.

+    Parameters: a string containing the comma delimited items to be parsed.

+    Returns: a dictionary object containing the parsed line.

+    """

+    dChan = {} # define an empty dictionary object

+    lchan = sline.split(',') # split the line at the commas

+    # If the first line is a header line, ignore it.

+    if not lchan[0].isdigit():

+        return None

+    # Store the parsed items with the appropriate key in the dictionary object.

+    dChan['memloc'] = lchan[0]

+    dChan['rxfreq'] = lchan[1]

+    dChan['txfreq'] = lchan[2]

+    dChan['offset'] = lchan[3]

+    dChan['shift'] = lchan[4]

+    dChan['mode'] = lchan[5]

+    dChan['tag'] = lchan[6]

+    dChan['encode'] = lchan[7]

+    dChan['tone'] = lchan[8]

+    dChan['dcs'] = str(int(lchan[9]))

+    dChan['clarfreq'] = lchan[10]

+    dChan['rxclar'] = lchan[11]

+    dChan['txclar'] = lchan[12]

+    return dChan # return the dictionary object

+## end def

+

+# Define serial communications functions.

+

+def begin(baud=9600):

+    """

+    Description: Initiates a serial connection the the FT991. Should

+                 always be called before sending commands to or

+                 receiving data from the FT991.  Only needs to be called

+                 once.

+    Parameters: none

+    Returns: a pointer to the FT991 serial connection

+    """

+    global ptrDevice

+

+    # Determine OS type and set device port accordingly.

+    OS_type = sys.platform

+    if 'WIN' in OS_type.upper():

+        port = 'COM5'

+    else:

+        port = '/dev/ttyUSB0'

+

+    # In debug mode do not actually send commands to the FT991.

+    if debug:

+        return

+    # Create a FT991 object for serial communication

+    try:

+        ptrDevice = serial.Serial(port, baud,      

+                                  timeout=_INTERFACE_TIMEOUT)

+    except Exception, error:

+        if str(error).find('could not open port') > -1:

+            print 'Please be sure the usb cable is properly connected to\n' \

+                  'your FT991 and to your computer, and that the FT991 is\n' \

+                  'turned ON.  Then restart this program.'

+        else:

+            print 'Serial port error: %s\n' % error

+        exit(1)         

+    time.sleep(.1) # give the connection a moment to settle

+    return ptrDevice

+## end def

+

+def sendCommand(sCmd):

+    """

+    Description: Sends a formatted FT911 command to the communication

+                 port connected to the FT991.  Prints to stdout the

+                 answer from the FT991 (if any).

+    Parameters: device - a pointer to the FT991 comm port

+                sCmd - a string containing the formatted command

+    Returns: nothing

+    """

+    # Debug mode in conjunction with verbose mode is for verifying

+    # correct formatting of commands before they are actually sent

+    # to the FT991.

+    if verbose:

+        print sCmd,

+    # In debug mode do not actually send commands to the FT991.

+    if debug:

+        return ''

+

+    # Send the formatted command to the FT991 and get an answer, if any.

+    # If the command does not generate an answer, no characters will be

+    # returned by the FT991, resulting in an empty string returned by

+    # the receiveSerial function.

+    sendSerial(sCmd)

+    sResult  = receiveSerial();

+    if verbose:

+        print sResult

+    return sResult

+## end def

+

+def receiveSerial(termchar=';'):

+    """

+    Description: Reads output one character at a time from the device

+                 until a terminating character is received.  Returns a     

+                 string containing the characters read from the serial

+                 port.

+    Parameters:  termchar - character terminating the answer string

+    Returns: a string containing the received data

+    """

+    answer = '' # initialize answer string to empty string

+    charCount = 0  # reset read character count to zero

+

+    while True:

+        startTime = time.time() # Start read character timer

+        c =''

+        while True:

+            # Check for a character available in the serial read buffer.

+            if ptrDevice.in_waiting:

+                c = ptrDevice.read()

+                break

+            # Timeout if a character does not become available.

+            if time.time() - startTime > _SERIAL_READ_TIMEOUT:

+                break # Character waiting timer has timed out.

+        # Return empty string if a character has not become available.

+        if c == '':

+            break;

+        answer += c # Form a string from the received characters.

+        charCount += 1 # Increment character count.

+        # If a semicolon has arrived then the FT991 has completed

+        # sending output to the serial port so stop reading characters.

+        # Also stop if max characters received. 

+        if c == termchar:

+            break

+        if charCount > _SERIAL_READ_BUFFER_LENGTH:

+            raise Exception('serial read buffer overflow')

+    ptrDevice.flushInput() # Flush serial buffer to prevent overflows.

+    return answer           

+## end def

+

+def sendSerial(command):

+    """

+    Description: Writes a string to the device.

+    Parameters: command - string containing the FT991 command

+    Returns: nothing

+    """

+    # In debug we only want to see the output of the command formatter,

+    # not actually send commands to the FT991.  Debug mode should be

+    # used in conjunction with verbose mode.

+    ptrDevice.write(command) # Send command string to FT991

+    ptrDevice.flushOutput() # Flush serial buffer to prevent overflows

+## end def

+

+def main():

+    """

+    Description: Place code for testing this module here.

+    Parameters: none

+    Returns: nothing

+    """

+    # Test this module.

+    global verbose, debug

+

+    verbose = True

+    debug = False

+

+    begin()

+    sendCommand('IF;')

+    sendCommand('MC001;')

+    sendCommand('ZZZ;')

+

+    dMem = {'rxfreq': '146.52', 'shift': 'OFF', 'encode': 'OFF', \

+        'txclar': 'OFF', 'tag': 'KA7JLO', 'mode': 'FM', 'rxclar': 'OFF', \

+        'memloc': '99', 'clarfreq': '0'}

+    setMemory(dMem)

+    print getMemory(99)

+   

+## end def

+

+if __name__ == '__main__':

+    main()

new file mode 100755

@@ -0,0 +1,517 @@

+#!/usr/bin/python -u

+# The -u option turns off block buffering of python output. This assures

+# that output streams to stdout when output happens.

+#

+# Module: ft991utility.py

+#

+# Description:  A utility for backing up Yaesu FT991 memory and menu settings,

+#               and also for restoring memory and menu settings from

+#               a file.  Can be used both interactively or with command line

+#               arguments. Before running this utility, be sure to copy

+#               the file 'ft911.py' to the same folder as this utility.

+#

+# Copyright 2019 by Jeff Owrey, Intravisions.com

+#    This program is free software: 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 3 of the License, or

+#    (at your option) any later version.

+#

+#    This program 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 copy of the GNU General Public Licensef

+#    along with this program.  If not, see http://www.gnu.org/license.

+#

+# Revision History

+#   * v10 23 Nov 2019 by J L Owrey; first release

+#

+# This script has been tested with the following

+#

+#     Python 2.7.15rc1 (default, Nov 12 2018, 14:31:15) 

+#     [GCC 7.3.0] on linux2

+#2345678901234567890123456789012345678901234567890123456789012345678901234567890

+

+import os, sys, serial, time

+import ft991 # module should be in same directory as this utility

+

+# Constant definitions

+

+_DEFAULT_MENU_SETTINGS_FILE = 'ft991menu.cfg'

+_DEFAULT_MEMORY_SETTINGS_FILE = 'ft991mem.csv'

+_MAX_NUMBER_OF_MENU_ITEMS = 154

+_MAX_NUMBER_OF_MEMORY_ITEMS = 118

+

+# Global definitions

+

+menuBackupFile = _DEFAULT_MENU_SETTINGS_FILE

+memoryBackupFile = _DEFAULT_MEMORY_SETTINGS_FILE

+commandLineOption = ''

+

+# Command processing functions

+

+def doUserCommand():

+    """

+    Description: Provides an interactive user interface where the user can

+                 enter simple text commands at a command line prompt.  The

+                 commands that a user can enter are listed in a menu splash

+                 that the user can display anytime with the 'm' command.

+                 Also this function processes commands provided as command

+                 line options.  In the case of a command line option this

+                 function operates non-interactively.

+    Parameters: none

+    Returns: nothing

+    """

+    # When command line arguments have not been provided,

+    # use interactive mode and give the user a prompt.

+    if commandLineOption == '':

+        cmd = raw_input('>').strip()

+    # If command line arguments have been provided, then

+    # execute the command non-interactively.

+    else:

+        cmd = commandLineOption

+

+    # Process the user command.   

+    if cmd == '':

+        return

+    elif cmd == 'm':

+        printMenuSplash()

+    elif cmd == 'bu':

+        backupMenuSettings()

+    elif cmd == 'ru':

+        restoreMenuSettings()

+    elif cmd == 'bm':

+        backupMemorySettings()

+    elif cmd == 'rm':

+        restoreMemorySettings()

+    elif cmd == 'p':

+        passThroughMode()

+    elif cmd == 'v':

+        toggleVerboseMode()

+    elif cmd == 'x':

+        exit(0)

+    else:

+        print "invalid command"

+## end def

+

+def backupMemorySettings():

+    """

+    Description: Backs up all memory settings to a file.  The user has the

+                 option of providing a file name or accepting a default

+                 file name.

+    Parameters: none

+    Returns: nothing

+    """

+    # Prompt the user for a file name in which to store

+    # backed up memory settings.

+    fileName = getFileName(memoryBackupFile)

+    # Read the memory settings from the FT991...

+    print 'Backing up memory settings...'

+    settings = readMemorySettings()

+    # and write them to the file.

+    writeToFile(settings, fileName)

+    print 'Memory settings backed up to \'%s\'' % fileName

+## end def

+

+def restoreMemorySettings():

+    """

+    Description: Restores all memory settings from a file.  The user has the

+                 option of providing a file name or accepting a default

+                 file name.

+    Parameters: none

+    Returns: nothing

+    """

+    # Prompt the user for a file name from which to retrieve backed up

+    # memory settings.  Also make sure the file exists.

+    fileName = getFileName(memoryBackupFile)

+    if not os.path.isfile(fileName):

+        print 'File not found.\n' \

+              'Please enter a valid file name.  Be sure to correctly ' \

+              'enter\nthe full path name or relative path name of the file.'

+        return

+    # Read the memory settings from the file...

+    print 'Restoring memory settings...'

+    settings = readFromFile(fileName)

+    # and write them to the FT991.

+    writeMemorySettings(settings)

+    print 'Memory settings restored from \'%s\'' % fileName

+## end def

+

+def backupMenuSettings():

+    """

+    Description: Backs up all menu settings to a file.  The user has the

+                 option of providing a file name or accepting a default

+                 file name.

+    Parameters: none

+    Returns: nothing

+    """

+    # Prompt the user for a file name in which to store

+    # backed up menu settings.

+    fileName = getFileName(menuBackupFile)

+    # Read the menu settings from the FT991...

+    print 'Backing up menu settings...'

+    settings = readMenuSettings()

+    # and write them to the file.

+    writeToFile(settings, fileName)

+    print 'Menu settings backed up to \'%s\'' % fileName

+## end def

+

+def restoreMenuSettings():

+    """

+    Description: Restores all menu settings from a file.  The user has the

+                 option of providing a file name or accepting a default

+                 file name.

+    Parameters: none

+    Returns: nothing

+    """

+    # Prompt the user for a file name from which to retrieve backed up

+    # menu settings.  Also make sure the file exists.

+    fileName = getFileName(menuBackupFile)

+    if not os.path.isfile(fileName):

+        print 'File not found.\n' \

+              'Please enter a valid file name.  Be sure to correctly ' \

+              'enter\nthe full path name or relative path name of the file.'

+        return

+    # Read the menu settings from the file...

+    print 'Restoring menu settings...'

+    settings = readFromFile(fileName)

+    # and write them to the FT991.

+    writeMenuSettings(settings)

+    print 'Menu settings restored from \'%s\'' % fileName

+## end def

+

+def passThroughMode():

+    """

+    Description: An interactive mode whereby the user an enter FT991 CAT

+                 commands directly on the command line.  This mode greatly

+                 facilitates development and debugging.

+    Parameters: none

+    Returns: nothing

+    """

+    print 'Entering passthrough mode. Type \'exit\' to exit mode.'

+    while(True):

+        # Prompt the user to enter an FT991 CAT command, and

+        # process the  command string.

+        sCommand = raw_input('CAT# ').upper()

+        if sCommand == 'EXIT': # exit this utility

+            break

+        # If the user fails to end a CAT command with a semi-colon,

+        # then provide one.

+        elif sCommand[-1:] != ';':

+            sCommand += ';'

+

+        if sCommand == '': # no command - do nothing

+            continue

+        else: # run a user command

+            ft991.sendSerial(sCommand)

+            sResult = ft991.receiveSerial();

+            if sResult != '':

+                print sResult

+## end def

+

+def toggleVerboseMode():

+    """

+    Description: Toggles the verbose mode on or off, depending on the

+                 previous state.  Verbose mode causes CAT commands to be

+                 echoed to STDOUT as they are sent to the FT991.  If a

+                 CAT command returns a string, that is also echoed. 

+    Parameters: none

+    Returns: nothing

+    """

+    if ft991.verbose:

+        ft991.verbose = False

+        print 'Verbose is OFF'

+    else:

+        ft991.verbose = True

+        print 'Verbose is ON'  

+## end def

+

+def getFileName(defaultFile):

+    """

+    Description: Prompts the user for a file name.

+    Parameters: defaultFile - file name to use if the user does not

+                              provide a file name

+    Returns: the user provided file name if provided, or the default

+             file name, otherwise.

+    """

+    # If a command backup or restore argument provided, then do not

+    # query the user for a file name.  A file name may be provided

+    # as an option on the command line.

+    if commandLineOption != '':

+        return defaultFile

+    # Otherwise query the user for a file name

+    fileName = raw_input("Enter file name or <CR> for default: ")

+    if fileName == '':

+        return defaultFile

+    else:

+        return fileName

+## end def

+

+def readMenuSettings():

+    """

+    Description: Reads all menu settings from the FT991.

+    Parameters: none

+    Returns: a list object containing all the menu settings

+    """

+    lMenuSettings = []

+    # Iterate through all menu items, getting each setting and storing

+    # the setting in a file.

+    for inx in range(1, _MAX_NUMBER_OF_MENU_ITEMS):

+        # Format the read menu item CAT command.

+        sCommand = 'EX%0.3d;' % inx

+        # Send the command to the FT991.

+        sResult = ft991.sendCommand(sCommand)

+        # Add the menu setting to a list object.

+        lMenuSettings.append(sResult)

+    return lMenuSettings

+## end def

+

+def writeMenuSettings(lMenuSettings):

+    """

+    Description: Writes supplied menu settings to the FT991.

+    Parameters: lMenuSettings - a list object containing menu settings

+    Returns: nothing

+    """

+    for item in lMenuSettings:

+

+        # Do not write read-only menu settings as this results

+        # in the FT-991 returning an error.  The only read-only

+        # setting is the "Radio ID" setting.

+        if item.find('EX087') > -1:

+            continue;

+        # Send the pre-formatted menu setting to the FT991.

+        sResult = ft991.sendCommand(item)

+        if sResult.find('?;') > -1:

+            print 'error restoring menu setting: %s' % item

+            exit(1)

+## end def

+

+def readMemorySettings():

+    """

+    Description: Reads all defined memory settings from the FT991.  The

+                 settings are reformatted into a readable, comma-delimited

+                 (csv) file, which can be viewed and modified with a

+                 spreadsheet application such as LibreOffice Calc.

+    Parameters: none

+    Returns: a list object containing memory location settings. Each item

+             in the list represents a row, in comma-delimited form, that

+             specifies the settings for a single memory location. The first

+             item in the list are the column headers for remaining rows

+             contained in the list.

+    """

+    # Define the column headers as the first item in the list.

+    lMemorySettings = [ 'Memory Ch,Rx Frequency,Tx Frequency,Offset,' \

+                        'Repeater Shift,Mode,Tag,Encoding,Tone,DCS,' \

+                        'Clarifier, RxClar, TxClar' ]

+

+    for memoryLocation in range(1, _MAX_NUMBER_OF_MEMORY_ITEMS):

+        # For each memory location get the memory contents.  Note that

+        # several CAT commands are required to get the entire contents

+        # of a memory location.  Specifically, additional commands are

+        # required to get DCS code and CTCSS tone.

+        dMem = ft991.getMemory(memoryLocation)

+        # If a memory location is empty (has not been programmed or has

+        # been erased), do not created a list entry for that location.

+        if dMem == None:

+            continue

+        # Get DCS and CTCSS.

+        tone = ft991.getCTCSS()

+        dcs = ft991.getDCS()

+        # getMemory, above, stores data in a dictionary object.  Format

+        # the data in this object, as well as, the DCS code and CTCSS

+        # tone into a comma-delimited string.

+        sCsvFormat = '%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,' % \

+               ( dMem['memloc'], dMem['rxfreq'], '', '', \

+                 dMem['shift'], dMem['mode'], dMem['tag'], dMem['encode'], \

+                 tone, dcs, dMem['clarfreq'], dMem['rxclar'], \

+                 dMem['txclar'] )

+        # Add the comma-delimited string to the list object.

+        lMemorySettings.append(sCsvFormat)

+        if ft991.verbose:

+            print

+    return lMemorySettings

+# end def

+

+def writeMemorySettings(lMemorySettings):

+    """

+    Description: Writes the supplied memory settings to the FT991.

+    Parameters: lMemorySettings - a list object containing the memory

+                                  settings in comma delimited format

+    Returns: nothing

+    """

+    for item in lMemorySettings:

+        # Parse the comma-delimited line and store in a dictionary object.

+        dItem = ft991.parseCsvData(item)

+        # The first item in the memory settings list are the column headers;

+        # so ignore this item.  (parseData returns None for this item.)

+        if dItem == None:

+            continue

+        # Set memory channel vfo, mode, and other data.

+        sResult = ''

+        sResult += ft991.setMemory(dItem)

+        # Set CTCSS tone for memory channel.

+        sResult += ft991.setCTCSS(dItem['tone'])

+        # Set DCS code for memory channel. 

+        sResult += ft991.setDCS(dItem['dcs'])

+        # Process any errors returned by the CAT interface.

+        if sResult.find('?;') > -1:

+            print 'error restoring memory setting: %s' % sResult

+        if ft991.verbose:

+            print

+## end def

+

+def writeToFile(lSettings, fileName):

+    """

+    Description: Writes supplied settings to the specified file.

+    Parameters: lSettings - a list object containing the settings

+                 fileName - the name of the output file

+    Returns: nothing

+    """

+    fout = open(fileName, 'w')

+    for item in lSettings:

+        fout.write('%s\n' % item)

+    fout.close()

+## end def

+

+def readFromFile(fileName):

+    """

+    Description: Reads settings from the specified file.

+    Parameters:  fileName - the name of the input file

+    Returns: a list object containing the settings

+    """

+    lSettings = []

+

+    fin = open(fileName, 'r')

+    for line in fin:

+        item = line.strip() # remove new line characters

+        lSettings.append(item)

+    fin.close()

+    return lSettings

+## end def

+

+def setIOFile(option, commandLineFile):

+    """

+    Description: Provides a connector between the command line and the

+                 interactive interface.  Commands included as arguments

+                 on the command line determine default file names, as

+                 well as the command executed by doUserCommand above. 

+    Parameters: option - the command supplied by the command line

+                         argument interpreter getCLarguments.

+                commandLineFile - the name of the file supplied by the

+                          -f command line argument (if supplied). 

+    Returns: nothing

+    """

+    global menuBackupFile, memoryBackupFile, commandLineOption

+

+    commandLineOption = option

+    if commandLineFile == '':

+        return

+    if (option == 'bu' or option == 'ru'):

+        menuBackupFile = commandLineFile # set menu backup file name

+    elif (option == 'bm' or option == 'rm'):

+        memoryBackupFile = commandLineFile # set memory backup file name

+## end def

+

+def printMenuSplash():

+    """

+    Description: Prints an menu of available commands for use in

+                 interactive mode.

+    Parameters:  none

+    Returns: nothing

+    """

+    splash = \

+"""

+Enter menu item number.

+m - show this menu

+bm - backup memory to file

+rm - restore memory from file

+bu - backup menu to file

+ru - restore menu from file

+p - enter passthrough mode

+v - toggle verbose mode

+x - exit this program

+"""