OS/2 Shareware BBS: OtherApp/OtherApp.zip/cm17ce.zip/fcinst.EXE/cm17ce.inf

OS/2 Help File | 2000-01-18 | 44KB | 1,343 lines

ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ

This document serves two purposes: It explains how to use the Comm Engine and
it documents the REXX program interface.

For Comm Engine operation and troubleshooting, refer to each of the sections
below.

Description | Installation | Getting Started | Important Notes | Menu
Description | Network Operation | Troubleshooting

For REXX program interface and function description, refer to each of the
sections below. This section is only intended for people who write their own
REXX client program to control X10 events.

Comm Engine Function Description | X10FLDLL Function Description


ΓòÉΓòÉΓòÉ 2. Description ΓòÉΓòÉΓòÉ

CM17A Comm Engine ver. 2.0 - Shareware. Designed for the CM17A Firecracker
interface by X10. This program is part of HOUSE/2, a series of home automation
& security applications for OS/2.

CM17A Comm Engine is an OS/2 version 3.0 and later program to control the home
automation interface model CM17A made by X10. This program provides a separate
REXX-enabled and network aware communications engine for this inexpensive X10
controller. Can use the Virtual Keychain Remote program as a graphical user
interface front end.

The CM17A Comm Engine is shareware. Registration is available through BMT Micro
at www.bmtmicro.com or through the author directly. See the section How To
Register for details.

The CM17A Communications Engine has the following features:

      Γûá Fully supports the X10 CM17A Firecracker via a serial port.

      Γûá Acts as a REXX-enabled server for the X10 Firecracker device.

      Γûá Uses named pipes to communicate to client programs like the Virtual
      Keychain Remote or other custom client programs. Sample source for custom
      programs is included.

      Γûá Can be controlled over a network (LAN or peer-to-peer) allowing X10
      home control through the CM17A from any workstation.

      Γûá Accepts commands like A1 ON and translates them into X10 code for the
      CM17A interface.

 Note: In order to fully take advantage of the program's features, you must buy
 the X10 Firecracker. This can be done for around $6 total to get you started
 and it can easily be expanded from that point on. See Internet Links for Home
 Automation for information on home control devices.

 X10 devices are available for most international power configurations. Please
 see Internet Links for Home Automation for information on X10 representatives
 around the world.

 In case you were wondering: The icon of this program is a picture of the
 Doritaenopsis Firecracker "Malibu", a medium-sized warm-growing monopodial
 epiphyte hybrid orchid.


ΓòÉΓòÉΓòÉ 3. Important Notes ΓòÉΓòÉΓòÉ

Use the Virtual Keychain Remote as a graphical user interface to control X10
devices. The CM17A Comm Engine must be started separately and be online to the
controller before the Virtual Keychain will operate. The CM17A Comm Engine can
be set to auto-connect on start-up.

To run the Comm Engine alone, the following minimum files are required to be
present: CM17CE.EXE, CM17CE.INI, CM17CE.HLP, RXASYNC.DLL, X10FKDLL.DLL and
X10FLDLL.DLL.

You can integrate X10 module control into your OS/2 desktop with object menus.
The file CMDA1ON.CMD is included just for that purpose. See

 http://home.att.net/~ASchw

for details on how to setup object menus.


ΓòÉΓòÉΓòÉ 4. Getting Started ΓòÉΓòÉΓòÉ

This section describes the various ways how the CM17A Comm Engine can be
applied.

Default Operation

Default operation is for running the CM17A interface from a single computer.
Start-up the Comm Engine and connect to the interface. There are settings for
auto-connect and minimize on start-up. Use the Virtual Keychain remote or your
own custom REXX script to control X10 devices.

Network Operation

For operation over a LAN or peer-to-peer network, do the following. Install the
CM17A at one of the workstations or server. Install the Comm Engine at the same
computer where you installed the CM17A. Start up the Comm Engine (CM17CE.EXE)
and connect to the interface. Leave the Comm Engine running so other programs
can access it.

Install the Virtual Keychain or your own REXX script on any other computer on
the network. Start up the Virtual Keychain and on the Settings page fill in the
computer name where the Virtual Keychain can find the Comm Engine.

Note: The computer name of a system can be found in the file IBMLAN\IBMLAN.INI
which is a text file. Under the [requester] section you will find Computername
= CLIENT527 for example. Simply type in the name CLIENT527 in the text field to
indicate on which computer the Comm Engine is running at.

Operation with your own REXX Program

If you want to use your own REXX programs to access the CM17A functions, simply
start the Comm Engine and use your REXX program to communicate via the named
pipe to the Comm Engine. Remember that only one program can access the named
pipe at one time. See the section on REXX Examples for a sample REXX program.


ΓòÉΓòÉΓòÉ 4.1. REXX Examples ΓòÉΓòÉΓòÉ

The sample program below shows how to use the Comm Engine's REXX features. This
program is also part of the CM17A Comm Engine distribution and is named
CLIENT.CMD. Look for other CMD files for more examples. CLIENT.CMD can be used
to interactively control the CM17A interface and X10 modules.

This example requires the Comm Engine (CM17CE.EXE) to be running.


/* CLIENT.CMD - Interactive REXX script for CM17A Comm Engine */

