XA - X10 Command Interpreter for the CP-290 Computer Interface Version 01.06 January 1992 Copyright þ 1991-1992 by Bruce Christensen All rights reserved. This manual, and the software described in this manual, are copyrighted. All rights are reserved. Table of Contents 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 XA - X10 Command Interpreter . . . . . . . . . . . . . . 5 POWERUP - AUTOEXEC Time Check Utility. . . . . . . . . . 6 2. Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3. XA - The X10 Command Interpreter. . . . . . . . . . . . . . . . . . 7 4. XA Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.1 Tokens - Quick Reference . . . . . . . . . . . . . . . . . . 12 4.2 Tokens in Detail . . . . . . . . . . . . . . . . . . . . . . 14 Action Tokens. . . . . . . . . . . . . . . . . . . . . . 14 ON. . . . . . . . . . . . . . . . . . . . . . . . 14 OFF . . . . . . . . . . . . . . . . . . . . . . . 14 {DIM %%}. . . . . . . . . . . . . . . . . . . . . 14 Module Address tokens. . . . . . . . . . . . . . . . . . 16 {HOUSE x} . . . . . . . . . . . . . . . . . . . . 16 {UNIT y}. . . . . . . . . . . . . . . . . . . . . 16 {UNIT ALL}. . . . . . . . . . . . . . . . . . . . 16 A1...P16. . . . . . . . . . . . . . . . . . . . . 16 Coordinate tokens. . . . . . . . . . . . . . . . . . . . 17 {LATITUDE dm} . . . . . . . . . . . . . . . . . . 17 {LONGITUDE dm } . . . . . . . . . . . . . . . . . 17 {TIMEZONE x}. . . . . . . . . . . . . . . . . . . 18 Clock tokens . . . . . . . . . . . . . . . . . . . . . . 19 {SYNCHRONIZE PC (EXACT)}. . . . . . . . . . . . . 19 {SYNCHRONIZE X10 (EXACT)} . . . . . . . . . . . . 19 Day tokens . . . . . . . . . . . . . . . . . . . . . . . 20 WEEKENDS, WEEKEND . . . . . . . . . . . . . . . . 20 WEEKDAYS, WEEKDAY . . . . . . . . . . . . . . . . 20 EVERYDAY. . . . . . . . . . . . . . . . . . . . . 20 TODAY . . . . . . . . . . . . . . . . . . . . . . 20 TOMORROW. . . . . . . . . . . . . . . . . . . . . 20 Specific Date tokens . . . . . . . . . . . . . . . . . . 21 {DATE mm/dd/yyyy} . . . . . . . . . . . . . . . . 22 {DATE mm/dd/yyyy THRU mm/dd/yyyy} . . . . . . . . 23 Time tokens. . . . . . . . . . . . . . . . . . . . . . . 24 {TIME hh:mm AM} . . . . . . . . . . . . . . . . . 24 {TIME hh:mm PM} . . . . . . . . . . . . . . . . . 24 SUNRISE . . . . . . . . . . . . . . . . . . . . . 24 SUNSET. . . . . . . . . . . . . . . . . . . . . . 24 {OFFSET +-mm} . . . . . . . . . . . . . . . . . . 24 NORMAL. . . . . . . . . . . . . . . . . . . . . . 25 SECURITY. . . . . . . . . . . . . . . . . . . . . 25 RANDOM. . . . . . . . . . . . . . . . . . . . . . 25 Miscellaneous tokens . . . . . . . . . . . . . . . . . . 26 {BASECODE x}. . . . . . . . . . . . . . . . . . . 26 {PORT COMx} . . . . . . . . . . . . . . . . . . . 26 {IRQ=x} . . . . . . . . . . . . . . . . . . . . . 27 {IO=x}. . . . . . . . . . . . . . . . . . . . . . 27 {DEFINE x z}. . . . . . . . . . . . . . . . . . . 27 {EVENT xxx} . . . . . . . . . . . . . . . . . . . 29 {CLEAR EVENT xxx} . . . . . . . . . . . . . . . . 29 ERASE . . . . . . . . . . . . . . . . . . . . . . 29 DIAGNOSE. . . . . . . . . . . . . . . . . . . . . 30 MONITOR . . . . . . . . . . . . . . . . . . . . . 30 LOG . . . . . . . . . . . . . . . . . . . . . . . 30 REPORT1 . . . . . . . . . . . . . . . . . . . . . 30 REPORT2 . . . . . . . . . . . . . . . . . . . . . 30 :LABEL. . . . . . . . . . . . . . . . . . . . . . 30 :EXIT . . . . . . . . . . . . . . . . . . . . . . 31 {GOTO label [x]}. . . . . . . . . . . . . . . . . 31 {DELAY secs}. . . . . . . . . . . . . . . . . . . 32 5. Command files . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6. Report Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Report Style 1 - Sort by Day and Time. . . . . . . . . . . . . . 35 Report Style 2 - Sort by Day, Module, and Time . . . . . . . . . 36 7. Monitoring and Logging Events . . . . . . . . . . . . . . . . . . . 37 8. POWERUP Utility . . . . . . . . . . . . . . . . . . . . . . . . . . 39 9. Other Programs and X10 Information. . . . . . . . . . . . . . . . . 40 10. License Agreement and Registration . . . . . . . . . . . . . . . . 41 1. Introduction This floppy contains a set of useful DOS utilities for the X10 Computer Interface (CP-290). These fully functional programs are being marketed under the try-before-you-buy concept (also known as SHAREWARE) to allow you a complete test of the product before you are required to register. Shareware provides you with low-cost, high-performance software and support. Registration will provide you with the latest updates, and an opportunity to voice your suggestions for new product features. Many features have been added based on input from users. For more information, see "License Agreement and Registration" (page 41), and register your copy of XA. To take full advantage of the features in this package, you should connect your computer to an X10-compatible Appliance module. This way, the combination of the X10 hardware and the XA software can take your home automation to a higher level. From now on, you can have the CP-290 update itself on a weekly basis. These updates may include events that can be scheduled days, months, even years in advance. There are (2) two programs distributed on this disk. XA - X10 Command Interpreter This utility can read and download commands to the CP-290 in two modes. The first mode is from command line arguments, i.e., the DOS prompt and batch files. The second mode can read an entire file of commands containing both timed events or direct commands. Besides these functions, the interpreter has several features not found with the original X10 software. Some of these features are:  Better reporting facilities. XA has now added (2) report formats to document the events you downloaded to the CP-290.  Exact Sunrise/Sunset times based on the latitude, longitude, and timezone of your city.  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.  GOTO statements may be embedded in command files. This allows you to execute a series of commands as often as you like. For example, program special holiday lighting sequences to continue forever.  Synchronize your PC's clock with the time maintained by the CP-290, or synchronize the CP-290 clock with the time maintained by your PC. These settings can be made down to the second, so both your PC and CP-290 are exactly synchronized.  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. POWERUP - AUTOEXEC Time Check Utility This utility is provided for those of you that control your computer with an X10 Appliance module. When placed in your AUTOEXEC.BAT file, this utility compares the current PC time with a pre-set time "window" that you define. During your computers powerup, if the PC's time falls within this "window", it will return an errorlevel of 1. This errorlevel can then be checked and used to perform any number of functions you desire. For instance, you can have X10 turn your computer at 3:00 AM every Sunday morning and automatically update the CP-290 with an entire new schdule of events. Your computer can then perform disk optimizations, disk backups, communications, etc., without any operator intervention. For more information, refer to the section - "Powerup Utility" (page 39). 2. Installation Copy the contents of this floppy to the same drive and directory in which your X10 software resides. It's also a good idea to 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;D:\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 command files. SET XA=D:\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. 3. XA - The X10 Command Interpreter As stated earlier, XA can operate on commands from the DOS prompt, or a command file. In either mode, XA uses several options to alter its operation. The XA command has the following form: XA [f=filename] [c=comm port] [i=irq] [o=io_addr] [-e] [-s] [+m] [+l] [+r1] [+r2] [+h] ["commands"] The options may appear in any order, but the presence of some of these options negates other options. [f=filename] - this is the name of the file containing the commands to be interpreted by XA. To use XA in its file mode, you would type: XA f=filename The default file name is XA.CMD. If you want to use the default file, you do not have to specify the filename - just type: XA [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 The default port is 1. To use the default, you do not have to specify the port number - just type: XA See Miscellaneous tokens - Port (pg. 26) for a different way to set the comm port within a command file. Also, see the next two options if your comm port uses a different IRQ level, or a different IO port address. [i=irq] - use this option if your communications port uses a different IRQ level than what is "standard". See Miscellaneous tokens - PORT (pg. 26) for the default assignments. The default IRQ level is 4. If your serial port uses IRQ 5, then include: XA i=5 NOTE: If your computer uses (3) or more serial ports (MODEM on COM1, MOUSE on COM2, CP-290 on COM3), you may experience a problem with XA unless each COM port is assigned a unique IRQ level. Usually, COM1 is set for an IRQ4, COM2 is set for IRQ3. If COM3 is set for IRQ4, then a conflict will arise when the devices attached to COM1 and COM3 are activated since they will share the same IRQ. To remedy this situation, assign a different IRQ to COM3, for instance IRQ5. To do this, you may have to alter the DIP switch settings on the COM board, or run a hardware setup program supplied with your computer (sometimes built- in to the BIOS diagnostics that you can activate by a keystroke during the boot phase of your computer). [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=2E8 ["commands"] - "commands" consist of several tokens (huh? - see Tokens pg 11) that describe an event of direct command. 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, but they must be enclosed by 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" One other note, the presence of any commands on the command line will nullify the use of a command file. Therefore in the next example, the XA utility will ignore the file request and process just the commands: XA f=null.cmd "A1 A2 A3 A4 ON" [-e] - this option is used to prevent any communications to the interface. Use this option only when you want to validate commands in a file. [-s] - this option is used to prevent sorting the commands based on their EVENT numbers. [+m] - this option will monitor the comm port for any events reported by the CP-290. Press the key to terminate. Note: You can run this as a background task in Windows 3.0 (386 enhanced mode) to avoid tying up your computer. See section "Monitoring" (pg. 37). [+l] - this option will append any monitoring information to the file XA.LOG. The [+m] option must also be specified for this command to work. See section "Monitoring" (pg 37). [+r1] - this option will produce a report file (called XA.RPT) of all events that were just stored in the CP-290. The format of the report contains a sorted list of events (based on time) for each day of the week. [+r2] - this option will produce a report file (called XA.RPT) of all events that were just stored in the CP-290. 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" section - pg 7). 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 "Report Files" (pg. 34) for more information. [+h] - displays a brief summary of the options described above. 4. XA Tokens What are tokens? A token is to a command as a word is to a sentence. Individual words are constructed to form a complete sentence - tokens are constructed to form complete commands. This section will describe each token that is recognized by the interpreter. Often, 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 sometimes be arranged in groups, and 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 along with the line number it appeared in. Then it displays the entire line that contains the error: WARNING: Unrecognized token "PC" in line 1. PC SYNCHRONIZE 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 contained in parentheses (..). 4.1 Tokens - Quick Reference The following is a list of available tokens. Tokens that must be arranged in a certain order will be contained in curly braces {..}. Other tokens that may be optional will be denoted in parentheses (..). All these tokens will discussed in more detail in the next section: Action tokens ON - turns ON the specified modules. OFF - turns OFF the specified modules. {DIM %%} - DIM to a % (percentage) level of brightness. Module address tokens {HOUSE x} - module HOUSEcode A...P {UNIT z} - module UNITcode 1...16, ALL A1...P16 - HOUSE UNIT combined Coordinate tokens {LATITUDE dm} - your LATITUDE in Degrees and Minutes {LONGITUDE dm} - your LONGITUDE in Degrees and Minutes {TIMEZONE x} - your TIMEZONE (Standard/Daylight Savings) 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 - Event occurs only on weekdays WEEKDAYS - " WEEKEND - Event occurs only on weekends WEEKENDS - " 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 Time tokens {TIME hh:mm AM} - Schedule event time {TIME hh:mm PM} SUNRISE - Calculate time of sunrise SUNSET - Calculate time of sunset {OFFSET +/-mm} - Event +/- 1440 mins of prog time NORMAL - Event occurs at specified time SECURITY,RANDOM - Event occurs within the hour of prog time Miscellaneous tokens {BASECODE x} - change house BASECODE of interface to A...P {PORT COMx} - send commands via PORT COM1..4 {IRQ x} - customize IRQ level for port. {IO x} - customize port address (must be in hex). {DEFINE x z} - substitute string 'x' for string 'z' {EVENT xxx} - Place event xxx in a known location of CP-290 memory DIAGNOSE - Invoke CP-290 self-test routine MONITOR - Watch events as the CP-290 executes them. LOG - Append event info to file XA.LOG {CLEAR EVENT xxx} - Clear (delete) event xxx from CP-290 memory ERASE - Erase ALL events from CP-290 memory REPORT1 - Produce report file based on daily events. REPORT2 - Report based on daily events, on a module by module basis. :LABEL - Identify an area to "goto" later. :EXIT - Special shutdown location jumped to when pressed. {DELAY secs} - Wait for "seconds" to pass before executing the next command. {GOTO label [x]} - Jump to location identified by "label". After jumping "x" times, continue with the rest of the command file. 4.2 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 module 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. See Note 3 below for compatibility issues with X10.EXE. XA "A1 DIM 50" Notes: 1) 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" 2) 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" 3) If you download a timed event that contains the DIM token, the X10 interface program (X10.EXE) reports the DIM level @ 90%, even though you may have the level at some other intensity. The reason for this discrepancy is because X10.EXE stores a mirror image of the data it sends to the CP-290 (along with some other information) in a file called X10.DAT. The exact format of this file is unknown. Eventually, when the format is determined, XA will be able to create a similar file so that the proper levels will be displayed by X10.EXE. Module Address tokens {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" 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" Notes: 1) 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" 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. Your local library or city hall may also have the precise coordinates. If your events don't require these functions, then don't worry about them. {LATITUDE dm} Your LATITUDE in degrees (0...+/-90) and minutes (0...59). LATITUDE 41d35m {LONGITUDE dm } Your longitude in degrees (0...+-180) and minutes (0...59). Longitudes West of the prime meridian are positive, those East of the prime meridian are negative. In the US, all longitudes are positive. LONGITUDE 81d20m {TIMEZONE x} Exact calculations depend on the local time. Use the following table to determine your time zone. Zone x Eastern Standard Time: 5 Eastern Daylight Time: 4 Central Standard Time: 6 Central Daylight Time: 5 Mountain Standard Time: 7 Mountain Daylight Time: 6 Pacific Standard Time: 8 Pacific Daylight Time: 7 Example: TIMEZONE 5 Notes: 1) Since all three tokens in this group are required for sunrise and sunset calculations, it is easier to include these tokens in a file and invoke the XA utility in the file mode: XA f=rise_set.cmd where the file "rise_set.cmd" contains the following commands: : LATITUDE 41d35m LONGITUDE 81d20m TIMEZONE 5 : 2) Remember to change TIMEZONE to the value that's appropriate during the Spring and Fall when the time is adjusted. 3) If you select either report mode (+r1/+r2, or REPORT1/REPORT2) and you have included the LATITUDE, LONGITUDE, and TIMEZONE tokens in the command file, then XA will print the sunrise and sunset times for the upcoming week in your event report file. Clock tokens {SYNCHRONIZE PC (EXACT)} These tokens instruct the XA utility to set your computers clock based on the current time retrieved from the CP-290. It will not affect the computers 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 the XA utility 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 seconds counter rolls over from 59 to 00 ensuring a synchronization of clocks to within 1 second, however you may have to wait for up to 1 minute for this rollover to happen. XA "SYNCHRONIZE X10 EXACT" Notes: 1) 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 a on-board battery backed-up clock. Note that this command will not set up the date since X10 does not contain a real-time calendar. 2) Use: XA "SYNCHRONIZE PC" or, XA "SYNCHRONIZE X10" in your AUTOEXEC.BAT file if either your PC or CP-290 do not keep accurate time. Day 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. SUNDAY, SUN MONDAY, MON TUESDAY, TUE WEDNESDAY, WED THURSDAY, THU FRIDAY, FRI SATURDAY, SAT These tokens specify 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. TOMORROW Event will occur tomorrow only at the specified time. It is then deleted from the interface after midnight. 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. In addition, 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), or an event may be scheduled to trigger on selected days between specific dates (such as Christmas and New Years). By plugging your computer into an Appliance module, you can have the CP-290 turn your computer on automatically on a once- per-week basis. By using 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. Also, this method guarantees that specific dates will be evaluated and events will be triggered at the proper time in the future. See section "Powerup" (pg. 39) for more details. VERY IMPORTANT NOTE: When using the following DATE tokens, you should include the "ERASE" token in 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 - 0, 1, or 2 digits (1 = Jan ... 12 = Dec) Day - 0, 1, or 2 digits Year - 0, or 4 digits (1991 - NOT 91). 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 on every 4th of July at sunset, leave off the "yyyy" field: DATE 7/4/ A5 ON SUNSET 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 Use DEFINE statements to clarify certain dates. DEFINE CHRISTMAS_DAY DATE 12/25/ A1 ON CHRISTMAS_DAY TIME 5:00 AM {DATE mm/dd/yyyy THRU mm/dd/yyyy} 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, 1993 and August 1, 1993, and you want the bedroom lights (A3) turned on and off in a random fashion during the evenings: DATE 7/1/1993 thru 8/1/1993 ON A3 TIME 9:00 PM SECURITY DATE 7/1/1993 thru 8/1/1993 OFF A3 TIME 11:30 PM SECURITY Use DEFINE statements for clarification, and reduce typing for multiple entries (note that both uppercase and lowercase is used): DEFINE Vacation DATE 7/1/1993 THRU 8/1/1993 DEFINE BEDROOM_LIGHTS A3 DEFINE ON_EVENING TIME 9:00 PM SECURITY DEFINE OFF_NIGHT TIME 11:30 PM SECURITY DEFINE XMAS A1 : Bedroom_Lights On_Evening Vacation Bedroom_Lights OFF_Evening Vacation To turn on your Christmas lights everyday between Dec. 1st and Jan. 1st: DATE 12/1/ THRU 1/1/ XMAS ON SUNSET If you want to turn them off at 10:00 pm on WEEKDAYS: DATE 12/1/ THRU 1/1/ XMAS OFF TIME 10:00 PM WEEKDAYS If you want to turn them off at 11:30 pm on WEEKENDS: DATE 12/1/ THRU 1/1/ XMAS OFF TIME 11:30 PM WEEKENDS 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} {TIME hh:mm PM} Schedule event at a certain time. XA "SUNDAY ON TIME 12:30 AM D1" 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 tokens to be included. Therefore, these tokens should be used in the file mode. MONDAY ON SUNSET D1 If multiple day tokens appear in the command line, the sunrise or sunset will be calculated for the last day token that appears in the command line. 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 +-mm} Push or postpone the scheduled event by up to 1440 minutes, (that's 1 day). 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 45 minutes before sunrise: MONDAY OFF SUNRISE D1 OFFSET -45 See section Miscellaneous Tokens - DEFINE (pg. 27) for another way of specifying DUSK or DAWN using the DEFINE token. For example: DEFINE DUSK SUNSET OFFSET 30 DEFINE DAWN SUNRISE OFFSET -45 : MONDAY ON DUSK D1 MONDAY OFF DAWN D1 NORMAL This token activates the event at the specified time. It is the default mode, therefore it does not need to be specified. SECURITY RANDOM This token allows the interface 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" XA "A1 ON TIME 7:30 PM RANDOM EVERYDAY" Miscellaneous tokens {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" During upload, the interface sends all 128 possible events that are stored in its memory. If an event actually exists, then an up arrow is displayed, otherwise a dot (ú) is displayed. During download, a down arrow is displayed. Downloads will take significantly longer due to the overhead involved with sending synch bytes for each event. {PORT COMx} These tokens allow you to specify which comm port the interface is attached to. Legal ports are: I/O Address Interrupt COM1 = 0x3F8 4 COM2 = 0x2F8 3 COM3 = 0x3E8 4 COM4 = 0x2E8 3 These tokens were intended to be placed in command files. They will take precedence over the 'c=x' command line argument. Example line in a command file: PORT COM3 If your port assignments do not match those in the above table, then use the command line parameters [i=x] and [o=xxx], or the file mode tokens "IRQ" and "IO" (see below) to customize the communication characteristics. {IRQ=x} Use these tokens in your command file only if your communications port uses a different IRQ level than what is "standard" (see the above table for the default assignments). The default IRQ level is 4. If your serial port uses IRQ 5, then use the following line in your command file: IRQ=5 These tokens were intended to be placed in command files. They will take precedence over the 'i=x' command line argument. If you experience problems with XA (it doesn't work - but X10.EXE works), the problem is likely to be caused by an IRQ conflict. Make sure that all your devices are assigned a unique IRQ. Failure to do so may cause your system to lock-up. {IO=x} 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 the following line in your command file: IO=2E8 These tokens were intended to be placed in command files. They will take precedence over the 'o=x' command line argument (see section 3). {DEFINE x z} This token is designed to be used in 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. Up to 50 custom tokens are allowed. For example, you can assign a token "XMAS_ON" to an equivalent group of tokens "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 The 'x' and 'z' strings can be up to 60 characters each. 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: CHRISTMAS_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 HOUSE A UNIT ALL 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 the XA utility monitor the CP-290 for events as they occur. See Section - Monitoring (pg. 37). DEFINEs must be declared before being used. The following would cause an error message because the DEFINE was placed out of order: OUTSIDE_LIGHTS ON SUNSET EVERYDAY DEFINE OUTSIDE_LIGHTS A1 {EVENT xxx} The CP-290 can store up to 128 events in its memory. Each event occupies fixed locations in memory. When you download events to the interface, an event number will be assigned to the command. The first event will have an event number of 0, the second will be 1, etc. Therefore, any event that was previously stored at those locations will be overwritten. The token {EVENT xxx} allows you to override the number assigned to this command. If you normally use one command file then the need to use this token is probably unnecessary. If multiple command files are used, then this token is helpful. MON ON SUNSET D1 EVENT 100 TUE ON SUNSET D1 EVENT 101 WED ON SUNSET D1 EVENT 102 When you produce a report file, the event number assigned to each event is printed in the right-most column of the listing. {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" 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. 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. DIAGNOSE This token triggers the X10 diagnostic routine. You will be informed of the results after a few seconds. VERY IMPORTANT NOTE: The diagnostics on the CP-290 will destroy all the event information stored in its memory. Make sure you have all the event information contained in a command file so that you can restore this data once the diagnostics have completed. 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" (pg. 37) for more information. LOG This token appends the monitored information in the file XA.LOG. You must also specify either MONITOR in the command file or +m on the command line for this action to occur. 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. :LABEL This token identifies a location in your command file that you may GOTO later. A label must always be defined prior to a reference made by a GOTO token. You may include up to 15 labels within your command file, each label can be no more than 60 characters in length. 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. 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. {GOTO label [x]} These tokens instruct XA to jump to an earlier sequence of commands identified by the "label". The label must have already been defined, and in this instance should not contain the leading colon ":". The optional "x" parameter is used for controlling jumps. It specifies the number of times to goto the label. When the number of jumps has been satisfied, XA continues with the rest of the command file. If you don't specify the "x" parameter, XA assumes you want to jump to the defined label forever (a continuous loop state). The following is a portion of the sample command file GOTO.CMD. Note the special use of the :EXIT label, which ensures that the module is always turned OFF when complete. # FLASH B1 three times... :LABEL1 B1 OFF B1 ON GOTO LABEL1 3 # Now DIM B1 to 10%, back to 100% twice... :DIM_LABEL B1 DIM 10 B1 DIM 100 GOTO DIM_LABEL 2 # Now repeat the whole thing forever... GOTO LABEL1 # pressed. Make sure the module is OFF. :EXIT B1 OFF 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 XMAS.CMD for an example. {DELAY secs} These tokens allow you wait for the specified number of "seconds" to pass before executing the next command. 5. Command files Since the CP-290 is only capable of storing a single weeks worth of events, command files were created to allow easy update 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. 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. You may place comments in your command file. A comment is delineated by the pound sign character '#'. This character must appear in the first column of the line. # This is an example comment. Comments are ignored by the interpreter. Therefore, comments can be placed in front of commands you do not want to download to the interface at this time. Blank lines are permitted in the command file. These allow you to group similar events together. See the sample command file "XA.CMD" (included in this package) I use for automating events in my home. XA defaults to reading a command file if there are no commands in the command line. The default command file is called 'XA.CMD'. You may keep a number of command files around. To use a different command file, use the 'f=' parameter 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 See section - Monitoring (pg. 37) for a discussion of monitoring and logging events, and the use of a command file called MONITOR.CMD to show how this is done. 6. Report Files XA can produce a report of all events that were just stored in the CP-290. These reports come in 2 styles - events sorted by day and time, and 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 (see page 7). 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 the command file, 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 (see pg. 27). 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 on pg. 29, and CLEAR EVENT on pg. 29). 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. Wed - October 23, 1991 Sunrise: 7:45:27 Sunset: 6:34:06 Time Cmd Mode Module Address/Description Event 12:30 am OFF Security (A1) OUTSIDE_LIGHTS ( 45)* 1:30 am OFF Security (A3) BEDROOM_LIGHTS ( 47)* 5:30 am DIM (A1) OUTSIDE_LIGHTS ( 42)* 5:35 am ON (A2) LIVING_ROOM_LAMP ( 43)* 7:45 am OFF (A1) OUTSIDE_LIGHTS ( 19) 7:57 am OFF (A2) LIVING_ROOM_LAMP ( 44)* 5:34 pm ON (A4) FAMILY_ROOM_LAMP ( 22) 6:34 pm DIM (A1) OUTSIDE_LIGHTS ( 18) 6:44 pm ON (A2) LIVING_ROOM_LAMP ( 20) 10:55 pm ON (A3) BEDROOM_LIGHT ( 46)* 11:30 pm OFF (A4) FAMILY_ROOM_LAMP ( 23) 11:30 pm OFF (A2) LIVING_ROOM_LAMP ( 21) 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. Wed - October 23, 1991 Sunrise: 7:45:27 Sunset: 6:34:06 Module Time Function Mode Event (A1) OUTSIDE_LIGHTS 12:30 am OFF Security ( 45)* 5:30 am DIM ( 42)* 7:45 am OFF ( 19) 6:34 pm DIM ( 18) (A2) LIVING_ROOM_LAMP 5:35 am ON ( 43)* 7:57 am OFF ( 44)* 6:44 pm ON ( 20) 11:30 pm OFF ( 21) (A3) BEDROOM_LIGHT 1:30 am OFF Security ( 47)* 10:55 pm ON ( 46)* (A4) FAMILY_ROOM_LAMP 5:34 pm ON ( 22) 11:30 pm OFF ( 23) 7. Monitoring and Logging events The CP-290 sends a message to your computer after 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 events if desired. XA will enter its monitor mode after all other commands have been processed. You can activate the monitor feature in two ways, as a command, or as a command line parameter. Command example: XA "MONITOR" Command line parameter example: XA +m In the first example, 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 command file 'XA.CMD' 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. See the next example: XA +m -e When XA begins to monitor, it displays the following message: Monitor events. Press when finished... XA waits for a message 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: 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 broadcast 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. Monitoring is useful when running on a multi-tasking system. It has been tested as a background task under Windows 3.0 (386 enhanced mode). It should work for Desqview as well. 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. For logging to work, you must have invoked the monitoring feature by specifying either MONITOR in the command file or [+m] on the command line. 8. 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]...] s=hh:mm e=hh:mm The command line parameters may appear in any order, and they must all be present: 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, WEEKENDS, EVERYDAY. 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 hour format) 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. In addition, you can even perform other activities such as backups, communications, etc. without being at your computer. See the sample AUTOEXEC.BAT file included in this package that I use to accomplish this task. 9. 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 (or TSR) that silently sits 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 transmited 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. 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. For ordering information (X10 paper ONLY): Steve Mueller Silicon Valley Video Group 335 Bodega Way San Jose, CA. 95119-1603 10. License Agreement and Registration You may make copies of this program, manual, and other files and give it to your friends, upload it to bulletin boards, or include it in the library of a non-profit computer club. I expressly forbid any for-profit venture from selling this software and documentation, either separately or as part of a "library" diskette, unless written permission is granted. I disclaim any liability for its use, misuse, or abuse, including any direct or indirect actions. The user accepts full responsibility for his or her use of this program. SUPPORT SHAREWARE! This package contains fully functional programs. Nothing has been "crippled". If you find this software has any value for you, please use the included registration form and send a contribution. Contributions of $20 will entitle you to (2) registered updates of this program as new enhancements are added, as well as a printed, formatted copy of this user manual. 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, or America Online. Bruce Christensen 6594 Hudson Avenue Mentor, OH. 44060-4545 Prodigy ID: MHNC39A America Online: AuggieBen Please share this software with others. X-10 is a registered trademark of X-10 (USA) Inc. Desqview is a trademark of Quarterdeck Office Systems. Windows is a trademark of Microsoft Corporation. Prodigy is a registered service mark and trademark of Prodigy Services Co. America Online is a registered service mark of Quantum Computer Services, Inc.