x10sched - the alternative X10 software for the CP-290 scheduler For Windows 3.1 and proper simulations. Version 1.1.4 smayo@iii.net ======== Release Notes ========== Needed files x10sched.exe dox10.dll x10*.txt (help files) x10city.dat (not essential) vbrun300.dll (Visual Basic runtime, available separately) This application is my modest contribution to X10dom. It is provided to control a CP-290, the X10 device that is hooked to a PC and provides up to 128 scheduled commands throughout the week to your X10 devices. CP-290s are available from Radio Shack or by mail order; ask around in comp.home.automation for suppliers and technical details. They run around $50 (Oct 1995). We've changed the distribution rules! We don't bundle vbrun300.dll in, anymore, since many folk already have it and it made the release procedure awkward. It is now available separately (for free). This is not freeware. You may purchase a copy for $14.00 (US funds only). You don't get the right to resell or redistribute; full copyright laws apply. It is distributed by uuencoded pkzip mail; contact smayo@iii.net for details or to arrange alternate forms of distribution. To use it, you need a copy of vbrun300.dll. You may already have this - it comes as part of a number of software packages - and if you don't, you can get it for free (details below). You can receive a demo version automatically by email! It does everything the real version does except actually send your scripts into the CP-290, so you can play with it and build your script database with it. You do have to have a CP-290 hooked up to use it, and it will do ancillary operations like automatically setting the CP-290's time and giving you control of Immediate On and Off commands. To get the free demoware, send mail to smayo@iii.net, using this exact header, and an empty message body: To: smayo@iii.net Subject: daemon: get x10demo If you don't already have vbrun300.dll, the Visual Basic runtime, you can get it for free, by sending mail: To: smayo@iii.net Subject: daemon: get vbrun300 Note you need vbrun300.dll for both the demo and the actual product. vbrun300.dll belongs in your Windows directory (often c:\windows). The mail daemon generally replies within 24 hours. You receive a uuencoded, pkzip'd file. The file for vbrun300 makes for a large mail message. If you want to buy the actual product, send me email (smayo@iii.net) and prepare to write a check in the amount listed above. Prices are subject to change (increases) as I add nifty new features. ======== Changes ========== ***1.1.4 additions A Fancy scene's operations can now be set to "cascade", so that each scheduled operation depends on the time of the previous operation, within a given script. See the notes on Incremental times, ***1.1.3 additions Simple scenes allowed you to specify an All command, but wouldn't let you edit it without getting an error. Fixed. "Freeze entire scene" option added. You can choose to use a 24 hour clock. 12 clock is the default. ***1.1.2 additions Sunrise and Sunset features added, based on your location. You'll like it! Grey backgrounds - less stressful for the eyes. Calculation for DST got October wrong in some years, in 1.1.1 - fixed ***1.1.1 additions X10sched, in Simple Script mode, remembers which Time you just added your operation to, making it easier to add another one to the same time. Additional help files added. A way to download scripts automatically on startup has been added. The DLL has been compiled without debug information, and with size optimization, making it smaller. Memory usage is better. =================================================================================== --- Concepts --- In X10Sched, you have: schedules, scripts and units. You also have unit groups, commands and times, but we'll take this slowly. A unit is a familiar X10 unit, with its letter and number code. When you define a unit in X10Sched, you also give it a short name, and you indicate whether the unit is capable of dimming lights or is strictly On/Offish. A time, in CP-290 terms, is a combination of an hour, a minute, and a selection of weekdays. Thus, "Monday, Wednesday and Saturday; at 9am" is a time. The CP-290 also supports a Security mode (effectively randomizing the minutes field), a Today mode (the event happens just once, instead of on certain weekdays), and a Tomorrow mode (like Today, but off by one.) In addition to what the CP-290 supports, X10sched supports an additional option, called Random Minute, explained later. It also has support for local sunrise and sunset times. Commands are: On, Off, Dim, Dim all the way Off, All Lights On, and All Units Off. A Command and a Unit together are called an Operation. The point of the CP-290 is to allow you to combine times and operations. Thus you could tell it, Turn unit A3 On on Mondays and Wednesdays at 10pm. In order to make life easier, X10sched adds Unit Groups, or just Groups. This is a collection of units (or groups, or both) that are given one name and can be used anywhere a unit can be used. So instead of turning on A3, you could set up a command to turn on a group you have defined called Night Lights, and "on" commands will be sent to all the units in that group, even if they are scattered across several house codes. It also adds two flavors of "Scripts". Scripts are collections of scheduled commands. The simple flavor of script allows you to specify a time and a series of units and commands, and then another time and another set of units and commands, and so on. The Fancy flavor allows you to specify a set of units and commands, and them easily specify multiple times for that combination to occur - and also to allow individual units to do their bit a given number of minutes from the script's start time, which is a significant help in scripting certain kinds of actions. Finally, a collection of scripts is gathered into a Schedule. Basically, you open up a Schedule, make any changes you like to its scripts, and then download the whole shebang into the CP-290. You can have collections of Schedules, but only one can be loaded into the CP-290 at any given time. Having multiple schedules is useful for different seasons, vacations, and so on. So things go together like this: X10Sched / \ / \ / \ | \ | \ | Schedules (up to 999) | | | | | Scripts (up to | 256 per Schedule) | / \ | / \ | Operations Times (M,W,F at 2:30pm) | / | \ | / | \ | / | \ Groups (collections / | \ of up to 64 units or other | \ groups) / Commands (On, Off...) | / | / Units (up to 256 / in 16 housecodes) --- --- Features --- Features: if you are familiar with LightHouse for Windows, this app will seem more or less like it, but some of the features I found clumsy or limiting in LightHouse are less clumsy here. You get: Automatic setting of the CP-290 clock from the PC clock - and it will do it accurately, roughly to the second, without being told to. (However, it behooves you to have your PC clock set more or less properly.) The ability to work while it is downloading commands. You can rapidly turn units on and off and download schedules; in the background, X10sched will feed these commands to the CP-290 at its own rate. Accurate sunrise and sunset calculations, based on your latitude, longitude, and elevation. The Today and Tomorrow commands are handled well. If you schedule a command for Tomorrow at 3pm, and start up X10Sched tomorrow morning, you will see the command listed as "Today." If you schedule a command for Today, then tomorrow X10Sched will still list the command but will have "frozen it" so that it doesn't affect anything. Real scripting. LightHouse only gives you what it calls "scenes", in which you specify a bunch of times and a bunch of units and commands, and the commands happen at those times. But what if you want a light to go on, dim 5 minutes later, and go off after an hour? In LightHouse that is three scripts, that have to be edited and synchronized separately. In X10Sched it is one script - and trivial to do. Example - my kids' bedtime varies depending on the day of the week. They also tend to be a little slow about getting ready for bed. So at bedtime (defined at different times for different days), the bedroom hall light goes on. After a half hour, it dims to act as a nightlight (and to tell them they should be in bed now!). Later, it dims to Off. One script. The same script also controls other lights. =============================== Help ============================= --- Installation --- Exit and restart Windows. This will eliminate problems with resident DLLs. Create a directory, and copy the listed files to it. This usually involves running pkunzip. Next, set the PC's clock accurately, as the CP-290 is going to inherit the time from the PC's clock. From File Manager, drag a copy of x10sched.exe to a suitable group in your Program Manager. Hook up your CP-290, and start x10sched, by double clicking on the icon. You will be asked to provide a Comm Port number for the serial port the CP-290 is hooked up to. And that's it. Note: if you choose the wrong port, your machine may "lock up" for several seconds as Windows tries to communicate with things that aren't there. Eventually it will give up, and you can change the incorrect setting with the Set menu pick on the main form. The CP-290 stores one house code (A-P), which is used with the switches on the top. You can set this with the "Set:Set House Code..." menu pick from the main window. You should generally set this initially, as setting it erases data from the CP-290. If you want to schedule events based on sunrise and sunset, you need to tell X10Sched where you live, with the Set:Location option. You are asked to provide your latitude, longitude, appromixate elevation, time zone, and Daylight Saving Time information. (Yes, all that!) Or you can just specify that you are near a given city and let it appromixate most of the values for you. If you don't set a location, sunrise/sunset times are badly approximated with a sine curve. When you install, X10Sched will create a single, empty Schedule, called "Home", and set things up so that it is automatically opened when you start X10Sched. You can rename it (File:Open and click on Edit). --- Using for the first time --- --- Defining Units --- If you don't want the CP-290 buttons to work on house code A, the first step is to run X10 and visit the Set menu. Pick Set House Code, click past the warning, and click on the letter. This will clear the CP-290 of existing events. The next task is to define the units you have. Click on the "Units..." menu pick on the main window, and click on "Add New Unit". You are presented with a small window. Specify a description for the unit you are defining (up to 44 characters) and click on the buttons to define the house and unit code. (You can't specify one you have already defined. When the window appears it usually has already guessed which house and unit code you are defining, by choosing the first unused unit code.) If the unit you are defining has dimmer capability (wall switches and lamp modules do, appliance modules don't) then click on "Dimmable". Then click Save. The unit is defined. Repeat for each unit you have. "Save and Add Another" makes adding lots of units easy. --- Defining Groups --- Groups of units can be controlled with one command, and are very useful if you typically want to turn more than one unit on or off simultaneously. For example, X10 does not support an All Light Off command, but this might be a function you find useful at bedtime. You can define a "Lights" group containing all the units that happen to be lights, and then use this group anywhere in x10sched you would use a single unit. You can define groups of units with the "Add New Group" button on the main form. You provide a name for the group, and click on each unit that you want to be in that group. Click on Save, and the group is defined. You can use a group anywhere you would use a single unit. A unit can be part of any number of different groups, and units in groups can still be controlled individually. Yes, you can use groups to define other groups. A single group can contain up to 64 other units or groups in any combination. With groups of groups you can contain a group that addresses every device X10 can support. Once you have units (and optionally groups) defined, you can start to create Scripts. --- Setting the Time --- X10Sched does this automatically, when your PC's clock reaches the beginning of a minute. This gives you nearly to-the-second accuracy. (Note that the CP-290 generally fires commands a second or two late, and X-10 commands in general take a few seconds to take effect.) X10Sched does this clock-setting only once per run, and it will not do it if it is busy downloading other commands. Once it does it, a green indicator on the main form lights up, saying "Time Set". --- Defining scripts --- There are two different kinds of scripts (combinations of units, commands and times) you can create - Simple and Fancy. --- Simple scripts --- A Simple script is a list of weekdays and times, and for each of those, a list of units (or groups) with a command to send. An example of a Simple script (perhaps called Wake Up) might be: MoTuWeThFr.... 07:30 "Alarm Clock" On "Coffee Pot" On MoTuWeThFr.... 08:05 "Coffee Pot" Off ............Su 08:30 "Alarm Clock" On During weekdays, the unit called "Alarm Clock" will go off at 7:30am, and the coffee pot will be started at the same time. Note that, in the language of the CP-290 controller, all of that can be done as one "event" of the 128 possible ones (assuming the alarm clock and coffee pot are part of the same house code.) X10sched will automatically combine operations in this fashion if it can, even if they are part of different scripts. (We presume the Alarm clock is an X10 universal unit, which turns itself off after it beeps, so there is no Off command for it listed.) During weekdays, the coffee pot will be turned off at 8:05am, so you don't come home from work to burnt sludge or a fried coffee maker. On Sundays, at 8:30am, the alarm clock will sound, but the coffee pot isn't turned on, as we have set our hope on the church coffee. To create a simple script, click on "Add New Simple script" and then, in the script window, click on "Add Time". You are presented with a small window that allows you to choose which weekdays you want your command sent, with lazy buttons for the common combinations (every day, weekdays, weekends), and a place to specify the time (in either military time, as in 17:30, or 12 hour time, as in 5:30pm or 3am). Once you've defined a time, you can add commands to it with the "Add command" button. Here you select one unit or group, and a command (On, Off, Dim to Off, or Dim and a level). Units that don't support dimming disable the Dim to Off and Dim options. As an alternative, you can specify one of the X10 "All" commands - All units off or All lights on - for any housecode. If you want to add multiple commands to a time, use the Add Command button repeatedly. You can add a different time, and add different commands to any time you've specified by clicking on the line naming the time, and then clicking on the Add Command button. You can also delete commands, or delete a time (which deletes all the commands specified for that time.) If a time is defined with the Random Minute option, all the commands listed under that time will be assigned a random minute to occur. (Described below) Note that scripts are not loaded into the CP-290 until you use the Download command on the main window! If you make any changes and then try to exit without donwloading them, you are asked if you want to download, automatically. Note that you can "turn off" a script with the "Freeze script" option. X10Sched simply ignores frozen scripts at Download time. --- Fancy scripts --- Fancy scripts are like simple scripts, in that you specify times and operations. However, fancy scripts are more suited to a common set of operations that you want to occur at different times on different days. You also get the ability to specify that some of the commands occur some number of minutes after or before the starting time of the script itself. For example, assume the kids' bedtime is 8pm every night except Friday, when it is 8:30pm. You have a hallway light you want to come on at bedtime, to dim down for use as a nightlight after they should be in bed, and then go off an hour later. You would specify two times for the start of the show: MoTuWeTh..SaSu 8pm ........Fr.... 8:30pm And you would specify these operations: "Hallway Light" On "Hallway Light" Dim to 50% after 15 min "Hallway Light" Fade to Off after 1 hour X10sched will take the two times, the three operations, and generate the six events needed. Note that you can specify "time offsets" up to 24 hours either before or after the script's start time, and if you cross into the next day, X10sched will work the scheduling out properly. (If you use the Today or Tomorrow options, and add a time offset that effectively changes the day, X10Sched will fix things if it can. If it can't, it will "freeze" that time and not download that portion of the script.) You can also execute a Fancy script Immediately, with the Execute Now button. X10Sched has a few special rules in this case. Any command listed with a "time offset" is skipped in immediate mode, and commands that can be combined will tend to be combined even if they are moved into a different order to do it. Note that you can "turn off" a script with the "Freeze script" option. X10Sched simply ignores frozen scripts at Download time. As an additional option to make some kinds of programming easier, you can tell X10Sched to treat the "time offsets" as "Increments". This means that X10sched will walk down the list of operations, in order, and sum up the offsets, so that a list like this: "Hallway Light" On "Hallway Light" Dim to 50% after 15 min "Hallway Light" Fade to Off after 1 hour [x] Treat as Incremental Would treat have the Dim command occur 15 minutes after the script started and the Fade to Off occur 1:15 after the script started, and so on. This is a useful option when you want a set of devices to go on and off one at a time, in a set order: "A1" On "A1" Off after 20 min "A2" On "A2" Off after 15 min "A3" On "A3" Off after 25 min [x] Treat as Incremental This script spans an hour, with A1 on for the first 20 minutes, A2 on for the next 15, and A3 on for the last 20 minutes. Editing the time offset of an operation early in the list will affect the scheduled times of all subsequent operations in the list. If the sum of your offset extends over one day (1440 minutes or more), X10Sched will adjust days accordingly, but the results may be confusing. Mixing Incremental offsets and the Random Minute option also "works" but the effects are likely to be confusing, and you should carefully examine sched.txt after your Donwload to make sure you got what you wanted. Note that for Fancy Scripts, the order of operations listed becomes important if you use the Incremental option. You can click on an operation and then click on Insert Operation to squeeze in a new operation above the selected one, or just use Add Operation to add to the bottom of the list. -- Selecting Times --- First we'll talk about times that don't involve Sunrise or Sunset. When you enter a time, you can use 12 hour time (5:30pm) or 24 hour time (17:30). If you use 12 hour time, you should include pm or am - if you leave it out, am is implied. When you select times, you have the options of specifying two special modes: Security (supported by the CP-290), and Random Minute (supported by X10Sched). These are NOT the same thing. Security mode causes the CP-290 to pick a different time, within the hour you specify, to give your command. Each time the CP-290 activates that event, it changes the minutes field for next use. This is done by the CP-290 itself, and you don't have to run X10sched each day to make it happen. Note that if you list two units to go on as part of a command, they will go on simultaneously; the Security mode simply reschedules the command, and the command affects two devices. Random Minute is different. It causes a random choice of minute for EACH unit within the command. This means that, except by coincidence, two units listed in the same operation will not be affected at the same time. You can combine Random Minute and Security, gaining a very random appearance to when the units act. Note also that the Random Minute for each unit is set when the commands are downloaded into the CP-290, and ///don't change after that///, unless you download them again. Yes, you can combine Random Minute with the CP-290's security mode. A final option is Freeze. If selected, X10Sched will ignore that time and any commands scheduled for it in that script. This means you can "turn off" parts of scripts easily. Note: Using Random Minute with an All Units Off command "works", but it works by breaking the command into 16 Off commands and scheduling them at random minutes within the hour. You probably do not really want to mix these settings. On the other hand, All Lights On is not split up by a Random Minute setting (because X10Sched can't tell which units will respond to this command and doesn't dare starting splitting up the request by unit numbers.) --- Sunrise, Sunset --- Instead of specifying an hour and minute, you can specify sunrise or sunset. This only works well if you have filled in your location information (with the Set:Location menu option. If you don't, simpleminded defaults are taken.) The calculations are supposed to be accurate to within a minute or two. Please note that if you live above latitude 60N or below 60S, accuracy may be less; and note that if you live above latitude 75N (below 75S) you wouldn't be basing daily events on sunrise anyway, and shouldn't ask X10sched to try. :) When you click on the sunrise or sunset option, you can specify an offset in minutes, up to 255 minutes either behind or ahead of the sun. This gives you a way to account for local conditions (a high mountain range to your immediate west could make for an earlier sunset, for example.) This setting is ///in addition to/// the ability to specify an offset for an event in a Fancy Script. How do Sun settings work with Random Minute? First, we add any offset you specifed; then, if you specified Random Minute, we ///add/// between 0 and 59 minutes to the time (this is different from other uses for Random Minute). If you specify an offset of -30, you end up with an event scheduled within a half hour of the sun. It will change each time you download it. It is important to note that sunrise and sunset times change each day, albeit not by much in most places at most times. They change fastest around the spring and fall equinox. The CP-290 knows none of this, of course. To keep the definition of sunrise and sunset current, you should download your scripts each week or so; perhaps less often in summer and winter. See "Automatic Downloads" for a way to make this easier. --- 24 hour clock --- If you select it under the Set menu, you can have all times displayed in 24 hour clock mode, in which 1pm is 13, 4pm is 16, and so up up to 23 for 11pm. If you leave this off, note that in the 12 hour clock, 12am is midnight and 12pm is noon. You can always enter time in either style you like - the setting just controls how times are displayed back to you. --- Combined Commands --- It is worth noting that X10Sched will tend to "combine commands" wherever it can. For example, if one script specified that unit A3 will go off at 8:15pm, and a different script specifies that unit A6 goes off at that time as well, these two commands will be combined into one event before the CP-290 sees it. This conserves space in the fixed array of events (128 long) the CP-290 gives you, but more importantly, it allows your scheduled commands to be sent to your units much more quickly. Combining of commands can also occur if you use X10Sched to turn a bunch of units on or off immediately (either with the On/Off buttons or by executing a script in Immediate mode). --- Downloading --- Once you have defined your scripts, click Download on the main window to send all the scripts to the CP-290. Usually, compiling the scripts into CP-290 commands takes just a moment, and actually downloading them takes several seconds. While commands are trickling into the CP-290, the main window shows a red box with the number of commands still to send in it. Note: you should not exit the program until this box leaves. If you end in the middle of a download, the CP-290 might be left with no events, some events, or a somewhat messed-up state. (X10Sched will ask you if you really mean it if you try to exit before work in progress is all accepted by the CP-290.) If you make any changes to any units or scripts, and don't use Download to send them to the CP-290, you will be asked if you want to when you try to exit. --- Automatic Downloads --- You can set things up to make Automatic Downloading of scripts easy. Create a second icon for X10sched in your program manager, and click the "Run Minimized" option. (Alt-Enter, Alt-R) If X10sched sees that it has been started up as a minimized icon, it will assume you want to immediately download and exit. The icon caption will reflect the download progress. You should not set up automatic downloads until you have your port and scripts and location all set up. --- Exiting --- When you exit (File:Exit), X10Sched will automatically save everything you told it. It will also ask if you want to download information to the CP-290, if you have made changes. Note that it often saves information while you are running, too. --- Reporting --- When a download command is done, X10sched created a file called sched.txt, which outlines the events generated to the CP-290. This will show you what your scripts compile down into. You should examine this file after downloading your scripts. --- Multiple Schedules --- You can maintain multiple schedules (combinations of scripts) but only one can be active in the CP-290 at a time. File:New creates a new schedule, and Delete Current deletes the current schedule. X10Sched will always have a schedule open - if you delete one, it opens another; if you delete them all, it creates an empty one. Note that when you create a new Schedule, you have the option of having it inherit a copy of all existing scripts. If you don't accept this option, the new Schedule will have no scripts in it. Creating a schedule with a copy of the currently open schedule's scripts is usually a good idea. The smart way to set up your schedules is to create a base one that reflects how you normally wants devices controlled, and then create variations of that in other schedules (for vacations, cold weather, and so on.) Note that the units and groups you define are always available to all schedules and scripts. If you delete units, they are deleted from all schedules. Deleting them and then "putting them back" does not automatically put them back into scripts - the code assumes you had a compelling reason to delete the device and doesn't assume that a new device on the same housecode should be treated the same. --- How Do I? --- > How do I convince the software not to ask me "Are you sure?" on every delete command? The Set menu has an option for Skip "Are you sure". Click it on. The setting will be remembered. > How do I see what the CP-290 was told to do? After Download is clicked, a file named sched.txt is created. It contains a list of CP-290 events. > How do I write a script that reacts to current conditions? I don't want to schedule a dim command for a light that is already off! Sorry. The CP-290 doesn't support the ability to detect what units are currently on or off, so you can't do this. Would that it did. > How do I see what time the software thinks Sunrise and Sunset are? Use Set:Location to set up your location, and then click on the window next to the save button. This will update itself to show you sunrise and sunset, based on your picks, and also saves your new setting automatically. > It's not working. What next? The software is provided "as is." However, you have my email address, and I want to hear about bugs. Before you assume something is broken, though, try using the switches on top of the CP-290 to control things. If they don't work, X10Sched likely won't work either. Make sure you set the Base code (under the Set menu) and that the CP-290 knows what time it is (you can force X10Sched to set an approximate time immediately with the Set menu). If you have selected the wrong port, you may /appear/ to have success downloading, but you might in fact be downloading CP-290 commands to your mouse or modem. --- Final Notes --- Subsequent versions will certainly gain features if people like this one. Suggestions may be mailed to smayo@iii.net. Subsequent versions will probably cost more, of course, but if I like your suggestion you might get an update for free. :) [end X10sched.txt 10/12/95]