XA X10 Command Interpreter Version 2.00 - October 1993 Copyright 1993 by Bruce Christensen. All Rights Reserved. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 1. 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. 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 of $29 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, see "License Agreement and Registration" and register your copy of XA. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 2. Introduction ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 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. It gets even worse when 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 at HOUSE A UNIT 9, or whatever address you choose (you define modules and their addresses in the file XA.INI, discussed later). 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 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 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ The next section highlights the many additions to XA Version 2.00. Note that some items are reserved only for "registered" users. The "shareware" version of XA provides all the features of past versions, plus many newer features. When you register your copy of XA, you will receive a floppy with a "registered" status allowing full use of the commands described in this manual. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 3. Summary of NEW Features for Version 2.00 ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ The last "official" release of XA was Version 1.07b (dated July, 1992). Version 2.00 is a complete re-write, allowing such features as conditional statements, operators, and user-variables to be supported. Also, XA performs sun-related calculations much faster. The following list highlights the major enhancements of Version 2.00. Additional details may be found in later sections. * Improved HELP screens Type "XA /?" at the DOS prompt to get on-line information about XA's syntax and features. * Power-fail recovery mode. This feature allows you to restore the programmed state of each module in the eventuality of a power failure, or other circumstance. XA determines the latest state of the 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. * Improved DATE handling. A new token "EXCEPT" has been added which allows to program events to occur EXCEPT when certain dates arrive: DEFINE MEMORIAL_DAY DATE 5/31 BEDROOM_LIGHTS ON WEEKDAYS 6:30 EXCEPT MEMORIAL_DAY * 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). * IF/ELSE/ENDIF constructs. (Registered Version Only) Finally! Support for conditional statements within your command files. Now you can perform a test to see whether SUNRISE falls within a certain time period, and schedule events based on the result. IF/ELSE statements may be nested up to 100 levels deep. * Variable assignments (Registered Version Only) 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. * Logical, Arithmetic operators. (Registered Version Only) Operations may be performed on variables and later evaluated. * 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). * INPUT/OUTPUT (I/O) control. (Registered Version Only) Use your Joystick port, LPT port (or any other 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. * 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. * Nested DEFINE support. In the past, XA could not handle a statement with multiple DEFINE substitutions. The following is now permitted: DEFINE PORCH A1 DEFINE GARAGE A2 DEFINE OUTSIDE PORCH GARAGE * "ALL_LIGHTS_ON", "ALL_UNITS_OFF". These "undocumented" CP-290 commands are fully supported. * 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 acknowledgement message thus speeding up overall execution time. * Conditional COLOR highlighting. (Registered Version Only) XA can optionally display each line of the XA.INI and command file as it's parsed. In addition, 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. * 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. * Utility to locate CP-290 port connection. A new 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. Other Features ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ - 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 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ - You can program the CP-290 to repeat a series of commands to produce unique lighting effects. - 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 2 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. - The ability to change the base housecode without losing all the data already stored in the interface. - String substitution in the command file allows you to equate a device (FAMILY_ROOM_LAMP) with its module address (A3). - Comments are allowed in the file to properly document its content. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 4. 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. For more information, refer to the section - "Powerup Utility". 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 address and IRQ 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. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 5. 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. 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 chapters dealing with XA.INI - INITIALIZATION FILE, and FINDX10.EXE later in this manual for more details. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 6. Getting Started ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ XA may be invoked several different ways. How you configured XA, or the types of parameters that you use with it, determine 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 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 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" 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. Events are distinguished from direct commands by the fact that events normally contain a DAY modifier (in this case MONDAY - but you could also use TODAY or TOMORROW) and a TIME modifier (SUNSET is a special TIME token). 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. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 7. XA Syntax and Command Line Arguments ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ XA understands the following command line options: XA ["commands"...] [f=filename] [-e] [+l] [+m] [+p] [-p] [+r1] [+r2] [c=comm port] [i=irq] [o=io_addr] [/?] Options appearing on the command line always override any options that have been specified in XA's command and initialization files. 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 any conflict. 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. ["commands"] "commands" consist of one or more tokens (see "Tokens" later in this document) 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". You can specify a default command file using the "XACMD" token in the XA.INI initialization file (described in greater detail later). See also: Miscellaneous tokens: XACMD XA.INI - Initialization file [-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. [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 the table listed in the "Communications Tokens" section, later in this document. See also: Communication tokens: COM1...COM4 Command Line options: [o=io_addr] [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 See also: Communication tokens: IO x [i=irq] Interrupt-driven: i=irq (3,4,5...) Default: i=4 (for COM1). See also: Communication tokens: IRQ x [+m] This option will monitor the comm port for any events reported by the CP-290. Press the key to terminate. See also: Reporting tokens: MONITOR "Monitoring and Logging Events" [+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 "Installation"). See also: Reporting tokens: LOG "Monitoring and Logging Events" [+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 "Report Files" [+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"). 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 "Report Files" [+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 module to its scheduled state. By default, XA uses the last 7 days to determine the state. You can tell XA to use fewer days if necessary. Simply append a number between 1and 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. See also: "Powerfail Recovery" [/?] [/h] [/H] Displays a summary of the options described above, along with a list of all supported tokens recognized by the interpreter. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 8. 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 the token 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 parentheses (..). Most or the examples in the next 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. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 9. Tokens in Detail ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ Action Tokens ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ON This token informs the interface to turn ON the selected modules. XA "A1 ON" OFF This token informs the interface to turn OFF the selected modules. 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. The percentage level you select may not correspond exactly with level reported by the X10-supplied program X10.EXE. XA "A1 DIM 50" {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 in the next section): XA "HOUSE A UNIT ALL OFF" {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. XA "ALL_LIGHTS_ON HOUSE A" 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 were 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" 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" 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" or use the faster method: XA "HOUSE P ALL_UNITS_OFF" Notes: * 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" * You can give your module's more descriptive names by using the DEFINE token (described later). For instance, place the following line in your XA.INI file: DEFINE COFFEE HOUSE A UNIT 10 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 U.S. 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 41d35m20s -or- LATITUDE 41ø35'20" {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 81d20m45s -or- LONGITUDE 81ø20'45" {TIMEZONE x} Exact calculations depend on the local time. Use the following table to determine your time zone. Previous versions of XA included "Daylight Savings" values in this table. It is no longer necessary to manually change these tokens. Use the DST token to automatically adjust time changes. ZONE TIMEZONE ============= ======== Eastern 5 Central 6 Mountain 7 Pacific 8 Alaska/Hawaii 10 Aleutian 11 TIMEZONE 5 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 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 "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 "SYNCHRONIZE X10 EXACT" Notes: * 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. 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 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 MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY. 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" 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" is also programmed causing the event to trigger before midnight, the event will be modified for TODAY status. 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 XA'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 TIME 11:00 PM" * Registered Users - 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. Note: Use of the IF/ELSE/ENDIF and CDAY tokens, as well as the "==" and "OR" operators will be discussed later in this document. IF ((CDAY == SAT) OR (CDAY == SUN)) XACMD WEEKEND.CMD ELSE XACMD WEEKDAY.CMD ENDIF 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. 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" 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. {DATE 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, or 4 digits (1994 - NOT 94). To specify module A5 ON July 4, 1994 at 5:00 pm: A5 ON DATE 7/4/1994 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: DATE /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: DATE 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: DATE 7/4 A5 ON SUNSET You may specify multiple dates in the same command: DATE 7/4 DATE 7/6 DATE 7/8 A5 ON SUNSET {DATE mm/dd/yyyy THRU mm/dd/yyyy (DAY)} 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, 1994 and August 1, 1994, and you want the bedroom lights (A3) turned ON and OFF every weekday in a random fashion during the evenings: DATE 7/1/1994 THRU 8/1/1994 ON A3 TIME 9:00 PM SECURITY WEEKDAYS DATE 7/1/1994 THRU 8/1/1994 OFF A3 TIME 11:30 PM WEEKDAYS To turn ON your Christmas lights everyday between Dec. 1st and Jan. 1st. Turn them OFF at 10:00PM on weekdays, turn them off at 11:30 during the weekends: DATE 12/1 THRU 1/1 XMAS ON SUNSET DATE 12/1 THRU 1/1 XMAS OFF TIME 10:00 PM WEEKDAYS DATE 12/1 THRU 1/1 XMAS OFF TIME 11:30 PM WEEKENDS 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 DATE 5/31 You may specify multiple exception dates in the same command: A7 ON WEEKDAYS SUNSET EXCEPT DATE 5/31 DATE 7/1 Notes: - Use the format: {EXCEPT DATE 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 DATE 12/1/1994 THRU 1/1/1995 Special Note: When dates "rollover" into the next year, you must specify the "year" within the date statement (as in the above example). - Use the format: {DATE mm/dd/yyyy THRU mm/dd/yyyy EXCEPT DATE mm/dd/yyyy THRU mm/dd/yyyy} to specify a range of dates that a module should not activate, within a range of dates that they should be activated. For instance, turn on deck lights only during the summer, except while you are on vacation: DECK ON SUNSET DATE 6/21 THRU 9/22 EXCEPT DATE 7/1 THRU 7/14 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. {TIME hh:mm (AM/PM)} Schedule event at a certain time. XA "D1 ON SUNDAY TIME 12:30 AM" AM is the default. You may specify military-style time as follows: XA "D1 ON SUNDAY TIME 23:34 " 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 If more accuracy is needed, then break each daily event into its own command. MONDAY ON SUNSET D1 TUESDAY ON SUNSET D1 WEDNESDAY ON SUNSET D1 {OFFSET +/-hh:mm} {OFFSET +/-mins} 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: MONDAY ON SUNSET D1 OFFSET 30 Turn lights OFF 1 hour before sunrise: MONDAY OFF SUNRISE D1 OFFSET -1:00 See section Miscellaneous Tokens - DEFINE for another way of specifying DUSK or DAWN using the DEFINE token. For example: DEFINE DUSK SUNSET OFFSET 30 DEFINE DAWN SUNRISE OFFSET -1:00 : MONDAY ON DUSK D1 MONDAY OFF DAWN D1 {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. This 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 hours later Earlier versions of XA required the use of the EVENT token in order to prevent overwriting existing events in the CP-290's memory. XA Version 2.0 automatically appends the command to current schedule, eliminating the need to figure this out manually. NORMAL This token activates the event at the specified time. It is the default mode, therefore it does not need to be specified. {RANDOM +/-hh:mm} {RANDOM +/-mins} Prior to Version 1.07, RANDOM used to be synonymous with the SECURITY token, which merely activated the CP-290 built-in time adjustment. This feature would pseudo-randomly select a time for event activation anytime within the programmed hour. "RANDOM hh:mm" now gives you complete control over the random window. "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 TIME 5:00 PM RANDOM +9 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. 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 of either side of SUNSET: # Sunset @ 9:00 PM 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. SECURITY This token allows the CP-290 to 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:18 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 TIME 7:30 PM SECURITY EVERYDAY" 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. The "registered" version of XA can also read data from an I/O port, allowing X10 commands to be synchonized with an external event. PAUSE When this token is executed, it displays a message and halts further execution of the command file.: "Press any key to continue..." When a key press is detected, an 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 mm:ss.s This token informs XA to issue a command when the internal timer reaches "mm:ss.s". The built-in 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 (Registered version may use INPORT) token to intialize the timer, as well as provide 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:10.0 # At 10 seconds, turn on A1 A1 DIM 0 TIMER 0:20.5 # At 20.5 seconds, fade light out. 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, the amount of time it takes to turn on a lamp may take as much as 1.4 seconds. 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: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: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 'minutes' field, even if it is zero. Otherwise, XA will convert the 'seconds' field to minutes, and you'll be waiting a long time. For example, do this: TIMER 0:15.5 <--- Do this TIMER 15.5 <--- NOT this RESET When the RESET token is parsed, the internal timer is preset to 0. The PAUSE token also presets the 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 can monitor a bit of a selected port and force a RESET when the bit goes TRUE. INPORT is only available in the "registered" version). {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. To wait 5 seconds between commands, use: 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. 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 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 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". NOTE: Earlier versions of XA used the following syntax: GOTO :label times where "times" acted as a counter. This method is no longer supported. Use the conditional statements (IF/ELSE - "registered" versions only) instead to control looping. The following code flashes (turns ON and OFF) a module addressed as A1 three times. It uses a variable (see Section - Variables) named "COUNTER" that is incremented and tested every time the loop is executed. When COUNTER reaches 3, the IF portion of the test is no longer true, so XA continues with the rest of the program: 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 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 everchanging 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. It is good practice to place subroutines in the beginning of the command file so that searching will be minimized. See the sample "XMAS.CMD" command file for an example. 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 FAST By default, XA always waits for an acknowledgement 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" 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 acknowledgement 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. 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 offending port. Comm Port I/O Address IRQ Level --------- ----------- --------- COM1 3F8H (Hex) 4 COM2 2F8H 3 COM3 3E8H 4 COM4 2E8H 3 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. {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 using HEXADECIMAL numbers, you must specify the H. This is no longer implied. * 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 I/O Port Control ( ** Registered Version Only ** ) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ XA can read and write to most of the I/O ports. Of particular interest is the Joystick or Game port. This port (location 201 Hex) provides up to four digital inputs. XA can read the state of these ports and react accordingly. See the sample command file "JOYSTICK.CMD" for an example of turning a light on or off based on the state of the joystick switch settings. {(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 byte value to the selected io_port. 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 you might possibly inflict on you or your computer. 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 TIME 8:00 PM EVERYDAY" as follows: DEFINE XMAS_ON HOUSE A UNIT 4 ON TIME 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 TIME 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 TIME 6:00 AM EVERYDAY PLANT_GROW_LIGHTS OFF TIME 12:00 AM EVERYDAY : OUTSIDE_LIGHTS OFF SUNRISE EVERYDAY : ALL_ON SUNDAY TIME 7:30 PM The use of DEFINES is helpful if you want to monitor the CP-290 for events as they occur. See Section - Monitoring. {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. When you produce a report file, the event number assigned to each event is printed in the right-most column of the listing. If you produced a report file while using the "-e" (no command execution), then the event number displayed will be -1, signifying that the event is not stored in the CP-290. {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" 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. Use the report listing to display each events 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. ERASE This token erases all events from the CP-290 memory. If you use XA to maintain you 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 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 memory automatically. {BASECODE 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 are downloaded back into the interface. Valid housecodes are A...P. XA "BASECODE D" XA displays a bar graph during the upload and download phases providing a visual indication of progress, as well as the amount of available event storage. DIAGNOSE This token triggers the CP-290's built-in diagnostic routine. 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 are downloaded back to the CP-290. {XACMD filename} This token is intended to be placed inside the XA initialization file (XA.INI - see next section). It defines the default command file that XA should parse and execute if no other commands files or direct commands are present. If your XA.INI file contains the following line: 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 later section for IF/ELSE programming): IF ((CDAY == MON) OR (CDAY == WED) OR (CDAY == FRI)) XACMD M_W_F.CMD ELSE XACMD XA.CMD ENDIF {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 begin 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 >= DATE 8/21) AND (CDATE <= DATE 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 (taken from JOYSTICK.CMD) tells the SoundBlaster to play the GREETING.VOC file: DOS c:\sblaster\vplay c:\sblaster\greeting.voc Display a directory: DOS dir Use XA to kickoff a communications program at a precise time (see PHONE.CMD): # At 11:15, Call BBS... DISPLAY OFF :WAIT IF (CTIME < TIME 11:15 PM) GOTO :WAIT ENDIF DOS PROCOMM options... # Invoke PROCOMM with command line # parameters... BEEP The BEEP token will issue a short tone through your PC's speaker. {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, comments, 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 turn 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 toggle 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. 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. See section - "Monitoring and Logging Events" for more information. LOG This token appends the monitored information in the file XA.LOG. REPORT1 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. Powerfail Recovery ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Powerfail recovery allows you to restore each module to its scheduled state. By default, XA uses the last 6 days to determine the state. You can tell XA to use additional 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. 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 %% Example: FORCE P_C ON {IGNORE module} Ignores sending any command to module during a powerfail recovery. "Module" can be a module address or pre-defined name. Example: IGNORE DEHUMIDIFIER 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 Screen Color Control ( ** Registered Version Only ** ) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Screen color control lets you program how commands should be displayed. You will be able to tell at a glance how certain conditional statements (IF/ELSE) were evaluated by XA just by looking at the display. {VIDEO1 Foreground Background} IF or ELSE evaluates to TRUE {VIDEO2 Foreground Background} IF or ELSE evaluates to FALSE {VIDEO3 Foreground Background} Sending DIRECT commands to CP-290 {VIDEO4 Foreground Background} Sending EVENTS to CP-290 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 To display a "TRUE" IF/ELSE statement in GREEN foreground characters on a BLACK background, and a "FALSE" IF/ELSE 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 ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 10. Programming Additions ( ** Registered Version Only ** ) ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ Variables ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Variables are user-defined objects which may be assigned values, or examined. You can assign numbers, dates, times, port data, true/false data into a variable. Variables are dynamically created at the first instance when XA parses a token that is not part of the normal XA language. For instance, the following statement declares a variable called VACATION, because VACATION is not part of XA's syntax. vacation = WEEKEND Internally, variables are treated as 32 bit integer values. When variables are created they are initialized to 0 as soon as they are parsed. However, they may be assigned a different value in the declaring statement. In the above example, "VACATION" was assigned the value WEEKEND (the internal value is set to 96, or 60 Hex - but you don't really need to know that). The next example declares a variable called "ATHOME", assigning it a value of 1. DEFINE TRUE 1 DEFINE FALSE 0 ATHOME = TRUE First, we define constants TRUE and FALSE to be 1 and 0 respectively. Next, we declare a variable called ATHOME. Internally, the variable is created and initialized to 0. The statement is parsed further, the assignment operator "=" sets ATHOME equal to TRUE (or 1). When declaring variable, the first character in its 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 characters are converted to UPPERCASE. The list of legal characters are: ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_ Examples: BIRTHDAY <--- This is OK! 1_BIRTHDAY <--- Can't start with a numeric value BIRTH,DAY <--- Comma not a valid character 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 hexadeciaml digits in the range of 0...F. The trailing H indicates the number is hex and is always required. Example: IO 3E8H Note: 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 to 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 >= DATE 11/25) AND (CDATE <= DATE 12/31)) INCLUDE XMAS.CMD ENDIF When comparing dates with CDATE, make sure you specify the DATE token: IF (CDATE == 12/25) <--- This is WRONG! IF (CDATE == DATE 12/25) <--- This is CORRECT! 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 >= TIME 11:30 PM) GOTO EXIT ENDIF ELSE IF (CTIME >= TIME 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. 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 Relational Operators ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Operator Function ======== ============================= = Assigns a value to a variable < Less than > Greater than <= Less than or equal >= Greater than or equal <> Not equal == Equals (values match) 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 Truth Table for logical operators ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 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 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 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 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. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 11. 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 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 Installation) 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, this allows you to send descriptive X10 commands that don't rely on your memory for the actual house and unit codes. For instance: XA "DEN ON" turns ON the unit at Housecode A Unit 5. Do not place events or direct commands in this file, or they will be executed every time you invoke XA. 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 appear in any 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. The token XACMD specifies the default command file that should be executed if no direct command was included at the DOS prompt. The next section describes what command files are and how they are used with XA. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 12. 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 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. 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.0, 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 (Registered version only). For example, suppose your normal command file (XA.CMD) contains special lighting events that you activate when you plan on vacationing for the weekend: 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" ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 13. 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 (including 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 intialization 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, 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 later evaluated so special actions can be taken inside your command file. See the previous section for more details. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 14. Report Files ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ XA can produce a report of all events that were just parsed by the interpreter. These reports come in 2 styles: * Events sorted by day and time * Events sorted by day, module, and time. You have the option of selecting any style, or both 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, revision number, 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 DEFINE must include both the HOUSE and UNIT tokens when describing a module. You should not use the short cut method, such as: DEFINE Porch_Lights A 1 <=== will NOT work. DEFINE Porch_Lights HOUSE A UNIT 1 <=== will work. 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, and all event numbers will be set to -1. 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. 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. Saturday - September 25, 1993 Sunrise: 7:15:27 Sunset: 7:18:53 Time Cmd Mode Module Address/Description Event ======== === ==== ========================== ===== 1:30 am OFF (A3) BEDROOM_LIGHT ( 75) 5:00 am ON (B2) DEHUMIDIFIER ( 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 ( 72) 7:18 pm DIM (A9) OUTSIDE_PORCH_LIGHT ( 66) 7:23 pm ON (A1) DECK_LIGHTS_1 ( 69) 7:48 pm DIM (A6) STAIRS ( 82)* 7:48 pm DIM (A1) DECK_LIGHTS_1 ( 70) 7:48 pm ON (A8) LIVING_ROOM_LAMP ( 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)* 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. 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)* (H1) HALLWAY 6:48 am OFF ( 81)* 9:45 pm DIM ( 86)* ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 15. 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 as well as 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 -e In the first example, XA "MONITOR", the command "MONITOR" informs XA to watch for any transmissions from the CP-290. The second example uses command line options and has the same effect, but remember that if no commands were actually present, the XA utility will try to open the default command file and process the commands found in there. If you don't want that to happen, use the "-e" option which tells XA not to execute (or download) those commands. When XA begins to monitor, it displays the following message: Monitor events. Press when finished... XA then waits for messages from the CP-290. You may exit this function by pressing the 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 HOUSE A UNIT 1 DEFINE Plant_Grow_Lights HOUSE A UNIT 5 DEFINE Family_Room_TV HOUSE A UNIT 6 DEFINE Basement_Computer HOUSE A UNIT 7 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 In the above messages, a combined House and Unit code (A6) is automatically provided, you don't have to include it as part of the DEFINE token. Also, the DEFINE must include both the HOUSE and UNIT tokens when describing an object. You can not use the short cut method, such as: DEFINE Porch_Lights A 1 <=== will NOT work. DEFINE Porch_Lights HOUSE A UNIT 1 <=== will work. If different modules are controlled by a single event, the module which has the lowest UNIT code will be displayed. Therefore, if modules C9 and C10 are programmed as a single event, only C9 will be displayed. 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. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 16. 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 after your computer boots. 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="): 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 optionally 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: 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 errorlevel == 1 echo It's time! If your computer is controlled by an Appliance module, you can now automatically download revised event times. See the sample AUTOEXEC.BAT file included in this package. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 17. FINDX10.EXE ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ A new 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. Because of the wide variety of hardware in use, FINDX10 may not be able to locate the CP-290. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 18. Other Programs and X10 Information ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 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 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 1.2) now comes with utility package called XTS.EXE. XTS has direct access to XT's database of 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) 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". This function analyzes all events stored in the CP-290 and sets each module to its proper state based on this information. This feature can be activated during program installation, or whenever the menu is displayed. Other Information ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ If you would like further information about the X10 system, then contact Steve Mueller of the Silicon Valley Video Group. Steve has put together a paper (currently 60 pages) which covers such topics as: X10 transmission theory, undocumented functions of the CP-290, debugging spurious failures, modifying X10 devices (local dimming), descriptions of the PL-513 and TW-523 modules, CP-290 Users and Programming Guides, and manufacturers/retailers of X10 compatible equipment. There is a charge for Steves paper. You may contact Steve via: Steve Mueller Silicon Valley Video Group 335 Bodega Way San Jose, CA. 95119-1603 or via Prodigy - SJCR28A ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 19. Acknowledgements ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ I would like to thank the following people for their help in making XA a better program. The beta testers - Dave Mabry, Ed Christie, David Huras, Nira Johnson. Also, my thanks to Arnold Sprague for proofreading the documentation. Finally, to all the folks who have taken the time to register this program and offer suggestions. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 20. 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, its utilities and this document is Copyright (C) 1991-1993 by Bruce Christensen. 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. All rights are reserved. Copying, duplicating, selling or otherwise distributing the registered version of this product is a violation of the Law. However, we grant you the right, in fact encourage you 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. 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 a $29 registration fee to the address below. 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 on Prodigy, America On-line, or Internet. Bruce Christensen 6594 Hudson Avenue Mentor, OH. 44060-4545 Prodigy ID: MHNC39A America On-line: AuggieBen Internet: auggieben@aol.com Future Updates ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Future updates of the shareware version XA can be found on these BBS's as they become available. The current version of XA will be named "X10XA200.ZIP". The last 3 digits of the filename will indicate the revision level (in this case, 2.00). Dave Mabry, a sysop of the "Going Down BBS" has offered free access to his BBS to anyone interested in X10 - Home Automation. You will be granted access once you have completed a short questionnaire. The new user password is currently "DRYSUIT". This BBS can be reached at: 1-(313)-576-7882. 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. X-10 is a registered trademark of X-10 (USA) Inc. Prodigy is a registered service mark and trademark of Prodigy Services Co. America On-line is a registered service mark of Quantum Computer Services, Inc. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ 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. {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 WEEKDAY, WEEKDAYS - Event occurs only on weekdays WEEKEND, WEEKENDS - Event occurs only on weekends Time tokens ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ {TIME 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 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ {DATE mm/dd/yyyy} - Event occurs on specified date {DATE mm/dd/yyyy THRU mm/dd/yyyy (SUNDAY...SATURDAY)} - Event occurs between two dates {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 {DATE mm/dd/yyyy THRU mm/dd/yyyy EXCEPT mm/dd/yyyy THRU mm/dd/yyyy} - Special exceptions within a given range. 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 {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 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 {DISPLAY ON/OFF} - Turn XA output display on or off. DIAGNOSE - CP-290 performs internal diagnostics. 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. 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 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} - 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 ( ** Registered Version Only **) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 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 ( ** Registered Version Only ** ) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ * Multiply A = B * C / Divide B = A / C + Addition C = A + B - Subtraction A = C - B - Unary minus A = -B Relational Operators ( ** Registered Version Only ** ) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ = 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 ( ** Registered Version Only ** ) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ AND Logical AND && Logical AND OR Logical OR || Logical OR ! NOT Bitwise Logical Operators ( ** Registered Version Only ** ) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ & Bit "AND" | Bit "OR" Screen Color Control ( ** Registered Version Only ** ) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ {VIDEO1 Foreground Background} - IF or ELSE evaluates to TRUE {VIDEO2 Foreground Background} - IF or ELSE evaluates to FALSE {VIDEO3 Foreground Background} - Sending DIRECT commands to CP-290 {VIDEO4 Foreground Background} - Sending EVENTS to CP-290 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 ( ** Registered Version Only ** ) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ {(variable =) INPORT io_port} - read status of port {OUTPORT io_port value} - output value to port Pre-defined Variables ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ CDAY - The current day CTIME - The current time CDATE - The current date 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 ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ Appendix B. Returned Error Codes ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ The following is a list of Error messages that XA may generate. Also included is a specific error code that XA returns when it is finished. These error codes may be examined using ERRORLEVEL parameter in batch files. Code: 0 "Completed OK." Normal operation, XA ran successfully. Code: 1 "No commands to execute." The "-e" command line option was used, preventing any commands or events to be sent to the CP-290. Note that a report file (XA.RPT) may have been generated, however the X10.DAT file was not updated. Code: 2 "Timeout occurred. Check your cables." First, make sure the CP-290 is connected to the correct serial port. Also, make sure you are using the proper communication settings. Code: 3 "Illegal comm port - Use 1...4." Use i=1...4 only! Code: 4 "Timeout occurred or interface defective." XA waited for the CP-290 to return a status code after initiating it's internal diagnostics. First, check to see if the CP-290 is properly connected to the PC. If the connection is OK, then the CP-290 may be defective. All events stored in the CP-290 have been deleted. Code: 5 "Interface FAILED diagnostic." The CP-290 has failed its internal diagnostics. All events stored in the CP-290 have been deleted. Code: 6 "XA.EXE is corrupt." XA has detected a change in its internal code. This may be the result of a possible virus, or other problem with the file. Re-install XA from the distribution diskette. Code: 7 "Timeout occurred. Check cable, irq, and i_o settings." First, make sure the CP-290 is connected to the correct serial port. Also, make sure you are using the proper communication settings. This type of problem is usually caused by specifying an improper interrupt vector. Run the utility FINDX10.EXE to assist you in determining the proper configuration of your serial port. Code: 8 (No error assigned) Code: 9 "Not enough memory." XA reserves memory for "variable" storage, "define" statements, "labels" (for GOTO/GOSUB), and "include" filenames. When this error occurs, try reducing these statements. Code: 10 " key pressed. Exiting..." XA was aborted due to operator intervention. A file may not have been downloaded to the CP-290 properly. Code: 11 "XA internal date stack overflow." More than 100 dates were specified in a single statement. Reduce the number of dates, or use DATE ... THRU. Code: 12 "XA internal date stack underflow." Try rewriting statement, contact author. Code: 13 "XA internal stack overflow." More than 100 tokens were specified in a single statement. Reduce complexity of statement. Code: 14 "XA internal stack underflow." Try rewriting statement, contact author. Code: 15 "XA internal gosub stack overflow." Too many levels of subroutines called. Rewrite your command files. Code: 16 "XA internal gosub underflow." Try rewriting statement, contact author. Code: 17 "Not enough FILE handles, or file not found." An attempt was made to read or write to a file. The file could not opened because it: 1) does not exist, 2) you need to increase the number of files that can be opened. See DOS manual - command: FILES=??? (normally in your CONFIG.SYS). Code: 18 "XA internal except date stack overflow." More than 100 "EXCEPT" dates were specified in a single statement. Reduce the number of dates, or use DATE ... THRU. Code: 19 "XA internal except date stack underflow." Try rewriting statement, contact author. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ Appendix C. Passing arguments to your command file. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ By default, XA will only accept input from either the DOS command line (ie, 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 included in the SPECIAL.CMD file and 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" ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ Appendix D. 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. ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ Appendix E. Updating from Version 1.07b to 2.00 ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ There are a few differences with some of the commands in this version. * GOTO label "x_times" is no longer supported. You may either use GOSUBS, or condition statements and counters. * TIMEZONE changes. Use DST in conjunction with your "Standard Time" timezone. * DELAY hh:mm:ss (not DELAY mm:ss) * TIMER mm:ss.hs Place action tokens before the TIMER tokens: A1 ON TIMER 0:20.5 TIMER 0:20.5 A1 ON <--- Not this way * DEFINES must be declared prior to their usage in a command. XA is no longer a multi-pass parser. * X10DAT is no longer supported. The file X10.DAT is always created. * ADJUST token is no longer supported.