      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]