    Filename README.TXT, copyright W. L. Sexauer, November 2, 1991.

    The XCONTROL program was written to provide a better method of
    operating the Powerhouse X10 (TM) controller than the software
    provided with the controller.  The principal advantage of this program
    is that it allows events to be varied with the local sunrise and
    sunset without the effort of editing files or individually deleting
    and re-entering events. The XCONTROL program also allows the following
    additional functions: setting the clock in the controller, setting the
    base housecode of the controller, deleting a single event from those
    stored in the controller, loading a complete schedule of events into
    the controller, loading a single event for execution now, today or
    tomorrow, or displaying or printing the events stored in the
    controller.
    
    The program is marketed under the shareware concept.  You are free
    to try out the program, and to distribute it to others as long as you do
    not charge for it and provided that you include this file unaltered.
    If you find that the program is useful, please send a payment of
    $25.00 to the author:  William L. Sexauer, 15548 SE 175th Court,
    Renton, WA, 98058.  Registered owners will be notified of new versions
    as they are developed.



                       SYSTEM REQUIREMENTS

    System requirements are minimal, an IBM PC or compatible with 256K
    memory, dual floppy drive or single floppy drive and a hard drive, CGA
    or better monitor, and an X-10 PowerHouse (TM) model CP290 computer
    interface unit attached to COM port 1 or 2.  The computer interface
    unit is hereafter referred to as the controller.

                             NEW FEATURES

    Version 2.0 has many new features.  (Thanks to all those who wrote 
    or phoned with ideas.)
    
    The installation program, XCInstal, has been revised to save its
    settings, so that updating the SUNRISE.FIL data file for each year
    after the original installation does not require re-entry of all
    settings.  Also, the data files used by the installation program have
    been renamed to .FIL extensions so that the only .DAT file(s) are
    your schedule file(s).
    
    If your computer clock seems to be more accurate than the X10
    controller's clock, you can now have the X10 controller's clock reset
    each time you run the XCONTROL program.  The reset only occurs when
    you load the schedule file (choice L from the XCONTROL main menu.)
    This feature is enabled by the XCInstal program if you select it.

    The XCONTROL program now keeps track of whether the current day is
    using daylight savings time.  Whenever you load a schedule file to the
    X10 controller (choice L from the XCONTROL main menu) the program
    will check to see if daylight savings time is supposed to be used for
    the current date, and will ask you if you want to update both the 
    computer's DOS clock and the X10 controllers clock on the first day of 
    daylight saving time and the first day after daylight saving time.  
    (If your computer has a battery backed up clock that is not reset with 
    the DOS TIME command, that clock will not be reset by XCONTROL.  You 
    must run whatever utility you would normally use to copy the DOS time 
    into the battery backed up clock.)

    The XCONTROL command line now accepts a schedule file name as well as
    a single command.  This makes it possible to load a temporary
    schedule from the command line, XCONTROL L VACATION.DAT for example.

    A new unit code of 99 has been added.  This code represents all
    devices so that it is possible to turn off everything at once.
    The program now supports monochrome monitors.  (I don't know about
    Hercules graphics cards, I don't have one and can't try it out.)

    The program has been modified to find data files (.DAT, .ERR, .FIL and
    .INI) in the current directory, in any directory listed in an
    environment variable named XCTL, or in any directory in your PATH.
    This allows you to keep your schedule files in a directory other than
    the one that the program is in.

                              BUG FIXES

    Version 1 had several bugs which have been fixed in version 2.01.  The
    installation program didn't always compute the local sunrise and
    sunset times correctly, but should now.
 
    Version 1 also had some errors in the communication between the
    computer and the X10 controller; these errors only affected some
    users.  I have corrected the code so that it works more reliably.

                                   
                  INSTALLATION - FLOPPY DISC SYSTEMS

    The first step should be to make a backup copy of the distribution
    disc.  You will then need three more blank discs.  Label one of them
    XCONTROL PROGRAM DISC, the second one XCONTROL EDIT/INSTALL DISC, and
    the third one XCONTROL SCHEDULE FILES.

    Copy the files onto the three discs as follows:
    XCONTROL PROGRAM            XCONTROL EDIT/INSTALL           SCHEDULE
        DISK                        DISK                            DISK
    BASIC.ERR                   BASIC.ERR                       SAMPLE.DAT
    XCONTROL.ERR                XCEDIT.ERR
    XCONTROL.EXE                XCINSTAL.ERR
                                XCEDIT.EXE
                                XCINSTAL.EXE
                                CITIES.FIL
                                XCINSTAL.FIL

    At this point, you should have the proper program files on the proper
    discs.  Enter SET XCTL=B:\. This will tell the XCONTROL programs where
    to find your schedule file(s). The next step is to create the files
    XCONTROL.INI and SUNRISE.FIL using the XCINSTAL program.  Put the
    XCONTROL EDIT/INSTALL DISC in the A drive, put the XCONTROL SCHEDULE
    FILES DISC in the B drive, change to the B drive and then type
    A:XCINSTAL.  The XCINSTAL program will create files XCONTROL.INI and
    SUNRISE.FIL on the B drive.  (You may use different drive letters if
    your drives are not A and B, or if you want the programs in B and the
    data files in A.  Make sure that you put the proper drive letter in
    the SET XCTL= command.)

    The data file installation will require your location, either by entry
    of your latitude and longitude or by selection of your state and city
    from a list.  It also needs to know whether your area observes
    daylight saving time and, if so, when it starts and ends.  For areas
    observing the Federal Daylight Saving Time, it will start on the first
    Sunday in April and end on the last Sunday in October (choice no. 1
    from the menu.)  The installation program will then calculate the
    sunrise and sunset time for each day of the year for your location.
    It will be accurate to about 5 minutes, excluding errors such as
    result from a nearby mountain range delaying sunrise or speeding
    sunset.  I have found this to be sufficiently accurate for turning
    lights on and off to give my house a lived-in appearance.

    If your area does observe daylight saving time, you will need to run
    the XCInstall program each year sometime between January 1 and the
    first day of daylight saving time.  This will update the SUNRISE.FIL
    to contain the proper daylight saving time data for the current year.
    Otherwise, you will have a few days at the beginning and end of
    daylight  saving time where XCONTROL is an hour different than your
    clocks.

    You should put the following line into your AUTOEXEC.BAT file.        
          SET XCTL=B:\
    (use the drive letter for the drive where you intend to keep  your
    schedule files.) This will tell the XCONTROL programs where to find
    your schedule file(s).

    To modify your schedule file(s) or to run the installation program to
    update the SUNRISE.FIL data file for a new year, put the XCONTROL
    EDIT/INSTALL disc in the A drive and the XCONTROL SCHEDULE FILES disc
    in  the B drive.  To operate the XCONTROL program and the X10
    controller, put  the XCONTROL PROGRAM disc in the A drive and the
    XCONTROL SCHEDULE FILES  disc in the B drive.


                 INSTALLATION - HARD DISC SYSTEMS

    The first step should be to make a backup copy of the distribution
    disc.  Next, just copy all of the files to the directory where you 
    wish to keep them.

    Then, run program XCINSTAL and follow the instructions.  This will
    create the data files XCONTROL.INI and SUNRISE.FIL which are necessary
    for the XCONTROL and XCEDIT programs to operate.

    The data file installation will require your location, either by entry
    of your latitude and longitude or by selection of your state and city
    from a list.  It also needs to know whether your area observes
    daylight saving time and, if so, when it starts and ends.  For areas
    observing the Federal Daylight Saving Time, it will start on the first
    Sunday in April and end on the last Sunday in October (choice no. 1
    from the menu.)  The installation program will then calculate the
    sunrise and sunset time for each day of the year for your location.
    It will be accurate to about 5 minutes, excluding errors such as
    result from a nearby mountain range delaying sunrise or speeding
    sunset.  I have found this to be sufficiently accurate for turning
    lights on and off to give my house a lived-in appearance.
    
    If your area does observe daylight saving time, you will need to run
    the XCINSTAL program each year sometime between January 1 and the
    first day of daylight saving time.  This will update the SUNRISE.FIL
    to contain the proper daylight saving time data for the current year.
    Otherwise, you will have a few days at the beginning and end of
    daylight saving time where XCONTROL is an hour different than your
    clocks.
                     CREATING A SCHEDULE FILE

    The default schedule file name is SCHEDULE.DAT.  You may copy a sample
    from the distribution disc, or you may begin from scratch.  If you
    wish to keep your schedule files in a different  directory or on a
    different drive than the XCONTROL program files, you have two choices.
    The programs will find data files in any directory listed in your
    current PATH, or you may set an environment variable  called XCTL.
    Just add a line to your AUTOEXEC.BAT file that reads:
               SET XCTL=C:\DATA\XCTL
    Of course, you may use any drive letter and directory name that you
    wish.

    (Hint: I keep all of my data files in subdirectories under the
    subdirectory \DATA.  That way, I only have to do routine back-ups of
    the \DATA directory and its subdirectories.  I only have to back up my
    entire hard disc if I have added a major new program.)

    Run the program XCEDIT to create and/or modify the schedule file.
    Select Add to program an event.  I keep my schedule file sorted by
    adding new lines at specific line numbers, but you may just press
    RETURN instead of specifying a line number, this will add a new line
    at the end of the file.

    You will get a formatted entry screen.  The cursor keys, tab and
    backtab keys may be used to move from field to field.  It does not
    matter whether you use upper or lower case letters, the program will
    make all input lower case except that the initial character of each
    field will be set to upper case.  Press RETURN only when you have
    filled all of the fields you intend to use, this will cause the
    program to examine all of your input and accept it or issue an error
    message(s) and ask you to correct the input data.

    Please note that the XCEDIT program updates the schedule file when you
    enter an event with no errors.  Once an event has been entered, using
    the  escape key does not cancel the edit, it simply exits to the
    previous menu or  out of the program.

    Most fields are self explanatory, but a couple are briefly described
    here.  A complete description of all of the fields is at the end of
    this  file.
  
    FUNCTION may be On, Off or Dim.  The DIM field is used only if the
    function is Dim; it is a number between 0 and 15 specifying the
    brightness of the lamp.  0 is off, 15 is full brightness.

    TIME must be entered in the format hh:mm.  You may use a space or a
    zero in the first column for single digit hours, but you must use a
    zero for single digit minutes.  For example, 05:07 and  5:07 are both
    valid, but  5:7 is not.  Instead of entering a time, you may enter an
    offset from sunrise or sunset.  Entries such as SR-75 or SS+22 are
    valid and specify that the event should occur 75 minutes before
    sunrise or 22 minutes after sunset.  Offsets of up to 99 minutes are
    allowed.

    MODE may be Regular or Security (simply R or S is a sufficient entry.)
    Security mode sets the event to occur at a random time sometime during
    the specified hour.  The minutes are ignored for the security mode,
    but must be entered anyway.
    DAYS are specified by filling one column for each day of the week
    desired.  You may enter "M W F" for Monday, Wednesday and Friday, or
    you may use x's for each day.  "X X X" does the same job as "M W F".
    You may make a comment line that does not cause any X10 devices to
    operate by simply leaving the day field blank.
 
    The MONTHS field may be used to limit the event to specific months.
    Simply enter the first and last months by using the first three
    letters of each, with a - (dash) in between.  For example, Oct-Mar
    will cause the event to be scheduled only between October and March,
    inclusive.

    The following TIME LIMIT feature is extensively changed from
    version 1 of the XCONTROL system.  Your schedule files may have
    to be updated if you have used this feature!

    The TIME LIMIT field may be used to indicate a limiting time to
    prevent a variable time from varying too far.  This field is only used
    with times programmed as offsets from sunrise or sunset.  The limit
    code format is <HH:MMy where:  The first character may be a < to set a
    limit on how early  the event may occur, or it may be a > to set a
    limit on  how late the event may occur.  The HH:MM is the limit time.
    The last character may be a Y or N.  If it is a Y, the event will be
    scheduled at the limit for all times outside the limit.  If it is a an
    N, the event will not be scheduled at all if the variable time is
    outside the limit.  If the last character is left blank, it defaults
    to a Y.  For example: Sr+45 and <07:30Y will schedule an event for 45
    minutes after sunrise, unless sunrise is earlier than 6:45.  If it is,
    the event is schedule to occur at 7:30.  Another example:  Ss-15 and
    >06:15N will schedule an event for 15 minutes before sunset, unless
    sunset is after 6:30.  If it is, the event is not scheduled at all.
                   RUNNING THE XCONTROL PROGRAM

    Simply type XCONTROL to run the program.  You will get a menu of
    possible functions.  If no function is specified on the command line,
    the menu will be presented.  At the completion of any function, the
    menu will return.

    The XCONTROL program reads three data files and uses the information
    from them to download a set of event programs to a Powerhouse X10 (TM)
    controller.  The data files are XCONTROL.INI, SUNRISE.FIL and
    SCHEDULE.DAT.

    The XCONTROL.INI file contains the settings for your customized
    installation.  These include your comm port number, your lattitude and
    longitude, etc.  It also contains a flag indicating whether the
    current  date is or is not using daylight savings time.  This file is
    created by  the XCINSTAL program during initial installation.

    The SUNRISE.FIL file contains the approximate sunrise and sunset
    times.  This file is also created by the XCINSTAL program.
 
    The SCHEDULE.DAT file contains the list of events that you wish to
    have programmed in the X10 controller. The events are stored in the
    controller by line number of the file, not by unit number.  However,
    the XCONTROL program will clear all events not listed in the file.
    The SCHEDULE.DAT file may be updated by using the XCEDIT program.
    Other filenames may be used if desired.  (I use a separate file called
    VACATION.DAT for the Christmas holiday season.)

    The XCONTROL program updates the events which are scheduled based on
    sunrise or sunset whenever the L (load controller) function is used.
    It is not a memory resident program that will automatically update the
    times.  I find that running it about once a week is adequate.  You
    don't need to revise the schedule file, just type XCONTROL L daily,
    weekly or whenever you wish.  It will also ask you if you want to 
    adjust both your computer clock and the X10 controller's clock 
    whenever you load your schedule file and the program detects that 
    daylight saving time has started or ended since the last time you 
    loaded the schedule file.  This feature is disabled when you run the
    program from the command line, such as the command "XCONTROL L" in a 
    batch file.  This prevents the program from asking you a question when
    you are not at the computer when the program runs.

            RUNNING THE XCONTROL PROGRAM FROM A BATCH FILE

    You may enter a schedule file name on the command line, with or
    without a command.  If a command is entered on the command line, the
    XCONTROL program will perform that single command and then terminate.
    This makes it easy to run from a batch file.  A batch file containing
    the line XCONTROL L will load the contents of the schedule file
    SCHEDULE.DAT into the CP290 controller.  Similarly, entering the line
    XCONTROL L VACATION will load the contents of file VACATION.DAT into
    the CP290 controller.

    The .DAT file extension need not be entered unless you have no command
    and have a single character schedule file name.  XCONTROL R will
    display the X10 controller schedule, it will not load a schedule file
    named R.DAT.  However, XCONTROL R.DAT will load a schedule file named
    R.DAT, and  XCONTROL L R will both load the schedule file R.DAT and
    download it to the  X10 controller.  (I use XCONTROL L VACATION so
    that I can sleep in on  holidays.)
                       SCHEDULE FILE FORMAT

    The format of the schedule file is provided for those who wish to use
    another editor, you don't need to worry about it if you plan on using
    the XCEDIT program to maintain your schedule file(s).  The format is
    as follows.

    Column  1 contains the housecode of the device to be programmed. This
    must be a letter in the range of A to P.

    Column  2 should be blank.

    Columns 3-4 contain the unit code of the device to be programmed.
    Unit code 99 will operate all devices for the housecode on that line.

    Columns 5-30 are a description of the unit to be programmed.

    Columns 31-33 are the function code.  ON, OFF and D (dim) are the
    allowed codes.  If D is entered, it must be followed by a number from
    0 to 15 representing the desired brightness level.  0 is full dim, or
    off; while 15 is fully bright.

    Column  34 should be blank.

    Columns 35-39 are the time to be programmed.  Two formats are
    possible.  The first format is HH:MM, where HH is the hour (1-12) and
    must have a leading space if both columns are not used. The minutes
    may be 00 to 59.  The second format is SR+MM, where SR may be used to
    indicate sunrise or SS may be used for sunset.  The + indicates that
    the minutes following are to be added to the sunrise or sunset time,
    while a - would subtract the minutes from the sunrise or sunset.  The
    minutes in this case may vary from 00 to 99.  For example, SR+15 would
    indicate 15 minutes after sunrise.

    Column  40 should be blank.

    Columns 41-42 must be either AM or PM.

    Column  43 is blank.

    Columns 44-50 may be used to set a limiting time to prevent a variable
    time from varying too far.  A < sign denotes that the time in columns
    45-49 is the earliest time that may be programmed.  For example, <
    4:40 indicates that the event will occur no earlier than 4:40.  A >
    sign denotes that the time in columns 45-49 is the latest time that
    the event may be programmed.  A final character of Y (or blank)
    indicates that the event will be programmed at the limit time if the
    computed variable time is outside the limit.  A final character of N
    means that the event will not be programmed for times outside the
    limit.  For example, an entry of > 7:00N for a limit on a light
    scheduled with respect to sunrise would mean that if the sunrise is
    sufficiently late that the light would be turned on after 7:00, it
    will not be turned on at all.  Similarly, an entry of < 4:40Y (or <
    4:40 ) for a sunset scheduled lamp means that if the sunset is so
    early that the lamp should come on before 4:40 PM, it won't come on
    until 4:40.  Note! This feature has been revised since version 1.
    Your schedule files should be modified if you used the time limit
    feature.

   Columns 51-59 are the mode.  Allowable entries are REGULAR, SECURITY,
    or blank.  A blank mode will clear the event in the X10 controller.

    Column  60 is blank.

    Columns 61-67 are the days.  Column 61 is M for Monday if the event is
    to be scheduled, otherwise it is blank.  Similarly, columns 62-67
    contain T W T F S S or blanks.  Since it is the position of the
    character which is important, not its value, the use of T for both
    Tuesday and Thursday is not a problem.  Similarly with the letter S.
    When using the XCEDIT program to add or revise an event, you may
    simply enter an X in the columns desired.  The XCEDIT program will put
    the proper letters in the output file.  If you leave all of the days
    blank, you will have a comment line in your file that shows all of the
    data but has no effect on the CP290 controller.
  
    Column  68 is blank.

    Columns 69-75 may be used to limit the event to particular months.
    Examples are: DEC-DEC would only be programmed during December.  APR-
    JUN would be programmed during April through June.  OCT-FEB would be
    programmed during October through December AND January through
    February.  Columns 76-77 should contain a carriage return and line
    feed.

    It is critical that every line in the file be EXACTLY 77 characters
    long (or 75 text characters plus the carriage return and line feed.)
    The  program WILL NOT operate correctly with any other line length.
    The file  is an ASCII file and may be modified with any word processor
    that will  allow keeping the fixed length lines.  However, use of the
    XCEDIT  program will be the most convenient method of updating the
    schedule files.

    I hope that this program is useful to you.  If you have any questions
    or suggested improvements, please let me know.



    William L. Sexauer
    15548 SE 175th Ct.
    Renton, Washington, 98058


         ----------------end-of-author's-documentation---------------

                         Software Library Information:

                    This disk copy provided as a service of

                           Public (software) Library

         We are not the authors of this program, nor are we associated
         with the author in any way other than as a distributor of the
         program in accordance with the author's terms of distribution.

         Please direct shareware payments and specific questions about
         this program to the author of the program, whose name appears
         elsewhere in  this documentation. If you have trouble getting
         in touch with the author,  we will do whatever we can to help
         you with your questions. All programs have been tested and do
         run.  To report problems,  please use the form that is in the
         file PROBLEM.DOC on many of our disks or in other written for-
         mat with screen printouts, if possible.  PsL cannot debug pro-
         programs over the telephone, though we can answer questions.

         Disks in the PsL are updated  monthly,  so if you did not get
         this disk directly from the PsL, you should be aware that the
         files in this set may no longer be the current versions. Also,
         if you got this disk from another vendor and are having prob-
         lems,  be aware that  some files may have become corrupted or
         lost by that vendor. Get a current, working disk from PsL.

         For a copy of the latest monthly software library newsletter
         and a list of the 3,000+ disks in the library, call or write

                           Public (software) Library
                               P.O.Box 35705 - F
                            Houston, TX 77235-5705

                                 Orders only:
                                1-800-2424-PSL
                              MC/Visa/AmEx/Discover

                          Outside of U.S. or in Texas
                          or for general information,
                              Call 1-713-524-6394

                          PsL also has an outstanding
                          catalog for the Macintosh.


