Unfortunately, we do not have the resources to provide substantial support -- we are funding any distribution of OAA-related material on internal funding, and the software must be accepted on a as-is basis. However, in the section below you may find some information which may help you overcome various problems.

If, after reading OAA documentation and considering the information presented below, send problems or questions to the oaa-users mailing list Not all questions can be answered (by us), but we will try to be responsive.

Note: The trouble-shooting information listed below contains some information for OAA 1.0 agents as well as the OAA 2.3 distribution. Most of the information is relevant for users of the Automated Office application.

  • Troubleshooting


    1. Facilitator


    The Facilitator doesn't start, and prints the message:
    Loading setup file: '/home/trestle2/cheyer/'
    Currently unable to access zuma port 3344.
       Try again? [y)es, n)o, h)elp]: 

    Solution 1:

    If this is the first time you are trying to connect the Facilitator to this host and port, you may be a problem in the way you've defined the host and port for agents. This value is obtained by the Facilitator (and every other agent) by first reading the command line (-oaa_host -oaa_port ), then checking the environment variables (OAA_HOST and OAA_PORT), and finally reading the configuration file "", first checking the local directory and then your home directory.

    • Make sure the host variable is the correct machine name for the host you are actually running the Facilitator on.

    • Try a different port number (larger than 2000) to see if it was simply the case that the port was already being used.

    • Perhaps the format of the host is wrong (Quintus's TCP library does not accept all representations of host addresses). Try the following trick: set the host value to a Prolog variable (e.g. -oaa_host X -oaa_port 3366) and then start the Facilitator. If the Facilitator starts up correctly, note the exact name of the host printed by the Facilitator (in the example below, it's "trestle") and use exactly this value for oaa_host next time.
      Loading setup file: '/home/trestle2/cheyer/'
      Listening on trestle port 3347

    Solution 2:

    If the Facilitator was previously working on this host and port, and no longer works, the port must be blocked. This sometimes occurs when the Facilitator is shut down before disconnecting all client agents. Try finding and killing any agents which may still be running and connected to the defunct Facilitator, wait a minute or two, and try starting the Facilitator again. Or else, you can always modify the port number, finding a free port.

    2. Start-It


    The command "startit" fails with following output:
    % ./startit -noexpect ../office.config
    Warning: locale not supported by Xlib, locale set to C
    Warning: X locale modifiers not supported, using default
    Segmentation fault (core dumped)


    The problem is Start-It is not finding the nls/ directory. That directory is normally installed on Sun machines, however a copy is shipped with distribution to be sure. Make sure to setenv XNLSPATH to the nls directory.


    Start-It is having trouble executing programs or agents on either local or remote machines.


    Make sure your environment supports the following check-list:
    • Start-It currently only supports a "csh" or "tcsh" user environment. It does not work when run from "sh".

    • You must be able to rsh FROM the machine startit is running on, TO every machine which you will run things on, ==> INCLUDING the "from" machine itself (check the /etc/hosts.equiv file for this)

    • make sure any info that needs to be in the user's environment, e.g. the $path variable, get set in the "interactive shell" portion of the user's .cshrc (i.e. outside of any checks for "$?prompt", or more explicitly, when "$?prompt" is allowed to be false) )


    The colors for Start-It are not correct.


    Start-It's colors are defined in an X resource file called Startit. You may copy this file to one of your local directories and modify the colors to your liking. To make sure that Start-It uses your modified version of the resource file, set the environment variable XUSERFILESEARCHPATH to include the directory where your file has been stored.
    	setenv XUSERFILESEARCHPATH ./%N:/home/trestle4/OAA/demo/%N

    3. Nuance Speech Recognition

    3.1 Testing audio configuration

    You should set up your microphone, optional preamp, and then test the whole setup using /usr/demo/SOUND/soundtool. You are striving for a good clean (flat) signal during silence and a clean active one during speaking. Set the gain control on your preamp or the volume level in soundtool appropriately. You should also play back your recorded test to make sure that it sounds clear and not distorted.

    Be aware that there are two input sources on a Sun (mic and line) but that these are mutually exclusive (ie it's a toggle). If soundtool doesn't appear to hear you, this is probably the problem.

    Once you have found ideal setting values for your audio configuration, you probably will want to make them permanent with respect to Nuance by storing them in ~/nuance-resources. This is described in a later section.

    3.2 Creating and compiling a speech grammar

    Setup environment
    The following must be executed before doing anything with Nuance:
       setenv NUANCE /home/YourNuancePath
       source $NUANCE/SETUP

    Create a grammar

    Grammar files always end in a '.grammar' extension.

    Remember that speech grammars are made up of NONTERMINALS (which start with a capital letter) and combinations of non-terminal vocabulary words.

       NON_TERM  (a b)    # means a AND b
       NON_TERM2 [a b]    # means a OR b
       NON_TERM3 ?a       # means optionally a
       NON_TERM3 *a       # means 0 or more occurrences of a
       NON_TERM4 +a       # means 1 or more occurrences of a
    Non-terminals can only refer to non-terminals that have been defined above them in the grammar file (enforces regular grammar constraint.

    Special Non-Terminals starting with a '.' are called top-level Non-Terminals and provide the starting point of the tree to be recognized.

    Here's a simple test grammar, in file 'test.grammar'.

       Statement    (testing [one two three])
       Question     (is this a ?great test)
       .TOP         [Statement Question]
    Compile the grammar
    To compile the grammar, type:
       nuance-compile test ptm6
    test is the basename for your grammar file, ptm6 is one of the model sets that can be used (different model sets possess different characteristics of robustness/speed). To see a list of the current choices for model sets, run "nuance-compile test" without specifying the model and Nuance's error message will list available model sets.

    If a word in your grammar file is unknown in Nuance's default dictionary, the compile will print an error and put the word into a file called 'test.missing'. You should then create a file called 'test.dictionary' where you give the pronunciation for all missing words in 'test.grammar'. You must specify the pronunciation using using phonemes listed in the nuance manual (or in the ADT users manual). An easy way to figure out the pronunciations for a word is to look up pronunciations for words that sound similar using the command 'pronounce word'.

    After a successful compilation, Nuance creates a directory named 'test' containing all the required files for speech recognition. This directory is now called a 'package'.

    3.3 Testing grammar with Nuance tools

    Nuance provides two tools for testing recognition: sample-application (a text-based tester) and Xapp (an XWindows-based one).

    To test your grammar, try :

         sample-application -package ./test
         Xapp -package ./test
    Sample phrases from our test grammar above might be:
          testing one
          is this a great test
          is this a test
          testing two
    If you have problems (such as sample-application doesn't appear to hear you when you speak), you should know that starting Nuance will set all audio parameters to their default values as defined in the file $NUANCE/data/nuance-resources.defaults. You can override the default values by putting a nuance-resources file in your home directory, with values appropriate to your audio setup. Here is my nuance-resources file which sets some audio parameters such as volume, input source, etc:
            audio.InputSource       line    # may also be mic
            audio.InputVolume       200     # range 0-255
            audio.OutputVolume      200     # range 0-255
            client.WriteWaveforms   FALSE   # don't save utterances
            ep.EndSeconds           0.75    # end of speech silence wait
            rec.BacktraceFinalsOnly  TRUE   # only allow complete sentences
            config.ServerDebugWindow TRUE   # show server trace window
    Nuance has many parameters, which are listed in their manual. Parameters may also be given at runtime for any Nuance-enabled program as command line arguments: this is useful for testing values to find the best one.
       Example: sample-application -package test audio.InputVolume=150

    1.2.4 Testing OAA speech agent

    If you have made it to this step, you should have no problem with the next one. SRX is just an OAA-enabled Nuance client application, very similar to the code in Xapp.

    First, of course, run a Facilitator.

    Start srx using

       srx -rf srx.rf -package ./test

    If Nuance complains about an incompatible version number, then the version of srx that you are not using is not compatible with the version of Nuance defined by your $NUANCE variable. Either:

    1. You must obtain a version of srx that is compiled with the library files used by your current version of $NUANCE
    2. You must obtain a version of Nuance that is compatible with your version of srx.

    srx opens up an XWindows display which lets you test locally. Clicking on the NextGrammar button will cycle through all the top-level nonterminals in your grammar file. When you see one you like, press enter in the Do: textfield.

    Pressing clickToTalk button will start recognition. Abort will abort recognition. You should set Trace to be On in the Edit menu.

    You can also test speech recognition by sending speech solvables from another agent. For instance, from the XWindows oaa interface agent, you could try solve(recognize(X),[]) to start recognition.

    4. Automated Office

    4.1 Adding user bitmaps

    I want to add new users bitmaps to the Office Assistant user interface on the PC. Also, how can I change the default user, which always appears to be "Adam Cheyer".
    You must edit the file /windows/interfac.ini.
    Use Mailtalk Agent=0
    [User Data]
    You can specify your own users and their photos, as well as which user is the default user (CurrentUser=1)

    5. Computerfone

    Computer (especially Sun Workstation) doesn't "talk" to the Computerfone.
    Solution 1
    The manual is initially confusing on whether the Computerfone is DTE (terminal) or DCE (modem): "whatever cable your host would normally use to connect it to a modem or terminal would probably be adequate" (page 2-12 of User Guide of 1-95). Later on, it is documented as DCE (page 2-13), which is what you would expect since it is similar to a modem. To connect it to a Sun Workstation (DTE), we use an AT Serial Modem Cable, DB9 Female to DB25 Male.

    If you don't know if your cable is a modem cable or null modem cable, try inserting a null modem into the connection chain (modem + null-modem = null-modem; null-modem + null-modem = modem).

    Solution 2
    On Sun workstations where TTY ports A and B are combined in a single DB-25 connect, port B does NOT have modem control. If you are using port B, you need to set the DIP jumper in your Computerfone to use XON/XOFF handshaking. At the time of this writing, this was DIP G.
    Solution 3
    Many serial devices work in either RS-232 or the newer RS-423 mode. The TTY ports on newer Sun Workstations are coming configured as RS-423, resettable to RS-232 by jumpers on the main board. The Computerfone Manual says it has an RS-232 interface, and on more than one occasion, switching the jumpers in a Sun to RS-232 fixed a problem with the Sun not talking to the Computerfone. However, we have also had Computerfones work on Suns where the jumpers were still set to RS-423.

    For the Sun SPARCstation 10, see "Changing the Serial Port Jumpers" (pages 60-61) in the "Desktop SPARC Hardware Owner's Guide--December 1992".
    For the Sun SPARCstation 20, see "Changing the RS423/232 Jumpers" (chapter 6; pages 24-27) in the "SPARCstation 20 Installation Guide").
    In both the SS-10 and SS-20, the pair of jumpers that control this selection are labeled J0801 and J0802 and are located very close to the rear panel (requires some dexterity to switch the jumpers).
    For the Sun Ultra, ****???