/*
  Written by: Lone Peak Automation, LLC
  Date: Jan. 15, 2000
  This program requires the CM17A Comm Engine.
  See http://home.att.net/~ASchw for more information.

  Important: The CM17A Comm Engine must be running and be connected
        to the X10 FireCracker before using this script.

This is an example to show how to access the CM17A Comm Engine functions.
*/

/* Load CM17A Comm Engine Functions */
call RxFuncAdd 'X10FLLoadFuncs', 'X10FLDLL', 'X10FLLoadFuncs'
call X10FLLoadFuncs

/* Load the REXXUTIL.DLL */
call RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs'
call SysLoadFuncs

pipename = '\PIPE\CM17ACE'

/* Note: If running over a network, precede the pipe name with the computer name as shown below. */
/* pipename = '\\CLIENT527\PIPE\CM17ACE' */  /* note the _two_ backslashes preceding the computer name */

SAY pipename

rc = FCLOpenPipe(pipename)
Say 'PipeOpen = ' || rc

IF rc = 0 then
 DO
  rc =  FCLPeekPipe('0')
  Say 'PipePeek ' || rc
  IF Right(rc, 1) = 3 then
   SAY 'pipe connected'
  else
   DO
    SAY 'pipe unavailable, close'
    rc = FCLClosePipe('0')
    Say 'PipeClose ' || rc
   END
 END
ELSE
 DO
  SAY 'pipe not available'
  rc = FCLClosePipe('0')
  Say 'PipeClose ' || rc
 END


keyhit = ''
DO FOREVER

  SAY "Press R to read; W to write, P to peek, O to Open, S to cloSe,"
  SAY "Press C to connect; D to disconnect, Zx for COMx port, U to unload,"
  SAY "M for status,"
  SAY "+ to Show, - to Minimize,"
  SAY "ID1 HCDC ON/OFF/DIM/BRI for direct commands,"
  SAY "H for help, X to Exit"

  PARSE PULL keyhit

  SELECT
  WHEN keyhit = 'x' then
   LEAVE
  WHEN keyhit = 'h' then
   DO
    SAY 'PipePeek status: '
    SAY ' 1: the pipe is disconnected;'
    SAY ' 2: the pipe is listening for a connection;'
    SAY ' 3: the pipe is connected;'
    SAY ' 4: the pipe is closing.'
   END

   when POS('z', keyhit) = 1 | POS('Z', keyhit) = 1 then   /* COMx */
    do
     PortNum = Substr(keyhit, 2, 1)
     temp = '}SETPORTCOM' || PortNum
     rc = FCLWritePipe(temp)
     keyhit = ""
    end

   when keyhit = "c" | keyhit = "C" then   /* connect */
    do
     temp = '}CONNECT'
     rc = FCLWritePipe(temp)
     keyhit = ""
    end

   when keyhit = "d" | keyhit = "D" then   /* disconnect  */
    do
     temp = '}DISCONNECT'
     rc = FCLWritePipe(temp)
     keyhit = ""
    end

   when keyhit = "u" | keyhit = "U" then   /* unload  */
    do
     temp = '}CLOSE'
     rc = FCLWritePipe(temp)
     keyhit = ""
    end

   when keyhit = "m" | keyhit = "M" then   /* status  */
    do
     temp = '}STATUS'
     rc = FCLWritePipe(temp)
     keyhit = ""
     call SysSleep(2)    /* wait two seconds */
     rc = FCLReadPipe('0')
     SAY 'Status = >' || rc || '<'
    end

   when keyhit = "+" then   /* restore  */
    do
     temp = '}SHOW'
     rc = FCLWritePipe(temp)
     keyhit = ""
    end

   when keyhit = "-" THEN   /* min  */
    do
     temp = '}MINIMIZE'
     rc = FCLWritePipe(temp)
     keyhit = ""
    end

   when POS('ID1', TRANSLATE(keyhit)) = 1 then   /* direct cmd  */
    do
     temp = '}' || keyhit
     rc = FCLWritePipe(temp)
     keyhit = ""
    end

   WHEN keyhit = 'p' then
    DO
     rc = FCLPeekPipe('0')
     Say 'PipePeek ' || rc
    END
   WHEN keyhit = 'r' then
    DO
     rc = FCLReadPipe('0')
     SAY 'reading from pipe >' || rc || '<'
    END
   WHEN keyhit = 'w' then
    DO
     rc = FCLWritePipe('}ID1 A1 ON')
     SAY 'writing to pipe ' || rc
    END

   WHEN keyhit = 's' then
    DO
     rc = FCLClosePipe('0')
     Say 'PipeClose ' || rc
    END
   WHEN keyhit = 'o' then
    DO
     rc = FCLOpenPipe(pipename)
     Say 'PipeOpen = ' || rc
    END

   OTHERWISE
    NOP
  END
END

rc = FCLClosePipe('0')
call X10FLDropFuncs

EXIT


ΓòÉΓòÉΓòÉ 5. Menu Description ΓòÉΓòÉΓòÉ

Describes all menu items available for this program.


ΓòÉΓòÉΓòÉ 5.1. FILE - Show Commands ΓòÉΓòÉΓòÉ

This selection toggles the Show Commands on and off. If this menu selection is
checked, every command received from the Comm Engine by the client program will
be displayed on the main window. Only the last 20 commands will be kept in the
window. If this menu selection is unchecked, no commands will be displayed
except when the Comm Engine is first started it will display that the pipe has
been created. By default, the Show Commands is turned off (unchecked). Note:
The CM17A cannot receive X10 commands.


