XA Command Interpreter Version 01.04 August 1991 Copyright 1991 by Bruce Christensen All rights reserved. Table of Contents 1 Introduction.................................................... 3 2 Installation.................................................... 4 3 XA - the X10 Command Interpreter................................ 4 4 XA Tokens....................................................... 7 4.1 XA Token Reference............................................ 7 4.2 Tokens in detail.............................................. 8 4.2.1 Action Tokens (ON, OFF, DIM)................................ 8 4.2.2 Module Address Tokens (HOUSE, UNIT, A1...P16)............... 10 4.2.3 Coordinate Tokens (LATITUDE, LONGITUDE, TIMEZONE)........... 11 4.2.4 Clock Tokens (SYNCHRONIZE X10, PC, EXACT)................... 12 4.2.5 Day Tokens (SUNDAY...SATURDAY, WEEKDAYS, WEEKENDS, etc.) ... 13 4.2.6 Date Tokens (DATE, THRU).................................... 13 4.2.7 Time Tokens (TIME, SUNRISE/SET, OFFSET, NORMAL, SECURITY, RANDOM)............................. 15 15 4.2.8 Misc Tokens (BASECODE, PORT, DEFINE, EVENT, CLEAR, DIAGNOSE, MONITOR, IRQ, IO, LOG, ERASE)............................ 17 5 Command Files................................................... 20 6 Monitoring and Logging Events................................... 21 7 POWERUP Utility................................................. 23 8 License Agreement and Registration.............................. 24 XA Command Interpreter (Version 1.04) Page 3 1) Introduction This floppy contains a set of extremely useful DOS utilities for the X10 Computer Interface (CP290). These utilities are being marketed under the try-before-you-buy (Shareware) concept 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. Many features have been added to this product based on input from users. Registration will provide you with the latest updates, and an opportunity to voice your suggestions for new product features. See Section 8.0 - License Agreement and Registration, also the Registration form for more details. 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 "home automation" to a higher level. From now on, you can have the CP-290 update itself on once-per-week basis. These updates may include events that may be scheduled days, months, even years in advance. There are (2) two programs distributed on this disk. Briefly, A) XA - X10 Command Interpreter. (XA.EXE) This utility reads and downloads commands to the CP290 in two modes. The first mode is from command line arguments, ie, from the DOS prompt. The second mode can read an entire file of commands. These commands can be either 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: 1) Exact Sunrise/Sunset times based on the latitude, longitude, and timezone of your city. 2) 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. 3) 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. 4) Monitor events as the CP-290 executes them, and optionally log them to a file. 5) The ability to change the base housecode without losing all the data already stored in the interface. XA Command Interpreter (Version 1.04) Page 4 6) String substitution in the command file allows you to equate a device (FAMILY_ROOM_LAMP) with its module address (A3). 7) Comments are allowed in the file to properly document its content. 2) 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, X10 turns my computer on at 3:00 AM every Sunday morning. POWERUP checks the computers time and then invokes a complete optimization and backup of my hard drives as well as downloads updated times to the X10 Computer Interface. There will be more on this subject in Section 7 - Powerup Utility. 2) Installation You probably want to 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. Ex: SET PATH=C:\DOS;D:\X10;... You should set the XA environment variable to the drive and directory of your command files. This also can be placed in your AUTOEXEC.BAT file. Ex: SET XA=D:\X10 (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 command line, or from a 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] ["commands"] � � [-e] [-s] [+m] [+h] � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� XA Command Interpreter (Version 1.04) Page 5 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 CP290 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 Section 4.2.7 - Miscellaneous tokens 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 Section 4.2.7 - PORT COMx for the default assignments). The default IRQ level is 4. If your serial port uses IRQ 5, then include: XA i=5 [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 XA Command Interpreter (Version 1.04) Page 6 ["commands"] - "commands" consist of several tokens (huh? - see Section 4 - Tokens) 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 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 (see EVENTS described in Section 4.2.8 - Miscellaneous tokens). [+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. [+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. [+h] - displays a brief summary of the options described above. XA Command Interpreter (Version 1.04) Page 7 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 CP290 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) Token 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: 4.1.1 Action tokens - ON - turns ON the specified modules. OFF - turns OFF the specified modules. {DIM %%} - DIM to a % (percentage) level of brightness. 4.1.2 Module address tokens {HOUSE x} - module HOUSEcode A...P {UNIT z} - module UNITcode 1...16, ALL A1...P16 - HOUSE UNIT combined 4.1.3 Coordinate tokens: {LATITUDE d m} - your LATITUDE in Degrees and Minutes {LONGITUDE d m}- your LONGITUDE in Degrees and Minutes {TIMEZONE x} - your TIMEZONE (Standard/Daylight Savings time) XA Command Interpreter (Version 1.04) Page 8 4.1.4 Clock tokens: {SYNCHRONIZE PC (EXACT)} - set PC time based on X10 time {SYNCHRONIZE X10 (EXACT)} - set X10 time based on PC time 4.1.5 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 WEEKDAYS, WEEKDAY - Event occurs only on weekdays WEEKENDS, WEEKEND - Event occurs only on weekends 4.1.6 Specific Date tokens: {DATE mm/dd/yyyy} - Event occurs on specified date {DATE mm/dd/yyyy THRU mm/dd/yyyy} - Event occurs between two dates 4.1.7 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 + or - 60 mins of programmed time (dawn) NORMAL - Event occurs at specified time SECURITY,RANDOM - Event occurs within the hour of programmed time 4.1.8 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 CP290 memory DIAGNOSE - Invoke CP290 self-test routine MONITOR - Watch events as the CP290 executes them LOG - Append event info to file XA.LOG {CLEAR EVENT xxx} - Clear (delete) event xxx from CP290 memory ERASE - Erase ALL events from CP290 memory 4.2) Tokens in Detail 4.2.1 Action Tokens ON This token informs the interface to turn ON the selected modules. Example: XA "A1 ON" XA Command Interpreter (Version 1.04) Page 9 OFF This token informs the interface to turn OFF the selected modules. Example: 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. Example: 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 acted on. 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 discrepency 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. Eventually, when the exact format of this file is determined, XA will be able to create a similar file so that the proper levels will be displayed by X10.EXE. Any of you hackers out there that know this format, please step forword. XA Command Interpreter (Version 1.04) Page 10 4.2.2 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 address 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. Examples: XA "HOUSE A UNIT 1 ON" or, XA "UNIT 1 HOUSE A ON" Multiple UNITs may appear in a single command. Example: XA "HOUSE A UNIT 1 UNIT 2 UNIT 3 ON" Turn off all units on HOUSE P. Example: 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. Example: 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" XA Command Interpreter (Version 1.04) Page 11 4.2.3 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 d m} Your LATITUDE in degrees (0...+/-90) and minutes (0...59). Example: LATITUDE 41d35m {LONGITUDE d m } 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. Example: 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: Example: XA f=rise_set.cmd where the file "rise_set.cmd" contains the following commands: : LATITUDE 41d35m LONGITUDE 81d20m TIMEZONE 5 : XA Command Interpreter (Version 1.04) Page 12 2) Remember to change TIMEZONE to the value that's appropriate during the Spring and Fall when the time is adjusted. 4.2.4 Clock tokens {SYNCHRONIZE PC (EXACT)} These tokens instruct the XA utility to set your computers clock based on the current time retrieved from the CP290. It will not affect the computers date. Example: 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. Example: XA "SYNCHRONIZE PC EXACT" {SYNCHRONIZE X10 (EXACT)} These tokens instruct the XA utility to set the time and day of the CP290 internal clock based on the current time retrieved from your computer. Example: 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. Example: 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 CP290 do not keep accurate time. XA Command Interpreter (Version 1.04) Page 13 4.2.5 Day tokens: Use of these tokens indicate a timed event, ie, 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. Example: 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. Notes: 4.2.6 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 every day between specific dates (such as Christmas and New Years). If you plug you 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. XA Command Interpreter (Version 1.04) Page 14 Now you'll never forget to update your CP-290 - your computer does it for 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 7.0 on the Powerup utility 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 relavent 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 = January... 12 = December) Day - 0, 1, or 2 digits Year - 0, or 4 digits (1991 - NOT 91). To specify module A5 to turn on July 4, 1992 at 5:00 pm: A5 ON DATE 7/4/1992 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 seperator, 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 (see Section 4.2.8). DEFINE CHRISTMAS_DAY DATE 12/25/ A1 ON CHRISTMAS TIME 5:00 AM XA Command Interpreter (Version 1.04) Page 15 {DATE mm/dd/yyyy THRU mm/dd/yyyy} Event occurs between two dates. Use the same conventions as described above. If you will be going on vacation between July 1, 1992 and July 17, 1992, and you want the bedroom lights (A3) turned on and off in a random fashion during the evenings: DATE 7/1/1992 thru 7/17/1992 ON A3 TIME 9:00 PM SECURITY DATE 7/1/1992 thru 7/17/1992 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/1992 THRU 7/17/1992 DEFINE BEDROOM_LIGHTS A3 DEFINE ON_EVENING TIME 9:00 PM SECURITY DEFINE OFF_NIGHT TIME 11:30 PM SECURITY : Bedroom_Lights On_Evening Vacation Bedroom_Lights OFF_Evening Vacation 4.2.7 Time tokens: Use of these tokens indicate a timed event, ie, 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. Example: 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. Example: 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. Example: MONDAY TUESDAY WEDNESDAY ON SUNSET D1 XA Command Interpreter (Version 1.04) Page 16 If more accuracy is needed, then break each daily event into its own command. Example: MONDAY ON SUNSET D1 EVENT 0 TUESDAY ON SUNSET D1 EVENT 1 WEDNESDAY ON SUNSET D1 EVENT 2 {OFFSET +-mm} Push or postpone the scheduled event by up to 60 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. Example: Turn on lights 30 minutes after sunset MONDAY ON SUNSET D1 EVENT 0 OFFSET 30 Turn lights off 45 minutes before sunrise MONDAY OFF SUNRISE D1 EVENT 1 OFFSET -45 See Section 4.2.8 (Miscellaneous Tokens) for another way of specifying DUSK or DAWN. This can be accomplished using the "DEFINE" token. For example: DEFINE DUSK SUNSET OFFSET 30 DEFINE DAWN SUNRISE OFFSET -45 : MONDAY ON DUSK D1 EVENT 0 MONDAY OFF DAWN D1 EVENT 1 XA Command Interpreter (Version 1.04) Page 17 NORMAL This token activates the event at the specfied 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. Example: XA "A1 ON TIME 7:30 PM SECURITY EVERYDAY" XA "A1 ON TIME 7:30 PM RANDOM EVERYDAY" 4.2.8 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. Example: 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: COM1 = I/O address 0x3F8 Interrupt 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 (see section 3). Example line in a command file: PORT COM3 XA Command Interpreter (Version 1.04) Page 18 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 (see section 3). {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} These tokens were designed to be used in command files. They allow you to substitute several tokens into a single token of your choice. They help to make command files more readable. Up to 50 custom tokens are allowed. For example, you can assign a token "CHRISTMAS_ON" to an equivalent group of tokens "HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY" as follows: DEFINE CHRISTMAS_ON HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY ============ ======================================= x z The 'x' and 'y' 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 a SPACE character to separate the 'x' and 'y' components. Later in the command file, you can use the following command to activate your Christmas lights: CHRISTMAS_ON XA Command Interpreter (Version 1.04) Page 19 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 utilty monitor the CP290 for events as they occur. See Section 6 on Monitoring. **** Important Note **** 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 CP290 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. Example: MON ON SUNSET D1 EVENT 100 TUE ON SUNSET D1 EVENT 101 WED ON SUNSET D1 EVENT 102 {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. Example: XA "CLEAR EVENT 100" "CLEAR EVENT 101" XA Command Interpreter (Version 1.04) Page 20 ERASE This token erases all events from the CP-290 memory. Use this token when specific dates 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. 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴커 � *** WARNING ***: � � � � The diagnostics on the CP290 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 CP290 when it executes a stored event. See Section 6 - Monitoring and Logging Events 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. See Section 6 - Monitoring and Logging Events for more information. 5) Command files Since the CP290 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 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. XA Command Interpreter (Version 1.04) Page 21 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. For example, you can hide your Christmas lighting commands from the interpreter once the holidays are over: #DEFINE XMAS HOUSE A UNIT 2 #XMAS ON EVERYDAY SUNSET OFFSET 20 #XMAS OFF WEEKDAYS TIME 10:00 PM #XMAS OFF WEEKENDS TIME 12:00 AM Hint: Use the DATE tokens to to ensure that your lighting is only activated at certain times of the year. 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 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 utilty as: XA f=MONITOR.CMD The next section discusses the use of monitoring and logging events, and uses a command file called MONITOR.CMD to show how this is done. 6) Monitoring and Logging events The CP290 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 CP290. The second example use 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 Command Interpreter (Version 1.04) Page 22 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 CP290. You may exit this function by pressing the key. When the CP290 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 pretty meaningless. You can give this module a more descriptive name by using a command file that includes DEFINE statments for all your modules. Below is sample command file (MONITOR.CMD) 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 CP290, a scan of all the definitions will be made to see if the HOUSE and UNIT codes match. If so, then the 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/Garage_Lights A 1 <=== will NOT work. DEFINE Porch/Garage_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. XA Command Interpreter (Version 1.04) Page 23 Monitoring is useful when running on a multitasking 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 CP290 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. 7) POWERUP Utility The POWERUP utility is provided in this package to help you perform unattended, and automatic event downloads to the interface 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 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, and 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. Again, 24 hour format is required. 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 begining at NOON and lasting until 1:00pm every MONDAY, WEDNESDAY, and FRIDAY, you would enter: XA Command Interpreter (Version 1.04) Page 24 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 actvities such as backups, communications, etc. without being at your computer. I perform my backups and event revisons on Sunday mornings at 3:00 AM. This way, I never forget about backing up and now I don't have to sit around and wait for the process to finish. See the sample AUTOEXEC.BAT file included in this package that I use to accomplish this task. 8) 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! If you find this software has any value for you, please send a contribution. Contributions of $20 or more will entitle you to (2) updates of this program as new enhnacements are added. Please share this software with others. Your suggestions are always welcome. Send any comments to the address given below, or you may contact me on Prodigy, or America Online. Bruce Christensen 6594 Hudson Ave. Mentor, OH. 44060-4545 Prodigy ID: MHNC39A America Online: AuggieBen This software will be uploaded to the PC-OHIO BBS as new updates become available. Their number is: (216) 381-3320. 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.