



           XA - X10 COMMAND INTERPRETER - VERSION 3.2























     XA
     X10 Command Interpreter
     Version 3.2 - April 1996



















     Copyright c 1991-1996 by Bruce Christensen
     and AutoMagic Technologies - All Rights Reserved

     World Wide Web: http://members.aol.com/automagict/






     User's Guide and Reference                                           1




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Shareware
     =======================================

     This floppy contains a set of useful DOS utilities for X10's CP-290
     Computer Interface.  These programs are being marketed using the
     SHAREWARE concept which allows you a complete evaluation of the
     product before you are required to register it.  Shareware provides
     you with low-cost, high-performance software and support.  Shareware
     also provides incentives for programmers to continue to develop new
     products.  If you find XA and its support files useful and you
     continue to use them after a trial period not to exceed 45 days, you
     must make a registration payment to the author.  When you register,
     you will receive the latest, full-featured version of XA along with a
     printed User's Manual.  For more information, read the file
     REGISTER.TXT, complete the form, and register your copy of XA.

     You can order a registered version of XA with your credit card.   Full
     details may be found  in REGISTER.TXT for  registration by either  PsL
     (Public software Library), or through CompuServe's on-line services.

     Introduction
     =======================================

     `...XA is without a doubt, the most powerful, most flexible, most
     complete package we've reviewed to date.'
     Electronic House Magazine - 7/94

     You are probably familiar with the menu-driven program (X10.EXE)
     supplied with your CP-290.  The software approach used in that
     implementation is great for beginners since it offers a fool-proof
     method of organizing commands and events.  Unfortunately, that method
     also becomes a bottle-neck every time you want to activate a single
     module via your computer.  What's worse is trying to maintain a
     schedule of lighting events that vary due to seasonal changes.  XA is
     a shareware package designed to alleviate many of the frustrations you
     may have experienced with the X10-supplied software.  In addition, XA
     makes schedule maintenance a breeze.  Soon, your computer will
     automatically handle the monotony of CP-290 scheduling for you.  Be
     sure to read this manual to take full advantage of XA's power.

     What is XA?
     -------------------------------

     The XA program is an interpreter.  XA translates English-like
     sentences into commands that are understood by the CP-290.  For
     instance, you can quickly tell XA to turn on a set of lights with the
     following DOS command:

       XA `PORCH ON'

     XA knows that the PORCH lights are addressed as A9, or whatever
     address you choose (you DEFINE modules and their addresses in the file

     User's Guide and Reference                                           2




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     XA.INI, discussed later on pg.52).  Since XA accepts commands from the
     DOS prompt, you can place statements like these in your batch files
     too.  For instance, I use an X10-controlled nightlight near our
     downstairs phone to warn other family members if I'm `on-line' with a
     remote computer or BBS.  The light is turned on prior to the session,
     and turned off when I'm finished.  Here's the sample PHONE.BAT with
     X10 commands:

       XA `WARNING_LAMP ON'
       TELIX (or ProComm) statements here
       XA `WARNING_LAMP OFF'

     XA will also process X10 commands and events contained in a file.
     This is ideal for maintaining the CP-290's event schedule, or for
     running a Christmas `lightshow'.  Simply tell XA which file to read,
     and XA does all the work.  For instance, to run the Christmas lighting
     command file:

       XA F=XMAS.CMD

     To download my event schedule to the CP-290, type:

       XA f=XA.CMD

     XA calculates sunrise and sunset times based on your latitude and
     longitude, and automatically compensates for any Daylight Savings
     changes.  XA can be programmed to handle events for special dates that
     may be weeks, months, or years in the future.  Best of all, XA can
     automatically update the CP-290 on a once-per-week basis without any
     intervention on your part (an Appliance module is needed to control
     your PC).

     Registered vs. Shareware
     =======================================

     All of XA's features have been enabled for the shareware release.
     These features include IF/ELSE conditional statements, user-defined
     variables, boolean-logical-arithmetic operations, I/O programming,
     plus many other useful functions.

     However, once the evaluation period expires, the shareware version
     will only allow you to store 32 events to the CP-290.  In addition,
     the shareware version will occasionally remind you to register this
     software.  To bypass these reminders and restore XA to its full 128
     event functionality, simply order a registered version of XA.  PsL
     (Public software Library) accepts Discover, Visa, MasterCard, and
     American Express.  PsL also offers convenient registration via the
     World Wide Web.  Members of CompuServe may also order XA from through
     CompuServe's online shareware registration service.  You can also
     order a registered version of XA directly from the author.



     User's Guide and Reference                                           3




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     When you register your copy of XA, you will receive a printed User's
     Manual and a floppy with a `registered' version of XA allowing full
     use of the commands described in this manual.  Refer to REGISTER.TXT
     for complete details.

















































     User's Guide and Reference                                           4




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     New Feature Summary (since version 3.0)
     =======================================

     This section summarizes the enhancements made to XA since the release
     of version 3.0.  Full details are described in later sections.

     BRIGHTEN
     ----------------------

     This `undocumented' command of the CP-290 allows you to create
     artificial sunrises with your Lamp Modules.  These modules can be
     brightened in small steps without initially brightening all the way to
     100% illumination.  See pg 24 for the `BRIGHTEN' token description,
     and Section `Artificial Sunrise` on pg 82 for a sample application.

     Simplified programming
     ----------------------

     The use of tokens DATE and TIME are now optional.  XA will now
     recognize that 7/1/96 is a date, therefore, specifying DATE 7/1/96 is
     redundant.  Likewise, XA assumes that 12:34 AM is a time,  so writing
     TIME 12:34 AM is unnecessary.


     When using the DEFINE token to create an `alias' for selected modules,
     the HOUSE and UNIT tokens are no longer needed in the definition:

       Old way:  DEFINE PORCH HOUSE A UNIT 9
       New way:  DEFINE PORCH A9

     You can now override the default drive and directory path as specified
     by the XA environment variable.  XA will use whatever path you specify
     on the command line.

     CANCEL
     ----------------------

     This new command provides a simple and fast method for removing or
     modifying existing events.  For example, you can cancel all events
     scheduled for module P3 on Tuesday by entering the following command:

       XA `CANCEL P3 TUESDAY'

     See page 55 for more details:

     New Bargraph shows CP-290 event utilization
     --------------------------------------------

     Whenever XA completes a command sequence, a bargraph is displayed
     showing the amount of free and used space in the CP-290.  The %
     utilization is also calculated.


     User's Guide and Reference                                           5




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Improved error reporting and logging.
     --------------------------------------------

     File names and line numbers are reported on the screen as well as
     logged to the file XA.ERR when an error or warning message is
     encountered.

     Improved DATE handling.
     --------------------------------------------

     XA now allows you to program multiple date and date ranges per event.
     If you want to program a event to occur between the following dates:
     2/1...4/2, 6/3...7/1, 8/15...8/17, you would program it as follows:

       A1 ON SUNRISE 2/1 thru 4/2 6/3 thru 7/1 8/15 thru 8/17

     The token `EXCEPT' (see pg. 37) allows you to program events EXCEPT
     when certain dates arrive:

       DEFINE MEMORIAL_DAY 5/31
       BEDROOM_LIGHTS ON WEEKDAYS 6:30 EXCEPT MEMORIAL_DAY

     XA also accepts multiple date ranges following the `EXCEPT' token.

     XA now incorporates a smarter algorithm for determining actual dates
     when a date range is not programmed using the `yyyy' field.  XA can
     easily handle a range of dates that span multiple years.  See pg 37.

     New Tokens: ODD, EVEN
     --------------------------------------------

     You can use the ODD or EVEN tokens for events that you may need to
     execute on odd or even days.  For instance, if local ordinances
     restrict lawn watering to odd/even days based on your home's address
     (assume odd), you'll be able to schedule the watering as follows:

       LAWN_SPRINKLERS ON SUNRISE ODD
       LAWN_SPRINKLERS OFF SUNRISE +:20 ODD

     Non-Volatile variable storage in the CP-290:
     Tokens: NVOL1...NVOL20
     --------------------------------------------

     XA allows you to store up to 20 user-defined variables in the CP-290's
     non-volatile memory.  Once you assign a value to these variables, the
     value will be saved inside the CP-290 so you can access the variable
     during the next XA session.  See `Non-Volatile Variables` on pg 83 for
     further details.





     User's Guide and Reference                                           6




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     EXPAND
     --------------------------------------------

     This token expands a single event command into multiple event
     commands.  For example, if you had a statement such as:

       PORCH ON SUNSET EVERYDAY

     XA would program a single event in the CP-290.  This is fine for
     events that occur at fixed times.  However, for events that are
     programmed based on dynamic data (such as SUNRISE/SUNSET), you would
     get the average sun-time for the next 7 days.  Now, when EXPAND is
     programmed, XA will automatically create individual events using the
     proper sun-time for each scheduled day.

       PORCH ON SUNSET EVERYDAY EXPAND

     This command is also useful when programmed in conjunction with the
     RANDOM token.

     This command is described in more detail on page 32.

     Line Continuation Character - ($)
     --------------------------------------------

     The line continuation character ($) allows long command strings to be
     broken into multiple lines.  See pg 53.

     Declaring Variables
     --------------------------------------------

     In the past, XA would automatically create a variable when the parser
     did not recognize a legal XA token (possibly caused by a misspelled
     token).  All variables are now created with a `DECLARE variable'
     statement (discussed in more detail on page 71).

     Arithmetic operations can be performed on variables.  Variables can be
     substituted for DATES, TIMES, and DAYS.  For example, to program a
     device to activate for 80 days following the first day of Spring:

       DECLARE DATE SPRING = 6/21/95
       DECLARE DATE SPRING_80 = SPRING + 80

       A1 ON SUNRISE SPRING THRU SPRING_80 EXPAND

     Displays PC and CP-290 time
     --------------------------------------------

     Current PC time, CP-290 time and CP-290 basecode are displayed when XA
     is started.



     User's Guide and Reference                                           7




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     New token: SPAWN
     --------------------------------------------

     Spawns a DOS executable file (along with any command line arguments)
     and returns the `errorlevel' code from the program to XA.  For more
     information about this token, see pg. 54.

     New DISPLAY enhancements.
     --------------------------------------------

     You can now DISPLAY the current value of a variable (via DECLARE
     statement) or a DEFINE.  Earlier versions of XA required you to use
     either the DEBUG1 or DEBUG2 tokens which would display ALL DEFINES or
     DECLARES.

     New tokens: INKEY,  F1KEY...F12KEY,
                 SHIFT-F1...SHIFT-F12,
                 CTRL-F1...CTRL-F12,
                 ALT-F1...ALT-F12.
     --------------------------------------------

     These tokens allow a full screen menu to be displayed.  XA reads
     F1...F12 function keys (or combinations of ALT, CTRL, and SHIFT) to
     invoke user-defined actions, such as downloading an event file,
     monitoring CP-290 activity, controlling individual lights, creating
     special lighting sequences, or executing DOS commands.  See pg. 80 for
     more information.

     New REPORT3 token.
     --------------------------------------------

     This command sorts events by event numbers. Placing +r3 on the command
     line also works.  See pg 92.

     New token: STATUS
     --------------------------------------------

     This command returns the expected state of a module as determined by
     the CP-290's event schedule.  You can then use this information to
     program certain actions.

     Refer to the command file LO.CMD which illustrates a sequence of
     commands for `logging off' your computer.  This file determines if
     it's very late at night and whether certain lights need to be
     activated.  It also shows how optional tape backups can be performed
     (based on CDAY) prior to turning the computer off.

     See page 59 for complete details.





     User's Guide and Reference                                           8




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     New tokens: JOYSTICK  and predefined variables:
               JOY1B1, JOY1B2, JOY2B1, JOY2B2 for button switches
               JOY1X, JOY1Y, JOY2X, JOY2Y for resistive inputs.
     ------------------------------------------------------------

     Enhanced game port support allows you to read the current state of the
     (4) joystick switches as well as the resistive values of the (4) X and
     Y positions.  See description on pg 50.

     New tokens: VIDEO7 (for Bargraph attributes)
                 VIDEO8 (for Comment attributes)
     --------------------------------------------

     Attributes have been created for XA's newest features.  In addition,
     you can now prevent certain statements from being displayed.  Simply
     set the VIDEO foreground and background attributes of the selected
     style to the same color.  For example, to stop the display of all
     comment statements:

       VIDEO8  BLACK  BLACK

     If a statement begins with the `#' character (comment symbol), then
     the `#' character will not be displayed.

     New tokens: CHOUR, CMIN, CSEC
     --------------------------------------------

     These tokens contain the current hour, minute, and second,
     respectively.
























     User's Guide and Reference                                           9




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     XA's Other Features
     ===================================

     The following list highlights the other major features of XA.  All
     these features are described in greater detail in later sections of
     this document.

     Improved HELP screens
     --------------------------------------------

     Type `XA /?' at the DOS prompt to get on-line information about XA's
     syntax and features.

     DEMO program for new users.
     --------------------------------------------

     Type DEMOXA to start a special introduction on the capabilities of XA.

     Power-fail recovery mode
     --------------------------------------------

     This feature allows you to restore the programmed state of each module
     in the eventuality of a power failure, a new schedule change, or other
     circumstance.  XA determines the latest state of each programmed
     module by examining the CP-290's event schedule.  Selected modules may
     be excluded from recovery, others can be forced to a particular state
     no matter what XA determines. See page 65 for complete details.

     Program events `EVERY 'n' DAYS'
     --------------------------------------------

     XA now supports programming for events that need to repeat every `n'
     days.  For instance, you need to water your plants every 4 days, but
     it's impossible to schedule using MON, FRI, etc.

     The `EVERY 'n' DAYS' tokens will automatically calculate which days to
     program events.  XA ensures accurate weekly scheduling even when the
     required days do not fall within the same 7-day period. See page 33.

     Automatic Daylight Savings Time adjustment.
     --------------------------------------------

     Use the token DST to have XA determine when changes for Daylight
     Savings or Standard Time should go into effect. This means you only
     have to specify a single timezone token in your initialization file
     (XA.INI).







     User's Guide and Reference                                          10




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     IF/ELSE/ENDIF constructs.
     --------------------------------------------

     Finally! Support for conditional statements within your command files.
     Now you can perform a test the status of a selected module, or see
     whether SUNRISE falls within a certain time period and schedule
     special events based on the result.  IF/ELSE statements can be used to
     test many other conditions.  Feature description begins on pg. 78.

     Variable assignments
     --------------------------------------------

     Variables may be used as temporary storage locations.  These variables
     may then be evaluated later using IF/ELSE constructs to trigger a
     DIRECT command or to program an EVENT.

     Arithmetic / Relational / Logical operators
     --------------------------------------------

     Operations may be performed on variables using Arithmetic (+, - , \,
     *), Relational (<, <=, == , >=, >, !=), and Logical (AND, OR, &&, ||)
     operators.

     Appends new events automatically.
     --------------------------------------------

     You may now easily append a new event from the command line without
     having to figure out where the next `free' event resides in the CP-
     290.  XA finds the empty event slot for you.

     GOSUB/RETURN
     --------------------------------------------

     In addition to GOTO statements, XA now supports calling subroutines
     (GOSUB), and returning to the original calling statement (RETURN).
     See pg. 45

     INPUT/OUTPUT (I/O) control.
     --------------------------------------------

     Use your Joystick port or LPT port as a general purpose Input/Output
     port. Connect switches and/or relays to these ports and program XA to
     react to real-world events.  See pg. 50

     INCLUDE files
     --------------------------------------------

     Use the INCLUDE token to instruct the XA parser to read additional
     initialization or command files. Different files may be included based
     on the results of conditional IF/ELSE statements.  See pg. 57.



     User's Guide and Reference                                          11




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     `ALL_LIGHTS_ON', `ALL_UNITS_OFF'.
     --------------------------------------------

     These `undocumented' CP-290 commands are fully supported.  See pg. 25.

     Faster execution.
     --------------------------------------------

     XA reduces the number of passes required to process a file.
     Sunrise/set calculations are faster.  Also, a new token `FAST' can be
     included in a DIRECT command which informs XA to ignore the CP-290
     acknowledgment message thus speeding up overall execution time.

     Conditional COLOR highlighting.
     --------------------------------------------

     XA can optionally display each line of the XA.INI and command file as
     it's parsed.  You can define your own color attributes for conditional
     statements that evaluate TRUE or FALSE, as well as define special
     color attributes for EVENTS and DIRECT commands.  You can also prevent
     certain command styles from being displayed on the screen. See pg. 66.

     Shell to DOS capability.
     --------------------------------------------

     XA can invoke a copy of COMMAND.COM allowing you to execute a DOS
     program, batch file, etc. from within a command file.  See pg. 57.

     XA can also `SPAWN' DOS programs that return `errorlevel' status which
     can then be evaluated using IF/ELSE logic.

     Utility to locate CP-290 port connection.
     --------------------------------------------

     A utility called FINDX10.EXE searches all 4 COM ports for the CP-290
     interface.  If it is found, you are asked whether you would like the
     parameters stored in the XA.INI file for you.

     Expanded POWERUP.EXE Utility
     --------------------------------------------

     An additional `week' argument has been added allowing you to detect
     certain conditions. For example, on the 2nd Friday of the month,
     update the CP-290 and backup all hard drives.

     Supports COM1...COM4  (Interrupt-driven or Polling)
     --------------------------------------------

     Fully configurable communications. COM1...COM4. Interrupt driven or
     polling.



     User's Guide and Reference                                          12




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     SUNRISE-SUNSET calculations
     --------------------------------------------

     XA calculates precise sunrise/sunset times for your location based on
     the latitude and longitude of your city.

     Specific DATE handling
     --------------------------------------------

     Request any event to occur days, months, even years from now. XA
     expands X10's time base by allowing you to program an event for any
     day in the future, or you can schedule an event to occur between two
     defined dates.  You can also program modules to NOT activate on
     certain dates.

     Time synchronization
     --------------------------------------------

     XA can keep the internal clocks of your PC and CP-290 accurate to
     within 1 second of each other.  You can set either clock based on the
     time maintained by the other clock.

     Miscellaneous Features
     ========================================================

     X10.EXE compatible - creates X10.DAT file with the same module names
     and events that were downloaded by XA.

     Initialization file - XA.INI contains all module definitions,
     communication parameters, location coordinates, and other information
     that will greatly reduce redundant data used in command files.

     The tokens `TIMER', and `PAUSE' let you trigger X10 commands after a
     number of seconds have elapsed, useful for synchronizing X10-
     controlled lights with pre-recorded music.

     `NOW' allows you to program an event relative to the current time (for
     instance, turn off a battery charger 14 hours from now).

     `RANDOM' provides an even better security mode by offering precise
     control of random event times.

     Better reporting facilities.  XA has 3 report formats to document the
     events you downloaded to the CP-290.

     Monitor events as the CP-290 executes them and optionally log them to
     a file.

     You can easily change the basecode without losing all the data already
     stored in the interface.



     User's Guide and Reference                                          13




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     String substitution in the command file allows you to equate a device
     (FAMILY_ROOM_LAMP) with its module address (A3).



     Utilities supplied with XA
     =====================================================

     POWERUP.EXE
     --------------------------------------------

     This utility is provided for those of you who control your computer
     with an X10 Appliance module.  Powerup is designed to be called from
     your AUTOEXEC.BAT file.  You pass arguments to Powerup that specify a
     `window' of time based on day, week, and time. If your computer begins
     its boot phase during this window, it returns an errorlevel of 1,
     otherwise it returns a 0. This errorlevel can then be evaluated by
     simple batch file statements and a number of special functions can be
     executed.  For instance, you can have X10 turn on your computer at
     3:00 AM every Sunday morning and automatically update the CP-290 with
     an entirely new schedule of events.  Your computer can then perform
     disk optimizations, disk backups, communications, etc., without any
     operator intervention. When all is done, a command can be called to
     turn the computer off (XA `COMPUTER OFF').  All this can take place
     while you sleep.  This is what automation is all about!

     FINDX10.EXE
     --------------------------------------------

     This new utility is provided to help you determine the configuration
     of the serial port your CP-290 is connected to. After FINDX10 searches
     all COM ports in your system, it determines the I/O address and IRQ
     level of the port and attempts to communicate with the CP-290. If it
     successfully locates the CP-290, it displays the port setup and
     prompts you if it is OK to save the data in your XA.INI file.

     FINDX10 should be run in a DOS-only environment.  When run in a
     WINDOWS `DOS shell',  FINDX10 may not be able to detect the proper IRQ
     parameters.














     User's Guide and Reference                                          14




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Installation
     ======================================================

     First, copy the contents of this floppy to the same drive and
     directory in which your X10 software resides.  For example, if your
     X10 files are located on Drive C in the directory `X10', and the XA
     installation floppy disk is inserted in Drive A, you would type at the
     DOS prompt:

       C:
       CD \X10
       COPY A:\*.* C:

     If you haven't already done so, include this drive and directory
     within your PATH statement of the AUTOEXEC.BAT file.  The `PATH'
     statement tells DOS where to locate frequently used executable files.

       SET PATH=C:\DOS;C:\X10;...

     You should set the XA environment variable to the drive and directory
     of your command files.  This environment variable, which can also be
     placed in your AUTOEXEC.BAT file, tells XA where to find its
     initialization and command files.

       SET XA=C:\X10

     If you don't understand the concepts of the PATH or SET command, refer
     to your DOS User's Guide and Reference manual. Also, see the
     AUTOEXEC.BAT supplied with this package for an example.

     If you've never used XA before, now would be a great time to see what
     XA is all about. Here's how to start XA's demonstration program - just
     type:

       DEMOXA    (for color or MONOcHROME (LCD) systems)

     Finally, let XA's utility program `FINDX10' search your computer's
     serial ports for the CP-290. FINDX10 will determine the IO port
     address and IRQ (interrupt vector) for that particular port. These
     parameters are important for the successful operation of XA. If the
     CP-290 is located, you will be prompted if it's OK for FINDX10 to
     write those parameters into your XA.INI initialization file. Enter 'Y'
     for YES if you agree with these values.  You can always edit these
     statements later. See the chapter `FINDX10  Utility` on pg 96 for more
     details.

     Please read the file READ.ME that was distributed on this floppy disk
     (or compressed archive). This file contains any last minute
     information that was not included in the printed documentation (or
     XA_320.TXT file).



     User's Guide and Reference                                          15




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     This document will often discuss examples found in other files.  You
     may wish to print these files now so you can study the examples as
     they're being described:  AUTOEXC.BAT, XA.CMD, XA.INI, JOY.CMD,
     JOYSTICK.CMD, XMAS.CMD, LO.CMD, HALOWEEN.CMD and REGISTER.TXT







     Getting Started
     ========================================================

     XA may be invoked several different ways.  How you configured XA, or
     the types of parameters that you use with it, determines how XA
     behaves.

     Method 1 - The `HELP' screen.
     --------------------------------------------

     At the DOS prompt, enter:

       XA

     XA will display the first of many different `help' screens. These
     screens include a brief synopsis of XA, and a list of available
     commands that it recognizes.  NOTE: This method will not work if the
     token XACMD (pg 56) is defined in your XA.INI file. The default XA.INI
     file shipped on this floppy will have XACMD `commented out' (or
     undefined).

     Method 2 - The `HELP' screen.
     --------------------------------------------

     At the DOS prompt, enter:

       XA /?
       XA /h

     Again, XA will display the first of many different `help' screens.
     Use this method if your XA.INI file utilizes the XACMD token and you
     wish to see the help screens.

     Method 3 - Executing a DIRECT Command from DOS.
     ------------------------------------------------

     At the DOS prompt, enter:

       XA `A1 OFF'



     User's Guide and Reference                                          16




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     The above is a direct command which sends an X10 Off command to the
     module with a House-Unit code of A1. Direct commands are always
     executed immediately.

     Method 4 - Storing an EVENT into the CP-290's memory via DOS.
     -----------------------------------------------------------------

     At the DOS prompt, enter:

       XA `A1 ON MONDAY SUNSET'

     XA will determine which event slot is available in the CP-290's
     memory. The event will be downloaded for later execution.

     Method 5 - Executing a Command File
     --------------------------------------------

     At the DOS prompt, enter:

       XA f=XA.CMD

     The file XA.CMD contains a series of EVENT or DIRECT command
     statements.  These statements are either executed immediately as they
     are parsed, or sent to the CP-290 to be activated at some future time.







     Syntax and Command Line Arguments
     =========================================================

     XA understands the following command line options:

        XA   [`commands'...] [f=filename] [-e] [+l] [+m] [+p] [-p] [+u]
             [+r1] [+r2] [+r3] [c=comm port] [i=irq] [o=I/O addr] [/?]



     Options appearing on the command line always override any options that
     have been specified in XA's initialization (XA.INI) file.  This gives
     you the final `say' when overriding defaults.

     Options and commands are parsed from left to right.  Under normal
     circumstances, options may appear in any order without conflicts.
     Many of these options have equivalent tokens that can be embedded
     within a command file or the XA initialization file (XA.INI).
     Therefore, you won't have to specify these options every time you
     execute XA.


     User's Guide and Reference                                          17




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     [`commands']
     -----------------------------------

     `commands' consist of one or more tokens that describe an event or
     direct command.  When you send a DIRECT command or EVENT via the DOS
     command line, a command consisting of several tokens must be enclosed
     in `quotation marks'.  The quotation marks inform XA to treat the
     tokens as a group, not individual commands. For example:

       XA `A1 ON'

     In the above example, A1 and ON are tokens. Together they form a
     single command.  Multiple commands may appear in the command line as
     long as they are enclosed in their own quotation marks.  The next
     example shows the use of multiple commands to create a flashing
     effect.

       XA `A1 ON' `A1 OFF' `A1 ON' `A1 OFF'

     [f=filename]
     -----------------------------------

     This is the name of the file containing the commands to be interpreted
     by XA.  To use XA in its file mode with a command file called
     MONITOR.CMD, you would type:

       XA f=monitor.cmd

     Commands contained in files do not have to be enclosed in `quotation
     marks'.

     XA uses the path specified in the XA environment variable to locate
     command files.  You can override this path by including the
     drive:\directory along with the filename:

       XA f=d:\cmd_files\monitor.cmd

     See also:

       Miscellaneous tokens: XACMD (pg. 56)
       XA.INI - Initialization file  (pg. 79)












     User's Guide and Reference                                          18




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Installation  (pg. 14)

     [-e]
     -----------------------------------

     This option is used to prevent any communications to the interface.
     When you use this option, the parser verifies every statement, but
     does not send any event information or direct commands to the CP-290.



     Use this option for testing new command files, or for examining
     Powerfail Recovery's calculated event state.  Note that a report file
     will still be generated (if specified).  The files X10.DAT and XA.NVL
     will not be updated.

     [c=comm_port]
     -----------------------------------

     This allows you to select the serial port for communications with the
     interface.  You may select ports 1...4. For example, if your CP-290 is
     connected to COM3:

       XA c=3

     If not specified, the default port will be COM1.    When using this
     option, you are actually specifying both an IO address as well as the
     IRQ vector for this port.

     See also:

       Communication tokens: COM1...COM4 (pg. 48)
       Command Line options: [o=io_addr] (pg. 19)
       FINDX10  Utility: (pg. 96)

     [o=io_addr]
     -----------------------------------

     This option allows you to select a different IO address from the
     default 3F8 hex.  If your serial port is setup for 2E8 hex, then use:

       XA o=2E8H

     Under most circumstances, you should not need to use this option.

     See also:

       Communication tokens: IO x  (pg. 19)
       FINDX10  Utility: (pg. 96)

     [i=irq#]
     -----------------------------------

     User's Guide and Reference                                          19




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     XA supports interrupt-driven and polled-mode communications with the
     CP-290.  In general, interrupt-driven communications work best,
     especially if you intend to use XA in a multi-tasking environment such
     as Desqview, Windows, or OS/2, or you're using a slow computer.
     Running in interrupt mode requires a dedicated IRQ line.  If the
     serial port connected to the CP-290 shares an IRQ with another device,
     then use polled-mode communications.  Some bargraphs may not be
     displayed when polled-mode communication is active because slower
     processors can not handle the screen output and incomming data
     transmissions simultaneously.



     Interrupt-driven:

       i=(3,4,5...).
       i=4  (DEFAULT for COM1).

     For polling-mode, use:

       i=0

     See also:

       Communication tokens: IRQ x (pg. .19)
       FINDX10  Utility: (pg. 96)

     [+m]
     -----------------------------------

     This option will monitor the comm port for any events reported by the
     CP-290 after other XA operations have taken place.  Press the <ESC>
     key to terminate.

     If the token XACMD appears in your XA.INI file, or you specified a
     command file with f=file.cmd, then monitoring occurs after the command
     file has been parsed.  To skip parsing of the command file, you can
     use the `MONITOR' token instead:

       XA `monitor'

     See also:

       Reporting tokens:   MONITOR (pg. 64)
       `Monitoring and Logging Events' (pg. 93)

     [+l]
     -----------------------------------

     This option will append any monitoring information to the file XA.LOG.
     The report file will be saved on the same drive and directory as was
     specified by the XA environment variable (discussed in `

     User's Guide and Reference                                          20




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Installation` on pg. 14).

     See also:

       Reporting tokens: LOG (pg. 64)
       `Monitoring and Logging Events' (pg. 93)



     [+r1]
     -----------------------------------

     This option will produce a report file (called XA.RPT) of all events
     that were just processed by the interpreter.  The format of the report
     contains a sorted list of events (based on time) for each day of the
     week.

     See also:
       Reporting tokens: REPORT1 (pg. 64)
       `Report Files' (pg. 90)

     [+r2]
     -----------------------------------

     This option will produce a report file (called XA.RPT) of all events
     just processed by the interpreter.  The format of the report contains
     a sorted list of events (based on time), for each module, for each day
     of the week.  The report file will be saved on the same drive and
     directory as was specified by the XA environment variable (discussed
     in `Installation' pg. 14).  Any existing reports called XA.RPT will be
     overwritten.  You may specify both report types to be included in the
     same file, as in the following example.

       XA +r1 +r2

     See also:
       Reporting tokens: REPORT2 (pg. 64)
       `Report Files' (pg. 91)

     [+r3]
     -----------------------------------

     This option will produce a report file (called XA.RPT) of all events
     that were just processed by the interpreter.  The format of the report
     contains a sorted list of events based on the event number, or the
     order in which events are stored in the CP-290.

     See also:

       Reporting tokens: REPORT3 (pg. 64)
       `Report Files' (pg. 90)


     User's Guide and Reference                                          21




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     [+u]
     -----------------------------------

     XA is able to bypass the lengthy event uploads from the CP-290 by
     reading a copy of the schedule stored in the X10.DAT file.  Some
     shareware programs may not update this file properly, causing a
     possible conflict when XA appends new events to the CP-290's memory,
     or when a powerfail recovery is attempted.  Use the `+u' option to
     force XA to upload the schedule prior to any other processing.  Later,
     XA will restore X10.DAT to reflect the latest schedule.

     [+p]
     -----------------------------------

     Parses command file, then performs powerfail recovery.

     [-p]
     -----------------------------------

     Immediate recovery based on stored events, no parsing of command file
     takes place.

     Powerfail recovery allows you to restore each programmed module to its
     scheduled state. By default, XA uses the last 6 days to determine the
     state.  You can tell XA to use fewer days if necessary. Simply append
     a number between 1 and 6 to the command. If you want XA to review the
     event schedule of the previous 2 days in order to determine the
     correct state, then append a 2 to the command, for example:

       XA -p2

     Use `-e' in conjunction with either `+p' or `-p' to see how XA would
     restore each module without actually sending any X10 commands.  You
     can use `+u' to ensure the latest events are uploaded and analyzed
     prior to recovery.

     See also:

       `Powerfail Recovery' (pg. 65)

     [/?][/h][/H]
     -----------------------------------

     Displays a summary of the options described above, along with a list
     of all supported tokens recognized by the interpreter.








     User's Guide and Reference                                          22




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     XA Tokens
     ==================================

     What are tokens?
     -----------------------------------

     A token is to an X10 command as a word is to an English sentence.
     Individual words are constructed to form a complete sentence - tokens
     are constructed to form a complete command.  This section will
     describe each token that is recognized by the interpreter. Some tokens
     may appear anywhere in the command.  For example, the command:

       XA `A1 ON'    (may also be constructed as):
       XA `ON A1'

     In other instances, tokens must be arranged in groups.  Their order is
     important.  For example, the command to set your PC's internal clock
     to the time that is maintained by the CP-290 is:

       XA `SYNCHRONIZE PC' <---This is legal

     If the tokens SYNCHRONIZE and PC were reordered as in the following
     command:

       XA `PC SYNCHRONIZE' <---This is illegal

     The interpreter would respond with a message indicating it did not
     recognize the token.  Therefore, throughout this documentation any
     tokens that must be arranged in a certain order will be contained in
     curly braces {..}.  Other tokens may be optional and will be contained
     in square brackets [..].

     When XA encounters a syntax error in a command,  XA responds by
     displaying the filename, line number, and statement where the error
     was found.  In addition, this information is also placed in an error
     file called XA.ERR.  This file will be located on the same drive and
     in the same directory as specified by the XA environment variable.
















     User's Guide and Reference                                          23




           XA - X10 COMMAND INTERPRETER - VERSION 3.2




     Tokens in Detail
     =================================================

     Most of the examples in this chapter describe how the tokens may be
     used from the DOS command line. Therefore, the tokens that make up a
     complete command will be enclosed in `quotation marks'.  Other
     examples show how the tokens may be used in a file, therefore,
     quotation marks are not used, or needed.

     Action Tokens
     =================================================

     ON
     -----------------------------------

     This token informs the interface to turn the selected modules ON.

       XA `A1 ON'



     OFF
     -----------------------------------

     This token informs the interface to turn the selected modules OFF.

       XA `A1 OFF'



     {DIM %%}
     -----------------------------------

     These two tokens specify the intensity level of the selected lamp or
     wall switch module.  The modules will turn on, brighten to full
     intensity, then dim to the percentage specified in the second token.
     There are 16 different brightness levels available, the percentage you
     choose (0 to 100) is mapped to one of these levels.  Refer to `Table 4
     - Dimming Ranges' on page 62 for brightness level mappings.

       XA `A1 DIM 50'

     The percentage level you select may not correspond exactly with level
     reported by the X10-supplied program X10.EXE.

     {BRIGHTEN ##}
     -----------------------------------

     The {BRIGHTEN ##} command invokes an undocumented feature of the
     CP-290.  With this command, you can brighten a LAMP module in very

     User's Guide and Reference                                          24




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     small steps without having the CP-290 ramp the module to 100% full
     brightness as it normally does with the DIM command.

     The ## value is a relative increment, not an absolute level.  If you
     issue a `BRIGHTEN 1' command, the selected module will increase its
     brightness level by 1 step.  A `BRIGHTEN 5' will brighten the module
     by 5 steps.


     This effect is useful for creating an artificial sunrise.  During the
     winter months you can program a light in your bedroom to brighten
     gradually in 16 steps over a period of time.  See chapter `Artificial
     Sunrises on pg. 82 for further information.

     This command only works with LAMP modules, NOT WALL switches.  In
     fact, WALL switch modules will be TURNED OFF when a LAMP module with
     the same Housecode is BRIGHTENed.  That's because the CP-290 sends an
     `ALL_LIGHTS_OFF' command prior to the BRIGHTEN command.  You are
     hereby advised to use BRIGHTEN command only on LAMP modules that do
     not share the same housecode as WALL switches.


     An anomaly with X10 LAMP modules (and Wall Switch modules, too) is
     that if they are currently OFF, and then they are issued a BRIGHTEN
     command, they will turn on to 100% full brightness and stay at that
     level until they are dimmed or turned off.  Therefore, if you want to
     create a realistic sunrise effect, make sure that you DIM the
     appropriate module to 0% brightness instead of turning it OFF.

     {ALL_UNITS_OFF HOUSE x}
     -----------------------------------

     These tokens will issue the X10 `ALL_UNITS_OFF' command for the
     selected housecode. This command affects Appliance-style and Lamp
     Dimmer/Wall Switch modules.

       XA `ALL_UNITS_OFF HOUSE A'

     Using this command is faster than issuing: (as described on pg. 27).

       XA `HOUSE A UNIT ALL OFF'

     During Powerfail Recovery, XA converts events programmed as
     ALL_UNITS_OFF to individual OFF commands.

     {ALL_LIGHTS_ON HOUSE x}
     -----------------------------------

     These tokens will issue the X10 `ALL_LIGHTS_ON' command for the
     selected housecode. This command affects only Lamp Dimmer/Wall Switch
     modules.


     User's Guide and Reference                                          25




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


       XA `ALL_LIGHTS_ON HOUSE A'

     Powerfail Recovery does not attempt to restore any modules activated
     by the ALL_LIGHTS_ON command.  XA has no way of determining which
     modules (appliance vs. lamp/wall modules) can be controlled by this
     action.



     ACTION TOKEN NOTES:
     =================================

     Only one token in this category should appear in a command. If two or
     more of these tokens appear, only the last one will be processed.  For
     example:

       XA `A1 ON OFF'  -  will be interpreted as:
       XA `A1 OFF'

     If you are trying to flash the lights, the proper way to perform this
     action is:

       XA `A1 ON'  `A1 OFF'

     You may activate as many modules as you want in a single command
     providing these modules share the same HOUSE code:

       XA `A1 A2 A3 A4 A5 A6 ON'

     To activate modules with different HOUSE codes, use separate commands:

       XA `A1 A2 A3 ON'  `B1 B2 ON'  `C1 OFF'





















     User's Guide and Reference                                          26




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Module Address Tokens
     ===========================================

     A1...P16
     -----------------------------------

     This is a shortcut method of specifying both HOUSE and UNIT tokens.
     The house code must appear first, followed by the unit code.
     Specifying ALL is not permitted.

       XA `A1 ON'  `P16 OFF'

     {HOUSE x}
     -----------------------------------

     These two tokens specify the HOUSE code of the module you want to
     select.  There are 16 HOUSE codes available,  lettered A through P.
     This method of selecting addresses requires the use of the UNIT token.
     Only one HOUSE token should appear in a command.

     {UNIT y}
     {UNIT ALL}
     -----------------------------------

     These two tokens specify the UNIT code of the module you want to
     select.  There are 16 UNIT codes available, numbered 1 through 16.
     Specifying UNIT ALL operates on all 16 modules addressed by the HOUSE
     token.  This method of module addressing requires the use of the HOUSE
     token:

       XA `HOUSE A UNIT 1 ON'   or,
       XA `UNIT 1 HOUSE A ON'



     MODULE ADDRESS TOKEN NOTES:
     ====================================

     Multiple UNITs may appear in a single command:

       XA `HOUSE A UNIT 1 UNIT 2 UNIT 3 ON'

     Turn off all units on HOUSE P:

       XA `HOUSE P UNIT ALL OFF'
       XA `HOUSE P ALL_UNITS_OFF'    (This is the faster method)

     You may activate as many modules as you want in a single command
     providing these modules share the same HOUSE code:

       XA `A1 A2 A3 A4 A5 A6 ON'


     User's Guide and Reference                                          27




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     To activate modules with different HOUSE codes, use separate commands:

       XA `A1 A2 A3 ON'  `B1 B2 ON'  `C1 OFF'

     You can give your module's more descriptive names by using the DEFINE
     token (pg. 52). For instance, place the following line in your XA.INI
     file:

       DEFINE COFFEE A10

     To turn the coffee pot ON from your computer, all you have to type is:

       XA `COFFEE ON' or
       XA `A10 ON'

     Coordinate Tokens
     ========================================

     This group of tokens enable the precise calculation of sunrise and
     sunset times for your location.  This information can be found in
     almanacs, or extrapolated from maps.  Coordinates for major US cities
     may be found in the file US_LATIT.TXT supplied with XA. Your local
     library or city hall may also have your city's precise coordinates.
     These tokens should be placed in your XA.INI file so that all command
     files will be able to calculate sun-related events.

     {LATITUDE dms}
     {LATITUDE . ' `}
     -----------------------------------

     Your latitude in degrees (0...+/-90), minutes (0...59) and,
     optionally, seconds (0...59).

       LATITUDE 41.35'20'     # Mentor, OH.  USA
       LATITUDE -33d53m    # Sydney, Australia

       {LONGITUDE dms}
       {LONGITUDE . ' `}

     Your longitude in degrees (0...+-180), minutes (0...59) and,
     optionally, seconds.  Longitudes west of the prime meridian are
     positive, those east of the prime meridian are negative.  In the US,
     all longitudes are positive.

       LONGITUDE 81.20'45'    # Mentor, OH.  USA
       LONGITUDE -151d10m     # Sydney, Australia







     User's Guide and Reference                                          28




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     {TIMEZONE x}
     -----------------------------------

     Exact calculations depend on the local time.  Use the following table
     to determine your time zone.  Use the DST token to automatically
     adjust time changes.


     ZONE              TIMEZONE


     Eastern           5


     Central           6


     Mountain          7


     Pacific           8


     Alaska/Hawaii     10


     Aleutian          11


     Table 1 - US Timezones



     Longitudes that are east of the Prime Meridian should use negative
     timezone values.

       TIMEZONE 5     # Mentor, OH.  USA
       TIMEZONE -10 # Sydney, Australia

     DST
     -----------------------------------

     Use the token DST to have XA determine when changes for Daylight
     Savings or Standard Time should go into effect. This means you only
     have to specify a single timezone token in your initialization file
     (XA.INI).

       TIMEZONE 5  DST





     User's Guide and Reference                                          29




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Clock Tokens
     ==========================================

     {SYNCHRONIZE PC [EXACT] }
     -----------------------------------

     These tokens instruct XA to set your computer's clock based on the
     current time retrieved from the CP-290.  It will not affect the
     computer's date.

       XA `SYNCHRONIZE PC'

     Use the optional `EXACT' token to wait for the X10 time to rollover to
     the next minute.  This provides a synchronization within 1 second, but
     forces you to wait for up to one minute for this rollover to happen.
     XA instructs you to press any key to forego the wait period.

       XA `SYNCHRONIZE PC EXACT'



     {SYNCHRONIZE X10 [EXACT] }
     -----------------------------------

     These tokens instruct XA to set the time and day of the CP-290
     internal clock based on the current time retrieved from your computer.

       XA `SYNCHRONIZE X10'

     Using `EXACT' will force XA to wait until the PC's clock to rollover
     to the next minute.  This provides a synchronization within 1 second,
     but forces you to wait for up to one minute for this rollover to
     happen.  XA instructs you to press any key to forego the wait period.

       XA `SYNCHRONIZE X10 EXACT'

     You might want to include the command XA `SYNCHRONIZE PC' in your
     AUTOEXEC.BAT file to set your PC's internal clock if your system lacks
     an on-board battery backed-up clock.  Note that this command will not
     set up the date since the CP-290 does not contain a real-time
     calendar.



     Use XA `SYNCHRONIZE PC' or XA `SYNCHRONIZE X10' in your AUTOEXEC.BAT
     file if either your PC or CP-290 does not keep accurate time.







     User's Guide and Reference                                          30




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Day Tokens
     =======================================

     Use of these tokens indicates a timed event, i.e., the complete
     command will be downloaded to the interface and stored there for later
     activation.

     SUNDAY, SUN
     MONDAY, MON
     TUESDAY, TUE
     WEDNESDAY, WED
     THURSDAY, THU
     FRIDAY, FRI
     SATURDAY, SAT
     -----------------------------------

     These tokens describe the specific day of the event.  Multiple day
     tokens may appear within a command.

       XA `MONDAY FRIDAY A1 ON TIME 7:30 AM'

     WEEKENDS, WEEKEND
     -----------------------------------

     Event occurs on SATURDAY and SUNDAY.

     WEEKDAYS, WEEKDAY
     -----------------------------------

     Event occurs MON, TUE, WED, THU, FRI.

     EVERYDAY
     -----------------------------------

     Event occurs MON TUE WED THU FRI SAT SUN.

     TODAY
     -----------------------------------

     Event will occur today only at the specified time.  It is then deleted
     from the interface after midnight.  If `OFFSET hh:mm' (pg. 39) is also
     programmed causing the event to trigger after midnight, the event will
     be modified for TOMORROW status.

     TOMORROW
     -----------------------------------

     Event will occur tomorrow only at the specified time.  It is then
     deleted from the interface after midnight.  If `OFFSET hh:mm' (pg. 39)
     is also programmed causing the event to trigger before midnight, the
     event  will be modified for TODAY status.


     User's Guide and Reference                                          31




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     ODD
     -----------------------------------

     Event will be programmed to occur on odd numbered days of the month.
     For instance, if local ordinances dictate that you can only water you
     lawn on odd-numbered days, you can program your X10-controlled
     sprinkler system as follows:

       ZONE1 ON SUNRISE ODD
       ZONE1 OFF SUNRISE + :15 ODD

     Without any DAY tokens in the command, XA will assume EVERYDAY.  You
     can limit the programmed days by adding DAY qualifiers.  For example,
     control the a sprinkler zone to activate on odd weekdays as follows:

       ZONE2 ON SUNRISE + :15 WEEKDAYS ODD
       ZONE2 OFF SUNRISE + :30 WEEKDAYS ODD

     EVEN
     -----------------------------------

     Event will be programmed to occur on even numbered days of the month.
     See the `ODD' token above for similar examples

     EXPAND
     -----------------------------------

     This token will automatically expand a single event command into
     multiple event commands.

       A1 ON SUNSET EVERYDAY EXPAND

     will expand to:

       A1 ON SUNSET SUNDAY
       A1 ON SUNSET MONDAY
       A1 ON SUNSET TUESDAY
            :
       A1 ON SUNSET SUNDAY

     or any other DAY sequence you programmed.

     Use EXPAND for dynamic events such as those that are based on
     sunrise/set times.  This allows exact sun times to be used for each
     day rather than using the average sun time for the upcoming week.

     When used in conjunction with RANDOM (pg 32), unique random values
     will be used for each day rather than using the same value for all
     days.

       A1 OFF 11:30 RANDOM 10 EVERYDAY EXPAND


     User's Guide and Reference                                          32




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     The advantage of using this token is that it reduces the overall size
     of your command file because fewer statements are required.  However,
     keep in mind that command expansion consumes additional event storage
     in the CP-290.  It's possible that your schedule may exceed the
     capacity of the interface's memory.  The bargraph that appears after
     an XA session should help you determine the event utilization of your
     CP-290.

     Only use EXPAND for dynamic (sun-related, or random) events only.
     Events that occur at a fixed time each day do not need to be expanded.

     {EVERY 'n' DAYS [FROM mm/dd/yyyy] }
     {EVERY 'n' WEEKS [FROM mm/dd/yyyy] }
     -----------------------------------

     These tokens allow you to specify an event to repeat itself every 'N'
     days. Suppose you have a garden irrigation system that must be
     activated every 5th day.  It's impractical to use the DAY tokens (MON,
     SAT, etc.) because each week would require a different set of days to
     be programmed. Using `Every 'n' Days' solves this problem by correctly
     specifying the required days on a weekly basis.

       GARDEN ON SUNRISE EVERY 5 DAYS

     Assuming you schedule XA to update the CP-290 every Sunday (using
     POWERUP), the module addressed as GARDEN would be programmed as
     follows:

     Week 1:
       SUN - JULY 24, 1994
       FRI - JULY 29, 1994
     Week 2:
       WED - AUGUST 3, 1994
     Week 3:
       MON - AUGUST 8, 1994
       SAT - AUGUST 13, 1994

     Use the optional `FROM mm/dd/yyyy' tokens if you need to change the
     `period' of the event and you want to specify the new date which the
     event should be based on.

     For instance, after Week 2 you want to activate GARDEN every 6 days
     instead of 5.  If all you did was change the statement to:

       GARDEN ON SUNRISE EVERY 6 DAYS

     The result would be:

     Week 3:
       SUN - AUGUST 7, 1994
       SAT - AUGUST 13, 1994


     User's Guide and Reference                                          33




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     This is not what you wanted, since the difference between Aug. 3 and
     Aug. 7 is only 4 days. To offset this effect, include a reference date
     so XA can calibrate subsequent events.

       GARDEN ON SUNRISE EVERY 6 DAYS FROM 8/10/1994

     The results are:

     Week 3:
       TUE - AUGUST 9, 1994

     Activate the garden irrigation control between during the Spring and
     Summer:

       4/15 THRU 8/31 GARDEN ON SUNRISE EVERY 6 DAYS FROM 4/15

     You can also program an event cycle based on the number of WEEKS
     instead of days. Use the optional FROM mm/dd/yyyy tokens to specify
     the reference date to calibrate XA.



     DAY TOKEN NOTES:
     ==============================

     If you leave off a DAY token when downloading an event to the CP-290,
     XA will assign the command as a TODAY-only event. Therefore, at
     midnight the event will be cleared from the CP-290's memory. The
     following command will take place at 11:00 tonight and be deleted at
     midnight since it was given `TODAY' status (no other DAY was
     specified):

       XA `FAN ON 11:00 PM'

     See section Variables (DECLARE DAY -pg. 71) for an example of
     programming events to occur on random days.

     Using the `CDAY' token in conjunction with `SAT, SUN MON, TUE, WED,
     THU, FRI, WEEKEND, WEEKDAY' tokens allows you to program special
     functions based on the current day. For example, the statements below
     will the initialize the default command file (using XACMD) based on
     the current day.

       IF ((CDAY == SAT) OR (CDAY == SUN))
          XACMD WEEKEND.CMD
       ELSE  
          XACMD WEEKDAY.CMD
       ENDIF

     See `Programming Additions' (pg. 69) for a detailed explanation of
     this topic.


     User's Guide and Reference                                          34




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Specific Date Tokens
     ============================================

     Since the CP-290 does not contain an on-board calendar, there is no
     direct method of storing an event that occurs more than 1 week away.
     However, XA has the ability to evaluate dates and as long as XA is run
     at least once a week it can determine the appropriate time to download
     the event.  This feature allows you specify an event weeks, months, or
     years in advance.

     Date features:

     You can specify an event to occur on specific days of each month (such
     as every 10th day of the month), or annually (every 4th of July).

     Events may be scheduled to trigger on selected days between specific
     dates (such as Christmas and New Year's).  You can also program an
     event to NOT happen on an individual date, or between certain dates.

     XA makes use of screen color control (see VIDEO - pg. 66) to show you
     if a scheduled event meets date criterion.

     To guarantee that specific dates will be evaluated and events will be
     triggered at the proper time in the future, plug your computer into an
     Appliance module and have the CP-290 turn your computer on
     automatically on a once-per-week basis.  By using XA.EXE in
     conjunction with POWERUP.EXE (supplied with this package) you can have
     a new set of events automatically downloaded to the CP-290.  Now
     you'll never forget to update your CP-290, your computer does it for
     you automatically.  This is what `automation' is all about.  See
     section `Powerup' on pg. 95 for more details.

     When using the following `DATE' tokens, you should include the `ERASE'
     token at the beginning of your command file.  ERASE will clear the
     entire contents of the CP-290, removing all event information. The
     reason you want to erase its memory is because once XA downloads an
     event to the CP-290, it will remain there until it is deleted or
     overwritten.  The next time XA is run (next week) the event may still
     remain and trigger itself again and again until it is either manually
     deleted, or eventually overwritten by a new event. ERASE ensures that
     the data is cleared and that the interface will contain fresh
     information.  Also, since all your information is stored in a command
     file, the relevant information will always be placed in the CP-290.










     User's Guide and Reference                                          35




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     { mm/dd/yyyy}
     -----------------------------------

     Event occurs on specified date.  You must specify the date in the
     following format:

     Month  - none, 1, or 2 digits (1 = Jan ...  12 = DEC)
     Day    - none, 1, or 2 digits
     Year   - none, 2, or 4 digits

     To specify module A5 ON July 4, 1997 at 5:00 PM:

       A5 ON 7/4/1997 TIME 5:00 PM

     You may omit fields which is the equivalent of specifying any month,
     day, or year.  Each field must be delineated by a separator, either a
     '/' or '-' character.  For example, to specify module A5 to turn OFF
     on the 4th of every month at 6:00 AM:

       /4/ A5 OFF TIME 6:00 AM

     To specify module A5 to turn ON every 4th of July at sunset, leave off
     the `yyyy' field:

       7/4/ A5 ON SUNSET

     An exception to the separator requirement arises when the `yyyy' is
     not being programmed -simply omit the '/' or '-' character between the
     `dd' and `yyyy' fields. The above statement could be written as:

       7/4 A5 ON SUNSET

     You may specify multiple dates in the same command:

       7/4  7/6  7/8 A5 ON SUNSET



     { mm/dd/yyyy THRU mm/dd/yyyy [MON TUE...] }
     -----------------------------------------------

     The event will occur EVERYDAY between the two dates unless you place
     specific DAY tokens within the command.  Use the same date format
     conventions as described above.

     If you will be going on vacation between July 1, 1997 and August 1,
     1997, and you want the bedroom lights (A3) turned ON and OFF every
     weekday in security mode during the evenings:

       7/1/1997 THRU 8/1/1997  ON  A3   9:00 PM SECURITY WEEKDAYS
       7/1/1997 THRU 8/1/1997 OFF  A3  11:30 PM WEEKDAYS


     User's Guide and Reference                                          36




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     To turn ON your Christmas lights everyday between Thanksgiving and New
     Year's Eve, turn them OFF at 10:00PM on weekdays, and turn them off at
     11:30 during the weekends:

       DEFINE THANKSGIVING 11/24/96
       DEFINE NEW_YEARS_EVE 12/31/96
       THANKSGIVING THRU NEW_YEARS_EVE  XMAS ON SUNSET
       THANKSGIVING THRU NEW_YEARS_EVE XMAS OFF 10:00 PM  WEEKDAYS
       THANKSGIVING THRU NEW_YEARS_EVE XMAS OFF 11:30 PM  WEEKENDS

     You can now program multiple date ranges for a given event.

       PORCH ON SUNSET 1/21 thru 4/2  7/1 thru 7/6  8/15 thru 9/6

     EXCEPT
     -----------------------------------

     Once XA parses this token, any DATE (or DATE...THRU) statements become
     `exceptions', that is, events will not be scheduled to activate during
     that date (or period). For example, to turn a lamp (A7) on every
     weeknight except Memorial Day:

       A7 ON WEEKDAYS SUNSET EXCEPT  5/31

     You may specify multiple exception dates in the same command:

       A7 ON WEEKDAYS SUNSET EXCEPT  5/31  7/1



     SPECIFIC DATE TOKEN NOTES:
     ===============================

     Events that are not downloaded because they do not meet the date range
     criteria will be displayed using the VIDEO2 (pg 66) screen attributes
     (to signify a FALSE condition).


     Use the format:

       { EXCEPT mm/dd/yyyy THRU mm/dd/yyyy [DAY] }

     to  prevent an event from occurring between two dates.  EVERYDAY will
     be assumed unless you place specific DAY tokens within the command.
     For example, to prevent the porch lights from coming on while your
     Christmas lights are on:

       PORCH ON SUNSET EXCEPT  12/1  THRU 1/1





     User's Guide and Reference                                          37




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Use the format:

       { mm/dd/yy THRU  mm/dd/yy EXCEPT  mm/dd/yy THRU  mm/dd/yy}

     to specify a range of dates that a module should not activate, within
     a range of dates that it should be activated.  For instance, turn on
     deck lights only during the summer, except while you are on vacation:

       DECK ON SUNSET  6/21 THRU 9/22 EXCEPT  7/1 THRU 7/14

     You can perform date arithmetic using XA's enhanced operation with
     variables.  See the topic `Variables` (DECLARE DATE on page 69) for
     more information.

     XA now calculates the year for you if you don't use the `yyyy' field
     when programming date ranges.  Using the next example, see how XA
     adjusts the date based on the current date.

       DECK ON 8/1 thru 4/1 SUNSET

     If the current date is 3/15/97, then the adjusted date range is 8/1/96
     thru 4/1/97, and the event would be programmed.

     If the current date is 7/1/97, then the adjusted date range is 8/1/97
     thru 4/1/98, and the event would not be programmed.

     If the current date is 9/6/97, then the adjusted date range is 8/1/97
     thru 4/1/98, and the event would be programmed.

























     User's Guide and Reference                                          38




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Time Tokens
     ===============================

     Use of these tokens indicate a timed event, i.e., the complete command
     will be downloaded to the interface and stored there for later
     activation.

     { hh:mm [AM/PM] }
     -----------------------------------

     Schedule event at a certain time.

       XA `D1 ON SUNDAY 12:34 AM'

     AM is the default. You may specify military-style time as follows:

       XA `D1 ON SUNDAY 23:45'

     SUNRISE
     SUNSET
     -----------------------------------

     These tokens will calculate the sunrise or sunset for the day token in
     the command.  The use of these tokens also requires the LATITUDE,
     LONGITUDE, and TIMEZONE (and optional DST) tokens to be included in
     the XA.INI file.

       D1 ON MONDAY SUNSET

     If multiple day tokens appear in the command line, the sunrise or
     sunset time will be the average sunrise/set time for the next seven
     days.

       MONDAY TUESDAY WEDNESDAY ON SUNSET D1

     Use the EXPAND token (see pg. 32) to generate additional events for
     more accurate sun times when multiple DAYS are programmed in a single
     statement.

       MONDAY TUESDAY WEDNESDAY ON SUNSET D1 EXPAND

     { [OFFSET] +/-hh:mm}
     -----------------------------------

     Push or postpone the scheduled event by up to 24 hours (1440 minutes).
     This token is useful if you want to activate lights at dusk rather
     than sunset, or to deactivate lights at dawn rather than sunrise.  The
     '+' sign is the default condition, you must specify the  '-' if
     needed.  To turn ON lights 30 minutes after sunset:

       D1 ON MONDAY SUNSET OFFSET :30


     User's Guide and Reference                                          39




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     The OFFSET token is now optional.  XA recognizes the `:' within a
     numeric string as a time offset value.  To turn lights OFF 30 minutes
     before sunrise:

       D1 OFF MONDAY SUNRISE  - :30

     Use DEFINEs (see pg. 52) for another way of specifying DUSK or DAWN
     using the DEFINE token.  For example:

       DEFINE DUSK SUNSET  :30
       DEFINE DAWN SUNRISE  - :30
          :
       D1 ON MONDAY DUSK
       D1 OFF  MONDAY DAWN



     {NOW +mm}
     {NOW +hh:mm}
     -----------------------------------

     Creates a one-shot event based on the current DOS day and time, and
     the hh:mm offset specified in the token. The event will initially be
     given a `TODAY' status.  If the added offset causes the event to be
     scheduled past midnight, the event will be converted to `TOMORROW'
     status.  In either case, the event will be deleted from the CP-290 at
     midnight following its activation.

     The following command file example shows how to activate a battery
     charger and then turn it off 14 hours later. The example file is
     called CHARGER.CMD.

       DEFINE CHARGER H1
       CHARGER ON        # Turn the charger on...
       CHARGER OFF NOW 14:00  # Have the CP-290 turn it off 14 hrs later

     {RANDOM +/-hh:mm}
     {RANDOM +/-mins}
     -----------------------------------

     These tokens surpass the CP-290's built-in security feature by
     providing greater control over the random event sequence. `HH:MM' is
     the number of hours and minutes that a random offset should be
     added/subtracted from the programmed time. This offset should be in
     the range of 1 minute to 24 hours (1440 mins).

     If `hh:mm' is programmed with a `+' sign, then the calculated random
     value will be added to the programmed time. The following example will
     add between 0 and 9 minutes to the requested time, that is, anywhere
     between 5:00 PM and 5:09 PM.

       A5 ON  5:00 PM RANDOM +9

     User's Guide and Reference                                          40




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     If `mm' is programmed with a `-' sign, then the calculated random
     value will be subtracted from the programmed time. The following
     example will subtract between 0 and 15 minutes from the calculated
     SUNRISE time. If SUNRISE occurs at 6:00 AM, then the resulting time
     could be anywhere in the range of 5:45 through 6:00.

       A5 OFF SUNRISE RANDOM -:15

     If `mm' is programmed without any sign, then the calculated random
     value will either be added or subtracted to/from the programmed time.
     For example, to allow 90 minutes on either side of SUNSET:

       SUNSET RANDOM 1:30     # TIME ranges between 7:30 PM ... 10:30 PM

     RANDOM, as well as OFFSET, will automatically change the day if the
     adjustment causes a rollover into the previous or next day.

     Use the EXPAND token (see pg. 32) when multiple days are programmed in
     a single command.  This will ensure that a unique random time will be
     generated for each day:

       A5 ON EVERYDAY SUNSET RANDOM 1:30 EXPAND

     NORMAL
     -----------------------------------

     This token activates the event at the specified time.  It is the
     default mode, therefore it does not need to be specified.

     SECURITY
     -----------------------------------

     This token allows the CP-290 to pseudo-randomly select the activation
     time of the event.  This activation occurs within the hour of the
     programmed time.  Therefore, if the downloaded time was for 7:30 PM,
     actual activation time could range from 7:00 PM through 7:59 PM. This
     mode provides a security feature giving your lighting a more lived-in
     look.

       XA `A1 ON 7:30 PM SECURITY EVERYDAY'

     Do not program a module to turn ON and OFF in the same hour using the
     SECURITY token.  The CP-290 may not produce the desired results
     because the events can occur any time during the programmed hour.  The
     RANDOM token (pg 40) provides greater flexibility for multiple events
     programmed during the same hour.







     User's Guide and Reference                                          41




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Direct Command Control Tokens
     ==============================================

     The following tokens may be used within an XA command file so you can
     use the CP-290 to perform a series of lighting effects. Certain
     commands may be repeated a limited number of times or forever.
     Commands may also be synchronized with a key press, allowing special
     effects with a high degree of accuracy.  XA can also read data from an
     I/O port, allowing X10 commands to be synchronized with an external
     event.

     XA maintains an internal timer which allows you to synchronize
     lighting commands to specific time points.  The timer is initialized
     to 0 when XA is started, and increments itself every 1/10 second.  The
     timer is reset to 0 whenever the RESET token is issued, or following
     any keypress after the PAUSE token.

     PAUSE
     -----------------------------------

     When this token is executed, it halts further execution of the command
     file and displays the message:

       `Press any key to continue. . . .'

     When a key press is detected, XA's internal timer is reset to ZERO,
     and any remaining commands are executed. The internal timer is used in
     conjunction with the TIMER token.  This command is useful for
     synchronizing a series of commands to an external event.  See TIMER
     below, for an example.

     [module command] TIMER hh:mm:ss.s
     -----------------------------------

     This token informs XA to issue a command when the internal timer
     reaches `hh:mm:ss.s'.  The internal timer is initialized to 0 when XA
     is invoked, or whenever a key press follows a PAUSE command, or when
     the token `RESET' is parsed. All subsequent TIMER commands are
     evaluated from the point at which the internal timer was initialized.

     One very useful application of the PAUSE and TIMER commands is to
     synchronize X10-controlled lighting sequences with pre-recorded music.
     For instance, you could assign each song its own command  file.  Each
     file would start off with a PAUSE token to initialize the timer, or
     you could detect a contact closure using the INPORT token.  This
     provides a means to start the music and command chain from a common
     point.  TIMER statements would specify the exact times that the CP-290
     would trigger an X10 command at an appropriate moment in the song.

       PAUSE             # Wait for any key press, reset timer
       A1 ON TIMER 0:0:10.0     # At 10 seconds, turn on A1
       A1 DIM 0 TIMER 0:0:20.5  # At 20.5 seconds, fade light out.

     User's Guide and Reference                                          42




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     In this example, the PAUSE waits for a cue to start the sequence. 10
     seconds later, A1 is activated. 20.5 seconds after the cue, A1 is
     DIMMED to a level 0.

     XA will automatically anticipate and adjust for any delays that may be
     caused by the CP-290.  For instance, due to CP-290 communications, the
     amount of time it takes to turn on a lamp may take as much as 1.4
     seconds from the time the command is initially sent.  Even worse, the
     CP-290 forces a lamp module to go to the fully BRIGHT state before
     allowing the module to be dimmed - delaying the actual effect by 6
     seconds.  In order to have XA compensate for these delays, you should
     place an X10 command on the same line just prior to the timer command.
     For example, the following line turns the lamp on after 7 seconds.
     However, XA actually issues the command at 5.6 seconds:

       A1 ON TIMER 0:0:7.0

     Likewise, to completely dim a module to 0% after 10 seconds, XA will
     begin issuing the command after approximately 4 seconds have elapsed.

       A1 DIM 0 TIMER 0:0:10.0

     If no commands are programmed on the same line as the TIMER statement,
     then a default adjustment of 1.4 seconds will be used for commands
     that appear later.  It is very important that you program the 'hour'
     and 'minute' fields, even if they are zero. Otherwise, XA will convert
     the 'seconds' field to minutes, and you'll be waiting a long time. For
     example, do this:

       TIMER 0:0:15.5 <--- Do this
       TIMER 15.5     <--- NOT this

     RESET
     -----------------------------------

     When the RESET token is parsed, the internal timer maintained by XA is
     reset to 0.  The PAUSE token also resets this internal timer to 0, but
     only after a key has been pressed. This token may be useful when used
     in conjunction with the `INPORT port' statement. INPORT (pg 50)  can
     monitor a bit of a selected port and force a RESET when the bit goes
     TRUE.



     {DELAY hh:mm:ss}
     -----------------------------------

     These tokens allow you wait for the specified number of hours, minutes
     and seconds to pass before executing the next command.  These delays
     are relative to the present time and do not work in conjunction with
     the TIMER or PAUSE tokens.  Make sure you program the HH, MM, SS
     fields. To wait 5 seconds between commands, use:

     User's Guide and Reference                                          43




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


       A1 OFF
       DELAY 0:0:5
       A2 ON



     STOP
     -----------------------------------

     Normally, XA stops execution when it reaches the end of a command
     file.  The STOP token forces XA to immediately stop execution. It may
     be placed anywhere in the command file. See the GOSUB example below
     for an example.

     :LABEL
     -----------------------------------

     This token identifies a location in your command file that you may
     GOTO or GOSUB later.  Each label must start with a colon `:'
     character.  Labels must contain alpha or alphanumeric characters -
     numbers alone will be incorrectly parsed as `time' tokens. Normally,
     labels will occupy a line by themselves, however they may appear in a
     line containing other tokens.

     :EXIT
     -----------------------------------

     This special label has been reserved for providing controlled shutdown
     commands.  This label must begin with the colon `:' character.
     Whenever the <ESC> key is pressed, the interpreter will jump to the
     location where the :EXIT label is located and execute any commands
     placed after the label. Therefore, the :EXIT label should appear
     towards the end of the command file.  Note that the :EXIT label is not
     mandatory.  If <ESC> is pressed and the :EXIT label does not appear in
     the file, then the interpreter simply aborts the remaining commands.
     Examine the use of :EXIT in the next example below.

     {GOTO :label}
     -----------------------------------

     These statements instruct XA to jump to a sequence of commands
     identified by the `:label' and begin executing them.  XA continues
     executing all remaining statements from that point.  If XA has
     encountered `:label' previously, it will immediately jump to that
     location. Otherwise, XA will begin searching for `:label' in the
     remaining portion of the current file, or within other files that may
     have been `INCLUDED'.

     The following code flashes (turns ON and OFF) a module addressed as A1
     three times.  It uses a variable (see `Variables' DECLARE VAR pg. 71)
     named `COUNTER' that is incremented and tested every time the loop is


     User's Guide and Reference                                          44




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     executed.  When COUNTER reaches 3, the IF portion of the test is no
     longer true, so XA continues with the rest of the program:

       DECLARE var COUNTER = 0   # Declare and initialize COUNTER to 0
       :loop
       A1 ON
       A1 OFF
       COUNTER = COUNTER + 1
       IF (COUNTER < 3)  
          GOTO  :loop
       ENDIF

       :EXIT
       A1 OFF

     Note the special use of the `:EXIT' label in the above example. If the
     user pressed the <ESC> during execution inside the loop, XA would
     abort the loop and search for the `:EXIT' label. If found, XA would
     execute the `A1 OFF' statement ensuring that the module was in a known
     state. Without `:EXIT', XA would abort and possibly leave A1 in the ON
     state.

     By using the LABEL and GOTO constructs, you can produce some pretty
     sophisticated lighting displays.  One application where this could be
     put to use is for Christmas lighting.  Consider placing solid color
     Christmas tree light strands on individual lamp dimmers.  Vary the
     brightness levels of each strand for an ever-changing lighting effect.
     See the sample file XMAS.CMD for an example.



     {GOSUB :label}
     [statements go here...]
     RETURN
     -----------------------------------

     These statements instruct XA to jump to a sequence of commands
     identified by `:label' and begin executing them.  XA continues
     executing all remaining statements until it reaches the `RETURN'
     token.  XA then returns control of the program to the point from which
     it came.

     If XA has encountered `:label' previously, it will immediately jump to
     that location. Otherwise, XA will begin searching for `:label' in the
     remaining portion of the current file, or within other files that may
     have been `INCLUDED'.

     Placing a subroutine in a program allows you to repeat a sequence of
     statements in several places without writing the same statements
     several times.



     User's Guide and Reference                                          45




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     It is good practice to place subroutines in the beginning of the
     command file so that searching will be minimized.

     XA may call subroutines that are present in the current file, or any
     previously `included' file. You may nest up to 20 subroutine levels.

     The previous `flash' example (using GOTO's) could be rewritten to use
     GOSUBS as follows:

       GOSUB :flash      # Once...
       GOSUB :flash      # ...Twice
       GOSUB :flash      #    ...Three times
       STOP              # Tell XA to stop (prevents running into 
                         #subroutine)

       :flash            # Start of subroutine
       A1 ON  A1 OFF
       RETURN            # Return to original caller

       :EXIT             # Special shutdown sequence...
       A1 OFF            # ...Ensure A1 is OFF
































     User's Guide and Reference                                          46




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     FAST
     -----------------------------------

     By default, XA always waits for an acknowledgment message from the
     CP-290 after sending a direct command. You can avoid this wait and
     speed up the overall execution of XA by including the token `FAST' in
     your command:

       XA `PHONE_IN_USE  ON  FAST'

     The sample command file HALOWEEN.CMD contains several examples of the
     FAST token.  Read the description in that file how various effects
     were achieved with XA-controlled sound and light.  These effects could
     only be attained by including the FAST token on certain X10 commands.

     FAST is best used in single command statements. If you attempt to send
     multiple direct commands using the FAST token, XA will be forced to
     wait for the acknowledgment message before issuing the remaining
     commands.

     Some computers may experience problems when XA executes a single
     statement in a batch file using the FAST token. Avoid using the FAST
     token when the TSR program `XT.EXE' is installed.  In some instances,
     XA may restore the old communication interrupt vectors while the
     acknowledgment message is in transit from the CP-290. This may result
     in XT reading an incomplete message.  It may take several messages for
     XT to correct itself.  You should experiment with your computer to see
     if this affects your setup.

     FAST only works with DIRECT commands.  FAST has no effect on EVENTS
     since these commands are managed by the CP-290 firmware.






















     User's Guide and Reference                                          47




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Communications Tokens
     ==============================================

     This group of tokens allow you configure XA for your particular
     computers communications setup. The following table lists the
     `standard' I/O port addresses as well as typical IRQ assignments for
     the first (4) serial ports. Note the potential IRQ conflict that might
     arise with devices COM1/COM3 and COM2/COM4 because of the shared
     IRQ's.  If you have more than 2 devices attached to your computers
     serial ports, beware of this conflict and resolve it by assigning a
     different IRQ to the affected port.


     Comm Port    I/O Address   IRQ Level


     COM1         3F8H (Hex)    4


     COM2         2F8H          3


     COM3         3E8H          4


     COM4         2E8H          3


     Table 2 - COM Port Parameters

     XA was designed to work using interrupt-driven communications allowing
     features such as `monitoring' to operate effectively.  Since some
     users are unable to dedicate a unique IRQ for the CP-290 serial port,
     XA can be configured to communicate in a `polled' fashion. Simply use
     the `i=0' command line option or `IRQ 0' statement in your XA.INI
     file.



     COMx
     -----------------------------------

     This token allows you to specify which comm port the interface is
     attached to.  This token was intended to be placed in the XA
     initialization and/or command files.

       COM3

     If your port IO address does not match those in the above table, then
     use the command line parameter [o=xxx], or the file mode token `IO'
     (see below) to customize the communication characteristics.


     User's Guide and Reference                                          48




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     {IO x}
     -----------------------------------

     This option allows you to select a different IO address from the
     default 3F8H (hex).  If your serial port is setup for 2E8H, then use
     the following line in your command file:

       IO 2E8H

     Notes:

     When specifying a HEXADECIMAL number, you must include the trailing
     `H' character.

     These tokens were intended to be placed in the initialization or
     command files.



     {IRQ x}
     -----------------------------------

     This option allows you to select a different IRQ level from the
     default interrupt 4.  To use COM3 (an IO address of 3E8) with an IRQ
     level 5, use the following commands in the XA initialization file:

       IO 3E8H
       IRQ 5

     Use IRQ 0  for `polling mode' communications if you can't configure
     your system with a free IRQ for the CP-290 port. Note that operations
     such as Monitoring and Logging may not operate correctly in polled
     mode.  Some bargraphs may not be displayed when polled-mode
     communication is active because slower processors can not handle the
     screen output and incomming data transmissions simultaneously.


















     User's Guide and Reference                                          49




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     I/O Port Control
     ==========================================

     XA can read and write to most of the I/O ports. Of particular interest
     is the Joystick or Game port.  The joystick port provides four digital
     inputs, and four resistive inputs.  Normally, the resistive inputs are
     used to determine the joystick's X - Y coordinates.  This position is
     calculated by reading the resisitance of the small potentiometers
     embedded in the joystick.  You can connect other resistive devices to
     this port, such as a variable resistor (or potentiometer), a bank of
     resistors selectable by a switch, or even a thermistor (used to make
     temperature readings).  By reading these values and using XA's IF/ELSE
     logic and arithmetic expressions, you can create some pretty
     sophisticated control programs.

     The LPT or printer port also has a lot of uses.  You can control small
     relays, or read the status of switches.

     Applications involving I/O via the joystick or printer ports are
     beyond the scope of this document.

     IMPORTANT NOTE:
     ---------------------

     When dealing with IO ports, make sure you know what you are doing.
     Connecting devices that should not be connected to a port may cause
     damage to your computer, its peripherals, even you. Be careful that
     you are writing to the proper ports, otherwise you may crash your
     system.  If you are not sure what you are doing, then you better not
     do it. I will in no way be responsible for your use, misuse, or abuse
     that you might inflict on you or your computer.



     {(variable =) INPORT io_port}
     -----------------------------------

     Read the status of the selected port, and optionally store it into a
     variable for later processing.  Example: Read the status of the
     Joystick port (201H) and save it into a variable called `joy_port'.

       joy_port = INPORT 201H

     {OUTPORT io_port value}
     -----------------------------------

     Output a TRUE signal to LPT1 bit

       OUTPORT   278H   1




     User's Guide and Reference                                          50




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     JOYSTICK
     -----------------------------------

     This command invokes a call to your PC's BIOS to read the current
     states of all four switch inputs.  In addition, it returns the X-Y
     coordinates of the 2 possible joysticks, or the resistive values of
     other hardware connected to the joystick port.  The values that are
     returned are saved in the following pre-defined variables.

     The pre-defined digital input (switch) state are:

       JOY1B1       Joystick1, Button 1
       JOY1B2       Joystick1, Button 2
       JOY2B1       Joystick2, Button 1
       JOY2B2       Joystick2, Button 2

     The pre-defined resistive inputs

       JOY1BX    Joystick1, X coordinate
       JOY1BY    Joystick1, Y coordinate
       JOY2BX    Joystick2, X coordinate
       JOY2BY    Joystick2, Y coordinate

     The following example shows you how to read the joystick buttons and
     display their status on the screen.

       display off
       #
       # Declare some variables to hold retrieved joystick data...
       declare var OldJoy1_B1 # Joystick 1 - Button 1 status
       declare var OldJoy1_B2 # Joystick 1 - Button 2 status

       :loop
       JOYSTICK  # Read the latest state of the joystick
       if (OldJoy1_B1 != joy1b1)     # There's a change in Button1 state
          OldJoy1_B1 = joy1b1 # Save state
          if (joy1b1)      # Button is pressed
            display Button1 is closed.
          else
            display Button1 is open.
          endif
       endif
       if (OldJoy1_B2 != joy1b2)     # There's a change in Button2 state
          OldJoy1_B2 = joy1b2 # Save state
          if (joy1b2)         # Button is pressed
            display Button2 is closed.
          else
            display Button2 is open.
          endif
       endif

     goto :loop

     User's Guide and Reference                                          51




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Miscellaneous Tokens
     ==========================================

     {DEFINE x z}
     -----------------------------------

     This token is designed to be used in initialization or command files.
     It allows you to substitute several tokens into a single token of your
     choice.  It will help to make command files more readable.  For
     example, you can assign the token:

       `XMAS_ON'

     to an equivalent group of tokens, such as:

       `HOUSE A UNIT 4 ON 8:00 PM EVERYDAY'

     as follows:

       DEFINE  XMAS_ON HOUSE A UNIT 4 ON 8:00 PM EVERYDAY
               <  x--> <----------- z  ------------------>

     Notice that the `x' portion uses underscore characters `_' to
     separate the words but to keep the string contiguous.  This is
     important because the XA interpreter looks for the first SPACE
     character to separate the `x' and `z' components.  All subsequent
     SPACE characters are ignored.

     Later in the command file, you can use the following command to
     activate your Christmas lights:

       XMAS_ON

     Internally, XA will convert this string to its equivalent:

       HOUSE A UNIT 4 ON 8:00 PM EVERYDAY

     More examples:

          :
       DEFINE PLANT_GROW_LIGHTS A8
       DEFINE OUTSIDE_LIGHTS A1
       DEFINE ALL_ON ALL_LIGHTS_ON HOUSE A ON
          :
       PLANT_GROW_LIGHTS ON 6:00 AM EVERYDAY
       PLANT_GROW_LIGHTS OFF  12:00 AM EVERYDAY
          :
       OUTSIDE_LIGHTS OFF SUNRISE EVERYDAY
          :
       ALL_ON SUNDAY  7:30 PM



     User's Guide and Reference                                          52




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     The use of DEFINES is helpful if you want to monitor the CP-290 for
     events as they occur (pg 93), and for generating Report Files (pg 89).

     $      (line continuation character)
     ------------------------------------

     If certain statements are too long, you can now continue them over
     multiple lines.  Simply use the dollar symbol '$' as the last
     character in each line.

     XA has a limit of 14 continuation lines for a single statement.

       DEFINE KITCHEN_LIGHT     A1
       DEFINE HALLWAY_LIGHT     A2
       DEFINE STAIRWAY_LIGHT    A3
       DEFINE FAMILY_ROOM_LIGHT A4
       DEFINE GARAGE_LIGHT    A5

     You could write the following statement on 1 line, or make it more
     readable by using 2 lines:

       SUNSET ON 11:30 PM KITCHEN_LIGHT HALLWAY_LIGHT STAIRWAY_LIGHT   $ 
                           FAMILY_ROOM_LIGHT GARAGE_LIGHT

     {EVENT xxx}
     -----------------------------------

     The CP-290 can store up to 128 events in its memory.  Each event
     occupies fixed locations in memory.  Prior to XA Version 2.0 you were
     required to assign a unique event number if you did not want to
     overwrite an existing event.  Since XA now automatically determines
     the next available slot for you, there is little need for these
     tokens.  However, these tokens remain as part of XA should you need to
     overwrite a particular event.

     Refer to REPORTS on page 89.

     When you produce a report file of style 1 or 2, the event number
     assigned to each event is printed in the right-most column of the
     listing.  In report style 3, the event number is in the left-most
     column.

     {CLEAR EVENT xxx}
     -----------------------------------

     These tokens delete the specified event from the computer interface.
     See description for EVENT xxx above. Only 1 event may be cleared per
     command.

       XA `CLEAR EVENT 100' `CLEAR EVENT 101'



     User's Guide and Reference                                          53




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     When an event is cleared from the interface, the actual memory
     locations it occupied are cleared to zero.  All subsequent events
     remain in their assigned memory locations.  When XA displays the
     bargraph upon finishing, a `hole' will be shown where the former event
     was located.

     Use the report listing to display each event's number (or location) in
     the CP-290. This number is printed in the right-most column of the
     report.  Any event numbers that are followed by an asterisk `*'
     indicate that the event will be triggered on multiple days.

     Refer to the CANCEL token (pg 55) for another way to remove or modify
     events.



     BEEP
     -----------------------------------

     The BEEP token will issue a short tone through your PC's speaker.



     ERASE
     -----------------------------------

     This token erases all events from the CP-290's memory. If you use XA
     to maintain your CP-290 schedules, then this token should appear at
     the beginning of the command file. This is important because XA tries
     to append new events to the existing events in the CP-290.  If you do
     not erase the CP-290 memory, you will eventually exceed its 128 event
     capacity.

     Always use this token when specific dates (declared by the DATE/THRU
     tokens) are present in your command file.  This way, once the date has
     come and gone, it will be deleted from the CP-290's memory
     automatically.

     { [variable = ] SPAWN command_string}
     -----------------------------------

     Like the DOS token, SPAWN allows you to execute any DOS command from
     within XA, however SPAWN returns an optional `errorlevel' code
     allowing XA to react to the status of the spawned process.









     User's Guide and Reference                                          54




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     {CANCEL user-defined event}
     -----------------------------------

     This powerful command allows you to cancel or modify a number of
     events stored in the CP-290.  When you use the CANCEL command, you
     specify the parameters that XA will search for in the CP-290's event
     schedule.  These parameters are simply the tokens you normally use
     when creating an event.  When the parameters match an event's
     parameters, the event is either deleted or modified.  For instance,
     suppose your CP-290 contains the following events:

       Event 0:  A1 A2 A3  ON      7:30   WEEKDAYS
       Event 1:  A1 A2 A3  OFF     8:30   WEEKDAYS
       Event 2:  A4        DIM 50  10:30  WEEKENDS
       Event 3:  B1 B2 B3  DIM 50  10:30  MON WED FRI
       Event 4:  C1        OFF     11:00  SAT
       Event 5:  A1        ON      11:30  SUN
       Event 6:  A2 A3     ON      11:30  SAT

     Scenario 1:
     -----------------------------------

     You wish to cancel all events for A1. Enter:

       XA `CANCEL A1'

     XA will scan the event schedule and modify events 0 and 1 so that A1
     will not be activated.  Event 5 will be deleted because it only
     triggers module A1.  Events 0 and 1 will continue to control modules
     A2 and A3.

     Scenario 2:
     -----------------------------------

     You wish to cancel all ON commands for FRI. Enter:

       XA `CANCEL ON FRI'

     After XA scans the event schedule, Event 0 is modified so that modules
     A1, A2 and A3 are only activated MON, TUE, WED, and THUR.  Event 5
     remains untouched because A1 is only triggered on SUN, and A2 and A3
     are activated on SAT.

     Scenario 3:
     -----------------------------------

     Prevent any modules on housecode A from triggering:

       XA `CANCEL HOUSE A UNIT ALL'

     Events 0, 1, 2 and 5 are removed.


     User's Guide and Reference                                          55




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Scenario 4:
     -----------------------------------

     Don't execute any OFF commands:

       XA `CANCEL OFF'

     XA removes Events 1 and 4

     Note:

     XA can not currently search for `dynamic' events such as those created
     by the token RANDOM.



     DIAGNOSE
     -----------------------------------

     This token invokes the CP-290's built-in diagnostic firmware.  You
     will be informed of the results after a few seconds.  Since the
     diagnostics overwrite any existing events, XA first uploads the
     contents of the CP-290 memory prior to the diagnostic.  If the
     diagnostics report an OK status, then the events and other non-
     volatile data are downloaded to the CP-290.



     {BASECODE x}
     {HOUSECODE x}
     -----------------------------------

     These tokens change the base housecode of the interface WITHOUT losing
     the data stored in the interface. Prior to changing the housecode, a
     complete upload of all events stored in the interface is performed.
     The housecode is changed, then all events and non-volatile data are
     downloaded into the interface.  Valid housecodes are A...P.

       XA `BASECODE  D'  -or-
       XA `HOUSECODE  D'

     XA displays a bargraph during the upload and download phases providing
     a visual indication of progress as well as the amount of remaining
     event storage .

     {XACMD filename}
     -----------------------------------

     This token is intended to be placed inside the XA initialization file
     (XA.INI - see pg. 79).  It defines the default command file that XA
     should parse and execute if no other command files or direct commands
     are present.  If your XA.INI file contains the following line:

     User's Guide and Reference                                          56




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


       XACMD EVENTS.CMD

     Then each time XA is invoked without any arguments, the file
     `EVENTS.CMD' will be parsed and executed.  The following examples show
     how you can specify unique command files based on the day of the week
     (see: `Advanced Programming` and `IF/ELSE/ENDIF Statements`):

       IF ((CDAY == MON) OR (CDAY == WED) OR (CDAY == FRI))
          XACMD M_W_F.CMD
       ELSE
          XACMD XA.CMD



     {INCLUDE filename}
     -----------------------------------

     These tokens allow XA to parse additional files.  When XA reads the
     `INCLUDE filename' statement, it begins to parse the requested file.
     Upon reaching the end of the new file, XA will resume parsing the
     original file at the statement following the INCLUDE.  This concept is
     similar to calling and returning from a subroutine.

     The include file may be called from your XA.INI as well as XA.CMD (or
     any other file). Include files may be nested up to 20 levels deep.
     The following example shows you how XA.CMD could include VACATION.CMD
     if the current date (CDATE) falls between AUG 21 and AUG 28.

       IF ((CDATE >= 8/21) AND (CDATE <=  8/28))
          INCLUDE VACATION.CMD
       ENDIF



     {DOS command_string}
     -----------------------------------

     The DOS token allows you to execute any DOS command from within XA.
     The following line tells the SoundBlaster to play the GREETING.VOC
     file:

       DOS c:\sblaster\vplay c:\sblaster\greeting.voc

     Clear the screen from within your command file:

       DOS CLS







     User's Guide and Reference                                          57




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     {DISPLAY ON}
     {DISPLAY OFF}
     -----------------------------------

     XA will display just about every statement as its parsed.  There may
     be instances where you don't want the display active, for instance,
     parsing the XA.INI file, or when critical loops are being  processed.
     XA allows you to control the display with the commands:

       DISPLAY ON
       DISPLAY OFF

     In some instances, it will be necessary to issue the command DISPLAY
     OFF because of time considerations. If you are in a tight loop
     monitoring an IO port for a bit to change, you may miss the transition
     while XA is printing the current statement to the CRT. By turning the
     display off, you allow XA to execute much faster, virtually
     eliminating any bottlenecks that may cause XA to miss an event from
     the port.

     The sample XA.INI file shipped with this version has the display
     turned off at the start of the file, and restores the display at the
     end of the file.



     {DISPLAY defined string}
     {DISPLAY declared variable}
     -----------------------------------

     If your XA.INI or *.CMD file contains any DEFINE or DECLARE variables,
     you can now output their latest values by using the DISPLAY command.
     For instance, suppose you have the following statements:

       DECLARE time START_TIME = 8:00
       DECLARE date START_DATE = 4/2/96

     When you perform time or date arithmetic on these variables, you can
     use the DISPLAY token as debugging aid when you run your files.  This
     is especially useful if you place these statments within a loop.

       START_TIME = START_TIME + 1:30
       START_DATE = START_DATE + 5

     Using `DISPLAY start_time'  and  `DISPLAY start_date' would produce
     the following output:

       START_TIME --> 9:30 am
       START_DATE --> 4/7/96 Sun




     User's Guide and Reference                                          58




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Note that you could also use the DEBUG1 and DEBUG2 statments, but
     these commands display ALL defines and declared variables.  You can
     also output a message to the screen using the DISPLAY command:

       if (joy1b1)
          display Joystick 1 Button 1 pressed
       endif

     The DISPLAY `string' or `variable' command ALWAYS prints it's output
     to the screen, whether the current display mode is ON or OFF.











































     User's Guide and Reference                                          59




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     { [STATE = ] HOUSE-UNIT STATUS }
     -----------------------------------

     These tokens allow you to evaluate the state of a selected module.  XA
     will examine the CP-290's event schedule (using X10.DAT) to determine
     what state the module is currently in.  You could then use this
     information to program certain actions. Returned values are:




     Returned Command
     Value


     0        OFF (issued from an ALL_UNITS_OFF
              command)


     1        ON  (issued from an ALL_LIGHTS_ON
              command)


     2        ON  (standard ON command)


     3        OFF (standard OFF command)


     4        DIM (standard DIM command)


     5        DIM (standard DIM command) High
     See:     byte contains dim level (0...F),
     Note 1   low byte contains 5 (Dim
              command).


     6        BRIGHTEN (`undocumented' command)
     See:     High byte contains step level,
     Note 2   low byte contains 6 (Bright cmd)


     7        UNKNOWN command


     Table 3 - Module State Values






     User's Guide and Reference                                          60




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Note 1:  When XA returns the status of a module that is currently DIM,
     the brightness level (0...F) is placed in the upper byte of the status
     value.  The DIM command (5) is placed in the lower byte.  The
     following table lists the returned dimmed values and their associated
     brightness level.




     Returned value (upper byte)   Brightness level


     0                             100%


     1                             94-99


     2                             87-93


     3                             80-86


     4                             74-79


     5                             67-73


     6                             60-66


     7                             53-59


     8                             47-53


     9                             40-46


     10 (A)                        34-39


     11 (B)                        27-33


     12 (C)                        20-26




     User's Guide and Reference                                          61




           XA - X10 COMMAND INTERPRETER - VERSION 3.2




     13 (D)                        14-19


     14 (E)                        7-13


     15 (F)                        0-6


     Table 4 - Dimming Ranges

     Assume module B2 was programmed to a brightness level of 75%.  The
     STATUS command would return a value of 45 hexadecimal (or 69 decimal).
     The `4' in the upper bytes indicates the brightness level in the range
     of 74...79, and the `5' in the lower byte describes the last X10
     command which was DIM.

     To examine the current state of A3, and turn it OFF if it is currently
     ON:

       A3_STATE = A3   STATUS
       if (A3_STATE == 2)  # If A3 is ON
          A3 OFF      # ...  send immediate command to turn it off
       endif

     Refer to LO.CMD for another example.  This sample command file
     performs several interesting functions.  The primary service is to
     `logoff' (shut down) the computer.  Prior to turning the computer off,
     it checks to see what the current time is (using CTIME - see pg. 73).
     If it's late evening or early morning, and several CP-290 controlled
     lights were turned off because they were scheduled to,  then XA turns
     them back on for a 2 minute period so I don't have walk in a darkened
     room.  In this example, we are only concerned with the state of the
     module (ON, OFF, or DIM), not its brightness level.  Therefore we
     `mask off' the brightness value in the upper byte.  This can be
     accomplished with bitwise AND (`&') operator (described in detail on
     page 77).














     User's Guide and Reference                                          62




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


       DEFINE  X10_OFF  3
       DECLARE  VAR  STAIRS_STATE

       #   Mask off upper byte (possible DIM level)
       Stairs_State  = (H1 STATUS & 0FH)

       DISPLAY ON

       IF ( ( SUNSET < CTIME )  ||  ( CTIME < SUNRISE ) )
          #
          # Determine if it's necessary to activate any lights...
          #

          IF (Stairs_State == X10_OFF)  # Is it OFF?
            Stairs On                   # Yes, turn it ON now
            Stairs Off NOW 2            # ...and turn it OFF in 2 mins
          ENDIF
       ENDIF

     Note 2:  When XA returns the status of a module that has been
     BRIGHTENED, the brightness `step' level (0...F) is placed in the upper
     byte of the status value.  The BRIGHT command (6) is placed in the
     lower byte.  The `step' level is really (1-step) you programmed.
     Therefore, if the you programmed the following statements

       A1 BRIGHT 5 10:00 pm

     Later, you retreived the status of A1:

       declare var STATE_A1
       STATE_A1 = A1 STATUS
       DISPLAY STATE_A1

     The result would be:

       STATE_A1  -> 70(46H)

     That is, the 46H is broken down as:

       40H  -  Steps = 5 - 1

       06H     Bright command











     User's Guide and Reference                                          63




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Reporting Tokens
     ========================================

     MONITOR
     -----------------------------------

     This token informs XA to continuously monitor the communications port
     for any messages sent by the CP-290 when it executes a stored event or
     when one of the panel buttons is pressed.

     `Monitor' and its command line counterpart `+m' may operate
     differently based on your XA configuration.  See section -
     `Monitoring and Logging Events' for more information.



     LOG
     -----------------------------------

     This token appends the monitored information in the file XA.LOG.



     REPORT1
     -----------------------------------

     Refer to Monitoring and Logging events on page 93 for sample files.

     This token will produce a report file with events sorted by day and
     time.



     REPORT2
     -----------------------------------

     This token will produce a report file with events sorted by day,
     module, and time.



     REPORT3
     -----------------------------------

     This token will produce a report file with events sorted by event
     number







     User's Guide and Reference                                          64




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Powerfail Recovery
     ==================================

     Powerfail recovery allows you to restore each module to its scheduled
     state.  XA determines this state by reading the event information
     stored in the CP-290.  By default, XA uses the last 6 days to
     determine the state.  You can tell XA to use fewer days if necessary.
     Also, you can tell XA to FORCE a module to a particular state
     overriding the calculated state, or have XA IGNORE the calculated
     state and not send any command to the module.

     Powerfail recovery may be invoked from the command line using the
     following parameters:

       +P - parses command file, then performs recovery.
       -P - immediate recovery, no parsing of command file.

     If you want XA to review the event schedule of the previous 4 days in
     order to determine the correct state, then append a 4 to the command,
     for example -P4 or +P4.  The maximum number of days that XA can scan
     is 6.  XA uses the information stored in the file X10.DAT for the
     schedule calculations because it's faster than uploading all the data
     from the CP-290.  Also, if you change your schedule with X10's
     original software package (X10.EXE), those changes will be reflected
     properly.  If XA can not find the X10.DAT, then XA will upload the
     data from the CP-290.  You can also tell XA to upload the latest
     schedule by using the `+u' command line option.

       XA +u -p

     Use the command line option `-e' in conjunction with powerfail
     recovery to see how XA would have restored each module without sending
     any X10 commands:

       XA -e -p

     XA will not restore modules programmed with the ALL_LIGHTS_ON command
     since XA does not know which modules control lights or appliances.
     Also, any events programmed with ALL_UNITS_OFF will be converted to
     individual OFF commands.

     There are two token statements which can override powerfail's
     determined module state. These overrides may be used for certain
     modules that do not have any programmed events stored in the CP-290.

     {FORCE module state}
     -----------------------------------

     Forces a module to a desired state, no matter what powerfail recovery
     thinks it should be in. `Module' can be a module address (A1) or pre-
     defined name (STAIRS). `State' can be any of the following X10
     commands: ON, OFF, DIM %%

     User's Guide and Reference                                          65




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Example (from XA.INI):

       FORCE P_C ON

     You can `force' a module from the command line too, thus overriding
     the calculated state:

       XA `FORCE DEN OFF' -P



     {IGNORE module}
     -----------------------------------

     Ignores sending any command to module during a powerfail recovery.
     `Module' can be a module address or pre-defined name.

     For example, you may not want a chime module that announces each hour
     to be restored during a powerfail recovery:

       IGNORE CHIME_MODULE

     You can tell XA to ignore sending any recovery actions to a module
     from the command line too:

       XA `IGNORE BEDROOM_LAMP' -P

     Screen Color Control
     =======================================

     Screen color control lets you program how commands should be
     displayed.  You will be able to tell at a glance how certain
     conditional statements such as IF/ELSE, DATE/THRU/EXCEPT were
     evaluated by XA just by looking at the display.

     {VIDEO1 Foreground Background}
     -----------------------------------

       IF or ELSE expression is TRUE.



     {VIDEO2 Foreground Background}
     -----------------------------------

     IF or ELSE expression is FALSE, or DATE/THRU/EXCEPT evaluates to
     FALSE.






     User's Guide and Reference                                          66




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     {VIDEO3 Foreground Background}
     ----------------------------------

     Statements resulting in DIRECT commands being sent to CP-290



     {VIDEO4 Foreground Background}
     -----------------------------------

     Statements resulting in EVENTS being sent to CP-290.



     {VIDEO5 Foreground Background}
     -----------------------------------

     Important messages reported by XA.



     {VIDEO6 Foreground Background}
     -----------------------------------

     Other non event or command statements processed by XA.



     {VIDEO7 Foreground Background}
     -----------------------------------

     Bargraph display (event upload, event utilization).

     {VIDEO8 Foreground Background}
     -----------------------------------

     Comments - commands the begin with `#' character.



     FOREGROUND may be any of the following:

       BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY, DARKGRAY,
       LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED, LIGHTMAGENTA, YELLOW,
       WHITE

     BACKGROUND may be any of the following:

       BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY




     User's Guide and Reference                                          67




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     To display a `TRUE' IF/ELSE statement in GREEN foreground characters
     on a BLACK background, and  a `FALSE' IF/ELSE (or DATE/THRU/EXCEPT)
     statement in RED foreground characters on a BLACK background:

       VIDEO1 GREEN BLACK
       VIDEO2 RED BLACK

     To display a DIRECT command (XA `P1 ON') in YELLOW on BLACK:

       VIDEO3 YELLOW BLACK

     You can prevent certain types of statements from being displayed on
     the screen.  Simply set both attributes to the same color.  For
     example, to turn off all lines beginning with comments `#', set the
     VIDEO8 statement to:

       VIDEO8 BLACK BLACK




































     User's Guide and Reference                                          68




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Advanced Programming
     ======================================

     Variables
     -----------------------------------

     Variables are user-defined objects which are assigned a value.  You
     can assign numbers, dates, times, port data, true/false data into a
     variable.  Later, these variables can be substituted for certain
     tokens in a command.  They may also be evaluated using
     relational/boolean/logical/arithmetic operations.

     Prior to their usage in a command, user-defined variables must first
     be declared.  Declaring a variable simply tells XA how the variable
     will be used later on.  Currently, XA supports 4 types of variables:
     DATE, TIME, DAY, and general purpose.  You can declare a variable
     using one of the following statements:



     {DECLARE  DATE  variable_name  [ = mm/dd/yyyy ] }
     {DECLARE  TIME variable_name  [ = HH:MM ] }
     {DECLARE  DAY variable_name  [ = MON | TUE | WED | ... SUN ] }
     {DECLARE  VAR variable_name  [ = value] }
     -------------------------------------------------------------

     Internally, variables are treated as 32 bit integer values.  If a
     variable is created without an initializer, it is set to 0.
     Otherwise, the variable is assigned the value following the assignment
     ( = ) operator.

     The following example creates a date type variable called `vacation'.
     It is not initialized until the second statement:

       DECLARE DATE vacation
       vacation = 7/14/95

     The same variable could be declared and initialized in the same
     statement:

       DECLARE DATE vacation =  7/14/95
       DECLARE DATE vacation_end = vacation + 14

     Use these variables in your program just like you would use regular
     dates.

       DEN ON SUNSET VACATION THRU VACATION_END EXPAND
       DEN OFF 11:30 RANDOM 10 VACATION THRU VACATION_END EXPAND

     When declaring variables, the first character in it's name should
     begin with an ALPHA character, that is, A...Z. You can then use
     numbers as part of the name, but they must not start the name. All

     User's Guide and Reference                                          69




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     characters are converted to UPPERCASE.  The list of legal characters
     are:

       ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_

     Prior to Version 3.0, XA would automatically create variables whenever
     the parser encountered a token that was not part of its language.
     However, an inadvertent spelling mistake could turn an event into a
     direct command or a comment without any explanation.  This can make
     debugging a command file very frustrating.  Now, declaring a variable
     as a TIME, DATE, DAY, or general purpose variable, makes XA much more
     powerful, and more robust.



     {DECLARE DATE variable_name  [ = mm/dd/yyyy ] }
     -----------------------------------

     DATE variables allow you to perform simple date arithmetic much
     easier.  A great example of how to use DATE variables and perform
     arithmetic operations on them is shown below.  It Is possible to
     calculate important dates in the Hebrew calendar because most of the
     holidays can be calculated as a fixed number of days from the first
     day of Passover.

       DECLARE DATE YTREF = 3/26/94
       DECLARE DATE Yom_Kippor_Eve = YTREF + 172
       DECLARE DATE Yom_Kippor = YTREF + 173

       A10 ON SUNSET Yom_Kippor_Eve



     {DECLARE TIME variable_name  [ = hh:mm ] }
     -------------------------------------------

     Use a variable of type TIME to program a chime module to activate
     every hour at the top of the hour between 8:00 am and 10:00 pm
     weekdays.  Note how the declared variable `hour' is adjusted by 1 hour
     in the loop.

       DECLARE  TIME hour = 8:00
       :hour_loop
       CHIME ON hour WEEKDAY
       hour = hour + 1:00
       if (hour <= 10:00 pm)
          goto :hour_loop
       endif





     User's Guide and Reference                                          70




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     {DECLARE DAY variable_name  [ = day [day...] ] }
     -------------------------------------------------

     The next example lets you activate a module on random days.  Use CDATE
     and CTIME to generate a random number. Then mask off the lower 7 bits
     to create a 7 day bitpattern for the programmed days.

       DECLARE  DAY rand_day
       rand_day = (CDATE * CTIME) & 7FH
       A1 ON SUNSET rand_day EXPAND



     {DECLARE VAR variable_name  [ = value] }
     -------------------------------------------

     Use this declaration for all other types of data.  For instance, to
     read input from the joystick port:

       DECLARE var joystick
       joystick = inport 201H



     Hexadecimal Notation
     -------------------------------------------

     Hexadecimal notation specifies an integer value in base 16 or `hex'
     (hexadecimal).  When writing computer programs, it is sometimes easier
     to work in this base than the normal base 10. A hex value has 3
     parts:

       0 NNNNNNN H

     where:

       0 - A leading zero is required if the first digit of the hex number
     is an alphabetic character (A...F) so that XA can distinguish it as a
     number and not a variable name. A leading zero may also be used in
     front of a numeric character in the hex number just as in a normal
     integer constant (0987H = 987H).

       NNNNNNN - The eight Ns represent the 8 hexadecimal digits in the
     range of 0...F.

       The trailing H indicates the number is hex and is always required.

     Example:

       IO 3E8H



     User's Guide and Reference                                          71




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Previous versions of XA assumed hex numbers for certain tokens (such
     as IO). This is no longer the case!



     Pre-Defined Variables:
     ============================================

     XA maintains several built-in variables that are accessible by your
     programs. These variables are:

     CDATE
     -------------------------------------------

     The current date (month-day-year).

     Internally, XA maintains the current date as a 32 bit long integer.
     CDATE is actually the number of days since 1/1/1970.  You can perform
     simple math and logical operations on this variable to test for
     special conditions. For instance, to run a special command file called
     XMAS.CMD between Thanksgiving and New Years Eve:

       IF ((CDATE >=  11/25) AND (CDATE <=  12/31))
          INCLUDE XMAS.CMD
       ENDIF



     CMONTH
     -------------------------------------------

     The current month (1=January, 2=February, 12=December).



     CMONTHDAY
     -------------------------------------------

     The current day of the month (1...31).



     CYEAR
     -------------------------------------------

     The current year (1994...xxxxx).







     User's Guide and Reference                                          72




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     CYEARDAY
     -------------------------------------------

     The current day of the year (1...365, 366 during leap years).



     CDAY
     -------------------------------------------

     The current day of the week (MON, TUE, WED...)

     Internally, XA maintains the current day as an X10 bit-pattern, that
     is MON = 1, TUE = 2, WED = 4, ...SUN = 40Hex. The Day Tokens (MON,
     TUE... SUN) are also mapped to these values, so you can use them in
     conjunction with logical operations when determining special days. The
     file XMAS.CMD performs a test on CDAY to see if its FRI or SAT, thus
     allowing the Christmas lights to stay on longer:

       IF ((CDAY == FRI) OR (CDAY == SAT))
          IF (CTIME >=  11:30 PM)
            GOTO EXIT
          ENDIF
       ELSE
          IF (CTIME >=  10:30 PM)
            GOTO EXIT
          ENDIF
       ENDIF
       GOTO LOOP    # It's not time yet, repeat the loop.



     CTIME
     -------------------------------------------

     The current time (in 24-hour format)

     Internally, XA maintains the current time as the number of seconds
     since midnight.  You can perform arithmetic and logical operations on
     this variable by using the TIME token. See the previous example for a
     way of leaving Christmas lights on until 11:30 pm on FRI and SAT
     nights, all other nights they are shutdown at 10:30 pm.

     CHOUR
     -------------------------------------------

     The current hour (in 24-hour format)






     User's Guide and Reference                                          73




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     CMIN
     -------------------------------------------

     The current minute (00...59)



     CSEC
     -------------------------------------------

     The current second (00...59)



     NVOL1...NVOL20
     -------------------------------------------

     Non-volatile variables that are stored in the CP-290.  These variables
     retain their values from session to session.  You can read and write
     them just as any user-defined variable.  See: Non-Volatile Variables -
     pg 83 for additional information.

     XA maintains additional pre-defined variables for joystick services.
     These variables are described in detail begining on page 50.





























     User's Guide and Reference                                          74




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Operators
     ======================================================

     Operators allow some kind of operation to be performed to variables
     and constants. Operators are evaluated as they are parsed from left to
     right.  When an expression is contained in parentheses, that
     expression will be evaluated first. When nested parentheses are
     present, the inner most expression is evaluated, then the one
     immediately outside of it, and so on.

     Arithmetic Operators


     Operator    Function      Example


     *           Multiply      A = B * C


     \           Divide        B = A \ C


     +           Addition      C = A + B


     -           Subtraction   A = C - B


     -           Unary Minus   A = - B


     %           Modulus       A = B % C


     Table 5 - Arithmetic Operators


















     User's Guide and Reference                                          75




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Relational Operators


     Operator      Function


     =             Assigns a value to a variable


     <             Less than


     >             Greater than


     <=            Less than or equal to


     >=            Greater than or equal to


     <>            Not equal to


     ==            Equal to (not assignment)


     Table 6 - Relational Operators

























     User's Guide and Reference                                          76




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Logical Operators

     These Logical Operators produce either a FALSE (0) or TRUE (1) result.


     Operator       Function


     AND            Logical AND


     &&             Logical AND (same as AND)


     OR             Logical OR


     ||             Logical OR (same as OR)


     !              NOT


     Table 7 - Logical Operators

     Truth Table


     A    B      A AND B    A OR B  !
                                    A


     0    0      0          0       1


     0    1      0          1       1


     1    0      0          1       0


     1    1      1          1       0


     Table 8 - Logical Operator Truth Table








     User's Guide and Reference                                          77




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Bitwise Logical Operators
     -------------------------------------------

     These operators are used to mask off some set of bits (AND), or to
     turn on some bits (OR). You will need these when using XA in
     conjunction with IO ports.


     Operator   Function


     |          Bitwise OR


     &          Bitwise AND


     Table 9 - Bitwise Logical Operators



     IF/ELSE/ENDIF Statements
     ====================================================

     The IF/ELSE/ENDIF statement provides a transfer of control based on
     the result of a relational or comparison expression. The IF/ELSE/ENDIF
     statement has the following format:

       IF (expression)
          statements
       [ ELSE
          statements ]
       ENDIF

     The expression within parentheses is evaluated. If the expression
     evaluates to TRUE, then the series of statements starting on the next
     line are executed. If the expression evaluates to FALSE, and there is
     an ELSE clause, then the series of statements on the lines following
     the ELSE will be executed.  The ELSE clause is optional. If there is
     no ELSE clause, then execution continues immediately following the
     ENDIF statement.

     Conditional IF/ELSE/ENDIF statements may be nested up to 100 levels
     deep.

       IF (1 < 2)
          IF (2 < 3)
            IF (3 < 4)
               A = 5
            ENDIF
          ENDIF
       ENDIF

     User's Guide and Reference                                          78




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Each conditional expression must finish with an ENDIF clause so the
     parser can evaluate further statements.

     Indentation is used throughout these examples and you are urged to
     indent your programs too. Proper indentation makes your program much
     easier to read.  Complex conditional statements may be evaluated. The
     above example could be rewritten as:

       IF ((1 < 2) AND (2 < 3) AND (3 < 4))
          A = 5
       ENDIF

     Use parentheses ( ) to group individual expressions. Grouping ensures
     that expressions are evaluated correctly, as well as makes your
     program more readable.

     The following example (found in XA.CMD) uses an IF statement to
     determine whether additional indoor/outdoor lighting is needed based
     on seasonal changes.  Let's say you leave for work around 5:30 am.
     During the winter, it's probably still dark, yet in the summer, dawn
     is already breaking.  This example determines if lights are needed by
     comparing the average weekly sunrise with a pre-determined time. If
     sunrise occurs after 6:00 am, then it's still dark at 5:30 am so we'll
     program the lights to turn on, then turn off at sunrise. Otherwise,
     there's enough daylight present and the additional lights are not
     needed.

       IF (SUNRISE > 6:00)
          OUTSIDE_PORCH_LIGHTS ON 5:30 WEEKDAYS RANDOM 10 EXPAND
          OUTSIDE_PORCH_LIGHTS OFF SUNRISE WEEKDAYS EXPAND
          LIVING_ROOM_LAMP ON 5:35 WEEKDAYS RANDOM 10 EXPAND
          LIVING_ROOM_LAMP OFF SUNRISE WEEKDAYS OFFSET 10  EXPAND
       ENDIF




















     User's Guide and Reference                                          79




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Menus / Functions Keys
     ===================================================

     XA allows you to activate special X10 lighting sequences or other
     actions with a simple press of a function key.  For instance, download
     a complete schedule update, or turn on the TV and dim the lights at
     the press of a key.  Up to 48 function keys may be programmed
     (F1...F12, Shift F1...Shift F12, Ctrl F1...Ctrl F12, and Alt F1...Alt
     F12)..

     Use the INKEY token to read data from the keyboard and store it into a
     user-defined variable. This variable must be declared prior to its
     usage:

       declare  var  key



     { [variable = ] INKEY}
     -------------------------------------------

     These tokens will read the keyboard and store the latest keypress
     value in a user defined variable.  `Variable' must have been
     previously declared or an error message will be displayed.

       key = inkey

     INKEY will not wait for the user to press a key.  The XA parser will
     continue processing statements if there has not been any new
     keypresses.



     { [variable = ] INKEYW}
     -------------------------------------------

     These tokens will read the keyboard and store the latest keypress
     value in a user defined variable.  `Variable' must have been
     previously declared or an error message will be displayed.

       key = inkeyW

     INKEYW will wait for the user to press a key.  The XA parser will not
     continue to process any further statements until a new key press is
     detected.








     User's Guide and Reference                                          80




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     F1KEY...F12KEY
     SF1KEY...SF12KEY
     CF1KEY...CF12KEY
     AF1KEY...AF12KEY
     -------------------------------------------

     XA handles all of the normal function keys, F1 through F10 (F11 and
     F12 if your keyboard supports them).  You can access a total of 48
     function keys by pressing either Shift, Ctrl, or Alt in unison with
     the function key.  That is, press <Shift> and <F1> together.

     Use a series of IF/ELSE statements to determine the keypress and the
     resulting action to be taken.

       DECLARE VAR KEY
       :LOOP
       KEY = INKEY
       IF (KEY == F1KEY)
          INCLUDE XA.CMD        # download XA.CMD
          ENDIF
       IF (KEY == SF1KEY)
          DOS XA `MONITOR'      # Monitor events
          ENDIF
       IF (KEY == AF1KEY)
          A1 ON               # Turn on Porch
          ENDIF
       IF (KEY == CF1KEY)
          A1 OFF              # Turn off Porch
          ENDIF
       GOTO :LOOP               # Loop until <ESC> pressed

     Refer to the sample command files `KEY.CMD' and `ALL_KEY.CMD' for
     examples of programming these function keys.  Note that these files
     use repeated looping so that additional sequences can be handled after
     each function.  Press the <ESC> key to exit the loop.

     Note how monitoring is activated when the <SHIFT><F1> keys are pressed
     in the sample code shown above.  If you had used the single token
     `MONITOR', then XA would have queued the request and would not have
     invoked monitoring until all direct commands and events were
     processed.  Since the program loops continuously, the monitor request
     won't be handled until the <ESC> key is pressed.  The trick to
     initiating monitoring immediately is to invoke another copy of XA with
     the monitor request as a command line parameter.  The `DOS' token
     loads and starts another program in the computer's memory (in this
     case, XA).  Since `MONITOR' is the only argument on the command line,
     XA begins monitoring immediately.  When you want to end monitoring,
     press the <ESC> key.  The second copy of XA is terminated returning
     control to the original copy of XA.




     User's Guide and Reference                                          81




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Artificial Sunrise
     ===============================================

     The `BRIGHTEN ##' token (see pg 24) invokes an `undocumented' CP-290
     function that brightens a lamp module in small, relative steps.
     Unlike the DIM command, BRIGHTEN does NOT ramp the module to 100%
     brightness before commanding the the desired level.

     The ## value is an increment, not an absolute level.  If you issue a
     `BRIGHTEN 1' command, the selected module will increase it's
     brightness level by 1 step.  A `BRIGHTEN 5' will brighten the module
     by 5 steps.

     This effect is useful for creating an artificial sunrise.  During the
     winter months you can program a light in your bedroom to brighten
     gradually in 16 steps over a period of time.  This may help you get
     out of bed on those cold, dark, snowy mornings.

     Prior to selecting a LAMP module that will receive the BRIGHTEN
     command, make sure the LAMP module does not share the same HouseCode
     as a WALL switch.  Remember, WALL switches will be turned OFF when
     they receive the BRIGHTEN command.

     Next, you must ensure that the desired LAMP module is NOT turned OFF
     prior to receiving the BRIGHTEN command.  If the module is in the OFF
     state, it will immediately turn ON to 100% brightness when the
     BRIGHTEN command is issued.  Instead, you can either program the
     module to DIM to 0% at some pre-determined time at night, or you can
     use a mini-controller to manually dim the module when you go to bed.

     Finally, program the CP-290 to begin brightening the lamp several
     minutes prior to your normal wake-up time.  This following example
     illustrates a `sunrise' effect for module B1 that starts about 10
     minutes prior to a wakeup time of 5:30 am (M...F) during the winter
     months.  We'll use a TIME variable, and an IF loop to construct the
     events:

       DECLARE TIME WAKEUP = 5:20  # Initialize variable to 5:20
       :LOOP
       # Send event to CP-290
       B1 BRIGHTEN 1 WAKEUP WEEKDAYS 11/1 thru 4/15
       WAKEUP = WAKEUP + 1    # Increment time by 1 minute
       IF (WAKEUP <= 5:36)    # Have we issued all events?
          GOTO :LOOP          #  - No, repeat the loop
       ENDIF








     User's Guide and Reference                                          82




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Non-Volatile Variables
     ============================================

     XA allows you to store up to 20 user-defined variables in the CP-290's
     non-volatile memory.  Each non-vol variable is stored as a 32-bit
     integer.  Once you assign a value to these variables, the value will
     be saved inside the CP-290 so you can access the variable during the
     next XA session.

     Use the pre-defined tokens NVOL1...NVOL20 to read the current value of
     the variables or write them to the CP-290.  You can dedicate a non-vol
     variable to keep track of the last time you updated the CP-290's event
     schedule.  By examining this variable, you can determine when you need
     to download an updated schedule.  For example, place the following
     statements in your XA.CMD file.

       if (CDATE > NVOL1)     # Devote NVOL1 as the date to update CP-290
          NVOL1 = NVOL1 + 7   # Save new date in CP-290
            :
          # REMAINING CP-290 EVENT SCHEDULE CONTAINED HERE
            :
       ENDIF

     The above example compares the current date (CDATE) with the date
     stored in the CP-290 (NVOL1).  It the current date is GREATER than the
     stored date, then all statements in the `IF' condition are processed.
     Note that the stored date is revised (NVOL1 = NVOL1 + 7) thus ensuring
     that XA will not process the `IF' condition code until the following
     week.  Refer to the supplied XA.CMD file for additional information
     about the concept of this example.

     In addition to storing the non-volatile data to the CP-290, XA also
     writes these variables to a file called XA.NVL, which is stored in the
     same drive and directory that the XA environment variable is set to.
     This file allows XA to process the non-volatile variables faster by
     avoiding the lengthy communication upload with the CP-290.

     XA only writes non-vol data to the CP-290 as long as the `-e' is not
     invoked.  Note that when a non-volatile variable is modified, only the
     changed variable is written to the CP-290.  XA displays a bargraph as
     data is written to the CP-290's non-volatile area.  The bargraph
     provides a visual indication of the remaining time needed to complete
     the variable update.  In most cases, this time is very short.
     However, the DIAGNOSE, ERASE, HOUSECODE, and BASECODE tokens cause the
     CP-290 to destroy all event and non-volatile data.  Therefore, it may
     take slightly longer for XA to initialize and restore the non-volatile
     data to the CP-290.

     The following example shows how to count the number of times the
     XA.CMD file is executed.  Note that we using NVOL2 here.  This
     prevents us from overwritting the NVOL1 variable which is already used
     in the above example.

     User's Guide and Reference                                          83




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


       # XA.CMD
       declare var counter
       NVOL2 = NVOL2 + 1
       COUNTER = NVOL2
       DISPLAY COUNTER


     Here NVOL2 is incremented each time XA.CMD is parsed.  If you want to
     display the value of NVOL2, you must assign it to a variable (refer to
     Variables - pg 69) called COUNTER.  Use the DISPLAY command to output
     the contents of COUNTER (NVOL2) to the screen:

       DISPLAY COUNTER

     XA.INI - Initialization file
     =================================================

     XA supports the use of an initialization file called XA.INI.  This
     file is intended to hold tokens and communication parameters that you
     use regularly.  For instance, the following tokens are ideal
     candidates for inclusion in the initialization file:

       COMx         - Communication port
       IO x         - Special IO port address
       IRQ x        - Special IRQ level
       DEFINE x y   - Place as many DEFINE statements as you want
       LATITUDE dms - The latitude of your city
       LONGITUDE dms- The longitude of your city
       TIMEZONE x   - Your timezone
       DST          - If Daylight Savings is observed
       XACMD file   - The command file to use as a default
       DECLARE ...  - Certain variables may be declared here

     This file, always called XA.INI, is the very first file that the XA
     parser looks for.  If it is found in the current directory (or the
     directory specified by the XA environment variable - see:

















     User's Guide and Reference                                          84




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Installation - pg. 14) then the file is scanned for all tokens
     described above.

     These tokens are then used to define modules or override default
     communication parameters.  The following example is taken from the
     file XA.INI distributed with this software:

       DEFINE P_C C1
       DEFINE DEN A5
       DEFINE GARAGE A1
          :
       LATITUDE 41.35'
       LONGITUDE 81.20'
       TIMEZONE 5 DST
          :
       COM3
       IRQ 5

     Since XA.INI is always parsed, any defines you use are pre-loaded by
     XA.  You don't need to remember what the specific House/Unit codes are
     for a module.  Just specify `DEN' in your command:

       XA `DEN ON'

     and it turns the unit at Housecode A Unit 5 ON.  Do not place events
     or direct commands in this file because they will not be executed.  XA
     is only looking for tokens that describe your particular setup.
     Events and direct commands should be placed in command files (see next
     section).

     You may place comments in your initialization file.  A comment is
     delineated by the pound sign character `#'.  The comment symbol may be
     placed in any column, however XA will not display the comment symbol
     if it appears in the 1st column. Once XA sees the comment, the rest of
     the line is ignored.  Therefore, comments can be placed in front of
     tokens you do not want to be parsed by the interpreter at this time.

       # This is an example comment. Place them after statements too:
       LATITUDE  41.35'          # Latitude of Mentor, OH.

     When creating this file, use an editor or word processor that stores
     its files in pure ASCII format.  Otherwise the formatting characters
     that the word processor embeds within the file will confuse the XA
     parser.  Either the DOS `EDIT' or Windows `NOTEPAD' are excellent
     utilities for modifying these files.








     User's Guide and Reference                                          85




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Command Files
     =========================================

     Since the CP-290 is only capable of storing a single weeks worth of
     events, command files were created to allow easy updates of the events
     that may need to be revised due to ever-changing conditions such as
     sunrise and sunset times.  Also, specific date information may be
     contained within this file.  XA has the capability to interpret these
     dates and update the CP-290 accordingly. See the sample command  file
     `XA.CMD' (included in this package) I use for automating events  in my
     home.

     Command files work very well for executing a series of direct commands
     too. See the sample file XMAS.CMD for an example of an X10 Christmas
     lighting script.

     Command files should only be created with an editor or word processor
     that saves files in pure ASCII format.  Any extraneous characters or
     control codes will cause the XA interpreter to ignore your commands.
     Either the DOS `EDIT' or Windows `NOTEPAD' are excellent utilities for
     modifying these files.

     XA defaults to reading a command file if there are no commands in the
     command line and as long as the statement  `XACMD filename' was
     included in your XA.INI file. You may override the default command
     file by using the `f=filename' option when starting XA.  For example,
     if you wanted to execute the commands found in a file called
     'MONITOR.CMD', you would start the XA utility as:

       XA f=MONITOR.CMD

     Prior to Version 2.0, XA would only execute either command files or
     commands passed as arguments to XA on the DOS command line - NOT
     BOTH.  With version 2.x, you can execute both types at the same time,
     however the file must be specified using the `f=filename' syntax.
     This is very useful when you want to pass a variable to a command
     file. For example, suppose your normal command file (XA.CMD) contains
     special lighting events that you activate when you plan on vacationing
     for the weekend:














     User's Guide and Reference                                          86




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


       XA.CMD:
          # Normal Events...
          GARAGE ON SUNSET WEEKDAYS
          # Special Vacation Events...
          if (vacation)
            HALLWAY ON TIME 9:30 PM WEEKENDS SECURITY
            HALLWAY OFF TIME 11:30 WEEKENDS RANDOM 10
            STEREO ON TIME 3:30 PM WEEKENDS RANDOM 15
            STEREO OFF TIME 11:15 PM WEEKENDS RANDOM 5
          endif

     To activate the vacation sequence, you must specify both XA.CMD and
     set the vacation variable to TRUE:

       XA f=XA.CMD `VACATION = 1'

     XA's new error handling requires that all variables must be declared
     before they can be used.  In the above example, if you invoke XA with
     the statement:

       XA f=XA.CMD `VACATION = 1'

     then the variable `VACATION' must have been pre-declared.  The best
     way to accomplish this is to place the declaration of VACATION in the
     XA.INI file.  This way, you will avoid an error message if the
     variable is not declared.

       DECLARE VAR VACATION

     Remember, only variables that you intend to pass on XA's command line
     should be declared in the XA.INI file.  For more information see pg.
     70





















     User's Guide and Reference                                          87




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Initialization file, Command files, and Command Line Options
     ================================================================

     This section tries to clear any confusion you may have about the
     initialization file, command files, and command line options. Each
     serves a unique purpose, offering a very easy and flexible means of
     controlling your X10 equipment.  As discussed earlier, XA provides the
     mechanism for controlling the CP-290 via the DOS prompt, batch files,
     or from a text-based file.  XA distinguishes which mode of operation
     it takes by examining the way you invoked XA.  If any direct (or
     immediate) commands are present, then XA sends the command directly to
     the CP-290.  For instance, the following is a direct command:

       XA `A5 ON'

     It's nicer to assign a meaningful name to your modules, so XA allows
     you to place these names in an initialization file called `XA.INI'.
     You define a module using the following token syntax:

       DEFINE DEN A5   

     Now you can activate the same module using a descriptive (and easier
     to remember) name:

       XA `DEN ON'

     Other items may also appear in the initialization file.  If your
     computer communicates with the CP-290 via COM3 serial port, then you
     may place the token `COM3' within the XA.INI too.  XA always looks at
     this file before attempting any communication with the CP-290.  Other
     tokens that XA looks for are:

       IRQ, IO, LATITUDE, LONGITUDE, TIMEZONE,
       DST,  XACMD, DEFINE, DECLARE, COMx

     After parsing the XA.INI file, XA then looks to see if the
     `f=filename' option was specified on the command line. This allows you
     to override the default command file you may have specified by using
     the XACMD token in the XA.INI file.  Next, the command line options
     are scanned. Any options defined here will override all previous
     options declared by the initialization file.  If a file and a series
     of commands are placed in the XA command line, then XA will execute
     the command and the file.  This allows you to set variables to a
     specific value and be later evaluated so special actions can be taken
     inside your command file. See the previous section for more details.








     User's Guide and Reference                                          88




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Report Files
     =========================================

     XA can produce a report of all events that were just parsed by the
     interpreter.  These reports come in 3 styles:

       Events sorted by day and time
       Events sorted by day, module, and time.
       Events sorted by event number.

     You have the option of selecting any style, or all styles.  The report
     file will be created after the events have been downloaded to the CP-
     290.  The file is named `XA.RPT', and is located in the same drive and
     directory that your `XA' environment variable is set to.

     Each report file will contain a header containing the XA copyright
     notice, XA's revision number, CP-290 base housecode, and the date and
     time the file was created.  Next, the event list will be generated
     starting with today's events.  Each day will have it's own heading,
     and if the LATITUDE, LONGITUDE, and TIMEZONE tokens were included in
     either of the initialization or command files, then the sunrise and
     sunset times for this day will be added to the report.

     The format of the report is self-explanatory, but a few items are
     worth noting. The `Description' column retrieves the module definition
     via the `DEFINE' statement.  The `Event' column displays the actual
     location of the event in the CP-290's memory.  Event locations range
     anywhere from 0 to 127.  Use this information if you want to CLEAR an
     event from the CP-290 interface (see EVENT, and CLEAR EVENT).  If you
     specify the '-e' command line option, then the events will not be
     downloaded, but they will be assigned an event number.  An asterisk
     (*) following the event number is a flag to warn you that the event is
     triggered on multiple days.  Therefore, if you do CLEAR this event,
     the event will be deleted for the other days as well.



















     User's Guide and Reference                                          89




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Report Style 1 - Sort by Day and Time
     -------------------------------------------

     Use the REPORT1 token in the command file (or use +r1 on the command
     line) to produce a report file which sorts every event by the day it
     takes place and the time it occurs.  The following is a condensed
     sample of this style.

     XA - X10 Command Interpreter - Version 3.2
     Copyright 1991-1996 by Bruce Christensen. All Rights Reserved.
     Registered to: Your name here - Your town here.

     Event report prepared: 04/14/96 9:14 PM       XA

     Saturday - September 25, 1993  Sunrise:  7:15:27   Sunset:  7:18:53
                                                   Sunrise
                                                   and
                                                   Sunset vent
                                                   displays
     Time      Cmd  Mode   Module Address/Description    E
     1:30 am   OFF         (A3) BEDROOM_LIGHT      times for
                                                         ( 75)
     5:00 am   ON          (B2) DEHUMIDIFIER       each day.
                                                         ( 77)*
     6:45 am   OFF         (A6) STAIRS                   ( 84)*
     6:45 am   OFF         (H1) HALLWAY                  ( 81)*
     9:00 am   OFF         (B2) DEHUMIDIFIER             ( 78)*
     12:30 pm  OFF         (A8) LIVING_ROOM_LAMP         ( 56)
     12:30 pm  OFF         (A4) FAMILY_ROOM_LAMP         ( 61)
     5:00 pm   ON          (B2) DEHUMIDIFIER       *     ( 79)*
     6:18 pm   ON          (A4) FAMILY_ROOM_LAMP   indicates
                                                         ( 72)
     7:18 pm   DIM         (A9) OUTSIDE_PORCH_LIGHTthe event
                                                         ( 66)
     7:23 pm   ON          (A1) DECK_LIGHTS_1      is    ( 69)
     7:48 pm   DIM         (A6) STAIRS             activated
                                                         ( 82)*
     7:48 pm   DIM         (A1) DECK_LIGHTS_1      on    ( 70)
     7:48 pm   ON          (A8) LIVING_ROOM_LAMP   multiple
                                                         ( 67)
     8:48 pm   OFF         (A1) DECK_LIGHTS_1            ( 71)
     9:00 pm   OFF         (B2) DEHUMIDIFIER             ( 80)*
     9:45 pm   DIM         (H1) HALLWAY                  ( 86)*
     10:34 pm  ON          (A3) BEDROOM_LIGHT            ( 74)
     10:43 pm  OFF         (A9) OUTSIDE_PORCH_LIGHT      ( 76)
     11:00 pm  DIM         (A6) STAIRS                   ( 83)*
















     User's Guide and Reference                                          90




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Report Style 2 - Sort by Day, Module, and Time
     ------------------------------------------------

     Use the REPORT2 token in the command file (or use +r2 on the command
     line) to produce a report file which sorts every event by the day it
     takes place, the module, and the time it occurs. The following is a
     condensed sample of this style.    

     XA - X10 Command Interpreter - Version 3.2
     Copyright 1991-1996 by Bruce Christensen. All Rights Reserved.
     Registered to: Your name here - Your town here.

     Event report prepared: 04/14/96 9:14 PM

     Base housecode: C

     Saturday - September 25, 1993   Sunrise:  7:15:27    Sunset:  7:18:53

     Module    Time      Function    Mode    Event  
     (A1) DECK_LIGHTS_1
               7:23 pm   ON                  ( 69)
               7:48 pm   DIM                 ( 70)
               8:48 pm   OFF                 ( 71)

     (A3) BEDROOM_LIGHT
               1:30 am   OFF                 ( 75)
               10:30 pm  ON                  ( 74)

     (A4) FAMILY_ROOM_LAMP
               12:30 pm  OFF                 ( 61)
               6:18 pm   ON                  ( 72)

     (A6) STAIRS
               6:48 am   OFF                 ( 84)*
               7:43 pm   DIM                 ( 82)*
               11:00 pm  DIM                 ( 83)*

     (A8) LIVING_ROOM_LAMP
               12:30 pm  OFF                 ( 56)
               7:48 pm   ON                  ( 67)

     (A9) OUTSIDE_PORCH_LIGHTS
               7:18 pm   DIM                 ( 66)
               10:31 pm  OFF                 ( 76)

     (B2) DEHUMIDIFIER
               5:00 am   ON                  ( 77)*
               9:00 am   OFF                 ( 78)*
               5:00 pm   ON                  ( 79)*
               9:00 pm   OFF                 ( 80)*



     User's Guide and Reference                                          91




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Report Style 3 - Sort by Event Number

     Use the REPORT3 token in the command file (or use +r3 on the command
     line) to produce a report file which sorts every event by the day it
     takes place, the module, and the time it occurs. The following is a
     condensed sample of this style.

     XA - X10 Command Interpreter - Version 3.2

     Copyright 1991-1996 by Bruce Christensen. All Rights Reserved.
     Registered to: Your name here - Your town here.

     Event report prepared: 04/14/96 9:14 PM

     Base housecode: C

     Event report prepared:  Sun - Feb 18, 1996   (10:43:08 PM)

     Sun - February 18, 1996         Sunrise:  7:18:08   Sunset:  6:00:44
     Mon - February 19, 1996         Sunrise:  7:16:45   Sunset:  6:01:58
     Tue - February 20, 1996         Sunrise:  7:15:20   Sunset:  6:03:12
     Wed - February 21, 1996         Sunrise:  7:13:54   Sunset:  6:04:26
     Thu - February 22, 1996         Sunrise:  7:12:27   Sunset:  6:05:39
     Fri - February 23, 1996         Sunrise:  7:10:59   Sunset:  6:06:52
     Sat - February 24, 1996         Sunrise:  7:09:30   Sunset:  6:08:05

     Event  Time    Cmd  Days   Mode      Module Address

       0  5:04 pm   ON   SMTWTFS     A               8                   
       1  6:08 pm   ON   S           A                  9
       2  6:11 pm   ON    M          A                  9
       3  6:12 pm   ON     T         A                  9
       4  6:03 pm   ON      W        A                  9
       5  6:11 pm   ON       T       A                  9
       6  6:04 pm   ON        F      A                  9
       7  6:16 pm   ON         S     A                  9
       8 11:30 pm   OFF  SMTWT       A                8 9
       9 12:30 am   OFF  S     S     A                8 9
       10 6:00 pm   DIM  S           A           6
       11 6:01 pm   DIM   M          A           6
       12 6:03 pm   DIM    T         A           6
       13 6:04 pm   DIM     W        A           6
       14 6:05 pm   DIM      T       A           6
       15 6:06 pm   DIM       F      A           6









     User's Guide and Reference                                          92




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Monitoring and Logging events
     ================================================

     The CP-290 sends a message to your computer after it processes a
     direct command (via XA.EXE or X10.EXE), or after one of its eight keys
     has been pressed, or when it executes an event stored in its memory.
     Most software packages (including X10.EXE shipped with the CP-290)
     will ignore these messages.  XA allows you to monitor and log these
     transmissions if desired.  XA will enter its monitor mode after all
     other commands have been processed.

     You can activate the monitor feature in two ways: as a command, or as
     a command line parameter.

     Command example:

       XA `MONITOR'

     Command line parameter example:

       XA +m

     In the first example, `MONITOR' is the only command that XA processes.
     XA ignores the default command file if it has been specified with
     XACMD.  In the second example, XA would process the default command
     file (if specified) and then initiate the monitor sequence.

     When XA begins to monitor, it displays the following message:

       Monitor events.  Press <ESC> when finished...

     XA then waits for messages from the CP-290.  You may exit this
     function by pressing the <ESC> key.  When the CP-290 executes an
     event, it sends a message to the PC with the following information;
     the HOUSE code, UNIT code, and the event FUNCTION (ON, OFF, DIM).  XA
     takes this information and adds the time and date information from
     your PC's clock and prints the following message to the monitor:

       Sun Mar 24 07:00:13 1991 HOUSE A UNIT 5 ON

     This message is semi-useful; it describes what just occurred but if
     you forgot what was addressed as HOUSE A UNIT 5 then the message is
     meaningless.  You can give this module a more descriptive name by
     using a command file that includes DEFINE statements for all your
     modules.  Below is sample command file (MONITOR.CMD - supplied with
     this package) that describes what we're talking about:

       DEFINE Porch_Garage_Lights A1
       DEFINE Plant_Grow_Lights A 5
       DEFINE Family_Room_TV A6
       DEFINE Basement_Computer A7


     User's Guide and Reference                                          93




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Now when a message is sent by the CP-290, a scan of all the
     definitions will be made to see if the HOUSE and UNIT codes match. If
     so, then that description will be used instead of the codes.
     Therefore, you would get the following message on your screen:

       Sun Mar 24 07:00:13 1991 (A6) Plant_Grow_Lights ON
       Sun Mar 24 08:43:13 1991 (A1) Porch_Garage_Lights ON



     You can also log these events to a file called XA.LOG by specifying
     either the LOG token in a command file or the [+l] option on the
     command line.  Each event reported by the CP-290 will be displayed on
     the screen, and also be appended to the file XA.LOG.  By appending the
     information, all previous events will be saved.  XA.LOG is located in
     the same drive and directory that your `XA' environment variable is
     set to.  See




































     User's Guide and Reference                                          94




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Installation (pg. 14) for more information about the XA environment
     variable.

     POWERUP Utility
     ======================================

     The POWERUP utility is provided in this package to help you perform
     unattended, automatic, event downloads to the CP-290 if your computer
     is controlled by an Appliance module.  POWERUP should be placed in
     your AUTOEXEC.BAT file so it will always be executed during your
     computer's boot phase.  This way, it can decide whether or not it's
     time to perform any updates to your interface, and it prevents you
     from needlessly sending commands when you don't need to.

     The POWERUP command has the following form:

       POWERUP d=day [[d=day]...] [w=1,2,3,4,5] s=hh:mm e=hh:mm   

     The command line parameters may appear in any order, and they must all
     be present (except for `w=` which is optional):

     d=day
     -------------------------------------------

     This is the text string for the day you want to check for.  Legal
     strings are:

       MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY,
       WEEKDAYS, WEEKDAY, WEEKENDS, WEEKEND, EVERYDAY.

     [w=week]
     -------------------------------------------

     This optional argument allows you to specify the week of the month you
     want POWERUP to check for. For instance, to have POWERUP check for the
     3rd SUNDAY of the month, specify:

       POWERUP d=SUNDAY w=3 s=2:55 e=3:05

     You may not specify multiple weeks, however the default condition (not
     specifying the w= command) will still check every week.

     s=hh:mm
     -------------------------------------------

     This is the `window' start time.  Hours must be entered in 24 hour
     format only.

     e=hh:mm
     -------------------------------------------

     This is the `window' end time.  (24 hr format). For example:

     User's Guide and Reference                                          95




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


       POWERUP d=SUNDAY s=2:55 e=3:05

     If the `day' specified matches the day reported by DOS, and the time
     reported by DOS falls within the specified `window', then POWERUP will
     return an ERRORLEVEL of 1, otherwise a 0 is returned. Therefore, by
     placing the proper batch file commands in AUTOEXEC.BAT, you can now
     execute a variety of functions at certain times.  You may enter
     multiple 'd=day' parameters.  For instance, to have Powerup check for
     a window beginning at NOON and lasting until 1:00 pm every MONDAY,
     WEDNESDAY, and FRIDAY, you would enter:

       POWERUP d=MONDAY d=WEDNESDAY d=FRIDAY s=12:00 e=13:00
       if not errorlevel 1 goto :not_day

     If your computer is controlled by an Appliance module, you can now
     automatically download revised event times.  The following example
     also appears in the sample AUTOEXC.BAT file supplied with XA:

       POWERUP d=SUN s=2:55 e=3:05
       if not errorlevel 1 goto SKIP
       XA F=XA.CMD +r1
       REM - Defragment utils, backups also appear here.
       XA `P_C OFF'
       :SKIP

     FINDX10  Utility
     ========================================

     A utility has been added to help determine the configuration of the
     serial port the CP-290 is connected to. After searching all ports in
     your system, FINDX10 determines the IRQ of the port and attempts to
     communicate with the CP-290. If it finds the CP-290, it displays the
     port setup and prompts you if it is OK to save the data in your XA.INI
     file.  If you select 'Y', the IO address and the IRQ level tokens are
     placed at the end of your XA.INI file.

     FindX10 may not work properly if run from a Windows DOS shell.  You
     must exit Windows completely and run standalone DOS.  Also, FINDX10
     may not be able to locate the CP-290 because of the wide variety of PC
     hardware in use.



     Other Programs
     ========================================

     XT - Memory Resident Software for the CP-290
     ----------------------------------------------

     XA is just one of a series of programs that have been developed for
     the X10 CP-290.  If you received XA on a floppy disk, then you should
     have also received a program called XT, a terminate-stay-resident

     User's Guide and Reference                                          96




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     program (or TSR) that sits silently in the background waiting for you
     to activate it with the proper keystroke.  This means you can
     instantly call it from any text-based application.  When activated, it
     displays a list of all modules that you can control with the CP-290.
     Each line on the list contains a description of the module, its
     address, and its current status.  You select the module you want to
     control, and then choose the action (ON, OFF, DIM).

     Since XT is resident, it continuously monitors the serial port for any
     communication transmitted by the CP-290 (such as when an event is
     issued or when one of the buttons on the unit is pressed).  The status
     of each module will always be properly reflected in the pop-up menu.

     XT (version 2.0) now comes with utility package called XTS.EXE.  XTS
     has direct access to XT's database of 256 module states.  Every
     command issued by the CP-290 is captured and stored by XT.  XTS can
     return these module states (via errorlevel statements), allowing you
     to write batch files that react to a module's X10 status.

     XA (2.0 and later) communicates with XT too.  Whenever XA executes a
     direct command, (or monitors X10 activity), it sends the information
     along to XT so the new state is reflected in the XT's database.

     Another feature of XT is its ability to perform a limited `power-fail
     recovery'.

     Look for X10XT200.ZIP.  The version number, 2.00, is the last 3 digits
     of the ZIP filename.  XT can be found on AutoMagic Technologies WWW
     home page, on many BBS's, AOL, and CompuServe. Refer to section
























     User's Guide and Reference                                          97




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Future Updates (pg. 102) .




















































     User's Guide and Reference                                          98




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     FX - TW-523 Command Interpreter
     -------------------------------------------

     FX.EXE is a DOS-based X10 command interpreter for the TW-523.  Valid
     X10 command are ON, OFF DIM and BRIGHT.  These commands can be input
     from the DOS command line, or they may be read from a `script' file.

     A special feature of FX is its ability to send SIMULTANEOUS Bright and
     Dim commands to multiple X10 modules.  This allows you to create some
     very interesting lighting effects.  My primary use for this program is
     for Halloween and Christmas lighting.

     FX communicates with the TW-523 via your computer's parallel port
     (LPT1...LPT3).  Complete instructions for building the necessary
     connectors are included in the documentation.

     Look for X10FX100.ZIP.  The version number, 1.00, is the last 3 digits
     of the ZIP filename.  FX can be found on AutoMagic Technologies WWW
     home page, on many BBS's, AOL, and CompuServe. Refer to section


































     User's Guide and Reference                                          99




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Future Updates (pg. 102) .

     Acknowledgments
     ========================================

     I would like to thank the following people for their help in making XA
     a better program. First of all, thanks go to my wife and children for
     letting me spend the time to pursue this hobby.  Next, my thanks go
     out to this version's primary beta tester: Steven Richardson.  Steve
     put in lots of hours testing many beta versions - the results are very
     worthwhile.  Finally, I'd like to thank all the folks who have taken
     the time to register this program and offer suggestions.









































     User's Guide and Reference                                         100




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Warranty, Copyright, and Registration Policy
     ================================================

     Limited Warranty
     -------------------------------------------

     THIS PRODUCT IS PROVIDED `AS IS' WITHOUT WARRANTY OF ANY KIND.  THE
     ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE PROGRAM IS
     ASSUMED BY YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU (AND NOT THE
     AUTHOR) ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING, REPAIR OR
     CORRECTION.  FURTHER, THE AUTHOR DOES NOT WARRANT, GUARANTEE, OR MAKE
     REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF
     THIS PROGRAM IN TERMS OF CORRECTNESS, ACCURACY, RELIABILITY,
     CURRENTNESS, OR OTHERWISE; AND YOU RELY ON THE PROGRAM AND IT'S
     RESULTS SOLELY AT YOUR OWN RISK.  THE AUTHOR CANNOT ACCEPT
     RESPONSIBILITY FOR SYSTEM DAMAGE, LOSS OF PROFIT, OR ANY OTHER
     SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGE RESULTING FROM THE USE OR
     INABILITY TO USE THIS PRODUCT.

     The author DOES warrant to the original licensee of a REGISTERED
     product that the program disk(s) on which the program is recorded be
     free from defects in materials and workmanship under normal use and
     service for a period of ninety (90) days from the date of delivery.
     The author's entire liability and your exclusive remedy shall be
     replacement of the disk not meeting this Limited Warranty.

     Copyright
     -------------------------------------------

     The XA software package, documentation, utilities, and additional
     support files are Copyright c 1991-1996 by Bruce Christensen and
     AutoMagic Technologies.
     All rights reserved.

     Any specific hardware/software names used in this document are
     trademarks of specific manufacturers.

     Regardless of the method of marketing, XA is not in the public domain.
     It is copyrighted by Bruce Christensen and AutoMagic Technologies.
     All rights are reserved.  Copying, duplicating, selling or otherwise
     distributing the REGISTERED version of this product is a violation of
     the Law.  However, you are granted the right, in fact encouraged, to
     make and distribute as many copies of the SHAREWARE version of XA as
     you wish, using any acceptable medium of exchange, with the following
     provisions:

     Please feel free to distribute this SHAREWARE version as often as you
     like, to any interested parties.

     Please do not distribute this program without all of its original
     related files, addendum files, documentation and this notice.


     User's Guide and Reference                                         101




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Please do not alter the program or documentation in any manner.

     DISTRIBUTION of the REGISTERED USER version of the program is in
     violation of license agreements and copyright Law!

     Registration
     -------------------------------------------

     If you are still using XA beyond the initial 45-day trial period, you
     must register this software with the author.  Please use the included
     registration form (REGISTER.TXT) and send the registration fee to the
     address below.  You may also register this product with Public
     software Library (PsL).  PsL accepts Discover, Visa, MasterCard, and
     American Express.  If you are a member of CompuServe, you may register
     XA using their on-line shareware registration service.  Refer to the
     file REGISTER.TXT that accompanied the XA program for complete
     details.  Your registration will entitle you to the latest full-
     featured registered version of this program, and a printed copy of
     this user manual.

     The registered version of XA and its utilities are licensed for
     individual personal use for an unlimited time.

     This is a `living' program - new features are added from time to time.
     Your input is the basis for future improvements.  Send any comments to
     the address given below, or you may contact me via the AutoMagic
     Technologies Word Wide Web page, CompuServe, America On-Line, or the
     Internet.

       Bruce Christensen
       6594 Hudson Avenue
       Mentor, OH.  44060-4545

       WORLD WIDE WEB    HTTP://MEMBERS.AOL.COM/AUTOMAGICT/
       COMPUSERVE:    73201,1531
       America On-line:  AUGGIEBEN
       Internet Email:     AUTOMAGICT@AOL.COM
       Internet EMAIL:     AUGGIEBEN@AOL.COM















     User's Guide and Reference                                         102




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Future Updates
     -------------------------------------------

     Future updates of the shareware version XA can be found on AutoMagic
     Technologies World Wide Web home page, CompuServe, and America On-
     Line.  Refer to the addresses listed above.  XA can also be found on
     the following Home Automation BBS's.  The current version of XA will
     be named `X10XA320.ZIP'. The last 3 digits of the filename will
     indicate the revision level (in this case, 3.2.0).

     Baran-Harper, a Canadian home automation mail order outfit, also runs
     a very popular BBS. There are many programs for the CP-290 for PC's,
     Mac's, and other computers. The Baran Harper BBS is a free BBS, their
     number is: 1-(905)-471-6776, or 1-(905)-471-9574.

     Circuit Cellar Inc. publishes `The Computer Applications Journal', and
     runs occasional articles on X10.  Their BBS number is 1-(203)-871-
     1988.



































     User's Guide and Reference                                         103




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Appendix A. Tokens - Quick Reference
     ================================================

     Action tokens
     -------------------------------------------
     ON - turns ON the specified modules.
     OFF - turns OFF the specified modules.
     {DIM %%} - DIM to a % (percentage) level of brightness.
     {BRIGHTEN ##} - BRIGHTEN lamp module by ## increments
     {ALL_UNITS_OFF HOUSE x} - turns OFF all modules on selected HOUSEcode.
     {ALL_LIGHTS_ON HOUSE x} - turns ON all lamp/wallswitch modules on 
          selected HOUSEcode.



     Module address tokens
     -------------------------------------------
     A1...P16
     HOUSE A...P
     UNIT 1...16
     UNIT ALL


     Coordinate tokens
     -------------------------------------------
     {LATITUDE dms} - your LATITUDE in Degrees and Minutes
     {LONGITUDE dms} - your LONGITUDE in Degrees and Minutes
     {TIMEZONE x} - your TIMEZONE (Standard/Daylight Savings)
     DST - Automatic Daylight Savings adjustments


     Clock tokens
     -------------------------------------------
     {SYNCHRONIZE PC [EXACT]} - set PC time based on X10 time
     {SYNCHRONIZE X10 [EXACT]} - set X10 time based on PC time


     Day tokens
     -------------------------------------------
     SUNDAY, SUN - Specific day for event to occur
     MONDAY, MON -   
     TUESDAY, TUE -
     WEDNESDAY, WED -
     THURSDAY, THU -
     FRIDAY, FRI -
     SATURDAY, SAT - 
     EVERYDAY - Event occurs everyday
     TODAY - Event occurs once today only
     TOMORROW - Event occurs once tomorrow only
     ODD - Event occurs only on odd-numbered days.
     EVEN - Event occurs only on event numbered days.
     EXPAND - Expands a single event into multiple events

     User's Guide and Reference                                         104




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     WEEKDAY, WEEKDAYS - Event occurs only on weekdays
     WEEKEND, WEEKENDS - Event occurs only on weekends
     EVERY `n' DAYS [FROM mm/dd/yy - Repeats event every number of days
     EVERY `n' WEEKS [FROM mm/dd/yy - Repeats event every number of weeks


     Time tokens
     -------------------------------------------
     {hh:mm (AM)(PM)} - Schedule event time
     SUNRISE - Calculate time of sunrise
     SUNSET - Calculate time of sunset
     {[OFFSET] +/-hh:mm} - Event occurs +/- 23h59m of prog time
     NORMAL - Event occurs at specified time
     SECURITY - Event occurs within the hour
     {RANDOM +/-hh:mm} - Event occurs within a random offset +/-23h59m.
     {NOW hh:mm} - Event occurs with respect to current time.


     Specific Date tokens
     -------------------------------------------
     {mm/dd/yyyy} - Event occurs on specified date, multiples allowed.
     {mm/dd/yyyy THRU mm/dd/yyyy (SUNDAY...SATURDAY)} -
          Event occurs between two dates, multiple ranges allowed.
     {EXCEPT mm/dd/yyyy} - Event does NOT occur on specified date
     {EXCEPT mm/dd/yyyy THRU mm/dd/yyyy (SUNDAY...SATURDAY)} -
          Event does NOT occur between two dates, multiple ranges allowed.
     {mm/dd/yy THRU mm/dd/yy EXCEPT mm/dd/yy THRU mm/dd/yy} -
          Special exceptions within a given range, multiple ranges allowed.

     Communication tokens
     -------------------------------------------
     {COMx} - send commands via COM1...COM4
     {IRQ x} - customize IRQ level for port.
     {IO x}  - customize port address (in hex).

     Miscellaneous tokens
     -------------------------------------------
     {BASECODE x} - Change BASECODE to A...P
     {HOUSECODE x} - Change BASECODE to A...P
     {DEFINE x z}      - Substitute string 'x' for 'z'
     {XACMD file.cmd} - Specify default command file.
     {INCLUDE filenme} - Specify another file to parse.
     {CLEAR EVENT xxx} - Clear event xxx from CP-290 memory
     {CANCEL -cmd-} - Remove or modify event from CP-290 memory
     ERASE - Erase ALL events from CP-290 memory
     {EVENT xxx} - Place event xxx in a known location of CP-290 memory
     BEEP - Causes PC speaker to beep.
     {DOS command} - Shell to DOS
     {SPAWN command} - Shell to DOS, returns `errorcode'.
     {variable = House/Unit STATUS} - determines programmed state of module
     {DISPLAY ON/OFF} - Turn XA output display on or off.
     {DISPLAY var} - Displays value of declared variable.

     User's Guide and Reference                                         105




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     {DISPLAY string} - Displays ascii string (regardless of ON/OFF 
          condition.
     DIAGNOSE - CP-290 performs internal diagnostics.
     {XACMD filename} - defines default command file.
     $ - Line Continuation Character.

     Reporting tokens
     -------------------------------------------
     LOG - Append event info to file XA.LOG
     MONITOR - Watch events as the CP-290 executes them.
     REPORT1 - Produce report file based on daily events.
     REPORT2 - Produce report file based on a module by module basis.
     REPORT3 - Produce report file based on event numbers.

     Direct Command Control Tokens
     -------------------------------------------
     :LABEL - Identify an area to `goto/gosub' later.
     {GOTO :label } - Jump to location identified by `label'.
     {GOSUB :label} - Execute subroutine identified by `label'. Upon 
          returning, continue with the rest of the cmd file.
     RETURN - from subroutine (used with GOSUB).
     STOP - Force XA to stop execution
     :EXIT - Special shutdown location jumped to when <ESC> pressed.
     {DELAY hh:mm:ss} - Wait for time to pass before executing the next 
          cmd.
     PAUSE - Halt execution of direct commands until key pressed, then 
          reset internal timer and resume direct commands.
     {TIMER hh:mm:ss.s} - Wait until `seconds' have elapsed (relative to 
          the internal timer).
     RESET - Reset internal timer.
     FAST - ignore ack message from CP-290, speeds up single cmds.

     Conditional Expressions
     -------------------------------------------
     IF (expression)     When expression evaluates TRUE...  
       statements        execute the following statements
     [ELSE          Otherwise...
       statements]       optionally execute the following statements
     ENDIF          Must always terminate conditional statements.

     Arithmetic Operators
     -------------------------------------------
     * Multiply       A = B * C
     \ Divide       B = A \ C
     + Addition     C = A + B
     - Subtraction    A = C - B
     - Unary minus  A = -B
     % Modulus   A = B % C





     User's Guide and Reference                                         106




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Relational Operators
     -------------------------------------------
     = Assign
     < Less than
     > Greater than
     <=Less than or equal to
     <>Not equal to
     >=Greater than or equal to
     ==Equals (not to be confused with '=' assignment operator)


     Logical Operators
     -------------------------------------------
     AND  Logical AND
     &&   Logical AND
     OR   Logical OR
     ||   Logical OR
     !    NOT


     Bitwise Logical Operators
     -------------------------------------------
     & Bit `AND'
     | Bit `OR'


     Screen Color Control
     -------------------------------------------
     {VIDEO1 Foreground Background} - IF/ELSE evaluates to TRUE
     {VIDEO2 Foreground Background} - IF/ELSE, or DATE/THRU/EXCEPT 
          evaluates FALSE
     {VIDEO3 Foreground Background} - Sending DIRECT commands to CP-290
     {VIDEO4 Foreground Background} - Sending EVENTS to CP-290
     {VIDEO5 Foreground Background} - Important XA messages
     {VIDEO6 Foreground Background} - Statements that are non-event or non-
          commands.
     {VIDEO7 Foreground Background} - Bargraph display
     {VIDEO8 Foreground Background} - Comments

       where FOREGROUND may be any of the following:  
          BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY,
          DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED,
          LIGHTMAGENTA, YELLOW, WHITE

       and BACKGROUND may be any of the following:  
          BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY

     I/O Port Control
     -------------------------------------------
     {(variable =) INPORT io_port} - read status of port
     {OUTPORT io_port value} - output value to port


     User's Guide and Reference                                         107




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Variables
     -------------------------------------------
     {DECLARE DATE variable_name [=mm/dd/yy] - Declare, initialize DATE 
          var.
     {DECLARE TIME variable_name [=hh:mm] - Declare, initialize TIME var.
     {DECLARE DAY variable_name [=MON|TUE...] - Declare, initialize DAY 
          var.
     {DECLARE VAR variable_name [=value] - Declare, initialize general 
          purpose var.

     Pre-defined Variables
     -------------------------------------------
     CDAY - The current day (Mon, Tue)
     CDATE - The current date
     CMONTH - The current month (1=Jan, 2=Feb)
     CMONTHDAY - The current day of the month (1...31)
     CYEAR - The current year (1994...)
     CYEARDAY - The current day of the year (1...366)
     CTIME - The current time (in 24 hr format)
     CHOUR - The current hour (00...23)
     CMIN - The current minute (00...59)
     CSEC - The current second (00...59)


     Joystick Support
     -------------------------------------------
     JOYSTICK - Reads current status of joystick and saves values in:
     JOY1B1 - Switch status of Joystick 1, Button 1
     JOY1B2 - Switch status of Joystick 1, Button 2
     JOY2B1 - Switch status of Joystick 2, Button 1
     JOY2B2 - Switch status of Joystick 2, Button 2
     JOY1X  - Resistive value of Joystick 1, X coordinate
     JOY1Y  - Resistive value of Joystick 1, Y coordinate
     JOY2X  - Resistive value of Joystick 2, X coordinate
     JOY2Y  - Resistive value of Joystick 2, Y coordinate


















     User's Guide and Reference                                         108




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Non-Volatile Variables
     -------------------------------------------
     NVOL1 - First 32-bit variable stored in CP-290's non-volatile memory 
          area.
     NVOL2
       :
     NVOL19
     NVOL20 - Last 32 bit variable stored in CP-290's non-volatile memory 
          area.

     Powerfail Recovery module status overrides
     -------------------------------------------
     {IGNORE HOUSE UNIT} - Leave module in its present state
     {FORCE HOUSE-UNIT state} - Force module to ON, OFF, DIM state


     Menus / Function Keys
     -------------------------------------------
     { [varaible = ] INKEY} - Read a keystroke If one is available.
     { [varaible = ] INKEYW} - Wait for a keystroke.
     F1KEY...F12KEY - Normal Function keys.
     SF1KEY...SF12KEY - <Shift> Function keys.
     CF1KEY...CF12KEY - <Ctrl> Function keys.
     AF1KEY...AF12KEY - <Alt> Function keys.





























     User's Guide and Reference                                         109




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Appendix B. Passing arguments to your command file.
     ========================================================

     By default, XA will only accept input from either the DOS command line
     (i.e., commands enclosed in `parentheses'), or via a file.

       XA `P1 OFF'    <=== DOS command line arguments.
       XA F=XA.CMD  <=== XA Command File.

     You may now override this feature and have XA interpret commands from
     the DOS command line as well as a file by using the following format:

       XA `command' f=file.cmd  -or-
       XA f=file.cmd `command'  (The order is not important).  

       XA `P1 OFF' f=XA.CMD

     This form of operation is very useful if you wish to pass special
     arguments into your command file and allow XA to activate special
     sequences. Your normal command file (XA.CMD) could contain some
     special commands that are only activated when you define a variable to
     be a certain value. The following sample code is executed when the
     variable `Babysitter' is set TRUE:

       IF (BABYSITTER)  
          FOYER_LIGHTS ON DUSK TODAY  
          HALLWAY ON SUNSET TODAY  
          DECK_LIGHTS ON SUNSET TODAY
       ENDIF

     To have XA execute the above sequence, you must program the command
     file name AND the variable assignment statement:

       XA F=SPECIAL.CMD `BABYSITTER = TRUE'



















     User's Guide and Reference                                         110




           XA - X10 COMMAND INTERPRETER - VERSION 3.2


     Appendix C. Running XA in Windows
     ================================================

     XA may be run in the Windows environment. A major advantage is the
     ability to multi-task your applications while XA monitors the CP-290,
     downloads new event schedules, or performs a special lighting
     sequences.  In order to use XA successfully in Windows, you must
     ensure that Windows understands your COM port configuration. Follow
     these steps (applies to Windows 3.1):

     Run `Program Manger'

     In the MAIN group, run `Control Panel'

     Run `Ports'

     Select the COM port that the CP-290 is connected to. This should match
     the COM token in you XA.INI file. Press `Settings'.

     Set the Baud Rate to 600, Data Bits to 8, Parity to None, Stop  Bits
     to 1, and Flow Control to None.

     If you use the tokens `IO, IRQ, i=, o=` in your XA.INI file (or
     command line), you should press `Advanced...' button to verify these
     settings.  Make sure the Base I/O Port Address matches the address of
     your COM port. See the table in the XA documentation for typical
     addresses of the COM ports.  Next, ensure that the IRQ is set
     properly. Select `OK'.

     Select OK.  Windows may need to reboot your machine in order to
     activate these parameters.

     Several PIF files were included with XA to perform such functions as
     downloading events, monitoring CP-290 activity, and recovering from a
     power failure. You will need to customize these files based on your
     installation.

















     User's Guide and Reference                                         111