ΓòÉΓòÉΓòÉ 5.2. FILE - Configuration ΓòÉΓòÉΓòÉ

Brings up the Comm Engine configuration window.

From that window, you can select the Com Port where the CM17A is connected to.
If the Auto Connect check box is checked, the Comm Engine will automatically
connect to the CM17A whenever it is started. By default, Auto Connect is off.
You can use the command line option to override this setting.

If the Minimize on Open check box is checked, the Comm Engine will be minimized
on start-up. You can go to the windows list (press CTRL-ESC) to show a
minimized Comm Engine. By default, Minimize on Open is unchecked (disabled).

Data Logging can be enabled by checking the Auto Event Log box. Log File Size
sets the maximum log file (CM17CE.LOG) size in kiloBytes. If the file size
exceeds this limit, the existing log is copied to the file CM17CE.000 and a new
log is started. Any existing CM17CE.000 file will be overwritten.

The Save button saves all the settings in the CM17CE.INI file and closes the
window.

Cancel will abort any changes and close the window. Closing the configuration
window from the system menu is equivalent to canceling changes.


ΓòÉΓòÉΓòÉ 5.3. FILE - Exit ΓòÉΓòÉΓòÉ

Exits the Comm Engine.  If it was online to the CM17A interface, the connection
is terminated and the pipe to the client program is flushed and closed.


ΓòÉΓòÉΓòÉ 5.4. INTERFACE - Connect ΓòÉΓòÉΓòÉ

Opens selected serial port to communicate to the CM17A interface. A check mark
on this menu item will indicate connection status.

See the section on Comm Engine Function Description for information on how to
control the CM17A interface using your own program.

Note: It is not possible to share the serial port with another device through
the CM17A pass-through connector when the Comm Engine is in a connected state.


ΓòÉΓòÉΓòÉ 5.5. INTERFACE - Disconnect ΓòÉΓòÉΓòÉ

Closes selected serial port to disconnect from the CM17A interface. A check
mark on this menu item will indicate connection status.

See the section on Comm Engine Function Description for information on how to
control the CM17A interface using your own program.


ΓòÉΓòÉΓòÉ 5.6. HELP - Help Contents ΓòÉΓòÉΓòÉ

Displays the help contents (but uses the OS/2 index feature). Note that help is
organized in sections and Help Contents brings up the section headings in
alphabetical order. This is a more logical way to organize help even if it goes
against common OS/2 convention.


ΓòÉΓòÉΓòÉ 5.7. HELP - Product Information ΓòÉΓòÉΓòÉ

Product information.


ΓòÉΓòÉΓòÉ 6. Comm Engine Function Description ΓòÉΓòÉΓòÉ

This section describes all functions available in CM17CE.EXE and how to use
them. It is only intended for people who want to write their own client program
to interface to the Comm Engine.

The Comm Engine acts as a server between the CM17A and any other client
program. It handles CM17A house, device and function code translation by
accepting commands like A1 ON and translating them to the required hex code for
the CM17A to understand.

The Comm Engine uses a named pipe as interface to client programs. Before the
Comm Engine functions can be used within your own REXX program, you must load
X10FLDLL.DLL and setup the pipe. See the section on X10FLDLL Function
Description for information on that subject.

The command structure for the Comm Engine is as follows:

Note: Curly brackets are used to separate out the various error flags, commands
and data. This helps in parsing the data and also indicates which way the
commands are flowing. Opening brackets indicate that the commands flow from the
Comm Engine to the client and closing brackets indicates the flow from the
client to the Comm Engine.

Sending command to the Comm Engine:

   }command options

The closing curly bracket indicates that the following command is sent from the
client to the Comm Engine. The command instructs the Comm Engine what operation
is to be performed on the Comm Engine itself or on the CM17A. Sample commands
are ID1, CONNECT, MINIMIZE etc.

The options contain data to set the CM17A or the Comm Engine. Sample options
are the direct commands like A1 ON to control modules, for example.

Receiving command from the Comm Engine:

   {XX }command {data

Commands sent out by the Comm Engine are replies to a command received by the
Comm Engine. The original command is returned as a confirmation of receipt. All
commands placed on the pipe will be buffered and processed on a first in, first
out basis.

The XX indicates any possible errors the previous command encountered. For
example, a zero indicates no error, a one indicates an unsupported command. The
error field is always padded to two digits and the next closing curly bracket
is always at position five.

The command following the closing curly bracket is the original command that
prompted this reply.

For more details on the command structure and samples, see each individual
command as listed below.


   ID1 - Direct command (instant on/off)

   Comm Engine STATUS

   Comm Engine SETPORTCOMx

   Comm Engine CONNECT

   Comm Engine DISCONNECT

   Comm Engine CLOSE

   Comm Engine SHOW

   Comm Engine MINIMIZE


ΓòÉΓòÉΓòÉ 6.1. ID1 - Direct command (instant on/off) ΓòÉΓòÉΓòÉ

This function sends out X10 commands to the CM17A interface to control modules.
See included sample REXX scripts for information on how to use the direct
commands. The command format is as follows:

   }ID1 hcdc command

The option hcdc command is of the following format: hcdc is any valid X10
address like A1 or B16. command format is listed below. Each of the two
variables are separated by a space from each other.

Valid Commands:

  ON       Turns module on.
  OFF      Turns module off.
  DIM      Dims module by 5% (not adjustable).
  BRI      Brightens module by 5% (not adjustable).

