home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: OtherApp
/
OtherApp.zip
/
cm17ce.zip
/
fcinst.EXE
/
cm17ce.hlp
(
.txt
)
< prev
next >
Wrap
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: 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.