@@ -21,20 +21,19 @@ 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.

+Email bug reports and comments to: fractal@intravisions.com

+

 Notes

 -----

 1. The files ft991utility.py and ft991.py should be downloaded from the

-   github repository and placed in the same folder.  At the root level

-   of the fractalxoas/ham repository, click on 'Clone or download'.

-   Experienced github users may choose to clone the repository, otherwise

-   select 'Download ZIP'.

+   github repository and placed in the same folder.

 2. To run the utility, open a terminal session in directory containing

    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

    to be run as an executable.  To change the permissions run the command

-       chmod +x ft991utility.py2.

+       chmod +x ft991utility.py

 3. Windows users will need to have the python 2.7 framework installed.

    Probably, the easiest way to get the framework is to install the

    Windows Subsystem for Linux Ubuntu platform.  Note that the utility

@@ -45,7 +44,7 @@ Notes

    name of the utility with no command line arguments, e.g.,

            ./ft991utility.py

 5. The utility saves memory settings in a comma-delimited file that

-   can be imported using a spreadsheet application for ease in viewing

+   can be imported into a spreadsheet application for ease in viewing

    and editing.  A LibreOffice Calc template 'ft991_memory_settings.ots'

    has been provided to facilitate creating a spreadsheet to upload memory

    settings to the FT991.

@@ -58,13 +57,13 @@ Notes

    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

-   'ft991mem_todaysDate.csv' so that you can restore from this file at a

+   'ft991mem_todaysDate.csv so that you can restore from this file at a

    later date if necessary.

 8. 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.

 9. The example file 'example.csv' shows how a memory settings file should

-   appear.  To load these settings into your FT991, run the 'rm' command in

+   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

@@ -75,5 +74,4 @@ Notes

     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.

-Email bug reports and comments to: fractal@intravisions.com

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

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

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

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

+# Define 'get' methods to encapsulate FT991 commands that return status info.

-def setMemory(dMem):

+def getMemory(memloc):

     """

-    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: 

+    Description: Get memory settings of a specific memory location.

+    Parameters: memloc - an integer specifying memory location 

+    Returns: a dictionary object containing the memory ettings

     """

     dMem = {}

     # Set memory location pointer in FT991.  This is done

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

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

+    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)

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

     sResult = sendCommand(sCmd)

     # Parse memory settings string returned by the FT991

@@ -207,9 +166,9 @@ def getMemory(memLoc):

 def getCTCSS():

     """

-    Description: 

-    Parameters: 

-    Returns: 

+    Description: Get the CTCSS tone setting for the current memory location.

+    Parameters: none

+    Returns: string containing the CTCSS tone

     """

     # Get result CTCSS tone

     sResult = sendCommand('CN00;')

@@ -219,9 +178,9 @@ def getCTCSS():

 def getDCS():

     """

-    Description: 

-    Parameters: 

-    Returns: 

+    Description: Get the DCS code setting for the current memory location.

+    Parameters: none

+    Returns: string containing the DCS code

     """

     # Get result of CN01 command

     sResult = sendCommand('CN01;')

@@ -229,41 +188,126 @@ def getDCS():

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

 ## end def

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

+

+def setMemory(dMem):

+    """

+    Description: Sends a formatted MT command.

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

+                       defined:

+

+                       memloc - the memory location to be written

+                       rxfreq - receive frequency of VFO-A in MHz

+                       clarfreq - clarifier frequency and direction

+                       rxclar - receive clarifier state

+                       txclar - transmit clarifier state

+                       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

+    """

+    # Format the set memory location (MC) command.

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

+    # Validate memory location data and send the command.

+    if iMemloc < 1 or iMemloc > 118:

+        raise Exception('Memory location must be between 1 and ' \

+                        '118, inclusive.')

+    sCmd = 'MC%0.3d;' % iMemloc

+    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 bug in the CAT interface.

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

+

+    # Format the set memory with tag command (MT).

+    sCmd = 'MT%0.3d' % iMemloc

+

+    # Validate and append the vfo-a frequency data.

+    iRxfreq = int(float(dMem['rxfreq']) * 1E6) # vfo-a frequency in Hz

+    if iRxfreq < 0.030E6 or iRxfreq > 450.0E6:

+        raise Exception('VFO-A frequency must be between 30 kHz and ' \

+                        '450 MHz, inclusive.')

+    sCmd += '%0.9d' % iRxfreq

+

+    # Validate and append the clarifier data.

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

+    if abs(iClarfreq) > 9999:

+        raise Exception('Clarifer frequency must be between -9999 Hz ' \

+                        'and +9999 Hz, inclusive.')

+    sCmd += '%+0.4d' % iClarfreq

+

+    # The following commands will automatically raise an exception if

+    # incorrect data is supplied.  The exception will be a dictionary

+    # object "key not found" error.

+    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'

+    sTag = dMem['tag']

+

+    # Validate and append the memory tag data.

+    if len(sTag) > 12:

+        raise Exception('Memory tags must be twelve characters or less.')