The Comm Engine will return the following:

   {XX }ID1 option

Where:

  XX = 0 if there was no error.
  XX = 1 unsupported or illegal command.
  XX = 5 command can't be executed because engine is offline.
  XX = 8 invalid data (house, device or function code).

  option = same string as sent with the ID1 command.

Example: Turn on appliance module A1.

Command:
    rc = FCLWritePipe( '}ID1 A1 ON' )

Reply:
    {0  }ID1 A1 ON


ΓòÉΓòÉΓòÉ 6.2. Comm Engine STATUS ΓòÉΓòÉΓòÉ

This function requests the Comm Engine online status and serial port setting.
The command format is as follows:

   }STATUS

No data needs to be supplied with the command.

The Comm Engine will return the following data:

   {XX }status portname

Where:

  XX = 0 if there was no error.
  XX = 1 unsupported or illegal command.

  status = ONLINE if online; OFFLINE if offline.

  portname = COMx where x = 1 through 8

Example: Get status of Comm Engine.

Command:
    rc = FCLWritePipe( '}STATUS' )

Reply:
    {0  }ONLINE COM2


ΓòÉΓòÉΓòÉ 6.3. Comm Engine SETPORTCOMx ΓòÉΓòÉΓòÉ

This function instructs the Comm Engine to change serial port. The Comm Engine
must be offline for the change to be successful. The command format is as
follows:

   }SETPORTCOMx

where x is the integer 1 through 8.

The Comm Engine will return the following data:

   {XX }command

Where:

  XX = 0 if there was no error.
  XX = 1 unsupported or illegal command.
  XX = 6 Comm Engine online, cannot change serial port.
  XX = 7 invalid serial port.

  command = SETPORTCOMx (original command as sent out).

Example: Set serial port of Comm Engine to COM5.

Command:
    rc = FCLWritePipe( '}SETPORTCOM5' )

Reply:
    {0  }SETPORTCOM5


ΓòÉΓòÉΓòÉ 6.4. Comm Engine CONNECT ΓòÉΓòÉΓòÉ

This function instructs the Comm Engine to connect to the serial port. The
command format is as follows:

   }CONNECT

No data needs to be supplied with the command.

The Comm Engine will return the following data:

   {XX }command

Where:

  XX = 0 if there was no error.
  XX = 1 unsupported or illegal command.
  XX = 2 connect error. RC will be returned in command.

  command = CONNECT (original command as sent out)
       or RC if there was an error.

  Of special interest is RC = 110 if the serial port is
  used by another application.

Example: Connect Comm Engine to CM17A.

Command:
    rc = FCLWritePipe( '}CONNECT' )

Reply:
    {0  }CONNECT


ΓòÉΓòÉΓòÉ 6.5. Comm Engine DISCONNECT ΓòÉΓòÉΓòÉ

This function instructs the Comm Engine to disconnect from the serial port. The
command format is as follows:

   }DISCONNECT

No data needs to be supplied with the command.

The Comm Engine will return the following data:

   {XX }command

Where:

  XX = 0 if there was no error.
  XX = 1 unsupported or illegal command.
  XX = 3 disconnect error. RC will be returned in command.

  command = DISCONNECT (original command as sent out)
              or RC if there was an error.

Example: Disconnect Comm Engine from CM17A.

mand:
    rc = FCLWritePipe( '}DISCONNECT' )

Reply:
    {0  }DISCONNECT


ΓòÉΓòÉΓòÉ 6.6. Comm Engine CLOSE ΓòÉΓòÉΓòÉ

This function terminates and closes the Comm Engine. Connection to the CM17A
will be closed automatically and the pipe is flushed and closed as well. The
command format is as follows:

   }CLOSE

No data needs to be supplied with the command.

The Comm Engine will not return any data.

Example: Terminate Comm Engine.

Command:
    rc = FCLWritePipe( '}CLOSE' )


ΓòÉΓòÉΓòÉ 6.7. Comm Engine SHOW ΓòÉΓòÉΓòÉ

This function restores the Comm Engine from a minimized state. The command
format is as follows:

   }SHOW

No data needs to be supplied with the command.

The Comm Engine will return the following data:

   {XX }command

Where:

  XX = 0 if there was no error.
  XX = 1 unsupported or illegal command.

  command = SHOW


ΓòÉΓòÉΓòÉ 6.8. Comm Engine MINIMIZE ΓòÉΓòÉΓòÉ

This function minimizes the Comm Engine. The command format is as follows:

   }MINIMIZE

No data needs to be supplied with the command.

The Comm Engine will return the following data:

   {XX }command

Where:

  XX = 0 if there was no error.
  XX = 1 unsupported or illegal command.

  command = MINIMIZE


ΓòÉΓòÉΓòÉ 7. X10FLDLL Function Description ΓòÉΓòÉΓòÉ

This section describes all functions available in X10FLDLL.DLL and how to use
them.

Note: This DLL is used to setup a named pipe to communicate with the Comm
Engine. The functions listed in this section need to be used only if you want
to write your own REXX client program to control the Comm Engine. See the
section on Comm Engine Function Description for information on how to control
the CM17A interface once the pipe is setup.

Description of pipe operation.

The Comm Engine uses a named pipe for inter-process communications. This pipe
allows two programs to exchange data between each other. These two programs may
be on the same computer or they may be on different computers connected through
a LAN or peer-to-peer network.

