═══ 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: itimms@ariel.ucs.unimelb.edu.au). 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: itimms@ariel.ucs.unimelb.edu.au). 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: LPASales@worldnet.att.net For support of the HOUSE/2 series of programs, UPS Monitor and DP Show, contact Lone Peak Automation, LLC directly via e-mail at: LPASupport@worldnet.att.net 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.