XT - TSR Shareware for the CP-290 Copyright 1991-1994 by Bruce Christensen. All Rights Reserved. Version 2.00 - June 1994 1. Introduction XT is a TSR (Terminate-Stay Resident) program written for the IBM-PC and compatible computers to control the X10 Computer Interface (CP-290). XT will "pop-up" a menu of all defined modules when the proper HotKey sequence is detected. Once a module is selected, another menu is presented allowing selection of the ON, OFF, and DIM commands. You may alter the position and color of each window to suit your needs. XT utilizes interrupt driven, data buffered, serial communications allowing constant monitoring of all activity generated by the CP-290. Therefore, the current status of each module will be maintained as long as XT is resident in your computer's memory. The latest state will be reflected in the menus. A utility program called XTS allows you to query the state of any X10 module from a batch file. XTS displays the state of individual modules, modules of a selected housecode, or all 256 modules supported by the CP-290. When you register your copy of XT, XTS will be upgraded to return an 'errorlevel' of the a module's status (ON, OFF, DIM) allowing you to interface other programs with your X10 modules. While XT was designed to be a resident program in your computer's memory, it can be easily removed by the press of a key. In addition, XT can be instructed to operate as any other non-TSR program with the use of a command line switch. This mode somewhat reduces the advanced capabilities of XT, but is useful for quickly controlling any number of home automation devices. XT can examine each modules event list stored in the CP-290 and force every module to its expected state. This is useful for resetting modules after a power failure, or if the CP-290 has been off-line for some time. This feature can be invoked at any time by the press of a key, or it may be activated automatically during XT installation. XT may communicate to the CP-290 via COM1...COM4 ports. Default parameters for I/O port assignments and IRQ levels have been preselected for most common installations, but these parameters can be easily modified to match your systems configuration. 2. Shareware This program is being marketed using the SHAREWARE concept which allows you a complete evaluation of the product before you are required to register. Shareware provides you with low-cost, high-performance software and support. Shareware also provides incentives for programmers to continue to develop new products. If you find XT and its support files useful and you continue to use them after a trial period not to exceed 45 days, you must make a registration payment of $25 to the author. When you register, you will receive the latest, full-featured version of XT/XTS along with a printed User's Manual. For more information, see "Warranty, Copyright and Registration Policy", fill out and mail the included "REGISTER.TXT" form, and register your copy of XT. 3. Installation First, copy the contents of this floppy to the same drive and directory in which your X10 software resides. For example, if your X10 files are located on Drive C in the directory "X10", and the XA installation floppy disk is inserted in Drive A, you would type at the DOS prompt: C: CD \X10 COPY A:\*.* C: If you haven't already done so, include this drive and directory within your PATH statement of the AUTOEXEC.BAT file. The "PATH" statement tells DOS where to locate frequently used executable files. SET PATH=C:\DOS;C:\X10;... You should set the XT 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 XT where to find its initialization file which is used to define menu strings and other items that configure your interface. SET XT=C:\X10 If you don't understand the concepts of the PATH or SET command, refer to your DOS User's Guide and Reference manual. Also, see the AUTOEXEC.BAT supplied with this package for an example. Finally, let XT's utility program "FINDX10T" search your computer's serial ports for the CP-290. FINDX10T will determine the IO port address and IRQ (interrupt vector) for that particular port. These parameters are important for the successful operation of XT. 4. Using XT Once you have installed XT on your computer, you can start it by typing the following at the DOS prompt: XT That's XT followed by pressing the key marked or . This will install XT as a TSR program using the following default parameters: - XT.INI is the default initialization file. - COM1 is the default communications port using IO address 0x3F8 and IRQ level 4. - is the activation "HotKey". It's possible that you may have the CP-290 attached to a different port. If this is case, see Section 5 - XT Details, for options to specify the correct port. For now, just read on and continue this section. XT should now be resident in your computer. If you did not get the "Completed OK." message, find and correct the problem, then restart the program. You activate XT's first menu by pressing the HotKey sequence, in this case, both and keys at the same time. Since you didn't specify an initialization file, XT will use the default (XT.INI) file which contains several sample module definitions, menu colors, etc. The menu should like: Ú Module Description ÄÄÄÄÄÂÄ Addr ÄÂÄ Cmd Ä¿ ³ Garage/Porch_Lights_Gar ³ A 1 ³ ? ³ ³ Living_Room_Lamp ³ A 2 ³ ? ³ ³ Bedroom_Lamp ³ A 3 ³ ? ³ ³ Family_Room_Lamp ³ A 4 ³ ? ³ ³ Flag ³ A 5 ³ ? ³ ³ Plant_Grow_Lights ³ A 6 ³ ? ³ ³ Basement_Computer ³ A 7 ³ ? ³ ³ 386_Computer ³ A 8 ³ ? ³ ³ Playroom ³ B 6 ³ ? ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÙ Figure 1 - Module Menu In this case, there are 9 modules defined. Each module has a name describing its location or function, an address, and the last command that was performed on this module. If your CP-290 has its Basecode set for 'A' (see X10 documentation provided with the CP- 290), you should be able to press any one of the 8 keys on the CP-290 and watch the display update the status of that particular module. This holds true with events stored in the CP-290 memory. As events are processed, they will be recognized by XT, and each item's status will be reflected in the menu. Now press the key - the menu should disappear. Again, press any key on the CP- 290. Now activate the menu by pressing the hotkeys and you should see the correct state of the module you just triggered. Since XT uses interrupt driven, buffered communications with the CP-290, the menu doesn't even have to be displayed in order to record the current status of a module. XT sits in the background processing any information the CP-290 sends it. This information will be displayed when you activate the menu via the HotKey, or when you use the utility XTS.EXE. When the module menu is displayed, a menu highlight bar will be placed on the last module description that was selected. Use the , , , , , or keys to position the highlight bar over the module you want to control. If there are more modules defined than can actually fit in the menu (due to menu location on the screen), the menu will scroll through the list. The following is a list of keys and their actions: - move the highlight bar up 1 row in the menu. When it reaches the first item, it stops. - move the highlight bar down 1 row in the menu. When it reaches the last item, it stops. - the first time this key is pressed, the item displayed at the top of the menu is highlighted. Subsequent presses cause the menu to display the items on the previous page. - the first time this key is pressed, the item displayed at the bottom of the current menu is highlighted. Subsequent presses cause the menu to display the items on the next page. - moves the highlight bar to the very first item in the menu. - moves the highlight bar to the very last item in the menu. - selects the highlighted item and displays the command menu. - leave the module menu, restore screen. When you have selected the item you want to control, press . For this example, choose the last item on the list "Playroom". A command menu will now appear on the screen: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ Playroom % Level ³ ³ Address: B 6 100 °°°° ³ ³ Status: ? 90 °°°° ³ ³ 80 °°°° ³ ³ Use / keys for 70 °°°° ³ ³ command/brightness. 60 °°°° ³ ³ Press to 50 °°°° ³ ³ activate, aborts. 40 °°°° ³ ³ 30 °°°° ³ ³ On Ü Off Ü Dim Ü 20 °°°° ³ ³ ßßßß ßßßßß ßßßßß 10 °°°° ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Figure 2 - Command Menu The first line displays the module information (Playroom). The second line displays its address (B6). The third line displays its status (?). XT will highlight the action it thinks you will want to perform. For example, if the current status of the device is either On or Dim, XT selects Off so all you have to do is press . Otherwise, use the , , or keys to highlight the action (On, Off, Dim) you want to perform on this module. If you are commanding either a lamp dimmer or wall switch, you have the capability of dimming that module. Use the or keys to select the level percentage. When you've selected the command, press to send the command. The active function will blink letting you know the command is in progress. If all goes well, the command menu will disappear upon completion of the command, and the status will be reflected in the module menu. Each time a command is sent to the CP-290, XT waits for an acknowledgment message. If that message is not received after a pre-determined time-out period, the following message will be displayed: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³Command not acknowledged. ³ ³Check cable, IRQ/IO assignments. ³ ³ ³ ³ Press any key to continue... ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ First, check your cable to make sure you're connected to the CP- 290. Next, make sure you've specified the proper COM port (see the "c=" option in the next section). If you're still not communicating with the CP-290, determine the IRQ and I/O Port of your serial port and use the "i=" and "o=" commands. Note: XT will only "popup" when the current video is in non- graphics mode. XT will continue to monitor the CP-290, but activation of the menus will occur once the video is restored to text-based mode. 5. XT Details If you have your PATH statement and XT environment set correctly (see Section 3 - Installation), you should be able to install XT into memory by typing the following command at the DOS prompt: XT When XT is invoked without any options, it assumes the following defaults: - the data file containing X10 module descriptions, addresses, and other custom options is called: XT.INI - the COM PORT that the CP-290 is connected to is COM1 (it is assumed that COM1 has its IRQ level set to 4 and the I/O port is located at 3F8 HEX). - memory reserved for the XT program is set at 512 paragraphs (more on this later). - the HotKey combination to activate the menu is , that is, both the CONTROL (labeled as Ctrl on most keyboards) and the LEFT SHIFT key are pressed at the same time. If these defaults do not apply to your system, then you may override these settings by passing the following options to XT when you install it into memory. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ The XT program has the following options: ³ ³ ³ ³ XT [f=filename] [c=comm port] [i=irq] [o=io_addr] [m=memory blocks] ³ ³ [h=hotkey] [+p] [-s] [-t] [+u] [/?] ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ where: [f=filename] - this is the name of the file containing X10 module descriptions, addresses, and other items such as menu color, and menu screen positions. The default file is: XT.INI If you want to specify a different file, such as "FRED.X10", then type: XT f=FRED.X10 [c=comm port] - this allows you to select the serial port for communications with the interface. You may select ports 1...4. The default port is: 1 (for COM 1). For example, if your CP290 is connected to COM3: XT c=3 Note: When using this option, XT assumes that the serial ports in your system are setup according to Table 1. In most cases, these assumptions are valid for COM1 and COM2, but lack of a standard for COM3 and COM4 will probably conflict with your setup if that's where your CP-290 is connected. To compensate for this potential problem, see the [i=irq] and [o=i_o] options later in this section. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ COM1 = I/O address 0x3F8 Interrupt 4 ³ ³ COM2 = " 0x2F8 " 3 ³ ³ COM3 = " 0x3E8 " 4 ³ ³ COM4 = " 0x2E8 " 3 ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Table 1 - COM port assignments [i=irq] - use this option if your communications port uses a different IRQ level than what is "standard" (see Table 1 for the "standard" assignments). The default IRQ level is: 4 (COM1) If your serial port uses IRQ 5, then you must specify it on the command line as: XT i=5 Note: If you can't get the XT program to function correctly (time-outs, etc.), the problem is most likely caused by an improper IRQ assignment. See the Troubleshooting section later in this document for determining your IRQ level. You can also run the program "FINDX10T.EXE" to see if it can determine the proper parameters. [o=io_addr] - use this option if your communications port uses a different IRQ level than what is "standard" (see Table 1 for the "standard" assignments). The default I/O Port address is: 3F8 HEX (COM1). If your serial port is setup for 2E8 hex, then use: XT o=2E8 [m=memory blocks] - this option is provided to allow you to adjust the amount of memory reserved by XT. This memory is used to store information such as module definitions, saving screen data when a menu pops up, and other internal storage. Ideally, you want to use as little memory as possible, but the amount required depends on how many modules XT is controlling. Too much reserved memory is wasteful, stealing memory from your other DOS applications. Too little reserved memory will most likely cause your system to crash, with DOS displaying the following message: Memory Allocation Error. System Halted. The amount of memory reserved by XT is in units called "blocks". Each block is 16 bytes. The default number of blocks that XT reserves is 512, or 8192 bytes (16 * 512). This value works with the 9 module definitions contained in the sample file (XT.INI) provided with this package. Finding the right value is pretty much trial and error. If your system crashes, add more reserved memory. For example: XT m=600 Note: System crashes or weird behavior may be the result of other TSR's loaded in your system. See the Troubleshooting section later in this document. [h=hotkey] - this option allows you to assign a different "HotKey" for menu activation. The default HotKey sequence is: That is, both the CONTROL and LEFTSHIFT keys pressed at the same time. To configure your own HotKey, you must use a combination of values from Table 2. KEY VALUE (hex) ========== =========== RIGHTSHIFT 0x0001 LEFTSHIFT 0x0002 CONTROL 0x0004 ALT 0x0008 SCROLLLOCK 0x1000 NUMLOCK 0x2000 CAPSLOCK 0x4000 INSERT 0x8000 Table 2 - Hotkey Codes You ADD the values (in HEX) for the corresponding key combination you want to use. Remember, the hexadecimal is base 16. Therefore, values are in the range: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F, 10, 11, ... The following examples may help to explain: Ex. 1 - Specify the keys. The value for is 0x0004 The value for is 0x0002 ====== Hex addition is --------------> 0x0006 Therefore, the HotKey option is: XA h=0006 or, XA h=6 ( you may skip leading zeros). Ex. 2 - Specify the key. The value for is 0x1000 Therefore, the HotKey option is: XA h=1000 Ex. 3 - Specify the keys. The value for is 0x0004 The value for is 0x0008 ====== Hex addition is ---------------> 0x000C (hexadecimal C, not 12). Therefore, the HotKey option is: XA h=000C or, XA h=C (you may skip leading zeros). [-s] - this option allows you to remove the shadow effect for each displayed window. The advantage to this is twofold: 1) if you don't like shadows... 2) reduces memory requirements. To reduce memory requirements you will also have to adjust the reserved memory (see [m=xxx] option). [-t] - this option will NOT install NOR keep XT resident. Once is pressed in the module menu, the program will return to DOS. To use XT again, you must run it from the DOS command line. [+p] - this option will initiate the powerfail recovery mode following successful installation of XT. XT will begin sending direct commands to the CP-290 based on the current state of each module in the menu. Use the "+u" option in conjunction with "+p" in order to obtain the latest state of each module prior to recovery. [+u] - this option uploads all event information from the CP-290 during XT initialization and displays the expected status of the module in the menu. The advantage of this is that XT will have an accurate picture of the state of each module. The disadvantage is the time required to upload the data from the CP- 290. [/?] - this option will display a short list of the options currently accepted by the XT program. 6. Removing XT To remove XT from memory, activate the module menu by pressing the HotKey combination. When the menu is displayed, press the letter 'R' on your keyboard. XT may only be removed from memory providing that no other programs are using the interrupt vectors that XT is monitoring. If these vectors are not being used by another program or TSR, XT will restore the vectors to their original state and remove itself from memory. Otherwise, XT will remain resident and display the following message: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³Sorry... ³ ³ Can't remove TSR right now. ³ ³ ³ ³ Press any key to continue... ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ XT does not have to be installed and remain resident. Instead, you can run it just like any other program by adding the "-t" option on the command line. This will immediately invoke XT, allowing you to control any module in the menu. When you are finished, simply press and you will be returned to DOS. This method of operation might be suitable for systems that may not have enough memory to support TSR's. One drawback is that you loose the background monitoring capabilities of this program. 7. Powerfail Recovery XT knows the status of each module controlled by the CP-290 since it is constantly monitoring its communications. In some cases, the actual state of a module may not be the state the CP-290 thinks it should be in. That is, you may have told the light to go OFF, but it remains ON. One cause of this may be faulty transmission of the command due to noise or weak signals. You can easily repeat the last known command to each module by pressing the letter 'P' whenever the module menu is displayed on the screen. To activate the module menu, press the HotKey combination. When you press 'P', the highlight bar positions itself over the first module in the menu that has a status other than ? (Unknown). The command is re-issued, and the highlight bar goes to the next module with a known status. Finally, when the last module is scanned, the highlight bar will reposition itself over the original module prior to this sequence. This feature can be invoked automatically during XT installation by including the [+p] and the [+u] options in the command line: XT +p +u XT +p +u The [+u] option tells XT to upload all event information from the CP-290. XT then determines what state each module should be in by looking at the event schedule from the past 2 days. Using this information, XT has a pretty good picture of what's on, and what's not. The [+p] option tells XT to display the module menu and immediately start the command reissue procedure. When the process is complete, the menu disappears, and control is returned back to DOS. Using the [+p] and [+u] options is useful for forcing each module to its scheduled state after a power failure. This feature easily restores your home environment if the CP-290 has been off- line for a while. 8. The Initialization File (XT.INI) To keep XT as small as possible, an initialization file is used to assign names and addresses to all the modules. This file should only be created with a text editor or word processor that saves files in pure ASCII format. Any extraneous characters or control codes will cause the XT interpreter to ignore your commands. You may place comments in your initialization 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 interpreted by XT at this time. Blank lines are permitted in the initialization file. These allow you to group similar items together. The "DEFINE" command ================================= The "define" command indicates to XT that you are identifying a module description, its address, and optionally, its state. This also tells XT that you want this module included in the module menu. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ The define command has the following syntax: ³ ³ DEFINE module_description address [state] ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ XT's parser looks for a SPACE character to separate the module description and its address. Therefore, if your module description contains several words, you should use the underscore character "_" to separate the words but to keep the string contiguous. For example: Ex. 1: define Christmas_lights A10 <--- This is CORRECT Ex. 2: define Porch lights A1 <--- This is WRONG define Porch_lights A1 <--- This is CORRECT Use the optional 'state' parameter if you wish to display a state for a particular module. For instance, since my computer is controlled by an Appliance module, rather than have a "?" in the CMD column of the menu, it would be better to have the menu reflect the actual state of the module. Since I know the computer must be ON, I can force the state with the following command: Ex. 3: define Den_Computer A8 ON <--- Valid states are: ON, OFF, DIM. The "WINPOS" command ================================= You have the ability to position the menus (almost) any place you desire. If you place a menu or error window too close to the right edge of your screen (so that the window does not fit), the window will wrap to the left side. The same holds true for windows positioned too close to the bottom of the screen. The only exception to the above limitations applies to the module menu. Since it's possible that you may have more modules than can fit on a screen, the module menu will prevent itself from exceeding the bottom of the screen. It will allow you to scroll through the menu using the cursor keys described earlier. There are three distinct windows in XT - two are menus, the other is a message window for displaying errors or warnings. When assigning new locations for the windows, use the following keywords to identify the window: WINPOS1 - the module menu WINPOS2 - the command menu WINPOS3 - the message window (errors or warnings) ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ The WINPOS command has the following syntax: ³ ³ WINPOS? ROW y COL x ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Row and Column coordinates are determined from the upper left hand corner of the screen starting at 0, 0. The default coordinates for each window in XT are as follows: Module menu: WINPOS1 ROW 1 COL 30 Command menu: WINPOS2 ROW 3 COL 2 Error messages: WINPOS3 ROW 18 COL 40 The "COLOR" command ================================= The XT utility uses black and white characters so that its menu displays will initially work on all types of video hardware. If you have a color system, you may alter these defaults to suit your own preferences. This can be accomplished using the COLOR command in the initialization file. When assigning new color schemes for the windows, use the following keywords to identify the window: COLOR1 - the module menu COLOR2 - the command menu COLOR3 - the message window (errors or warnings) ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ The COLOR command has the following syntax: ³ ³ COLOR? foreground_color ON background_color ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ See Table 3 - Color Choices for a list of acceptable color definitions that are recognized by the XT parser. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ Foreground Colors Background Colors ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³ BLACK BLACK ³ ³ BLUE BLUE ³ ³ GREEN GREEN ³ ³ CYAN CYAN ³ ³ RED RED ³ ³ MAGENTA MAGENTA ³ ³ BROWN BROWN ³ ³ LIGHTGRAY LIGHTGRAY ³ ³ DARKGRAY ³ ³ LIGHTBLUE ³ ³ LIGHTGREEN ³ ³ LIGHTCYAN ³ ³ LIGHTRED ³ ³ LIGHTMAGENTA ³ ³ YELLOW ³ ³ WHITE ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Table 3 - Color Choices The default colors for each window in XT are as follows: Module menu: COLOR1 WHITE ON BLACK Command menu: COLOR2 BLACK ON LIGHTGRAY Error messages: COLOR3 WHITE ON BLACK When you assign colors to a window, you are selecting the attributes for the window in general. For instance, in the module menu you are selecting the foreground and background colors for all items in the list. The color scheme for the highlight cursor is also taken from this choice, usually the inverse colors you selected for the main selections. The "UPLOAD" command ================================= Placing an UPLOAD command in the initialization file will perform a scan of all events stored in the CP-290 so that the past status of each module can be determined. XT will look at today's events as well as yesterdays events for each module in order to accurately calculate its status. If there is not enough information, a '?' will appear in the "CMD" column of the module menu. Also, if an event is scheduled to be triggered in SECURITY (random) mode within the current hour, a '?' will be displayed in the "CMD" column. A "+u" in the command line is similar to placing "UPLOAD" in the initialization file. The choice is yours. The "HOTKEY" command ================================= You may select your own "HotKey" combination from the list below: RSHIFT, LSHIFT, ALT, CTRL, CONTROL, SCROLLLOCK, NUMLOCK, CAPSLOCK, INSERT Multiple keys are allowed. The default HotKey sequence would be entered as: HOTKEY CONTROL LSHIFT When you place the HOTKEY command in the XT.INI file, it will override any selection you may have entered on the command line (the +h=xxxx command). ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ The HOTKEY command has the following syntax: ³ ³ HOTKEY key1 key2 ... ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ 9. XTS - DOS X10 Status Interface One of the advantages of a memory-resident program such as XT is that it's always monitoring the communications port for CP-290 activity. Every command issued by the CP-290, or via XA (an X10 Command Interpreter - see next chapter), or by XT, is captured and stored in XT's internal database of 256 modules. To gain access to these states, use the utility program XTS.EXE to view the current condition of each module. REGISTERED USERS: In addition, XTS will also return a unique value which may be queried using the DOS "errorlevel" statement. You can write special batch files which operate in a unique fashion based on the state of a specific module. XTS.EXE should be stored in the same directory as XT.EXE. Since XTS communicates directly with XT, you must already have XT (Version 2.0 or newer) installed. You will receive an error message if either XT is not installed, or an earlier version of XT which does not support XTS is running. Otherwise a copyright message and one of several different screens will appear depending on the command line arguments you passed to XTS. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ XTS has the following syntax: ³ ³ ³ ³ XTS [+m] [A...P] [A1...P16] [/?] ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Type "XTS /?" at the DOS prompt to get a summary of the various options and display modes supported by XTS. The first screen we will display is the system-wide view. Just type XTS at the DOS prompt. XTS - V2.xx - Copyright 1994 by Bruce Christensen. All Rights Reserved. Module Status may be any of the following: On, Off, Dim, or Unknown (ú). ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ 1 2 3 4 ³ 5 6 7 8 ³ 9 10 11 12 ³ 13 14 15 16 ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ A ³ Off ú Off On ³ ú Dim ú On ³ ú ú ú ú ³ ú ú ú ú ³ B ³ ú On ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ C ³ On ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ D ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ E ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú Dim ³ ú ú ú ú ³ F ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ G ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ H ³ Dim Dim ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ I ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ J ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ K ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ L ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ M ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ N ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ O ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ P ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ You will see the XTS Version, Copyright notice, and module status message. Next, a table of each module and its state is displayed. A module has 4 possible states - On, Off, Dim, or Unknown (shown using a "ú" character). The state of each module is determined when XT is first installed when the "+u" appears as a command line argument, and when the CP-290 reports X10 activity either via a key press or by a scheduled event. It is recommended that you always invoke XT with the "+u" option so that the states of scheduled modules are displayed properly. If you type: XTS +m you instruct XTS to "monitor" CP-290 activity - the states are continuously updated on the screen. Try pressing one of the 8 rocker switches on your CP-290. You should see its state reflected on the screen. Note the flashing arrows at the bottom of the screen. To exit monitor mode, simply press any key. Note that XTS will not return an "errorlevel" value when all 256 modules are displayed. You can also display the states of a selected housecode. To see the current status of all modules with a housecode of C, type: XTS C XTS will display the following for housecode C only: XTS - V2.xx - Copyright 1994 by Bruce Christensen. All Rights Reserved. Module Status may be any of the following: On, Off, Dim, or Unknown (ú). ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ 1 2 3 4 ³ 5 6 7 8 ³ 9 10 11 12 ³ 13 14 15 16 ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ C ³ On ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ You may also continuously monitor the states of a selected housecode by typing: XTS C +m !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! The following features of XTS are enabled only to registered users. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! In addition, XTS returns state information which may be examined with the DOS "errorlevel" statement. So, for the example described above, if you were to request status information for house code C, you would receive: XTS - V2.xx - Copyright 1994 by Bruce Christensen. All Rights Reserved. Module Status may be any of the following: On, Off, Dim, or Unknown (ú). ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ 1 2 3 4 ³ 5 6 7 8 ³ 9 10 11 12 ³ 13 14 15 16 ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ C ³ On ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ú ú ú ú ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Returning House C status = 8000 hex. It's easiest to think of the return value in hexadecimal format (or base 16). The status of Unit 1 will occupy the most significant bit of the returned code, Unit 16 will occupy the least significant bit of the returned code. Any module that is ON or DIM will be have a '1' in its designated position of the returned errorlevel. Any module that is OFF or UNKNOWN will have a '0' in its designated position of the returned errorlevel. Refer to Section: 8. The Initialization File (XT.INI) for a brief overview of hexadecimal notation, or consult a reference book on programming. Finally, you can request XTS to return the current state of a single module by typing its designated house-unit code. For instance, to find out what state module E12 is in: XTS E12 Status of Module E12 is Dim. Returning 4. The "errorlevel" codes returned for individual modules are listed in the following table. "errorlevel" Description =========== =================== 0 Off (All Units Of 1 On (All Lights On 2 On (Normal On iss 3 Off (Normal Off i 4 Dim 5 Dim 6 Off (All Lights O 7 Unknown (?) 255 XT not installed/ Table 4 - "errorlevel" codes Using "errorlevel" ==================== The following examples show how to use the returned "errorlevel" in your batch files. For more information about "errorlevel" checking, consult your DOS User's Guide and Reference manual. These examples use a program called XA (available from this author - see Section 11) to send direct commands to the CP-290. Ex. 1 - Toggle a light (P1) from On to Off, Off to On, etc. See sample batch file P1TOGGLE.BAT. XTS P1 if errorlevel 7 goto UNKNOWN if errorlevel 6 goto ON if errorlevel 5 goto OFF if errorlevel 4 goto OFF if errorlevel 3 goto ON if errorlevel 2 goto OFF if errorlevel 1 goto OFF if errorlevel 0 goto ON :OFF XA "P1 OFF" GOTO END :ON XA "P1 ON" :UNKNOWN :END 10. Troubleshooting A) Conflict with XA.EXE (X10 Command Interpreter) XA.EXE is a program written by this author that allows sending X10 commands from the DOS prompt, from batch files, or series of commands and event information to be downloaded from a file. XA - Version 2.xx is fully compatible with XT. Both programs have been designed to share CP-290 information with each other. If you don't have the latest version of XA, contact the author at the address listed at the end of this documentation. B) Conflicts with other TSRs This program has attempted to follow the rules that all "good neighbor" TSRs should follow. However, several conflicts may arise with other TSRs loaded in your system. If you experience problems with your other TSRs after installing this one, try changing the order in which the TSRs were loaded. This may alleviate some problems. C) IRQ - Which one is it? If you don't know what IRQ level your serial port is configured for, you have (2) alternatives: 1) Run FINDX10T.EXE which was supplied as a utility to XT. This program will search each COM port in your system noting the IRQ settings. Then each COM port will be queried to determine if the CP-290 is connected. If a CP-290 is found, you will be notified of the parameters. Use these parameters when installing XT. 2) Open your computer and look at the DIP switch settings on the serial card (or motherboard). Read the instructions that came with your computer equipment if you've never done this before. 3) Take a wild, stomping guess at the IRQ level. Invoke the program by trying every IRQ level between 2 and 7 (on XT machines), and between 2 and 15 (on AT machines). Call up a menu (by using the HotKey) and issue a command to a module. If you see the LED on the top of the CP-290 go on, then you've just found the right IRQ level. The status of the command should be reflected in the module menu. D) Optimizing memory usage Currently, there is no support for XT to automatically guess the correct amount of ram to reserve for its own use. This task is left up to you. One way to conserve memory is to use the "-s" option on the XT installation command line. 11. Other Products XA - X10 Command Interpreter ============================= You are probably familiar with the menu-driven program (X10.EXE) supplied with your CP-290. The software approach used in that implementation is great for beginners since it offers a fool- proof method of organizing commands and events. Unfortunately, that method also becomes a bottle-neck every time you want to activate a single module via your computer. What's worse is trying to maintain a schedule of lighting events that vary due to seasonal changes. XA is a shareware package designed to alleviate many of the frustrations you may have experienced with the X10-supplied software. In addition, XA makes schedule maintenance a breeze. Soon, your computer will automatically handle the monotony of CP-290 scheduling for you. What is XA? The XA program is an interpreter. XA translates English-like sentences into commands that are understood by the CP-290. For instance, you can quickly tell XA to turn on a set of lights with the following DOS command: XA "PORCH ON" XA knows that the PORCH lights are addressed at HOUSE A UNIT 9, or whatever address you choose (you define modules and their addresses in a file called XA.INI). Since XA accepts commands from the DOS prompt, you can place statements like these in your batch files too. For instance, I use an X10-controlled nightlight near our downstairs phone to warn other family members if I'm "on-line" with a remote computer or BBS. The light is turned on prior to the session, and turned off when I'm finished: XA "WARNING_LAMP ON" TELIX (or ProComm) statements here XA "WARNING_LAMP OFF" XA will also process X10 commands and events contained in a file. This is ideal for maintaining the CP-290's event schedule, or for running a Christmas "lightshow". Simply tell XA which file to read, and XA does all the work. For instance, to download my event schedule to the CP-290, type: XA f=XA.CMD XA calculates sunrise and sunset times based on your latitude and longitude, and automatically compensates for any Daylight Savings changes. XA can be programmed to handle events for special dates that may be weeks, months, or years in the future. Best of all, XA can automatically update the CP-290 on a once-per-week basis without any intervention on your part (an Appliance module is needed to control your PC). XA can be found on many BBS's, including those listed in the Future Updates section listed later in this document. Look for X10XA202.ZIP (the version number is the last 3 digits of the ZIP filename). FX - TW-523 Command Interpreter =============================== FX.EXE is a DOS-based X10 command interpreter for the TW-523. Valid X10 commands are ON, OFF, DIM and BRIGHT. These commands can be input from the DOS command line, or they may be read from a "script" file. A special feature of FX is its ability to send SIMULTANEOUS Bright and Dim commands to multiple X10 modules. This allows you to create some very interesting lighting effects. My primary use for this program is for Halloween and Christmas lighting. FX communicates with the TW-523 via your computers parallel port (LPT1...LPT3). Complete instructions for building the necessary connectors are included in the documentation. FX can be found on many BBS's, including those listed in the Future Updates section listed later in this document. Look for X10FX100.ZIP (the version number is the last 3 digits of the ZIP filename). 12. Warranty, Copyright, and Registration Policy Limited Warranty ---------------- THIS PRODUCT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE PROGRAM IS ASSUMED BY YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU (AND NOT THE AUTHOR) ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. FURTHER, THE AUTHOR DOES NOT WARRANT, GUARANTEE, OR MAKE REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS PROGRAM IN TERMS OF CORRECTNESS, ACCURACY, RELIABILITY, CURRENTNESS, OR OTHERWISE; AND YOU RELY ON THE PROGRAM AND IT'S RESULTS SOLELY AT YOUR OWN RISK. THE AUTHOR CANNOT ACCEPT RESPONSIBILITY FOR SYSTEM DAMAGE, LOSS OF PROFIT, OR ANY OTHER SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGE RESULTING FROM THE USE OR INABILITY TO USE THIS PRODUCT. The author DOES warrant to the original licensee of a REGISTERED product that the program disk(s) on which the program is recorded be free from defects in materials and workmanship under normal use and service for a period of ninety (90) days from the date of delivery. The author's entire liability and your exclusive remedy shall be replacement of the disk not meeting this Limited Warranty. Copyright --------------- The XT software package, its utilities and this document is Copyright (C) 1991-1994 by Bruce Christensen. All rights reserved. Any specific hardware/software names used in this document are trademarks of specific manufacturers. Regardless of the method of marketing, XT is not in the public domain. It is copyrighted by Bruce Christensen. All rights are reserved. Copying, duplicating, selling or otherwise distributing the REGISTERED version of this product is a violation of the Law. However, we grant you the right, in fact encourage you to make and distribute as many copies of the SHAREWARE version of XT as you wish, using any acceptable medium of exchange, with the following provisions: Please feel free to distribute this SHAREWARE version as often as you like, to any interested parties. Please do not distribute this program without all of its original related files, addendum files, documentation and this notice. Please do not alter the program or documentation in any manner. DISTRIBUTION of the REGISTERED USER version of the program is in violation of license agreements and copyright Law! Registration ------------ If you are still using XT beyond the initial 45-day trial period, you must register this software with the author. Please use the included registration form (REGISTER.TXT) and send a $25 registration fee to the address below. Your registration will entitle you to the latest full-featured registered version of this program, and a printed copy of this user manual. The registered version of XT and its utilities are licensed for individual personal use for an unlimited time. This is a "living" program - new features are added from time to time. Your input is the basis for future improvements. Send any comments to the address given below, or you may contact me on CompuServe, Prodigy, America On-Line, or Internet. Bruce Christensen 6594 Hudson Avenue Mentor, OH. 44060-4545 CompuServe: 73201,1531 Prodigy ID: MHNC39A America On-Line: AuggieBen Internet: auggieben@aol.com Future Updates --------------- Future updates of the shareware version XT can be found on CompuServe, America On-Line, as well as the following BBS's as they become available. The current version of XT will be named "X10XT200.ZIP". The last 3 digits of the filename will indicate the revision level (in this case, 2.00). MicroSellar BBS offers limited, free access to validated callers. Their number is: (201)-239-1151 v.32bis, or (201)-239-1331 HST 16.8/v.32 terbo. Dave Mabry, a sysop of the "Going Down BBS" has offered free access to his BBS to anyone interested in X10 - Home Automation. Users can gain immediate access to the home automation files by logging on with a userid and password of "X10". This BBS can be reached at: 1-(810)-576-7882. Baran-Harper, a Canadian home automation mail order outfit, also runs a very popular BBS. There are many programs for the CP-290 for PC's, Mac's, and other computers. The Baran-Harper BBS is a free BBS, their number is: 1-(905)-471-6776, or 1-(905)-471-9574. Circuit Cellar Inc. publishes "The Computer Applications Journal", and runs occasional articles on X10. Their BBS number is 1-(203)-871-1988. Home Automation Laboratories (HAL) has the best mail-order catalog for home automation equipment. Call 1-(800)-YEL-4HAL to request a catalog. HAL's BBS # is 1-(404)-319-6227.