The Comm Engine opens a pipe, \PIPE\CM17ACE for the control of the CM17A
interface.

To establish connection, the Comm Engine will first create a pipe with the
fixed name \PIPE\CM17ACE and place it into a listening mode. The client program
(Virtual Keychain or any other custom program) will then have to open the same
pipe and peek to check if it connected. From that point on, data can be placed
on the pipe by either program. All commands are buffered in the pipe and the
client program must check the pipe for available data and read it to prevent
buffer overrun and data loss. The buffer size for the pipe is 4096 bytes and if
full will not accept any additional data. Currently, no error is reported if
the buffer fills up.

If two programs are communicating through a pipe, they have exclusive access to
the pipe. A third program cannot connect to the same pipe. To free up the pipe,
the client program must close the pipe so the Comm Engine can make it available
to other programs. If a pipe is closed, all data in the buffer is flushed.

For more details on pipe operation and communication to the Comm Engine, see
the sample REXX programs included with the program archive.

Below is the list of functions to access and control the Comm Engine:


   X10FLLoadFuncs

   X10FLDropFuncs

   FCLReadPipe

   FCLWritePipe

   FCLPeekPipe

   FCLOpenPipe

   FCLClosePipe


ΓòÉΓòÉΓòÉ 7.1. X10FLLoadFuncs ΓòÉΓòÉΓòÉ

This function loads X10FLDLL.DLL to be used within your REXX program. A REXX
program using X10FLDLL must contain the following lines to access other
functions inside X10FLDLL:

   CALL RXFuncAdd 'X10FLLoadFuncs', 'X10FLDLL', 'X10FLLoadFuncs'
   CALL X10FLLoadFuncs

Standard REXX errors are returned for this function, for example: Error 43 -
Routine not found if X10FLDLL.DLL can't be found. X10FLDLL.DLL must be in the
current directory or in a directory where the LIBPATH statement points to.


ΓòÉΓòÉΓòÉ 7.2. X10FLDropFuncs ΓòÉΓòÉΓòÉ

This function unloads X10FLDLL.DLL from memory. A REXX program using X10FLDLL
must contain the following line to unload X10FLDLL:

   CALL X10FLDropFuncs


ΓòÉΓòÉΓòÉ 7.3. FCLReadPipe ΓòÉΓòÉΓòÉ

This function reads the contents of the pipe, one entry at a time. The pipe
must be open before it can be read. FCLPipeRead will first do a DOSPeekNPipe
call and then read the pipe if the character count is not zero. FCLPeekPipe
should be used to check if any data is available before a FCLReadPipe command.
See FCLOpenPipe and FCLPeekPipe for details.

The command is as follows:

   rc = FCLReadPipe( '0' )

The return value rc is made up of the following information:

  piperr charcount replypacket

Piperr is any possible error the read pipe command may have caused. If the
character count is zero, the piperr returns the value of DOSPeekNPipe. If the
character count is not zero, piperr returns whatever the DosRead returns which
can be the following values:


  0    NO_ERROR
  5    ERROR_ACCESS_DENIED
  6    ERROR_INVALID_HANDLE
  26    ERROR_NOT_DOS_DISK
  33    ERROR_LOCK_VIOLATION
  109   ERROR_BROKEN_PIPE
  234   ERROR_MORE_DATA

charcount is the character count of the data just read from the pipe.

replypacket is the reply the Comm Engine returns in response to one of the
commands as listed under Comm Engine Function Description.

Example read from pipe.

Command:
    rc = FCLReadPipe( '0' )

Contents of rc:
    0 12 {0  }CONNECT

There were 12 characters read from the pipe which corresponds
to the data displayed from the opening curly bracket to the T in
CONNECT. (There are two spaces between the curly brackets).


ΓòÉΓòÉΓòÉ 7.4. FCLWritePipe ΓòÉΓòÉΓòÉ

This function writes to the pipe. The pipe must be open before it can be
written to.

The command is as follows:

   rc = FCLWritePipe( command )

Command contains any of the valid Comm Engine commands as listed under Comm
Engine Function Description.

The return value rc is the same as what DOSWrite returns and can be the
following values:


  0     NO_ERROR
  5     ERROR_ACCESS_DENIED
  6     ERROR_INVALID_HANDLE
  19    ERROR_WRITE_PROTECT
  26    ERROR_NOT_DOS_DISK
  29    ERROR_WRITE_FAULT
  33    ERROR_LOCK_VIOLATION
  109    ERROR_BROKEN_PIPE

Example write to pipe.

Command:
    rc = FCLWritePipe( '}ID1 A1 DIM' )

Contents of rc:
    0

This example instructs the Comm Engine to command the
CM17A to dim module A1 by 5% using the direct command.
Dimming percentage is fixed at 5% for each command. You
must issue repeated dimming commands to reach the desired level.
This is a hardware design limit.


ΓòÉΓòÉΓòÉ 7.5. FCLPeekPipe ΓòÉΓòÉΓòÉ

This function checks if any data is available on the pipe to read. Use this
function before a FCLReadPipe command.

The command is as follows:

   rc = FCLPeekPipe( '0' )

The return value rc is made up of the following information:

  piperr charcount pipestate

Piperr is any possible error the DOSPeekNPipe command may have caused.
DosPeekNPipe returns the following values:


  0     NO_ERROR
  230    ERROR_BAD_PIPE
  231    ERROR_PIPE_BUSY
  233    ERROR_PIPE_NOT_CONNECTED

