1YV Windows X10 Controller Program X10WIN Version 3.0 September 8, 1991 Edward J. Tenholder Introduction: The XP-290 X10 Controller X10WIN is a Windows program for controlling an X10 light/appliance controller (Model CP-290) via the serial port. The CP-290 Controller, in conjunction with a personal computer and appropriate software, is used to store up to 128 timer EVENTS that can be used to turn ON, turn OFF, or DIM lamps and other devices that are attached to X10 MODULES at predetermined times. The X10 family of Controllers, Transmitters, and Device Modules work via existing household 110v wiring. The Transmitters and Controllers, via either button activation or execution of stored timer events, send signals across the house wiring that is received by Device Modules throughout the house. Lamps and other devices attached to these MODULES can be told to turn ON, turn OFF, or DIM to one of sixteen levels. The CP-290 contains its own micro-processor and EVENT memory. The personal computer is used in defining the timer EVENTS that are transmitted to the X10 Controller and stored for timer processing. The personal computer does not need to remain connected to the X10 Controller once the EVENTS are transmitted to it. The personal computer can also send Commands (ON, OFF, DIM) to the X10 Controller to be executed IMMEDIATELY, instead of stored as a timer EVENT to be executed later. The X10 Controller has its own built-in Clock that is used to process all stored EVENTS. The Clock is set via the personal computer interface, and maintains the Hour and Minute of the Day (24 hour clock), and the Day of the Week. A 9-volt battery can be used in the X10 Controller to maintain the Clock value and EVENT memory, even during power failures. The X10 system can address 256 different devices. Each device is addressed via its HOUSE code (A through P), and its MODULE code (1-16). The MODULES that control lamps and other devices have switches that must be set to identify the HOUSE and MODULE code to be used for that device. All commands transmitted from Transmitters and Controllers must identify the HOUSE and MODULE Code it is talking to. The CP-290 X10 Controller has eight rocker switches on the front panel, used to manually turn ON or OFF eight different devices. The switches address MODULES 1 through 8, of the BASE HOUSECODE defined for the X10 Controller. The Controller's BASE HOUSECODE is set via the personal computer interface. X10 EVENTS Each EVENT transmitted to the X10 Controller must specify the FUNCTION to be executed (ON, OFF, DIM), which MODULE(S) are to be addressed, the time of day the EVENT is to be executed, the MODE of execution of the EVENT (ONCE, NORMAL, RANDOM), and the day(s) of the week that the EVENT is to be executed. If the FUNCTION is DIM, then the LEVEL (1 through 16) must also be specified. The greater the LEVEL, the dimmer the light will be. Note that more than one MODULE within a single HOUSE may be addressed by a single EVENT. For instance, a single EVENT may turn on devices 2, 5, and 15 within HOUSE code E. The time of day is specified in military (24 hour) time. Although the X10 Controller only recognizes absolute times, the X10WIN program can be used to specify EVENT times that are offsets before or after sun up or sun down. This will be explained later in this document. The MODE of the EVENT indicates if it should be executed ONCE and then erased from Controller memory, or if it will be executed each week on the specified days. If the EVENT is defined to be executed ONCE, it can be specified to execute at the EVENT time on either TODAY or TOMORROW. If the MODE of the EVENT is not ONCE, than it will be executed each week on the days of the week specified. For these EVENTS, the MODE can be either NORMAL or RANDOM. If the MODE is defined as NORMAL, than the EVENT is executed at the precise time of day as specified in the EVENT. If the MODE is defined as RANDOM, than the EVENT will be executed at a different random time each day, within 60 minutes of the time of day specified. The RANDOM MODE can be useful when setting light ON/OFF patterns when away from home, so that the changes do not occur exactly at the same time each day. X10WIN Device Definitions All processing of X10 EVENTS by the X10WIN program uses defined DEVICE definitions, instead of referring to actual HOUSE and MODULE codes. Because X10 EVENTS can specify more than one MODULE within a single HOUSE code, the X10WIN program DEVICE definitions can consist one or more MODULES within a single HOUSE code. The X10WIN program provides a facility to define, change, and delete DEVICE definitions via the DEVICE Menu Command. A DEVICE definition consists of the HOUSE code, one or more MODULE codes, and an English description. These DEVICE defintions are used in all EVENT definition and processing by X10WIN, and are stored in file ITEMS.X10 in the X10 Directory created during program installation. When X10WIN displays a list of DEVICES, it displays the HOUSE and MODULES followed by the Description. The HOUSE and MODULES are displayed as the HOUSE Code followed by either a two digit number if only one MODULE is defined for the DEVICE (A-01), or a four digit hexadecimel number identifying from 2 to 16 MODULES (A-B001). Each bit of the hexadecimel number corresponds to one module, the left-most bit (8000) is set to specify MODULE 1, and the right-most bit (0001) is set to specify MODULE 16. For instance, a DEVICE Definition that consists of MODULES 2, 5, and 16 within HOUSE Code B would be displayed as: B-4801. X10WIN Main Windows The primary window displayed by X10WIN consists mainly of a Menu Bar used for executing X10WIN Commands. Immediately below the Menu Bar is a horizontal Meter Bar that is used to show the progress of various Commands. A solid bar moves from left to right as Command execution continues, and an estimate of the percent completion in shown in the center of the Meter Bar. Another optional window can be opened to display all characters that are transmitted to and received from the X10 Controller. This can be useful in better understanding how the interface between the personal computer and the X10 Controller works, and for program debugging. This window can be opened or closed by clicking on the WINDOW Menu Command and then Clicking on the Menu Sub-Command XMIT/RCV WINDOW. The X10WIN program runs significantly more slowly with the XMIT/RCV Window opened, and it is recommended that this window should normally be closed. The user can move both the MENU Window and the XMIT/RCV Window to different locations on the screen, but neither window can be re-sized. The current location of both windows can be saved from session to session via Sub-Commands of the WINDOW Menu Command . The status of the XMIT/RCV Window (OPEN or CLOSED) is also saved. Other windows or dialog boxes are opened and closed as needed during execution of several Menu Commands. A "Charity-Ware" guilt screen is displayed when X10WIN is first started, until the program is registered. Other than this annoying screen, all X10WIN functionality is available without registration. Information about registering X10WIN appears later in this document. Program Startup The X10WIN program is started by executing X10WIN.EXE (for memory constrained systems, see the description of the X10SMALL utility later in this document). When X10WIN is first started (after display of the "Charity-Ware" window for un-registered copies of the program), it attempts to establish communications with the X10 Controller. During this initialization, an X10WIN Program Information window is opened, and then closed when the program has been initialized. This same window can be displayed at any time via the FILE ABOUT Menu Command. The communications channel with the X10 Controller is tested by attempting to retrieve the Controller Date via the serial interface. If three attempts fail, an error message will be displayed, and the initialization can be either retried, or the program can be terminated. X10 Controller Clock If the Controller interface is initialized successfully, the Menu Bar will be displayed with the Controller DAY, TIME, and the Controller BASE HOUSE Code displayed at the far right of the Menu Bar (for example: SU 6:30 [A] ). The CLOCK Menu Command is used for managing the Controller Clock. Sub-Commands are used to retrieve the current Controller Clock value (update the Menu Bar display), Change the Controller Clock, and Change the BASE HOUSE Code. Dialog boxes are opened when needed. The dialog box used when changing the Controller Clock allows for setting the Controller Clock time and day of week; and also allows for indicating if the time is either Standard time or Daylight time. While the Standard/Daylight specification is not used to set the Controller Clock, it is saved with the SETUP Parameters (in file X10WIN.INI), and is used to compute the current sunrise and sunset times during EVENT processing. When the Controller's BASE HOUSE Code is changed, the Controller clears all currently defined EVENTS from its memory. X10WIN displays a warning message and allows the user to CANCEL the Command before it is executed. X10WIN SETUP Parameters In order for X10WIN to perform all functions properly, several pieces of information must be supplied during program installation. These SETUP parameters are stored in file X10WIN.INI in your Windows Directory. The first time X10WIN is started, it detects that X10WIN.INI does not exist in your Windows Directory, and displays a dialog box used to enter key SETUP parameters. There is also a SETUP Menu Command that is used set or change these and other SETUP parameters. There are four kinds of information that must be supplied: The number of the Com Port that the X10 Controller is attached to (COM1 through COM8); the drive and directory that contains all files needed by X10WIN; information needed about the location of the city in which you live, in order to compute the sunrise and sunset times each day; and the frequency, in days, for automatically updating the EVENTS (by adjusting sunrise and sunset offsets) stored in the X10 Controller (see description of the X10UPDTE.EXE program for more details). The drive and directory that contains all of the installation files (see Installation Procedures later in this document) must be specified. This directory will also contain all DEVICE and EVENT definitions that are saved to disk by the user. This directory must be defined for X10WIN to work properly. The X10 Directory, the Com Port, and the Event Update Frequency must be defined when X10WIN is started for the first time. A fourth set of parameters define the latitude, longitude, and time zone information about your location, to be used to compute sunrise and sunset times. These values are not specified during the initial SETUP processing, but should be specified later using the SETUP Menu Command. In order for X10WIN to compute the sunrise and sunset time each day, it must know the latitude, longitude, and time zone in which you live. Use the SETUP Menu Command to specify this information. The latitude and longitude are specified in DEGREES, MINUTES, and SECONDS. The time zone is specified as the number of time zones east of Greenwhich Mean Time. For example, the U. S. Eastern time zone would be specified as GMT Offset of -5, Central as -6, and the Pacific time zone as -8. The X10WIN SETUP dialog box displays a list of major cities for which it can automatically set the latitude and longitude parameters. Double-click on your city if it is in the list; if not, enter the latitude, longitude, and GMT Offset for your location. X10WIN does not have the GMT Offset information for all of the cities in the list box. If you select a city for which the GMT Offset is not known, X10WIN will place "???" in the GMT Offset Text Box and you will have to enter a valid GMT Offset yourself. The latitude and longitude information is stored in file LATLONG.DAT which must be in the X10 Directory, as specified during initial SETUP. In order for X10WIN to properly compute the sunrise and sunset times, it must know if your time zone is currently observing Daylight Savings time. Because you will need to reset the X10 Controller Clock each time your time zone changes in and out of Daylight Savings time, the dialog box used to set the Controller Clock is also used to specify Daylight Savings time observance. All X10WIN SETUP parameters, along with several other important parameters that control the execution of X10WIN are stored in file X10WIN.INI in your Windows Directory. These parameters can be modified using any standard ASCII editor, such as NOTEPAD.EXE. X10WIN Installation To install X10WIN, all files distributed must be copied to your hard disk. First, create a directory to contain the X10WIN files, such as: C:\WINDOWS\X10WIN\ Several of the distributed files must be in a directory that is defined as part of the DOS PATH. These files can either be copied to an existing file that is part of your DOS Path, or they can be placed in the same X10 Directory created above, and the X10 Directory can be added to your DOS Path. The following files should be copied to a directory in the DOS Path: X10WIN.EXE The X10WIN Main Program Executable File X10UPDTE.EXE The Automatic EVENT Update Utility X10SMALL.EXE The Pre-X10WIN.EXE Utility for systems that are memory constrained VBRUN100.DLL The Visual Basic Runtime Library PSETUP.DLL The Runtime Library containing the utility to modify Windows Printer Setup Parameters METER100.VBX The Runtime Library containing the Custom Control for the Meter Bar The following files should be copied to the X10 Directory created in the first installation step. This directory MUST be specified during the initial SETUP processing when X10WIN is first run. X10WIN.WRI A Windows Write file containing program documentation CHANGES.WRI A Windows Write file detailing program version information ITEMS.X10 Sample DEVICE Definitions EVENTS.E10 Sample Saved EVENTS file SUMMER.E10 Sample Saved EVENTS file WINTER.E10 Sample Saved EVENTS file The next step is to run file X10WIN.EXE. After the "Charity-Ware" and Program Information windows, you should be presented with the initial SETUP dialog box. Continue installation by specifying the directory in which you copied the distributed files, and the COMx Port that the X10 Controller is attached to. Next, select the SETUP Menu Command to complete installation. The SETUP dialog box will now contain additonal fields to allow the specification of the latitude, longitude, and the time zone in which you live. These values can be specified by typing them into the appropriate text boxes, or by selecting a city from the list box (by double-clicking the city name). Finally, select the CLOCK Menu Command, and then select the SET CONTROLLER CLOCK Sub-Command. Specify the current time in 24 hour format (HH:MM), specify the Day of the Week, and specify either Standard or Daylight time. Defining X10 Events X10WIN allows the user to define up to 128 EVENTS to be transmitted to the X10 Controller for later execution. These EVENTS can also be Loaded and Saved to and from multiple disk files, generally from the X10 Directory with an extension of .E10. These EVENTS can contain references to the current SunUp and SunDown values computed for the current day. The time specified in the EVENT is the time before/after either SunUp or SunDown. A Drop-Down list in the EVENTS UPDATE Window is used to specify if the time entered in the EVENT is the actual time, or SunUp/SunDown plus/minus the specified time. The EVENT list identifies a time as an offset from SunUp or SunDown by placing a "+" or "-" preceeding the time for +/- SunUp, or following the time for +/- SunDown. For instance, if an EVENT time is one hour before SunUp, then the time will be displayed as: -01:00. For two hours after SunDown: 02:00+. If you have transmitted EVENTS to the X10 Controller that are dependent upon SunUp and SunDown, they can be updated regularly to adjust to the changing length of day as follows: Retrieve the EVENTS from the X10 Controller (or Load EVENTS from a file) Transmit the EVENTS to the X10 Controller Another way to update the EVENTs currently stored in the Controller is to execute X10UPDTE.EXE regularly (via RUN= in WIN.INI, for instance). This utility runs as an icon, and will retrieve, update, and re-transmit all EVENTS from and to the Controller, if the number of days specified during SETUP has elapsed. The icon will display the progress as: Initialization, Retrieve, Transmit. Do not terminate X10Updte until it has completed, or the contents of the Controller may be destroyed. Updating DEVICES and EVENTS DEVICE and EVENT definitions can be created and modified using the DEVICES UPDATE DEVICES and the EVENTS UPDATE EVENTS Menu Commands. The dialog boxes for these Menu Commands work in similar ways. A list box is displayed showing all currently defined DEVICES or EVENTS, and various controls are present to be used to define the characteristics of the EVENT or DEVICE. In the case of the UPDATE EVENTS dialog box, a list box of DEVICES is also displayed for selecting the device the EVENT being defined will refer to. Double Click on any existing DEVICE or EVENT in the list box, and all associated controls on the dialog box will be updated to match the DEVICE or EVENT definition. To change an existing definition, double click on the DEVICE or EVENT to be changed, modify the contents of the dialog box controls defining the DEVICE or EVENT, and then click on the UPDATE Button. To remove an existing definition, click on the DEVICE or EVENT to be removed to select it in the list box, and then click on the DELETE Button. To add a new DEVICE or EVENT definition, enter the proper information into all of the dialog box controls to define the new DEVICE or EVENT, and then click on the ADD Button. When defining a new EVENT, don't forget to select the appropriate DEVICE for the new EVENT by clicking on it in the DEVICE list box. Complete the DEVICE or EVENT update process by clicking on the DONE Button. All EVENT definitions refer to the HOUSE and MODULE codes via reference to DEVICE defintions, as previously mentioned. The only way to define an EVENT is to use the DEVICE definitions, but it is possible to retrieve EVENTS from either a file or the Controller that references HOUSE and MODULES that are not defined by an existing DEVICE definition (another way is to delete the DEVICE definition that is referenced by an existing EVENT). X10WIN will display an EVENT without a corresponding DEVICE definition by displaying a warning and the actual codes referenced by the EVENT, as in the following example: No Device: A-01 . Printing EVENTs The EVENTs currently loaded in memory can be printed using the FILE PRINT EVENTS Menu Command. The FILE PRINTER SETUP Menu Command can be used to modify the setup parameters of your Windows printer before using the FILE PRINT EVENTS Menu Command. Memory Constrained Systems X10WIN.EXE has a fairly large memory requirement, and some users may experience problems getting X10WIN.EXE to load and run. This may be particularly true if you are attempting to run an unregistered copy of X10WIN.EXE, as the Charity-Ware Window is large. A separate utility program, X10SMALL.EXE, has been supplied to help reduce the memory requirments of X10WIN.EXE. X10SMALL.EXE must be run before each execution of X10WIN.EXE. X10SMALL will perform all initialization functions, including the guilt screen display, before you run X10WIN. If you then run X10WIN immediately, it will bypass all initialization processing already performed by X10SMALL, significantly reducing the memory requirements of X10WIN.EXE. A simpler solution is to register X10WIN, but the X10SMALL utility provides an avenue to check out all functions of X10WIN before registering it. CharityWare This program is being distributed as CharityWare. The program has full, 100% functionality. The only difference between the registered and unregistered version, is the Guilt screen that is displayed when the program is started. A donation as small as $10.00 is sufficient ($25.00 recommended), and registration will be granted for $.00 if the registration form is submitted. Registering X10WIN When the CharityWare guilt screen is displayed, click on the I want to Register X10WIN Button to display registration instructions. Mail the requested information to the address displayed in the dialog box. You will be sent via return mail, a registration number to be entered into X10WIN to complete registration. When the CharityWare screen is displayed, click on the I want to Register X10Win Button again, and then click on the Enter Registration Button. A dialog box will be displayed for you to enter your registration number. Click the OK Button to complete registration. To verify that your registration was successful, select the FILE ABOUT Menu Command to display registration information. Support I am very interested in feedback on program interaction with both the X10 controller, and the program user. Please direct all questions to me via Compu-Serve. The VB runtime library VBRUN100.DLL may not be included in the ZIP file, in order to save space and download time. It is available in library 6 of the MSLANG Forum on Compuserve (VBRUN.ZIP), and many other online bulletin boards. Ed Tenholder 76447,1030 he list box, and then click on the DELEvrniP e^ `R\mWSOZKPoF@ Zbw0s4o|kgc_[V:R@N<J <Ov r n iz!e!a)%]D%X[-T_-P-L-H --w-s-o-k3g*3b<^<Z<U@Q@M @I @+@w1@s2@oBkBgYCc_C_~CZxKVKRKNKI KLwLsLnMjMfMNbcN^)PZ4PUPQPMQI QQv Rr%RnESj_SfSbS^SZSVTRTNTI TYVw Rr%RnESj_SfSbS^SZSVTRTNTIiWTTTTTTTTTTT<<< yynn5n7nunwnnn n nN nP l\ l^ l<< <<^ p p p p p p p pppNpPpRnmnocc << <p<p>ppppnnAcCctcvccc8c:c << <:<pMnOnucwc c c c a a"V"VH$VJ$V8 << << <J$%%p'%p)%pB%nD%n 'c"'cA)cC)cv*cx*c,c,c-c-c0c< << <00p 2p 2p3p3p3p(3n*3n3c3c4c4cA5cC5cy5c{5c< << <{55p5p6p6p86p:6pv6p6p6p6p6p6p7p7p8p 8pS8pU8p< <U8|8p~8p8p8p8p8p8p8p1:p3:p;p;p<p<p<p<n<nU8p< <<4@p6@p@p@pApApkApmAp[Cp]Cp_Cp|Cn~CnEDcGDc< << <GDEpEpFpFpGpGpHpHpIpIpKpKpKpKnKnLc< << <LLpLnLnLnMcMc%Pc'Pc)Pc6Pa8PVQVQVQVK << << <QQyQyRnRnTnTnTnTnTnTlTl-Va/VaEVaYVa[Va << <<f=/2!898(nformation to the addressUaU box. You will be sent via return mail, a registration number to be entered into X10WIN to complete r #1m:Nisplayed, click on the I want to Register X10Win Button again, and then click on t Helvetication Button. A dialog box will be displayed for you to enter your registration number. Click the OK Button to