+    sCmd += '%-12s' % sTag

+    sCmd += ';' # Terminate the completed command.

+

+    # Send the completed command.

+    sResult = sendCommand(sCmd)

+    return sResult

+## end def

+

 def setCTCSS(tone):

     """

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

+    Description:  Sends 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

     """

+    # An exception will automatically be raised if incorrect data is

+    # supplied - most likely a "key not found" error.

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

     return sendCommand(sCmd)

 ## end def

 def setDCS(code):

     """

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

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

                   DCS code.

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

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

     Returns: a string containing the formatted command

     """

+    # An exception will automatically be raised if incorrect data is

+    # supplied - most likely a "key not found" error.

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

     return sendCommand(sCmd)

 ## end def

 def setPower(power):

     """

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

+    Description:  Sends a 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 

+    power = int(power)

+    # Validate power data and format command.

+    if power < 5 or power > 100:

+        raise Exception('Power must be between 0 and 100 watts, inclusive.')

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

     return sendCommand(sCmd)

 ## end def

+# Helper functions to assist in various tasks.

+

 def parseCsvData(sline):

     """

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

@@ -286,14 +330,43 @@ def parseCsvData(sline):

     dChan['tag'] = lchan[6]

     dChan['encode'] = lchan[7]

     dChan['tone'] = lchan[8]

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

+    dChan['dcs'] = 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 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

+

+# Low level serial communications functions.

 def begin(baud=9600):

     """

@@ -316,6 +389,7 @@ def begin(baud=9600):

     # 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,      

@@ -332,35 +406,6 @@ def begin(baud=9600):

     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

@@ -413,6 +458,10 @@ def sendSerial(command):

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

 ## end def

+# Main routine only gets called when this module is run as a program rather

+# than imported into another python module.  Code testing the functions in

+# this module should be placed here.

+

 def main():

     """

     Description: Place code for testing this module here.

@@ -425,17 +474,19 @@ def main():

     verbose = True

     debug = False

+    # Instantiate serial connection to FT991

     begin()

-    sendCommand('IF;')

-    sendCommand('MC001;')

-    sendCommand('ZZZ;')

-

+    # Commands that send a setting

     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)

-   

+    sendCommand('MC002;')

+    # Commands that return data

+    getMemory(99)

+    sendCommand('IF;')

+    # Invalid command handling

+    sendCommand('ZZZ;')

 ## end def

 if __name__ == '__main__':

@@ -241,52 +241,13 @@ def getFileName(defaultFile):

     if commandLineOption != '':

         return defaultFile

     # Otherwise query the user for a file name

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

+    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

@@ -301,7 +262,7 @@ def readMemorySettings():

              contained in the list.

     """

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

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

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

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

                         'Clarifier, RxClar, TxClar' ]

@@ -327,40 +288,86 @@ def readMemorySettings():

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

                  dMem['txclar'] )

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

-        lMemorySettings.append(sCsvFormat)

+        lSettings.append(sCsvFormat)

         if ft991.verbose:

             print

-    return lMemorySettings

+    return lSettings

 # end def

-def writeMemorySettings(lMemorySettings):

+def writeMemorySettings(lSettings):

     """

     Description: Writes the supplied memory settings to the FT991.

-    Parameters: lMemorySettings - a list object containing the memory

+    Parameters: lSettings - a list object containing the memory

                                   settings in comma delimited format

     Returns: nothing

     """

-    for item in lMemorySettings:

+    for item in lSettings:

         # 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'])

+        try:

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

+            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'])

+        except Exception, e:

+            print 'Backup settings file corrupted or incorrectly formatted.\n' \

+                  'Please make sure all values are correctly entered.'

+            print e

+            exit(1)

+

         # Process any errors returned by the CAT interface.

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

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

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

         if ft991.verbose:

             print

 ## end def

+def readMenuSettings():

+    """

+    Description: Reads all menu settings from the FT991.

+    Parameters: none

+    Returns: a list object containing all the menu settings

+    """

+    lSettings = []

+    # 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.

+        lSettings.append(sResult)

+    return lSettings

+## end def

+

+def writeMenuSettings(lSettings):

+    """

+    Description: Writes supplied menu settings to the FT991.

+    Parameters: lSettings - a list object containing menu settings

+    Returns: nothing

+    """

+    for item in lSettings:

+

+        # 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 writeToFile(lSettings, fileName):

     """

     Description: Writes supplied settings to the specified file.

@@ -398,8 +405,8 @@ def setIOFile(option, commandLineFile):

                  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). 

+                commandLineFile - the name of the file supplied by the -f

+                         command line argument (if supplied). 

     Returns: nothing

     """

     global menuBackupFile, memoryBackupFile, commandLineOption

@@ -436,7 +443,7 @@ x - exit this program

 ## end def

 def getCLarguments():

-    """ Description: gets command line arguments and configures this program

+    """ Description: Gets command line arguments and configures this program

                      to run accordingly.  See the variable 'usage', below,

                      for possible arguments that may be used on the command

                      line.