charcount is the number of characters available to read from the pipe.

pipestate is the state the pipe is currently at. Possible values are:


    1 =  the pipe is disconnected.
    2 =  the pipe is listening for a connection.
    3 =  the pipe is connected.
    4 =  the pipe is closing.

Example peek into pipe.

Command:
    rc = FCLPeekPipe( '0' )

Contents of rc:
    0 12 3

There are 12 characters available to read
from the pipe and the pipe is connected.


ΓòÉΓòÉΓòÉ 7.6. FCLOpenPipe ΓòÉΓòÉΓòÉ

This function opens the pipe to the Comm Engine.

The command is as follows if the Comm Engine and the client are running on the
same computer:

   pipename = '\PIPE\CM17ACE'
   rc = FCLOpenPipe( pipename )

For network operation, the pipe name must include the computer name where the
Comm Engine is running at. In this example, the computer name is CLIENTCM11 and
it must be preceded by two back slashes.

   pipename = '\\CLIENTCM11\PIPE\CM17ACE'
   rc = FCLOpenPipe( pipename )

This function returns the same values as the API call DosOpen. The values of
most interest are:


    0    NO_ERROR
    2    ERROR_FILE_NOT_FOUND
    3    ERROR_PATH_NOT_FOUND
    4    ERROR_TOO_MANY_OPEN_FILES
    5    ERROR_ACCESS_DENIED
    12    ERROR_INVALID_ACCESS
    231   ERROR_PIPE_BUSY

See the example CMD files included for details on how to run a pipe to the Comm
Engine.


ΓòÉΓòÉΓòÉ 7.7. FCLClosePipe ΓòÉΓòÉΓòÉ

This function closes the pipe to the Comm Engine.

The command format is as follows:

   rc = FCLClosePipe( '0' )

This function returns the same values as the API call DosClose. The values of
most interest are:


  0     NO_ERROR
  2     ERROR_FILE_NOT_FOUND
  5     ERROR_ACCESS_DENIED
  6     ERROR_INVALID_HANDLE

See the example CMD files included for details on how to run a pipe to the Comm
Engine.


ΓòÉΓòÉΓòÉ 8. Command Line Options ΓòÉΓòÉΓòÉ

The following command line options are recognized by CM17CE.EXE:

  -ComX        Connects to the serial port as specified by X. X ranges from 1 through 8.
  -Min          Minimizes Comm Engine on start-up.
  -i d:\path\inifile.ini   Redirects the Comm Engine ini file to another drive, directory or ini file name.

If -ComX is specified, the Comm Engine will over-ride the existing serial port
setting and open the specified port to establish a connection to the CM17A.

The -i option must be used if the Comm Engine is run from a networked drive
that is write-protected. You can redirect the ini file to a user directory with
this option.

To enter the startup options do the following:

      Γûá  For Warp 3.0:  Right-click on the CM17CE icon and select Settings.
      Under the Program tab in Optional Parameters enter the startup option.

      Γûá  For Warp 4.0:  Right-click on the CM17CE icon and select Properties.
      Under the Program tab in Optional Parameters enter the startup option.


ΓòÉΓòÉΓòÉ 9. Troubleshooting ΓòÉΓòÉΓòÉ

CM17A Interface Connection Problems.

If you are having problems getting the CM17A interface to work, then follow
these steps below.

      Γûá  Make sure the serial port setting in the configuration matches the
      serial port you use for the interface.

      Γûá  Try the standard COM1 or COM2 ports if you have problems with any
      other ports like COM3 - COM8. Also, remove any serial cable extensions or
      adapters and connect the interface directly to the computer.

      Γûá  Try using a different computer or different port to access the CM17A.

      Γûá  Check http://home.att.net/~ASchw for the HOUSE/2 and X10 frequently
      asked question page for additional information on troubleshooting.

      Γûá  E-mail Lone Peak Automation and we will try to help you out.
      (Eventually registering this program will give Lone Peak Automation extra
      incentive too!).


ΓòÉΓòÉΓòÉ 10. Installation ΓòÉΓòÉΓòÉ

Note:  REXX (classic or Object REXX) must be installed on your system for this
program to work. REXXUTIL.DLL is required.

CM17A Comm Engine is distributed as a self-installing executable using
PillarSoft's SFX Installer. See http://www.pillarsoft.net for more information
on that product.

When installing this program, simply follow the prompts given.

Installing this program on your system does not change any of the INI or
CONFIG.SYS files.

In rare instances, it may be possible that this program may not find the DLL
files and abort on start-up. To fix this, simply add the directory where you
installed the Comm Engine to the LIBPATH in your CONFIG.SYS. A reboot is
necessary for the changes to take effect.

