
        
       XT - TSR Shareware for the CP-290
       Copyright 1991-1994 by Bruce Christensen. All Rights Reserved.
       Version 2.00  -  June 1994




       1.   Introduction

            XT is a  TSR (Terminate-Stay  Resident) program  written for  the
            IBM-PC and  compatible  computers  to control  the  X10  Computer
            Interface (CP-290).   XT  will "pop-up"  a  menu of  all  defined
            modules when  the proper  HotKey sequence  is detected.   Once  a
            module is selected, another menu is presented allowing  selection
            of the ON, OFF, and DIM commands. You may alter the position  and
            color of each window to suit your needs.

            XT   utilizes   interrupt    driven,   data   buffered,    serial
            communications  allowing  constant  monitoring  of  all  activity
            generated by the CP-290.  Therefore,  the current status of  each
            module will  be maintained  as long  as XT  is resident  in  your
            computer's memory.  The latest  state will  be reflected  in  the
            menus.  A  utility program  called XTS  allows you  to query  the
            state of any  X10 module  from a batch  file.   XTS displays  the
            state of individual modules, modules of a selected housecode,  or
            all 256 modules supported by the CP-290.  When you register  your
            copy of XT,   XTS will be upgraded  to return an 'errorlevel'  of
            the a module's status  (ON, OFF, DIM)  allowing you to  interface
            other programs with your X10 modules.
            
            While XT was designed to be a resident program in your computer's
            memory, it  can be  easily removed  by  the press  of a  key.  In
            addition, XT can be  instructed to operate  as any other  non-TSR
            program with the use of a command line switch. This mode somewhat
            reduces the  advanced  capabilities  of XT,  but  is  useful  for
            quickly controlling any number of home automation devices.
            
            XT can examine each modules event  list stored in the CP-290  and
            force every module  to its expected  state.  This  is useful  for
            resetting modules after  a power failure,  or if  the CP-290  has
            been off-line for some time.  This feature can be invoked at  any
            time by the press of a key, or it may be activated  automatically
            during XT installation.
            
            XT may communicate to the  CP-290 via COM1...COM4 ports.  Default
            parameters for  I/O port  assignments and  IRQ levels  have  been
            preselected for most common  installations, but these  parameters
            can be easily modified to match your systems configuration.


       2.   Shareware

            This program is being marketed using the SHAREWARE concept  which
            allows you a complete  evaluation of the  product before you  are
            required to  register.   Shareware  provides you  with  low-cost,
            high-performance software and support.   Shareware also  provides
            incentives for programmers to  continue to develop new  products.
            If you find XT and its  support files useful and you continue  to
            use them after  a trial period  not to exceed  45 days, you  must
            make a  registration payment  of $25  to the  author.   When  you
            register, you will receive  the latest, full-featured version  of
            XT/XTS along with a printed User's Manual.  For more information,
            see "Warranty, Copyright and  Registration Policy", fill out  and
            mail the included "REGISTER.TXT" form, and register your copy  of
            XT.


       3.   Installation
             
            First, copy the  contents of this  floppy to the  same drive  and
            directory in which your  X10 software resides.   For example,  if
            your X10 files are located on Drive C in the directory "X10", and
            the XA installation floppy disk is inserted in Drive A, you would
            type at the DOS prompt:

                 C:
                 CD \X10
                 COPY A:\*.* C:

            If you haven't already done so, include this drive and  directory
            within your PATH statement of the AUTOEXEC.BAT file.  The  "PATH"
            statement tells DOS  where to locate  frequently used  executable
            files.

                 SET PATH=C:\DOS;C:\X10;...

            You should  set the  XT environment  variable  to the  drive  and
            directory of  your command  files.   This  environment  variable,
            which can  also be  placed in  your AUTOEXEC.BAT  file, tells  XT
            where to find  its initialization file  which is  used to  define
            menu strings and other items that configure your interface.

                 SET XT=C:\X10

            If you don't understand the concepts of the PATH or SET command,
            refer to your DOS User's Guide and Reference manual. Also, see
            the  AUTOEXEC.BAT supplied with this package for an example.

            Finally, let XT's utility program "FINDX10T" search your
            computer's serial ports for the CP-290. FINDX10T will determine
            the IO port address and IRQ (interrupt vector) for that
            particular port. These parameters are important for the
            successful operation of XT.


       4.   Using XT

            Once you have installed XT on your computer, you can start it  by
            typing the following at the DOS prompt:

                 XT <Enter>

            That's  XT  followed  by  pressing  the  key  marked  <Enter>  or
            <Return>.   This will  install  XT as  a  TSR program  using  the
            following default parameters:

               - XT.INI is the default initialization file.
               - COM1 is the default communications port using IO address
                    0x3F8 and IRQ level 4.
               - <CTRL> <LEFT SHIFT> is the activation "HotKey".

            It's possible  that  you  may  have  the  CP-290  attached  to  a
            different port. If this is case, see Section 5 - XT Details,  for
            options to specify the  correct port. For now,  just read on  and
            continue this section.

            XT should now be  resident in your computer.  If you did not  get
            the  "Completed OK."  message, find and correct the problem, then
            restart the program.
            
            You activate XT's first menu by pressing the HotKey sequence,  in
            this case, both <CTRL>  and <LEFT SHIFT> keys  at the same  time.
            Since you didn't specify an initialization file, XT will use  the
            default  (XT.INI)  file  which  contains  several  sample  module
            definitions, menu colors, etc. The menu should like:


                Module Description  Addr  Cmd Ŀ
                Garage/Porch_Lights_Gar   A  1     ?   
                Living_Room_Lamp          A  2     ?   
                Bedroom_Lamp              A  3     ?   
                Family_Room_Lamp          A  4     ?   
                Flag                      A  5     ?   
                Plant_Grow_Lights         A  6     ?   
                Basement_Computer         A  7     ?   
                386_Computer              A  8     ?   
                Playroom                  B  6     ?   
               

                         Figure 1 - Module Menu


            In this case, there are 9 modules defined. Each module has a name
            describing its location  or function,  an address,  and the  last
            command that was performed on this module. If your CP-290 has its
            Basecode set for 'A' (see X10 documentation provided with the CP-
            290), you should be able to  press any one of  the 8 keys on  the
            CP-290 and watch the display update the status of that particular
            module. This holds true with events stored in the CP-290  memory.
            As events are processed, they will be recognized by XT, and  each
            item's status will be reflected in the menu.  Now press the <ESC>
            key - the menu should disappear. Again, press any key on the  CP-
            290. Now activate the menu by  pressing the hotkeys <CTRL>  <LEFT
            SHIFT> and you  should see the  correct state of  the module  you
            just  triggered.  Since  XT   uses  interrupt  driven,   buffered
            communications with the CP-290, the menu doesn't even have to  be
            displayed in order to record the  current status of a module.  XT
            sits in  the background  processing  any information  the  CP-290
            sends it. This  information will be  displayed when you  activate
            the menu via the HotKey, or when you use the utility XTS.EXE.
            
            When the module menu is displayed,  a menu highlight bar will  be
            placed on the last module description that was selected. Use  the
            <Up-Arrow>, <Down-Arrow>, <PgUp>, <PgDn>,  <Home>, or <End>  keys
            to position  the  highlight  bar over  the  module  you  want  to
            control. If there are more modules defined than can actually  fit
            in the menu (due to menu  location on the screen), the menu  will
            scroll through the list.
            
            The following is a list of keys and their actions:

                 <Up-Arrow> - move the  highlight bar up 1  row in the  menu.
                      When it reaches the first item, it stops.

                 <Down-Arrow> -  move the  highlight bar  down 1  row in  the
                      menu.  When it reaches the last item, it stops.

                 <PgUp> -  the  first time  this  key is  pressed,  the  item
                      displayed at  the  top  of  the  menu  is  highlighted.
                      Subsequent presses cause the menu to display the  items
                      on the previous page.

                 <PgDn> -  the  first time  this  key is  pressed,  the  item
                      displayed  at  the  bottom  of  the  current  menu   is
                      highlighted.  Subsequent  presses  cause  the  menu  to
                      display the items on the next page.

                 <Home> - moves the highlight bar  to the very first item  in
                      the menu.

                 <End> - moves the highlight bar to the very last item in the
                      menu.

                 <Enter> -  selects the  highlighted  item and  displays  the
                      command menu.

                 <ESC> - leave the module menu, restore screen.


            When you have selected the item you want to control, press
            <Enter>.  For this example, choose the last item on the list
            "Playroom".  A command menu will now appear on the screen:

                    Ŀ
                     Playroom                  % Level 
                     Address: B  6            100  
                     Status:  ?                90  
                                               80  
                     Use / keys for          70  
                     command/brightness.       60  
                     Press <Enter> to          50  
                     activate, <ESC> aborts.   40  
                                               30  
                        On    Off    Dim    20  
                                 10  
                    
                          Figure 2 - Command Menu

            The first line displays the  module information (Playroom).   The
            second line displays  its address (B6).  The third line  displays
            its status (?).  XT will highlight the action it thinks you  will
            want to  perform.   For example,  if the  current status  of  the
            device is either On or Dim, XT selects Off so all you have to  do
            is press  <Enter>.    Otherwise, use  the  <Left-Arrow>,  <Right-
            Arrow>, or <Tab> keys to highlight the action (On, Off, Dim)  you
            want to perform on  this module. If you  are commanding either  a
            lamp dimmer or wall  switch, you have  the capability of  dimming
            that module.  Use the <Up-Arrow>  or <Down-Arrow> keys to  select
            the level percentage.   When you've  selected the command,  press
            <Enter> to  send the  command.   The active  function will  blink
            letting you know the command is  in progress.  If all goes  well,
            the command menu will disappear  upon completion of the  command,
            and the status will be reflected in the module menu.

            Each time  a command  is sent  to  the CP-290,  XT waits  for  an
            acknowledgment message.  If that message is not received after  a
            pre-determined time-out  period, the  following message  will  be
            displayed:

                    Ŀ
                    Command not acknowledged.        
                    Check cable, IRQ/IO assignments. 
                                                     
                        Press any key to continue... 
                    

            First, check your cable to make sure you're connected to the  CP-
            290.   Next, make sure you've specified the proper COM port  (see
            the "c="  option in  the  next section).    If you're  still not
            communicating with the CP-290, determine the IRQ and I/O Port  of
            your serial port and use the "i=" and "o=" commands.
            
            Note: XT will  only "popup"  when the  current video  is in  non-
            graphics mode.   XT  will continue  to  monitor the  CP-290,  but
            activation of the menus will occur once the video is restored  to
            text-based mode.


       5.   XT Details

            If you have your PATH statement and XT environment set  correctly
            (see Section 3 - Installation), you should be able to install  XT
            into memory by typing the following command at the DOS prompt:

                 XT <Enter>

             When XT is invoked without any options, it assumes the following
            defaults:

                 - the data file containing X10 module descriptions,
                      addresses, and other custom options is called:  XT.INI

                 - the COM PORT that the CP-290 is connected to is COM1 (it
                      is assumed that COM1 has its IRQ level set to 4 and the
                      I/O port is located at 3F8 HEX).

                 - memory reserved for the XT program is set at 512
                      paragraphs (more on this later).

                 - the HotKey combination to activate the menu is
                      <CONTROL><LEFT-SHIFT>, that is, both the CONTROL
                      (labeled as Ctrl on most keyboards) and the LEFT SHIFT
                      key are pressed at the same time.

            If these  defaults do  not apply  to your  system, then  you  may
            override these settings  by passing the  following options to  XT
            when you install it into memory.

     Ŀ
      The XT program has the following options:                           
                                                                          
      XT [f=filename] [c=comm port] [i=irq] [o=io_addr] [m=memory blocks] 
         [h=hotkey] [+p] [-s] [-t] [+u] [/?]                              
     


            where:

                 [f=filename]   - this is the name of the file containing X10
                      module descriptions, addresses, and other items such as
                      menu color,  and menu  screen positions.   The  default
                      file is: XT.INI

                      If you  want  to  specify a  different  file,  such  as
                      "FRED.X10", then type:

                         XT f=FRED.X10

                 [c=comm port]  - this allows  you to select the serial  port
                      for communications with the interface.  You may  select
                      ports 1...4.   The default  port is:  1   (for COM  1).
                      For example, if your CP290 is connected to COM3:

                         XT c=3

                      Note:   When using  this option,  XT assumes  that  the
                      serial ports  in your  system  are setup  according  to
                      Table 1.   In most cases,  these assumptions are  valid
                      for COM1 and COM2, but lack of a standard for COM3  and
                      COM4 will probably conflict  with your setup if  that's
                      where your CP-290 is connected. To compensate for  this
                      potential problem, see the [i=irq] and [o=i_o]  options
                      later in this section.

                                Ŀ
                                  COM1 = I/O address 0x3F8   Interrupt 4  
                                  COM2 =      "      0x2F8       "     3  
                                  COM3 =      "      0x3E8       "     4  
                                  COM4 =      "      0x2E8       "     3  
                                
                                        Table 1 - COM port assignments

                 [i=irq] - use this option if your communications port uses a
                      different IRQ level than what is "standard" (see  Table
                      1 for  the "standard"  assignments).   The default  IRQ
                      level is: 4 (COM1)

                      If your serial port uses IRQ  5, then you must  specify
                      it on the command line as:

                         XT i=5

                      Note: If  you  can't get  the  XT program  to  function
                      correctly (time-outs, etc.), the problem is most likely
                      caused  by  an   improper  IRQ   assignment.  See   the
                      Troubleshooting section  later  in  this  document  for
                      determining your  IRQ  level.   You  can also  run  the
                      program "FINDX10T.EXE" to see  if it can determine  the
                      proper parameters.

                 [o=io_addr] - use  this option if  your communications  port
                      uses a different IRQ level than what is "standard" (see
                      Table 1 for  the "standard"  assignments). The  default
                      I/O Port address is: 3F8 HEX (COM1).

                      If your serial  port is  setup for  2E8 hex,  then
                      use: 
                          XT o=2E8

                 [m=memory blocks] -  this option is provided to allow you to
                      adjust the amount of memory reserved by XT. This memory
                      is  used   to   store  information   such   as   module
                      definitions, saving screen  data when a  menu pops  up,
                      and other internal storage. Ideally, you want to use as
                      little memory  as  possible, but  the  amount  required
                      depends on how many modules XT is controlling. Too much
                      reserved memory is wasteful, stealing memory from  your
                      other DOS applications. Too little reserved memory will
                      most likely  cause  your  system  to  crash,  with  DOS
                      displaying the following message:

                                 Memory Allocation Error. System Halted.

                      The amount of memory reserved by XT is in units  called
                      "blocks". Each block is 16 bytes. The default number of
                      blocks that XT  reserves is 512,  or 8192  bytes (16  *
                      512). This value  works with the  9 module  definitions
                      contained in  the sample  file (XT.INI)  provided  with
                      this package.

                      Finding the right value is pretty much trial and error.
                      If your system crashes,  add more reserved memory.  For
                      example:

                          XT m=600

                      Note: System  crashes  or  weird behavior  may  be  the
                      result of other  TSR's loaded in  your system. See  the
                      Troubleshooting section later in this document.

                 [h=hotkey] - this option allows you to assign a different
                      "HotKey" for menu activation. The default HotKey
                      sequence is:

                         <CTRL><LEFTSHIFT>

                      That is, both the CONTROL and LEFTSHIFT keys pressed at
                      the same time. To configure  your own HotKey, you  must
                      use a combination of values from Table 2.

                                      KEY      VALUE (hex)
                                    ========== ===========
                                    RIGHTSHIFT  0x0001
                                    LEFTSHIFT   0x0002
                                    CONTROL     0x0004
                                    ALT         0x0008
                                    SCROLLLOCK  0x1000
                                    NUMLOCK     0x2000
                                    CAPSLOCK    0x4000
                                    INSERT      0x8000

                                    Table 2 - Hotkey Codes

                      You ADD the values (in  HEX) for the corresponding  key
                      combination you want to use. Remember, the  hexadecimal
                      is  base  16.  Therefore,  values  are  in  the  range:
                         0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B,  C, D, E, F, 10,
                         11, ...

                      The following examples may help to explain:

                      Ex. 1 - Specify the <CONTROL><LEFTSHIFT> keys.
                         The value for <CONTROL> is       0x0004
                         The value for <LEFTSHIFT> is     0x0002
                                             ======
                         Hex addition is -------------->  0x0006

                         Therefore, the HotKey option is:

                           XA h=0006    or,
                           XA h=6       ( you may skip leading zeros).

                      Ex. 2 - Specify the <SCROLLLOCK> key.
                         The value for <SCROLLLOCK> is    0x1000
                         
                         Therefore, the HotKey option is:

                           XA h=1000

                      Ex. 3 - Specify the <CONTROL><ALT> keys.
                         The value for <CONTROL> is       0x0004
                         The value for <ALT> is           0x0008
                                                          ======
                         Hex addition is ---------------> 0x000C
                                  (hexadecimal C, not 12).

                         Therefore, the HotKey option is:

                           XA h=000C      or,
                           XA h=C  (you may skip leading zeros).

                 [-s] - this option allows you to remove the shadow effect
                      for each displayed window. The advantage to this is
                      twofold:
                         
                         1) if you don't like shadows...
                         2) reduces memory requirements.

                      To reduce memory requirements you will also have to
                      adjust the reserved memory (see [m=xxx] option).

                 [-t] - this option will NOT install NOR keep XT resident.
                      Once <ESC> is pressed in the module menu, the program
                      will return to DOS. To use XT again, you must run it
                      from the DOS command line.

                 [+p] - this option will initiate the powerfail recovery mode
                      following successful installation of XT.  XT will begin
                      sending direct commands to the CP-290 based on the
                      current state of each module in the menu.  Use the "+u"
                      option in conjunction with "+p" in order to obtain the
                      latest state of each module prior to recovery.

                 [+u] - this option uploads all event information from the
                      CP-290 during XT initialization and displays the
                      expected status of the module in the menu. The
                      advantage of this is that XT will have an accurate
                      picture of the state of each module. The disadvantage
                      is the time required to upload the data from the CP-
                      290.

                 [/?] - this option will display a short list of the options
                      currently accepted by the XT program.


       6.   Removing XT

            To remove XT from  memory, activate the  module menu by  pressing
            the HotKey combination.  When the  menu is  displayed, press  the
            letter 'R' on your keyboard.
       
            XT may  only  be removed  from  memory providing  that  no  other
            programs are using the interrupt  vectors that XT is  monitoring.
            If these vectors are not being used by another program or TSR, XT
            will restore  the  vectors to  their  original state  and  remove
            itself from  memory.   Otherwise,  XT  will remain  resident  and
            display the following message:
                    Ŀ
                    Sorry...                         
                       Can't remove TSR right now.   
                                                     
                        Press any key to continue... 
                    

            XT does not have  to be installed  and remain resident.  Instead,
            you can run  it just like  any other program  by adding the  "-t"
            option on the  command line.   This will  immediately invoke  XT,
            allowing you to  control any  module in  the menu.  When you  are
            finished, simply press  <ESC> and you  will be  returned to  DOS.
            This method of operation might be  suitable for systems that  may
            not have enough memory  to support TSR's.   One drawback is  that
            you loose the background monitoring capabilities of this program.


       7.   Powerfail Recovery

            XT knows the status of each module controlled by the CP-290 since
            it is constantly monitoring its  communications.  In some  cases,
            the actual state  of a  module may not  be the  state the  CP-290
            thinks it should be in.  That is, you may have told the light  to
            go OFF, but  it remains  ON.   One cause  of this  may be  faulty
            transmission of the command  due to noise or  weak signals.   You
            can easily  repeat  the last  known  command to  each  module  by
            pressing the letter 'P' whenever the module menu is displayed  on
            the screen.    To activate  the  module menu,  press  the  HotKey
            combination.

            When you press 'P', the highlight  bar positions itself over  the
            first module  in  the  menu  that  has  a  status  other  than  ?
            (Unknown).  The command is re-issued, and the highlight bar  goes
            to the next module with a  known status.  Finally, when the  last
            module is scanned, the highlight bar will reposition itself  over
            the original module prior to this sequence.
            
            This feature can be invoked automatically during XT  installation
            by including the [+p] and the [+u] options in the command line:

                    XT +p +u
                    XT +p +u

            The [+u] option tells XT to upload all event information from the
            CP-290.  XT then determines what  state each module should be  in
            by looking at  the event schedule  from the past  2 days.   Using
            this information, XT has a pretty good picture of what's on,  and
            what's not.

            The  [+p]  option  tells  XT  to  display  the  module  menu  and
            immediately start  the  command  reissue  procedure.    When  the
            process is complete, the menu disappears, and control is returned
            back to DOS.
            
            Using the [+p] and [+u] options is useful for forcing each module
            to its  scheduled state  after a  power  failure.   This  feature
            easily restores your home environment if the CP-290 has been off-
            line for a while.


       8.   The Initialization File (XT.INI)

            To keep XT as small as  possible, an initialization file is  used
            to assign  names and  addresses to  all  the modules.  This  file
            should only be created with a text editor or word processor  that
            saves files in  pure ASCII format.  Any extraneous characters  or
            control codes  will  cause  the XT  interpreter  to  ignore  your
            commands.
            
            You may place comments in your initialization file.  A comment is
            delineated by the pound sign  character '#'. This character  must
            appear in the first column of the line.

               # This is an example comment.

            Comments are ignored by the interpreter. Therefore, comments  can
            be placed in front of commands you do not want interpreted by  XT
            at this time.

            Blank lines  are permitted  in the  initialization file.    These
            allow you to group similar items together.

            The "DEFINE" command
            =================================

            The "define" command indicates to XT  that you are identifying  a
            module description, its address, and optionally, its state.  This
            also tells XT that  you want this module  included in the  module
            menu.

             Ŀ
              The define command has the following syntax:    
                  DEFINE module_description address [state]   
             

            XT's parser looks for  a SPACE character  to separate the  module
            description  and   its  address.   Therefore,  if   your   module
            description contains several words, you should use the underscore
            character   "_" to  separate the  words but  to keep  the  string
            contiguous. For example:

               Ex. 1: define Christmas_lights A10   <--- This is CORRECT
               Ex. 2: define Porch lights A1        <--- This is WRONG
                    define Porch_lights A1          <--- This is CORRECT

            Use the optional 'state' parameter if you wish to display a state
            for a  particular  module. For  instance,  since my  computer  is
            controlled by an Appliance module, rather than have a "?" in  the
            CMD column  of the  menu, it  would be  better to  have the  menu
            reflect the actual state of the module. Since I know the computer
            must be ON, I can force the state with the following command:

                   Ex. 3: define Den_Computer A8 ON   <--- Valid states  are: 
                          ON, OFF, DIM.

            The "WINPOS" command
            =================================

            You have the ability to position the menus (almost) any place you
            desire. If you  place a  menu or error  window too  close to  the
            right edge of your screen (so that the window does not fit),  the
            window will  wrap to  the  left side.  The  same holds  true  for
            windows positioned too close to the bottom of the screen.

            The only exception to the above limitations applies to the module
            menu.  Since it's  possible that you may  have more modules  than
            can fit on  a screen, the  module menu will  prevent itself  from
            exceeding the bottom of the screen.  It will allow you to  scroll
            through the menu using the cursor keys described earlier.
            There are three distinct windows in XT - two are menus, the other
            is a  message  window for  displaying  errors or  warnings.  When
            assigning new  locations  for  the  windows,  use  the  following
            keywords to identify the window:

               WINPOS1 - the module menu
               WINPOS2 - the command menu
               WINPOS3 - the message window (errors or warnings)

                 Ŀ
                  The WINPOS command has the following syntax:  
                      WINPOS? ROW y COL x                       
                 
               
               
            Row and Column  coordinates are  determined from  the upper  left
            hand  corner  of  the  screen  starting  at  0,  0.  The  default
            coordinates for each window in XT are as follows:

               Module menu:     WINPOS1 ROW 1 COL 30
               Command menu:  WINPOS2 ROW 3 COL 2
               Error messages:  WINPOS3 ROW 18 COL 40


            The "COLOR" command
            =================================

            The XT utility uses black and  white characters so that its  menu
            displays will initially work on all  types of video hardware.  If
            you have a  color system, you  may alter these  defaults to  suit
            your own preferences.  This can be  accomplished using the  COLOR
            command in the initialization file.

            When assigning  new  color  schemes  for  the  windows,  use  the
            following keywords to identify the window:

               COLOR1 - the module menu
               COLOR2 - the command menu
               COLOR3 - the message window (errors or warnings)

                 Ŀ
                  The COLOR command has the following syntax:     
                      COLOR? foreground_color ON background_color 
                 

            See Table  3 -  Color  Choices for  a  list of  acceptable  color
            definitions that are recognized by the XT parser.
           Ŀ
              Foreground Colors        Background Colors  
           Ĵ
                   BLACK                    BLACK         
                   BLUE                     BLUE          
                   GREEN                    GREEN         
                   CYAN                     CYAN          
                   RED                      RED           
                   MAGENTA                  MAGENTA       
                   BROWN                    BROWN         
                   LIGHTGRAY                LIGHTGRAY     
                   DARKGRAY                               
                   LIGHTBLUE                              
                   LIGHTGREEN                             
                   LIGHTCYAN                              
                   LIGHTRED                               
                   LIGHTMAGENTA                           
                   YELLOW                                 
                   WHITE                                  
           
                        Table 3 - Color Choices



            The default colors for each window in XT are as follows:

               Module menu:     COLOR1 WHITE ON BLACK
               Command menu:    COLOR2 BLACK ON LIGHTGRAY
               Error messages:  COLOR3 WHITE ON BLACK

            When you  assign  colors  to a  window,  you  are  selecting  the
            attributes for the window in general. For instance, in the module
            menu you are selecting the  foreground and background colors  for
            all items in the list. The color scheme for the highlight  cursor
            is also taken from  this choice, usually  the inverse colors  you
            selected for the main selections.


            The "UPLOAD" command
            =================================

            Placing an UPLOAD command in the initialization file will perform
            a scan of all events stored in the CP-290 so that the past status
            of each module can be determined. XT will look at today's  events
            as well  as  yesterdays  events  for  each  module  in  order  to
            accurately  calculate  its  status.   If  there  is  not   enough
            information, a '?' will appear in the "CMD" column of the  module
            menu. Also, if an event is scheduled to be triggered in  SECURITY
            (random) mode within the current hour,  a '?'  will be  displayed
            in the "CMD" column.

            A "+u" in the command line is similar to placing "UPLOAD" in  the
            initialization file. The choice is yours.


            The "HOTKEY" command
            =================================
            
            You may select your own "HotKey" combination from the list below:
            
               RSHIFT, LSHIFT, ALT, CTRL, CONTROL,
               SCROLLLOCK, NUMLOCK, CAPSLOCK, INSERT

            Multiple keys are allowed. The default HotKey sequence would be
            entered as:

               HOTKEY CONTROL LSHIFT

            When you place the HOTKEY command in the XT.INI file, it will
            override any selection you may have entered on the command line
            (the      +h=xxxx command).

               Ŀ
                The HOTKEY command has the following syntax:  
                    HOTKEY key1 key2 ...                      
               


       9.   XTS - DOS X10 Status Interface

            One of the advantages of a memory-resident program such as XT  is
            that it's always  monitoring the communications  port for  CP-290
            activity.  Every command issued by the CP-290, or via XA (an  X10
            Command Interpreter - see  next chapter), or  by XT, is  captured
            and stored in  XT's internal database  of 256 modules.   To  gain
            access to these states, use the  utility program XTS.EXE to  view
            the current condition of each module.

            REGISTERED USERS:  In addition,  XTS will  also return  a  unique
            value which may be queried using the DOS "errorlevel"  statement.
            You can  write special  batch files  which  operate in  a  unique
            fashion based on the state of a specific module.
            
            XTS.EXE should be stored in the same directory as XT.EXE.   Since
            XTS communicates  directly  with XT,  you  must already  have  XT
            (Version    2.0    or    newer)    installed.        You     will
            receive an error  message if either  XT is not  installed, or  an
            earlier version  of XT  which does  not support  XTS is  running.
            Otherwise a  copyright  message  and  one  of  several  different
            screens will appear depending on  the command line arguments  you
            passed to XTS.

           Ŀ
              XTS has the following syntax:               
                                                          
                XTS [+m] [A...P] [A1...P16] [/?]          
           

            Type "XTS /?" at the DOS prompt to get a summary of the various
            options and display modes supported by XTS.

            The first screen we will display is the system-wide view. Just
            type XTS at the DOS prompt.

    XTS - V2.xx - Copyright 1994 by Bruce Christensen.  All Rights Reserved.
    Module Status may be any of the following: On, Off, Dim, or Unknown (). 
    Ŀ
       1   2   3   4    5   6   7   8    9  10  11  12   13  14  15  16 
    Ĵ
  A  Off    Off  On     Dim     On                            
  B      On                                               
  C   On                                                  
  D                                                      
    Ĵ
  E                                     Dim               
  F                                                      
  G                                                      
  H  Dim Dim                                               
    Ĵ
  I                                                      
  J                                                      
  K                                                      
  L                                                      
    Ĵ
  M                                                      
  N                                                      
  O                                                      
  P                                                      
    

            You will see the XTS Version, Copyright notice, and module status
            message. Next, a table of each module and its state is displayed.
            A module has 4 possible states - On, Off, Dim, or Unknown (shown
            using a "" character).  The state of each module is determined
            when XT is first installed when the "+u" appears as a command
            line argument, and when the CP-290 reports X10 activity either
            via a key press or by a scheduled event.  It is recommended that
            you always invoke XT with the "+u" option so that the states of
            scheduled modules are displayed properly.

            If you type:
                 XTS +m

            you instruct XTS to "monitor" CP-290 activity - the states are
            continuously updated on the screen.  Try pressing one of the 8
            rocker switches on your CP-290. You should see its state
            reflected on the screen.  Note the flashing arrows at the bottom
            of the screen.  To exit monitor mode, simply press any key.  Note
            that XTS will not return an "errorlevel" value when all 256
            modules are displayed.

            You can also display the states  of a selected housecode. To  see
            the current status of all modules with a housecode of C, type:

                 XTS  C

            XTS will display the following for housecode C only:

            
    XTS - V2.xx - Copyright 1994 by Bruce Christensen.  All Rights Reserved.
    Module Status may be any of the following: On, Off, Dim, or Unknown (). 
    Ŀ
       1   2   3   4    5   6   7   8    9  10  11  12   13  14  15  16 
    Ĵ
  C   On                                                  
    

            You may  also  continuously  monitor the  states  of  a  selected
            housecode by typing:

                 XTS  C  +m

           
            !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
                The following  features of  XTS are  enabled only  
                to  registered users.
            !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

            In addition, XTS returns state information which may be examined
            with the DOS "errorlevel" statement.  So, for the example
            described above, if you were to request status information for
            house code C, you would receive:

    XTS - V2.xx - Copyright 1994 by Bruce Christensen.  All Rights Reserved.
    Module Status may be any of the following: On, Off, Dim, or Unknown (). 
    Ŀ
       1   2   3   4    5   6   7   8    9  10  11  12   13  14  15  16 
    Ĵ
  C   On                                                  
    

    Returning House C status = 8000 hex.


            It's easiest to think of the  return value in hexadecimal  format
            (or base  16).    The status  of  Unit  1 will  occupy  the  most
            significant bit of  the returned code,  Unit 16  will occupy  the
            least significant bit of the returned  code.  Any module that  is
            ON or DIM will be  have a '1' in  its designated position of  the
            returned errorlevel.  Any module that is OFF or UNKNOWN will have
            a '0'  in its  designated position  of the  returned  errorlevel.
            Refer to Section: 8. The Initialization File (XT.INI) for a brief
            overview of hexadecimal notation,  or   consult a reference  book
            on programming.

            Finally, you can request XTS to return the current state of a
            single module by typing its designated house-unit code.  For
            instance, to find out what state module E12 is in:
                 XTS  E12

                 Status of Module E12 is Dim. Returning 4.

            The "errorlevel" codes returned for individual modules are listed
            in the following table.

                        "errorlevel"   Description
                         ===========   ===================
                              0        Off (All Units Of
                              1        On (All Lights On
                              2        On (Normal On iss
                              3        Off (Normal Off i
                              4        Dim
                              5        Dim
                              6        Off (All Lights O
                              7        Unknown (?)
                             255       XT not installed/

                          Table 4 - "errorlevel" codes


         Using "errorlevel"
         ====================

            The following examples show how to use the returned "errorlevel"
            in your batch files.

            For more information about "errorlevel" checking, consult your
            DOS User's Guide and Reference manual.

            These examples use a program called XA (available from this
            author - see Section 11) to send direct commands to the CP-290.

            Ex. 1 -  Toggle a light (P1) from On to Off, Off to On, etc.
                 See sample batch file P1TOGGLE.BAT.

                 XTS P1
                 if errorlevel 7 goto UNKNOWN
                 if errorlevel 6 goto ON
                 if errorlevel 5 goto OFF
                 if errorlevel 4 goto OFF
                 if errorlevel 3 goto ON
                 if errorlevel 2 goto OFF
                 if errorlevel 1 goto OFF
                 if errorlevel 0 goto ON
                 :OFF
                 XA "P1 OFF"
                 GOTO END
                 :ON
                 XA "P1 ON"
                 :UNKNOWN
                 :END

       10.   Troubleshooting

            A) Conflict with XA.EXE (X10 Command Interpreter)
                 XA.EXE is a program written by this author that allows
                 sending X10 commands from the DOS prompt, from batch files,
                 or series of commands and event information to be downloaded
                 from a file. XA - Version 2.xx is fully compatible with XT.
                 Both programs have been designed to share CP-290 information
                 with each other. If you don't have the latest version of XA,
                 contact the author at the address listed at the end of this
                 documentation.

            B) Conflicts with other TSRs
                 This program has attempted to follow the rules that all
                 "good neighbor" TSRs should follow. However, several
                 conflicts may arise with other TSRs loaded in your system.
                 If you experience problems with your other TSRs after
                 installing this one, try changing the order in which the
                 TSRs were loaded. This may alleviate some problems.

            C) IRQ - Which one is it?
                 If you don't know what IRQ level your serial port is
                 configured for, you have (2) alternatives:
                 
                 1) Run FINDX10T.EXE which was supplied as a utility to XT.
                    This program will search each COM port in your system
                    noting the IRQ settings.  Then each COM port will be
                    queried to determine if the CP-290 is connected.  If a
                    CP-290 is found, you will be notified of the parameters.
                    Use these parameters when installing XT.

                 2) Open your computer and look at the DIP switch settings on
                    the serial card (or motherboard). Read the instructions
                    that came with your computer equipment if you've never
                    done this before.

                 3) Take a wild, stomping guess at the IRQ level. Invoke the
                    program by trying every IRQ level between 2 and 7 (on XT
                    machines), and between 2 and 15 (on AT machines). Call up
                    a menu (by using the HotKey) and issue a command to a
                    module. If you see the LED on the top of the CP-290 go
                    on, then you've just found the right IRQ level. The
                    status of the command should be reflected in the module
                    menu.

            D) Optimizing memory usage
                 Currently, there is no support for XT to automatically guess
                 the correct amount of ram to reserve for its own use. This
                 task is left up to you. One way to conserve memory is to use
                 the "-s" option on the XT installation command line.


       11.  Other Products

            XA - X10 Command Interpreter
            =============================

            You are probably familiar with the menu-driven program  (X10.EXE)
            supplied with your CP-290.   The software  approach used in  that
            implementation is great  for beginners  since it  offers a  fool-
            proof method of organizing  commands and events.   Unfortunately,
            that method also  becomes a bottle-neck  every time  you want  to
            activate a  single module  via your  computer.   What's worse  is
            trying to maintain a schedule of lighting events that vary due to
            seasonal  changes.    XA  is  a  shareware  package  designed  to
            alleviate many of the frustrations you may have experienced  with
            the X10-supplied  software.    In  addition,  XA  makes  schedule
            maintenance a  breeze.   Soon, your  computer will  automatically
            handle the monotony of CP-290 scheduling for you.

            What is XA?

            The XA program  is an  interpreter.   XA translates  English-like
            sentences into commands that are understood  by the CP-290.   For
            instance, you can quickly tell XA to turn on a set of lights with
            the  following DOS command:

                 XA "PORCH ON"

            XA knows that the PORCH lights  are addressed at HOUSE A UNIT  9,
            or whatever  address you  choose (you  define modules  and  their
            addresses in a file  called XA.INI).   Since XA accepts  commands
            from  the DOS prompt, you can place statements like these in your
            batch  files  too.    For  instance,  I  use  an   X10-controlled
            nightlight near our downstairs phone to warn other family members
            if I'm "on-line"  with a remote  computer or BBS.   The light  is
            turned on prior to the session, and turned off when I'm finished:

                 XA "WARNING_LAMP ON"
                 TELIX (or ProComm) statements here
                 XA "WARNING_LAMP OFF"

            XA will also process X10 commands and events contained in a file.
            This is ideal for maintaining the CP-290's event schedule, or for
            running a Christmas "lightshow".   Simply tell  XA which file  to
            read, and XA  does all the  work.  For  instance, to download  my
            event schedule to the CP-290, type:

                 XA f=XA.CMD

            XA calculates sunrise and sunset times based on your latitude and
            longitude, and automatically compensates for any Daylight Savings
            changes.  XA can be programmed to handle events for special dates
            that  may be weeks, months, or years in the future.  Best of all,
            XA can automatically update the  CP-290 on a once-per-week  basis
            without any intervention  on your  part (an  Appliance module  is
            needed to control  your PC).

            XA can be found on many BBS's, including those listed in the
            Future Updates section listed later in this document.  Look for
            X10XA202.ZIP (the version number is the last 3 digits of the ZIP
            filename).

            FX - TW-523 Command Interpreter
            ===============================

            FX.EXE is a  DOS-based X10  command interpreter  for the  TW-523.
            Valid X10  commands are ON,  OFF, DIM and BRIGHT. These  commands
            can be input from the DOS command line, or they may be read  from
            a "script" file.

            A special  feature of  FX is  its  ability to  send  SIMULTANEOUS
            Bright and Dim commands to multiple X10 modules. This allows  you
            to create some very interesting lighting effects. My primary  use
            for this program is for Halloween and Christmas lighting.

            FX communicates with the TW-523 via your computers parallel  port
            (LPT1...LPT3).  Complete instructions for building the  necessary
            connectors are included in the documentation.
            
            FX can be  found on  many BBS's,  including those  listed in  the
            Future Updates section listed later in  this document.  Look  for
            X10FX100.ZIP (the version number is the last 3 digits of the  ZIP
            filename).



       12.  Warranty, Copyright, and Registration Policy

            Limited Warranty
            ----------------
            THIS PRODUCT IS PROVIDED  "AS IS" WITHOUT  WARRANTY OF ANY  KIND.
            THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE  PROGRAM
            IS ASSUMED BY YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU  (AND
            NOT  THE  AUTHOR)  ASSUME  THE  ENTIRE  COST  OF  ALL   NECESSARY
            SERVICING, REPAIR OR  CORRECTION.  FURTHER,  THE AUTHOR DOES  NOT
            WARRANT, GUARANTEE, OR MAKE REPRESENTATIONS REGARDING THE USE OF,
            OR  THE  RESULTS  OF  THE  USE  OF  THIS  PROGRAM  IN  TERMS   OF
            CORRECTNESS, ACCURACY,  RELIABILITY, CURRENTNESS,  OR  OTHERWISE;
            AND YOU RELY ON THE PROGRAM  AND IT'S RESULTS SOLELY AT YOUR  OWN
            RISK.  THE AUTHOR CANNOT ACCEPT RESPONSIBILITY FOR SYSTEM DAMAGE,
            LOSS  OF   PROFIT,  OR   ANY   OTHER  SPECIAL,   INCIDENTAL,   OR
            CONSEQUENTIAL DAMAGE RESULTING FROM THE  USE OR INABILITY TO  USE
            THIS PRODUCT.

            The author DOES warrant to the original licensee of a  REGISTERED
            product that the program disk(s) on which the program is recorded
            be free from  defects in materials  and workmanship under  normal
            use and service for a period of ninety (90) days from the date of
            delivery. The author's entire liability and your exclusive remedy
            shall be  replacement  of  the  disk  not  meeting  this  Limited
            Warranty.

            Copyright
            ---------------
            The XT  software  package, its  utilities  and this  document  is
            Copyright  (C)  1991-1994  by   Bruce  Christensen.  All   rights
            reserved.
            Any specific hardware/software  names used in  this document  are
            trademarks of specific manufacturers.
            Regardless of the method  of marketing, XT is  not in the  public
            domain. It is  copyrighted by Bruce  Christensen. All rights  are
            reserved. Copying, duplicating, selling or otherwise distributing
            the REGISTERED version of this product is a violation of the Law.
            However, we grant you  the right, in fact  encourage you to  make
            and distribute as many copies of  the SHAREWARE version of XT  as
            you wish,  using  any acceptable  medium  of exchange,  with  the
            following provisions:

               Please feel free to distribute this SHAREWARE version as often
               as you like, to any interested parties.

               Please do  not  distribute this  program  without all  of  its
               original related files, addendum files, documentation and this
               notice.

               Please do  not  alter  the program  or  documentation  in  any
               manner.

               DISTRIBUTION of the REGISTERED USER version of the program  is
               in violation of license agreements and copyright Law!

            Registration
            ------------
            If you are still using XT beyond the initial 45-day trial period,
            you must register this software with  the author. Please use  the
            included  registration  form  (REGISTER.TXT)   and  send  a   $25
            registration fee to  the address below.   Your registration  will
            entitle you  to the  latest full-featured  registered version  of
            this program, and a printed copy of this user manual.

            The registered version of XT and  its utilities are licensed  for
            individual personal use for an unlimited time.

            This is a "living" program - new features are added from time  to
            time.  Your input is the basis for future improvements.  Send any
            comments to the  address given below,  or you may  contact me  on
            CompuServe, Prodigy,  America On-Line, or Internet.

                 Bruce Christensen
                 6594 Hudson Avenue
                 Mentor, OH.  44060-4545
                 CompuServe: 73201,1531
                 Prodigy ID:  MHNC39A
                 America On-Line: AuggieBen
                 Internet: auggieben@aol.com

            Future Updates
            ---------------
            Future updates  of  the shareware  version  XT can  be  found  on
            CompuServe, America On-Line,  as well as  the following BBS's  as
            they become available. The  current version of  XT will be  named
            "X10XT200.ZIP". The last 3 digits  of the filename will  indicate
            the revision level (in this case, 2.00).

            MicroSellar BBS offers limited, free access to validated callers.
            Their number is:  (201)-239-1151 v.32bis,  or (201)-239-1331  HST
            16.8/v.32 terbo.

            Dave Mabry, a  sysop of  the "Going  Down BBS"  has offered  free
            access to his BBS to anyone interested in X10 - Home  Automation.
            Users can gain immediate access to  the home automation files  by
            logging on with a userid and  password of "X10". This BBS can  be
            reached at:  1-(810)-576-7882.

            Baran-Harper, a Canadian home automation mail order outfit,  also
            runs a very popular BBS. There  are many programs for the  CP-290
            for PC's, Mac's, and other computers.  The Baran-Harper BBS is  a
            free BBS, their number is: 1-(905)-471-6776, or 1-(905)-471-9574.
            Circuit  Cellar   Inc.  publishes   "The  Computer   Applications
            Journal", and runs occasional articles on X10.  Their BBS  number
            is 1-(203)-871-1988.

            Home  Automation  Laboratories  (HAL)  has  the  best  mail-order
            catalog for home automation  equipment. Call 1-(800)-YEL-4HAL  to
            request a catalog.  HAL's BBS # is 1-(404)-319-6227.

