O ********************** Start of X10_MONITOR_DOC.TXT ***************************   3 X10_MONITOR and X10_TIMER Documentation Version 1.0    May 15, 2003 Jason Brady  Lynnwood, WA USA     Contents   1. Overview  2. Installation  3. X10_MONITOR Operation 4. X10_TIMER Operation   Appendix A   Monitor Commands  Appendix B   Database Design1 Appendix C   Using a Terminal Server and LAT Port     O ===============================================================================     1. Overview  N     X10_MONITOR functions as a message switch application to facilitate inter-N     action between an X-10 controller (or other device employing a serial portE     interface) and a user interface or optional component X10_TIMER.    "                     User Interface                           | 7     +------------+        V             +-------------+ F     |            |-> Input mailbox  --> |             | <---> TerminalD     | X10_TIMER  |                      | X10_MONITOR |       SerialB     |  Process   |                      |   Process   |       PortF     | (optional) |<- Output mailbox <-- |             |      (Built-inE     +------------+                      +-------------+       or LAT)            ^ "           |           +----------+"           |           |          |8           +---------->| X10MONDB |<-----> User Interface(                       | Database |      "                       |(optional)|"                       +----------+  M     The user interface sends and receives command strings through two logical K     mailbox devices.  User interfaces are typically an interactive program; O     however, any type of interface or program with mailbox I/O capability will  L     work (another detached process, for example).  An interface need not be O     active for the Monitor to  function.  Once started, the Monitor runs until  9     explicitly shut down or experiences a critical error.   M     User interfaces are responsible for composing Monitor and X-10 controller M     device command strings.  The interface must have the ability to interpret M     and respond to both unsolicited and anticipated messages from the Monitor      and X-10 controller.  L     Optional component X10_TIMER manages timed events such as turning a lampO     module on and off at a pre-determined date and time.  Events, module infor- M     mation, etc. are stored in an Oracle Rdb relational database.  X10_TIMER  O     queries the database at a user-defined interval and forwards selected event /     command strings to X10_MONITOR for routing.   I     X10_MONITOR can easily be adapted for other uses such as monitoring a M     home weather station, alarm system, robotic device, etc.  As designed the I     program can handle intermittent data but could be altered to handle a N     continuous stream.  X10_TIMER can be modified to make use of files insteadM     of the Rdb DBMS.  A Web page, X-window, etc. application could be written M     to interact with the Monitor and database.  There are many possibilities!     O ===============================================================================     2. Installation  O     Follow these steps to install X10_MONITOR and optional component X10_TIMER. M     If you are installing the Timer, Oracle Rdb must already be installed and      functional.   
  __ STEP 1
     ------H     Create an application directory and copy the package contents to it.  %          $CREATE/DIR disk:[directory]   1          $COPY/LOG [location]*.* disk:[directory] 5          $COPY/LOG [location.SRC]*.* disk:[directory]     
  __ STEP 2	     ----- G     Define logical names (also place these commands in SYLOGICALS.COM).   3          $DEFINE/SYSTEM X10MON_DIR disk:[directory] 0          $DEFINE/SYSTEM X10MON_DEV [device name]      __ STEP 2a (optional)     ------------------H     Create the X10_TIMER database directory and define its logical name./     Place the define command in SYLOGICALS.COM.   %          $CREATE/DIR disk:[directory] 3          $DEFINE/SYSTEM X10MON_DBD disk:[directory]     
  __ STEP 3
     ------%     Set default to the new directory.             $SET DEF X10MON_DIR      __ STEP 4 (optional)      ----------------- 8     Compile X10_MONITOR source modules on your platform.  1          $CC/LIST X10_MONITOR.C,X10MON_RECV_AST.C   9          $COBOL/ANSI/LIST X10MON_SEND.COB,X10MON_RECV.COB       __ STEP 4a (optional)     ------------------6     Compile X10_TIMER source modules on your platform.            $CC/LIST X10_TIMER_AST   %          $COBOL/ANSI BUILD_EVENT_FILE   +          $SCOB :== $SQL$PRE/COBOL/ANSI/LIST )          $SCOB X10_TIMER,GEN_TIMER_EVENTS       __ STEP 5 (if STEP 4 skipped)     --------------------------/     Rename and link X10_MONITOR object modules:   4          $RENAME X10_MONITOR_AXP.OBJ X10_MONITOR.OBJ4          $RENAME X10MON_SEND_AXP.OBJ X10MON_SEND.OBJ4          $RENAME X10MON_RECV_AXP.OBJ X10MON_RECV.OBJ<          $RENAME X10MON_RECV_AST_AXP.OBJ X10MON_RECV_AST.OBJ            $LINK X10_MONITOR          $LINK X10MON_SEND.          $LINK X10MON_RECV_AXP,X10MON_RECV_AST       __ STEP 5a (if STEP 4a skipped)      -----------------------------     Rename and link X10_TIMER object modules.   0          $RENAME X10_TIMER_AXP.OBJ X10_TIMER.OBJ8          $RENAME X10_TIMER_AST_AXP.OBJ X10_TIMER_AST.OBJ>          $RENAME BUILD_EVENT_FILE_AXP.OBJ BUILD_EVENT_FILE.OBJ>          $RENAME GEN_TIMER_EVENTS_AXP.OBJ GEN_TIMER_EVENTS.OBJ  ?          $LINK X10_TIMER,X10_TIMER_AST,SYS$LIBRARY:SQL$USER/LIB           $LINK BUILD_EVENT_FILE <          $LINK GEN_TIMER_EVENTS_AXP,SYS$LIBRARY:SQL$USER/LIB    
  __ STEP 6
     ------H     Determine which terminal serial port is to be used.  Attach the X-10     controller and power it on.   J     Note:  Terminal device setup is covered in Steps 6a, 7 and Appendix C.      __ STEP 6a (Optional)     ------------------I     If you are using a terminal server port, enter the appropriate server J     and LAT$SYSTARTUP / LATCP commands.  See Appendix C - Using a Terminal7     Server and LAT Port for configuration instructions.     
  __ STEP 7
     ------J     Customize the startup and shutdown command procedures.  The proceduresI     assume that X10_TIMER is included.  Timer-related code can be commen- G     ted out or deleted if you only want X10_MONITOR to run.  Update the B     terminal set-up command string if necessary (i.e., baud rate).  !          $EDIT X10MON_STARTUP.COM "          $EDIT X10MON_SHUTDOWN.COM      __ STEP 7a (optional)     ------------------H     Modify your site-specific startup and shutdown procedures to include/     X10MON_STARTUP.COM and X10MON_SHUTDOWN.COM.   I          - The startup procedure should run after LATACP, RDM_MONITOR and K            other system processes are running and system-wide logical names F            have been defined.  You can submit the procedure to a batch            queue.   J          - The shutdown procedure should run before LATACP and RDM_MONITOR            are terminated.  
  __ STEP 8
     ------M     To configure the terminal port and start the Monitor and Timer processes, *     execute the startup command procedure.  (          $@X10MON_DIR:X10MON_STARTUP.COM.       or $SUBMIT X10MON_DIR:X10MON_STARTUP.COM          $SHOW SYSTEM   J     After the procedure completes, both Monitor and Timer processes should/     be running and in HIB (hibernation) status.      
  __ STEP 9
     ------=     Test the Monitor (Timer testing is covered in section 4).   C          From one interactive session:  $RUN X10MON_DIR:X10MON_SEND H          From a second interactive session:  $RUN X10MON_DIR:X10MON_RECV  H     Enter various commands from the X10MON_SEND menu.  The RECV program J     hibernates until the Monitor writes a message to the output mailbox atK     which point it awakens and displays the message in its entirety.  If an I     X-10 controller device is attached, unsolicited messages it generates J     should be displayed.  Note that the RECV program is terminated at the I     same time as the Monitor process (by input mailbox command 'X' being  H     forwarded to the output mailbox just before X10_MONITOR terminates).      __ STEP 10      ------- J     Shut the Monitor down by sending an 'X' command from X10MON_SEND. ThisI     also terminates X10MON_RECV.  Review the log file contents--files are G     closed and accessible for viewing upon Monitor program termination.   )          $@X10MON_DIR:X10MON_SHUTDOWN.COM .          $TYPE/PAGE X10MON_DIR:X10_MONITOR.LOG;          $TYPE/PAGE X10MON_DIR:X10_MONITOR.ERR (if present)     O ===============================================================================    3.0 X10_MONITOR OPERATION   H     X10_MONITOR runs in the context of a detached process and hibernates
     until:  @        a) An input mailbox message is received.  Note that there7           can be multiple writers to the input mailbox. B        b) An X-10 controller message is received (data written to >           terminal port, also called an "unsolicited" message)  3     At this point, the Monitor operates as follows:   ?        - Input mailbox commands are interpreted and appropriate B          action is taken.  If the command is destined for the X-10A          controller, the Monitor command code is stripped and the ?          remaining string text written to the terminal port.  A A          copy of the input mailbox command string is forwarded to ?          the output mailbox (unless output mailbox messaging is 5          disabled).  There are five Monitor commands:   :             1)  Enable/disable Monitor message logging (V);             2)  Enable/disable output mailbox messaging (W) 1             3)  Shut down the Monitor process (X) =             4)  Copy message from input to output mailbox (Y) 8             5)  Send message string to terminal port (Z)  <        - Unsolicited data received from the terminal port isA          appended to command code 'M' and forwarded to the output ?          mailbox (unless output mailbox messaging is disabled). @          The Monitor is designed to handle intermittent data and=          not a continuous stream.  See program code comments.   ?        - A record of timestamped message activity is maintained >          in a log file.  Additional items are written if debug@          mode enabled (source code variable set before compile).1          Monitor message logging can be disabled.     O ===============================================================================    4.0  X10_TIMER Operation  L      In order to prepare the Timer for operation database tables X10_Module,G      Module_Status, Timer_Events and App_Parms must first be populated.   L      App_Parms, X10_Module and Module_Status are populated by the SQL scriptJ      POPULATE_X10MONDB.SQL.  Edit the script if you want to customize the D      number of modules, their definition and application parameters.  $          $EDIT POPULATE_X10MONDB.SQL  I      A user interface program could also be written to manage table rows.   M      Be sure that for every module that is defined in X10_Module a correspon- J      ding row is inserted into Module_Status to satisfy foreign key const-N      raints.  Also, in order to store Type B events in Timer_Events, a "dummy"N      module row must exist in X10_Module:  House Code Z, Unit Code 0. Finally,?      set application parameters in table App_Parms (see below).   K      To define timer events, first build file TIMER_EVENTS.DAT.  Use a text @      editor or build the file with program BUILD_EVENT_FILE.EXE.           $EDIT TIMER_EVENTS.DAT             or(         $RUN X10MON_DIR:BUILD_EVENT_FILE  (      There are two categories of events.  .         1 - Specific date and time.  Examples:  9             Turn on unit A-12 at 14:37:03 on May 15, 2003 E             Send LynX-10 status request command (S3) on June 12, 2003                at 15:00:00   <         2 - Recurring on a specific day per week.  Examples:  5             Turn off unit J-7 each Monday at 06:30:00 H             Send message to the output mailbox each Saturday at 12:01:00  K      There are two types of events.  Either event can be scheduled to occur K      at a specific date and time (Category 1) or recur weekly (Category 2).   C         A - LynX-10 command for controlling X-10 devices.  Example:   /             N001 - Turn on unit 2, house code A   %         B - Other command.  Examples:   2             X    - Shut the Monitor and Timer down1             ZS3  - Send status request to LynX-10 0             ZR   - Send reset command to LynX-106             Yxxx - Route message xxx to output mailbox  H      The sample event file contains examples of all event categories andG      types as well as comment lines.  It shows which events should fail G      edits and those that should pass and end up as scheduled events in D      the database table if it falls within the generated date range.  I      After TIMER_EVENTS.DAT is populated, run the event generator program F      GEN_TIMER_EVENTS.  This program places an exclusive lock on tableF      Timer_Events so the Timer process should be shut down beforehand.  (         $RUN X10MON_DIR:GEN_TIMER_EVENTS  K      This program edits the event file, builds internal tables and inserts  K      rows into database table Timer_Events for every event file record that ;      passed edits.  See GEN_TIMER_EVENTS_SAMPLE_OUTPUT.TXT.   L      GEN_TIMER_EVENTS uses the event file entries to inserts rows into tableL      Timer_Events by date.  A user-specified number of days' worth of eventsL      is generated.  The table can be queried by date and time to view eventsJ      occurring on a particular date.  See program code for further detailsE      on how the event file entries are converted to scheduled events.        M      Several user-defined application parameters are stored in database table -      App_Parms.  They are indexed by App_Num:   J         1 - X10_TIMER query interval (how frequently the Timer awakens andL             queries Timer_Events for events scheduled between the last wake-K             up date/time and current system date/time).  Delta time format. L             If the row doesn't exist or contains an invalid value, X10_TIMER)             uses a default of 15 minutes.   H         2 - GEN_TIMER_EVENTS report mode setting.  Y = Full report mode,H             N = minimal report mode.  Full report mode is the default ifG             the row is missing or an invalid code (not N or Y) is used.   K         3 - GEN_TIMER_EVENTS maximum number of events per category setting. L             Regulates the number of category 1 and 2 events allowed per run.L             If the row is missing or exceeds 500, the default is set to 500.  F         4 - GEN_TIMER_EVENTS number of days to generate.  If the tableJ             value is missing or invalid then a default of 45 days is used.    O ===============================================================================    Appendix A - Monitor Commands  -----------------------------   I   X10_MONITOR responds to the following commands written to input mailbox I   X10MON_MSGIN.  A copy of received commands are forwarded to the output  =   mailbox (except when output mailbox messaging is disabled).   G     1)  Enable/Disable Monitor message logging.  If logging is enabled, M         message activity is written to file X10_MONITOR.LOG.  Output messages J         are suppressed if logging is disabled.  Program X10_TIMER responds<         in kind to this command and ceases activity logging.   &           V0 - Disable message logging%           V1 - Enable message logging   J     2)  Enable/Disable output mailbox messaging.  If disabled, no messagesF         are forwarded to output mailbox X10MON_MSGOUT.  The command isJ         forwarded to the output mailbox just before disabling takes place.M         Program X10_TIMER responds to this command by instructing the Monitor H         to re-enable this function because output mailbox messaging must4         always be enabled when the Timer is running.  /           W0 - Disable output mailbox messaging .           W1 - Enable output mailbox messaging  J     3)  Shut down the Monitor program.  When received, the Monitor processH         terminates.  Program X10_TIMER responds in kind to this command.  ;           X - Shut the Monitor (and Timer) process(es) down   K     4)  Copy input mailbox message directly to the output mailbox.  This isdO         used primarily for testing.  When this command is received, the MonitorTO         takes no action other than to route the message directly to the output BQ         mailbox.  The command is ignored if output mailbox messaging is disabled.=  .           Y + up to 29 alphanumeric characters  N     5)  Send a string of characters to the terminal device port.  Used to send/         command codes to the LynX10 controller.n  .           Z + up to 29 alphanumeric characters  O   Additionally, the Monitor writes an additional "command" string to the outputI   mailbox when  N     6)  an unsolicited message/data is received from the terminal device.  ForM         example, the LynX10's response to on/off commands is an asterisk (*). L         The LynX-10 detects codes sent by another X-10 controller and passesP         them to the terminal port. The Monitor forwards this type of informationO         to the output mailbox if output mailbox messaging is enabled; otherwise          it is ignored.  .           M + up to 29 alphanumeric characters    O ===============================================================================   % Appendix B - X10MONDB Database DesignI% -------------------------------------a  M   There are five tables in the X10MONDB Oracle Rdb database.  No provision is+N   made to store historical data in order to simplify the database design.  AllI   table primary keys are indexed (unique--no duplicates).  Two non-uniquerJ   indexes are defined for table TIMER_EVENTS on attributes Event_Date and M   Event_Time to improve event query efficiency.  Refer to SQL modules CREATE_dK   X10MONDB.SQL and POPULATE_X10MONDB.SQL for details.  Additionally, table  K   usage is documented in programs that interact with the database (*.SCO).       Database table structure:l  8     APP_PARMS                            MONITOR_MESSAGEJ   +-------------------------+          +---------------------------------+J   | Parm_Num  Smallint (PK) |          | System_Name   Char(16) (PK)     |J   |-------------------------|          | Time_Stamp    Timestamp(2) (PK) |J   | Parm_Len  Smallint      |          |---------------------------------|J   | Parm_Text Char(255)     |          | Source_Name   Char(16)          |J   +-------------------------+          | Message_Text  Char(50)          |J                                        +---------------------------------+    :     X10_MODULE                               MODULE_STATUSM   +--------------------------------+       +--------------------------------+iM   | House_Code       Char(1)  (PK) |  1:1  | House_Code (FK)  Char(1)  (PK) |bM   | Unit_Code        Smallint (PK) |-------| Unit_Code  (FK)  Smallint (PK) |kM   |--------------------------------|       |--------------------------------|aM   | Type_Code        Char(1)       |       | Status_Date      Date ANSI     |rM   | Description_Text Char(50)      |       | Status_Time      Time(2)       |=M   +--------------------------------+       | Status_Code      Char(1)       |nM                   |                        +--------------------------------+                    |                    | 1:many                   |      TIMER_EVENTS  |-$   +--------------------------------+$   | Timer_Event_ID   Smallint (PK) |$   |--------------------------------|$   | Event_Date       Date ANSI     |$   | Event_Time       Time          |$   | Event_Code       Char(1)       |$   | House_Code (FK)  Char(1)       |$   | Unit_Code  (FK)  Smallint      |$   | LynX10_Command   Char(4)       |$   | Other_Command    Char(50)      |$   +--------------------------------+     Table descriptions:_  K      1)  APP_PARMS         Used to store application parameters such as the K                            number of days to generate for GEN_TIMER_EVENTS.IK                            Discrete table; no foreign key constraints.  The 3                            primary key is Parm_Num.-  O      2)  MONITOR_MESSAGE   Supports message logging function by storing a copy  P                            of message traffic from X10_MONITOR's output mailbox.P                            Discrete table without foreign key constraints.  The N                            compound primary key is System_Name and Time_Stamp.  K      3)  X10_MODULE        Contains definitions of X-10 modules.  Parent to.I                            MODULE_STATUS and TIMER_EVENTS.  The compound LJ                            primary key is House_Code and Unit_Code.  Note:M                            "dummy" module Z-0 is necessary to satisfy foreign-M                            key constraints in Timer_Events for Type B events.0  I      4)  MODULE_STATUS     Current on/off/unknown status for each module._J                            Child table of X10_MODULE. The compound primaryJ                            key is House_Code and Unit_Code which are also 4                            constrained foreign keys.  J      5)  TIMER_EVENTS      Timed/scheduled events for all event types. TheI                            primary key is Timer_Event_ID.  Child table of J                            X10_MODULE; attributes House_Code and Unit_Code8                            are constrained foreign keys.    O ===============================================================================V  1 Appendix C - Using A Terminal Server and LAT PortS1 -------------------------------------------------F  N   Information on how to configure a DECserver 200/MC and LAT for use with the N   LynX-10 device and X10_MONITOR is provided here. Other terminal servers willO   work with appropriate modifications (a similar setup was successfully tested oM   on a DECserver 700). One should be able to adapt this setup to communicate -4   with other types of serial interface devices, too.  O   One issue to be aware of:  Initial communication must originate from OpenVMS,iO   not from the external device.  X10_TIMER sends a reset command to the LynX-10 N   at startup in order to initiate communication.  Bi-directional communication#   is successful from that point on.a     LynX-10 Cable and Connectionsa   ----------------------------- J   The male/female DB9 straight-through cable supplied with the LynX-10 is J   designed for attaching to a PC.  A custom cable or standard DB9 to DB25 F   cable is sufficient.  A DTE device is connected to a DCE as follows:  #     DECserver 200/MC       LynX-10  :       (DTE)  DB-25       (DCE)  DB-9           Connections:    -------------------------------------       -----------:    Pin  Signal  Test | Pin  Signal  Test       DB25 to DB9                      |:     2    TxD    Neg  |  3    TxD     X          2  <-->  3:     3    RxD     X   |  2    Rxd    Neg         3  <-->  2:     4    RTS    Pos  |  7    RTS     X          4  <-->  7:     5    CTS     X   |  8    CTS    Pos         5  <-->  8:     6    DSR     X   |  6    DSR     X          6  <-->  6:     7    Gnd     X   |  5    Gnd     X          7  <-->  5:     8    DCD    Pos  |  1    DCD     X          8  <-->  1:     20   DTR    Pos  |  4    DTR     X          20 <-->  4  K   For terminal servers lacking flow control (e.g., the DECserver 100), the rM   LynX-10 could be tricked into thinking that flow control is always enabled  M   by connecting pins 7, 1 and 4 to pin 8 (at the DB-9 side with no correspon-eM   ding connection on the DB-25 side) and disabling flow control in the server K   port setup.  This approach isn't recommended--use a terminal server with U   flow control capability.     LAT Configurationn   -----------------N@   In the LAT$SYSTARTUP.COM file, include the following commands:  *     $ lcp create port LTA207: /application=     $ lcp set port lta207: /node=dsv200 /port=port_7 /noqueuef  G   Use a logical name to avoid hard-coding a terminal device name in theaJ   application program.  X10MON_DEV serves this purpose for the X10_MONITORJ   system.  LAT must be started before the Monitor and Timer/user interface
   are run.     VMS Terminal Settingso   --------------------- L   Use the same settings provided in module X10MON_STARTUP.COM but change the>   device name to the designated LAT port name or logical name.  =     SET TERM LTA207: /PERM/SPEED=1200/NOINTERACTIVE/NOWRAP  -d=         /NOBROADCAST/NOLINE_EDITING/NOECHO/NOTTSYNC/NOSCOPE - 7         /NOINSERT-EDITING/ALTYPEAHD/NOHOSTSYNC/EIGHTBITY  J   After executing the above command, terminal device LTA207: is configuredK   for communication with the LynX-10 (which requires 1200 baud, 8 bits, no =   parity and one stop bit).      Terminal Server Configuration1   -----------------------------aL   The objective is to configure the terminal server port to function in the K   same manner as a built-in serial port.  As shown in the following screen iN   print, most "Enabled Characteristics" are disabled except for flow control. M   Set Access to Remote, Session Limit to 1, Break to Disabled, Modem Control iL   to Disabled.  Refer to the terminal server's documentation and online help'   facility for commands and parameters.   B   ----------------------------------------------------------------   Local> show port 7  7   Port 7:                                Server: DSV200n  A   Character Size:            8           Input Speed:        1200mA   Flow Control:            XON           Output Speed:       1200 A   Parity:                 None           Modem Control:  Disablede  A   Access:               Remote           Local Switch:       NonesA   Backwards Switch:       None           Name:             PORT_7sA   Break:              Disabled           Session Limit:         1 A   Forwards Switch:        None           Type:               Soft      Preferred Service: Noneo     Authorized Groups:   0   (Current)  Groups:   0     Enabled Characteristics:  *   Input Flow Control,  Output Flow ControlB   ----------------------------------------------------------------  O ************************ End of X10_MONITOR_DOC.TXT ***************************d