The following files belong to this program:

       CM17CE.EXE        The CM17A Communications Engine.

       CM17CE.HLP        The CM17A Communications Engine help file.

       CM17CE.INI        Configuration file. This file will be created the
                         first time CM17CE.EXE is run.

       CM17CE.LOG        A log file that contains all the events as sent to the
                         CM17A interface. Events are only logged when the
                         computer is connected to the interface and logging is
                         enabled. This is a text file and you can look at it
                         with a text editor.

       CM17CE.000        Archived log file. CM17CE.LOG is copied over to this
                         file whenever the log file size exceeds the set value.
                         The contents of the old CM17CE.000 file will be
                         deleted.

       VPOBJ.DLL         Dynamic Link Library required by executable.

       RXASYNC.DLL       Dynamic Link Library required for serial
                         communications to the CM11A interface. This library of
                         serial communications routines is included by
                         permission of Crucial Applications (Author: Ian Timms,
                         e-mail: [e-mail]). The entire
                         serial communications package, including the source
                         code for RXASYNC, is available at the Lone Peak
                         Automation home page or other major OS/2 sites by the
                         file name RXASYN20.ZIP. This DLL has been packed with
                         LXWARP for smaller size. Required by CM11CE.EXE only.

       X10FCDLL.DLL      Dynamic Link Library required by CM17CE.EXE only.

       X10FLDLL.DLL      Dynamic Link Library required by the sample REXX or
                         custom client programs only.

       CLIENT.CMD        Sample script to access most Comm Engine functions.

       MODCTRL.CMD       Sample script to access Comm Engine functions to
                         control a module.

       TIMEMOD.CMD       Sample script to access Comm Engine functions to
                         time-control a module.

       UNINSTAL.CMD      Uninstallation program. Removes HOUSE/2 completely
                         from your system.

       HISTORY.TXT       History of changes to the program.

       BMTORDER.TXT      Order form to register CM17A Comm Engine through BMT
                         Micro.

 To remove this program from your system, close the program and execute
 UNINSTAL.CMD from the CM17CE directory. This removes all Comm Engine files and
 subdirectory where the program was located in.


ΓòÉΓòÉΓòÉ 11. Network Operation ΓòÉΓòÉΓòÉ

Network operation allows to control X10 devices from any workstation on the
network. It is not necessary to map a serial port or drive onto another machine
as the Comm Engine is running on the workstation where the CM17A interface is
connected to. The CM17A Comm Engine uses a named pipe to communicate with any
graphical user interfaces like the Virtual Keychain. The requirements for
proper network operation are: The requesters on both machines must be running
and the assigned computer name where the Comm Engine is running at, must be
known.

To run this program over a network, do the following:

Connect the CM17A to one of the peer stations or the server. Start-up
CM17CE.EXE and configure it for the serial port of the CM17A. You can turn on
Minimize on Open in the configuration page of the Comm Engine if you like the
Comm Engine to start minimized. There is also a setting to Auto Connect to the
CM17A on start-up. Now, install Virtual Keychain Remote or your own REXX script
on another workstation. No need to run CM17A Comm Engine on that workstation.
In the Settings window of the Virtual Keychain Remote, enter the computer name
where the CM17A is connected to. Do not include any back slashes when entering
the name.

Note: The computer name of a system can be found in the file IBMLAN\IBMLAN.INI
which is a text file. Under the [requester] section you will find Computername
= CLIENT527 for example. Simply type in the name CLIENT527 in the text field to
indicate on which computer the Comm Engine is running at.

Only one client can communicate with the Comm Engine at any one time. If you
want to use a third workstation to access the Comm Engine, you must disconnect
any custom REXX script from the pipe to free up the Comm Engine. The Virtual
Keychain Remote is designed to automatically disconnect from the serial port
after each command is sent out.

The -i start-up option must be used if either CM17CE.EXE or Virtual Keychain
Remote is run from a networked drive that is write-protected. You can redirect
the ini file to a user directory with this option.


ΓòÉΓòÉΓòÉ 12. Shareware Limitation ΓòÉΓòÉΓòÉ

This shareware program is fully enabled with the exception of the following:

      Γûá Registration reminder when exiting.

      Γûá After sending 50 interactive commands to the CM17A controller, the Comm
      Engine will terminate with a registration reminder.

 The registered version has these limitations removed.


ΓòÉΓòÉΓòÉ 13. How to Register ΓòÉΓòÉΓòÉ

All registered users of the CM17A Comm Engine will receive a registration key
to fully unlock the program. Registration of the CM17A Comm Engine is for
life-time and any new versions of CM17A Comm Engine will not require any
re-registration. A registered user may not make registration key information
public nor pass it on to third parties.

You can register as follows:

Register through BMT Micro at www.bmtmicro.com. BMT Micro offers a variety of
purchasing methods, see the file BMTORDER.TXT for details. A registration key
will be sent to you within usually one day of purchasing the CM17A Comm Engine.
The cost is $20.00.

Quantity discounts are available. Please e-mail Lone Peak Automation for
details.

Registration key and instructions on how to enter the key to enable the
registered features will be given out at registration time.


ΓòÉΓòÉΓòÉ 14. License Agreement ΓòÉΓòÉΓòÉ

The CM17A Comm Engine is not public domain software, nor is it free software,
it is user supported.

Non-registered users are granted a limited license to use the CM17A Comm Engine
on a trial basis for the purpose of determining whether it is suitable for
their needs. Use of the CM17A Comm Engine, except for this limited purpose,
requires registration. See How To Register section on ways to register.

Use of non-registered copies of the CM17A Comm Engine beyond a 30 day
evaluation period by any person, business, corporation, governmental agency or
other entity or institution is strictly forbidden.

Use of registered copies of the CM17A Comm Engine by any business, corporation,
governmental agency or other entity or institution is strictly forbidden
without prior licensing arrangements and written consent of Lone Peak
Automation, LLC.

Registration grants a user the right to use the CM17A Comm Engine only on a
single computer unless prior arrangements are made with Lone Peak Automation,
LLC. A registered user may use the CM17A Comm Engine on a different computer,
but may not use the program on more than one computer at the same time.

You may not modify the CM17A Comm Engine in any way, including but not limited
to, decompiling, disassembling or otherwise reverse engineering the program.

No part of the CM17A Comm Engine documentation may be reproduced, in any form
or by any means, without permission in writing form from Lone Peak Automation,
LLC.

The unregistered version of the CM17A Comm Engine can be recognized by
containing the word "Unregistered" in the window title bar of the program.

All users are granted a limited license to copy the unregistered version of the
CM17A Comm Engine only for the trial use of others subject to the above
limitations. The following limitations apply for copying unregistered versions:

  The CM17A Comm Engine must be copied in unmodified form,
  complete with the file containing license and
  ordering information.

  The full documentation for the CM17A Comm Engine must be
  included in the archive.

  No fee, charge or other compensation may be
  accepted or requested by any licensee beyond a
  reasonable price for the media the CM17A Comm Engine is
  transferred on.

  Operators of electronic bulletin board systems and
  internet web/ftp sites may post the unregistered
  version of the CM17A Comm Engine for downloading by their users
  as long as the above conditions are met.

  Distributors of public domain or user supported
  software may distribute copies of the unregistered
  version of the CM17A Comm Engine subject to the above conditions.

DISCLAIMER

Lone Peak Automation, LLC accepts no responsibility for damages to property or
personal injury that may be caused by the use of the CM17A Comm Engine. The
CM17A Comm Engine is provided "AS IS" and you as its user assumes the entire
risk when you use it.

Because of potential fire hazards, Lone Peak Automation, LLC does NOT recommend
using the CM17A Comm Engine for controlling coffee pots, space heaters or
similar heat-creating appliances.

Lone Peak Automation, LLC is not connected to any companies mentioned nor do
they endorse any of the products mentioned.

All product names mentioned herein are the trademarks of their respective
owners.

CREDITS

RXASYNC.DLL required for serial communications to the CM17A interface, is a
library of serial communications routines and is included by permission of
Crucial Applications (Author: Ian Timms, e-mail:
[e-mail]). The entire serial communications package,
including the source code for RXASYNC, is available at the Lone Peak Automation
home page or major OS/2 sites by the file name RXASYN20.ZIP

The CM17A Comm Engine is protected using SecureIt. To get more information on
this shareware protection program, see http://www.bmtmico.com/catalog/secureit/

The CM17A Comm Engine is a shareware product and can be registered through BMT
Micro at www.bmtmicro.com for $20.00.

The CM17A Comm Engine is copyright (C) 2000 Lone Peak Automation, LLC


ΓòÉΓòÉΓòÉ 15. Contact ΓòÉΓòÉΓòÉ

The HOUSE/2 series of programs, UPS Monitor and DP Show are written by Lone
Peak Automation, LLC of Sandy, Utah, USA.

For general inquiry, contact Lone Peak Automation, LLC via e-mail at:

  [e-mail]

For support of the HOUSE/2 series of programs, UPS Monitor and DP Show, contact
Lone Peak Automation, LLC directly via e-mail at:

  [e-mail]

Visit the Lone Peak Automation, LLC home page, "The Warped Code Cellar" at:

  http://home.att.net/~ASchw

for other information and applications for OS/2. Monitor this web page
regularly for future upgrades of the available programs.

Lone Peak Automation programs are also available at the following sites:


  http://www.bmtmicro.com
  http://hobbes.nmsu.edu
  http://www.os2ss.com


ΓòÉΓòÉΓòÉ 16. Internet Links for Home Automation ΓòÉΓòÉΓòÉ

To get more information on home automation, you can visit any of the sites
listed here:

www.x10.com
Homepage of X10.
This is the manufacturer of X10 products.

www.x10.com/x10euro.htm
Links to European Representatives of X10.

www.smarthome.com
Home Automation System, Inc. Vendor carrying large
selection of home automation devices. Download
catalog in PDF format, search for part numbers online.

www.smarthome.com/foreign.html
Home Automation Systems, Inc. 220-240VAC (50Hz) Components.
Mail order company carrying some 220-240VAC (50Hz)
X10 products for international markets.

www.hwg-telekom.de
HWG Telekommunikations Systeme GmbH.
X10 Representative of Germany, Austria and
Switzerland. The CM11A is available as
PowerHaus-II in these countries.

www.automationplus.com
Mail order company for home automation devices.

www.asihome.com
Mail order company for home automation devices.

support.tandy.com/support_security/
Radio Shack Support. Follow the X10 links.
Contains FAQ for home automation devices.

www.hometoys.com
Mailing lists, newsletters, articles and product reviews
of home automation products and services.

www.hometeam.com
Information about products and services for home automation.

www.homecontrols.com
Large product catalog for home automation devices.
Also carries 220-240V models for international markets.

www.io.com/~lbs/
Laser Business Systems Ltd. Home Automation dealer in
the United Kingdom. Lists controllers and modules for many
other European countries.

www.homecontrol.co.uk/
Home Control. X10 home automation representative in the United Kingdom.

www.eon3.com
Eon3 Home Automation Pty. Ltd. Home Automation dealer in Australia.

www.X10BRASIL.com.br/
X10 Representative in Brasil.

www.infinet.com/~dhoehnen/ha/list.html
Comprehensive index of home automation related sites.