The 2-WAY COMPUTER INTERFACE for X-10 NOTE: To print this file, select File, then Print from the menu. This file prints in approximately 10 pages. Computer hobbyists and home automation enthusiasts can now use any computer with a standard RS-232 serial port to both send and receive X-10 signals. Programming it is simple with examples given in this README file and special software for Visual Basic under Windows. You'll be up and running in no time, with any system you dream up. The 2-Way Computer Interface supports all X-10 codes, full duplex operation, and supports collision detection (in case two X-10 events occur at the same time). During operation, the 2-Way Computer Interface is plugged into the computer's 25-pin serial port (or a 9-pin serial port with suitable adapter such as Radio Shack Cat. No. 26-209A -- See Appendix 2 for adapter pin wiring). A standard telephone cord connects the 2-Way Computer Interface to a 2-Way Powerline Module (X-10 Part No. TW-523) which plugs into an electrical outlet. Control your home or office using PC, laptop, notebook, or any computer or modem with an RS-232 serial port. Features: * Converts X-10 signals into standard ASCII characters (and vice versa) * Easy to install - Just plug into RS-232 port * Self-powered * Requires minimal processing by the computer * Reads back what was transmitted * Easy to program. Only a few lines of Basic code are needed to send and receive X-10 signals. Special software for Visual Basic included. * Measurements (overall): 2.4" x 3.8" x 1.0" * Required: 2-Way Powerline Module (X-10 Cat. No. TW-523) Getting Started With The 2-Way Computer Interface Like the mouse, this peripheral device gets its power from the serial port that it plugs into. The 2-Way Computer Interface contains a state-of-the art surface-mount microprocessor and additional components for reliable computer- to-powerline communications. What Is X-10? X-10 is a registered trademark of X-10 USA. A large and growing line of modules are available which use the powerline for communications. This means that without adding additional wiring it is possible to connect lamps, appliances, home security and other devices together into a total system for home or office automation. A few of the devices available are: Controllers and timers for sending X-10 signals, contact closure (pushbutton or switch) interface, lamp module, appliance module, 1-way computer interface, and now, this 2-way computer interface module. Briefly, all X-10 commands consist of a HOUSE CODE (from A to P) followed by either a "UNIT CODE" or a "FUNCTION CODE." There are 16 UNIT CODES (from 1 to 16) and 16 FUNCTION CODES (for example, ON, OFF, DIM, BRIGHT, ALL UNITS OFF, ALL LIGHTS ON, etc.). To turn ON module F1, X-10 protocol first sends the HOUSE CODE "F" followed by the UNIT CODE "1" and then sends the HOUSE CODE "F" again, this time followed by the FUNCTION CODE "ON." -- In other words: HOUSE CODE UNIT CODE HOUSE CODE FUNCTION CODE F 1 F ON In this case we say that module F1 is SELECTED, and then when the ON FUNCTION CODE for HOUSE CODE F is sent (F ON), the selected module(s) for that HOUSE CODE (in this case, only module 1) is/are turned ON. When a HOUSE CODE plus FUNCTION CODE comes along, IT APPLIES TO ALL THE MODULES THAT HAVE BEEN SELECTED for that HOUSE CODE. So, to turn ON several X-10 modules simultaneously, instead of in sequence, it is easy to do. For example, to turn ON in HOUSE CODE G, modules 1, 2 and 3 at the same time, the following X-10 codes would be sent: G 1 G 2 G 3 G ON The selected module(s) for a particular HOUSE CODE stay selected UNTIL A HOUSE CODE WITH A UNIT CODE IS SENT FOLLOWING A FUNCTION CODE for that HOUSE CODE. When that happens, that UNIT CODE becomes the first new UNIT CODE to be selected for that HOUSE CODE. In the above example, modules G1, G2 & G3 remain selected, and if the code: G OFF were sent, modules G1, G2 & G3 would all go to OFF together. But if the code: G 4 were sent, G1, G2 & G3 would no longer be selected -- the selected module is now G4. The examples above use the X-10 FUNCTION CODE "ON". There are actually 16 X-10 FUNCTION CODES, but only six of them are generally used. The 6 generally-used FUNCTION CODES are: X-10 FUNCTION CODE COMMENT (long) (short) (form) (form) ------- ------- ---------------------------------------------------------- ON ON Turns selected module(s) ON. NOTE: if a lamp module is in a DIM state, using the ON command does not change its brightness. OFF OF Turns selected module(s) OFF. DIM DI Applies only to lamp modules. Makes selected lamp module(s) dimmer. If a selected lamp module is OFF, using the DI command first turns it ON to FULL BRIGHTNESS, then dims it. The maximum amount of dimming that can occur is 20 steps, in which case the lamp will have an almost imperceptable glow. The amount dimming that occurs depends on how long the DIM button is held down on a X-10 Mini Controller with a dimmer. When the 2-Way Computer Interface receives a DI command from the computer, the amount of dimming depends on the setting of the REPETITION Value (described below). BRIGHT BR Applies only to lamp modules, Makes selected lamp module(s) brighter. If a selected lamp module is OFF, using the BR command turns it ON to FULL BRIGHTNESS. The maximum amount of brightening that can occur is 20 steps, in which case the lamp is effectively full ON. The amount of brightening that occurs depends on how long the BRIGHT button is held down on a X-10 Mini Controller with a dimmer. When the 2-Way Computer Interface receives a BR command from the computer, the amount of brightening depends on the setting of the REPETITION Value (described below). ALLOFF A0 Turns all lamp and appliance modules in the current HOUSE CODE to OFF (Note, the short-form command is "A-ZERO"). LIGHTSON L1 Applies only to lamp modules. Turns all lamp modules in the current HOUSE CODE to ON. NOTE: Appendix 1 at the end of this README file lists all 16 FUNCTION CODES for reference purposes. The 2-Way Computer Interface module can send and receive all these codes, even though commercially-available modules generally do not use many of them. The computer communicates with the 2-Way Powerline Interface in 3-character messages, followed by a (an ASCII 13) -- The first character is the HOUSE CODE, the next two characters are either the UNIT CODE (from 01 to 16) or the short form of a FUNCTION CODE (for example, BR is used for the FUNCTION CODE "BRIGHTEN"). Letters may be in either uppercase or lowercase. The 2-Way Powerline Interface usually sends back 4-character messages to the computer, followed by a (an ASCII 13) -- The first character is either: ! -- an exclaimation point -- meaning a valid message was read from the powerline. The "!" is followed by a valid 3-character message. ? -- question mark -- meaning the message sent to it by the computer was not a valid 3-character message followed by a . The "?" will be followed by the message it was sent. > -- caret -- If the first character is a caret, the characters that follow did not originate from the powerline. When the caret is followed by XXX, the 2-Way Powerline Interface did not read back the same code it sent -- This can happen when there is interference on the powerline, either caused by a noisy appliance or by another X-10 event occurring at the same time. A collision can be generated by sending a command with the computer and at the same time, pressing a button on a Mini Controller. There will be a "collision" and >XXX will be received. In this case, the computer can be programmed to "retry" the command later. When the caret is followed by "R" plus a two-digit number from 01 to 20 (for example, R10), the 2-Way Powerline Interface is echoing back a new Repetition setting used in Bright & Dim commands (discussed below). If the 2-Way Powerline Interface receives a message from the computer that is less than 3 characters, it will send back a question mark, followed by the characters it was sent. Connecting The Interface To The Computer Plug the 2-Way Computer Interface into an available RS-232 port. If necessary use a 9-pin to 25-pin adapter. Connect one end of the telephone cable supplied to the 2-Way Computer Interface, and the other end to a 2-Way Powerline Interface (TW-523). If you want to use a telephone cable other than the one supplied, note that you will need a standard 4-conductor cable which crosses red & green, and yellow & black wires. Plug the 2-Way Powerline Interface into an electrical outlet. Its red indicator light should turn ON. To demonstrate 2-way X-10 operation you should have a lamp connected to a Lamp Dimmer Module, an appliance connected to an Appliance Module, and have a Mini Controller or equivalent available to generate X-10 events. Terminal Operation Most computers have terminal software available. For example, Windows comes with a Terminal found in the Accessories group. Many other terminal programs are available, such as PROCOMM, QUICKLINK, BITCOM. Terminal software is easy to obtain as shareware from online services such as CompuServe. If wish, you can use the AUTODRV software supplied with this product to run under Windows (See section on Running AUTODRV.EXE below.) Terminal Settings should be: 2400 Baud 8 Data Bits 1 Stop Bit No Parity If you type (a Carriage Return, same as ), the 2-Way Computer Interface should respond with: ? This shows that the interface is "live." Now try typing: B01 (Note: Be sure to type a "zero" here and not the letter "oh") The response should be: !B01 which signifies that the X-10 code for HOUSE CODE B, Unit 1 was successfully sent to the powerline. At the same time the command is sent, the light on the 2-Way Powerline Interface should blink OFF, then return to ON. At this time module B1 is SELECTED. To turn it ON, send the code: BON (Note: Be sure to type the letter "oh" here, and not the number "zero") The response should be: !BON which signifies that the X-10 code for HOUSE CODE B, FUNCTION CODE ON was successfully sent to the powerline. At the same time the command is sent, the light on the 2-Way Powerline Interface should blink OFF, then return to ON. If you have a lamp or appliance module connected to HOUSE CODE B, UNIT CODE 1, then it will turn ON. If you press the "All Lights Off" button on a X-10 Mini Controller, you will see on your computer terminal: !BA0 which means that for HOUSE CODE B, the All Units Off command was sent over the powerline. Press other buttons on the Mini Controller and observe the codes received by the 2-Way Computer Interface. Lamp Dimmer Operation The 2-Way Powerline Interface can be sent a special command which tells it how much to brighten or dim a lamp module when a BR or DI code is sent. A value of 1 to 20 is saved in its "Repetition Register, " or "R-Register" for short. For example, assume a lamp is ON that is connected to a lamp module with HOUSE CODE A, UNIT CODE 1. To dim that lamp to 50% brightness, use the following commands: Command Comment ---------- ------------------------------------------------------------- A01 Select the module at HOUSE CODE A, UNIT CODE 1 R10 Set the R-Register to brighten or dim 10 steps. This value of 10 will remain in the R-Register until the next R command is sent. Commands from R01 to R20 are valid. ADI Dim the selected lamp 10 steps, leaving it at 50% brightness. Note that if DIM or BRIGHT commands are sent from an external device such as a Mini Controller, the 2-Way Computer Interface receives one DI or BR command for every 3 DIM (or BRIGHTEN) steps sent. This results from the operation of the 2-Way Powerline Interface. To determine the approximate brightness of a light that has been dimmed from an external source, multiply the number of DI commands received by 3 to gauge the number of steps received by the Lamp Dimmer Module. Example Of Two-Way Communication Between The Computer And Powerline This example illustrates an X-10 "dialog" between a computer and a 2-Way Computer Interface ("2WAYIF"): Message Sent Message Comments To 2WAYIF Received From Computer From 2WAYIF ------------- ----------- ---------------------------------------------- G14 You select HOUSE CODE G, UNIT CODE 14. !G14 The 2WAYIF echos the command received from the powerline. The "!" means, "This was received from the powerline." GON You tell the lamp (or appliance) at HOUSE CODE G, UNIT CODE 14 to turn ON. !GON The 2WAYIF has read a GON command back from the powerline. Transmission OK. R10 You set the Repitition-Register ("R-Register") in the 2WAYIF to 10. This register is used for DIM and BRIGHT commands and contains a value from 1 (5%) to 20 (100%). The R-Register may be set at any time and retains its value until the next command that sets it, or until the computer is turned OFF. >R10 The caret (>) indicates "This was sent by the 2WAYIF and did not come from the powerline." The R-Register has been set to a value of 10. GDI Send DIM commands to the currently selected module(s) in HOUSE CODE G (here, only module G14 has been selected). The number of DIM commands sent will be the current value in the R-Register (10 at present). !GDI 10 Dim codes sent to G14 -- if G14 was OFF or full ON before GDI was sent, G14 will be left at 50% brightness. G08 You select HOUSE CODE G, UNIT CODE 8. >XXX 2WAYIF has not received anything from the powerline when it expected to receive a G08. A collision has occurred. Note that in practice, this is an extremely rare event. G08 You re-send the G08 command. !G08 Transmission OK. GZ4 You send a meaningless code to the 2WAYIF. ?GZ4 Invalid code indicated. Nothing sent to the powerline. !A03 !AON !ADI !ADI !ADI Someone has used an external Mini Controller to turn a lamp ON at HOUSE CODE A, UNIT CODE 3, and has dimmed it to about half brightness. !B01 !BOF Someone has used an external Mini Controller to turn OFF the module at HOUSE CODE B, UNIT CODE 1. Visual Basic Operation Programmers of Visual Basic can quickly create sophisticated systems which integrate computer functions with the automation of lamps and appliances in the home, office or business. To simplify this task, two Visual Basic programs are included with the 2-Way Computer Interface: 1. Communications Server -- AUTODRV.EXE This small program can be run at any time under Windows. It puts a small control panel on the screen which allows direct communication from the keyboard to the 2-Way Computer Interface device. X-10 signals both sent and received are indicated. In addition, Visual Basic programs can easily send and receive messages to/from this server using DDE (Dynamic Data Exchange) -- with just a few lines of code, messages received by the 2WAYIF will appear in your label control(s) and data placed in your label control(s) will be automatically sent to the 2WAYIF. You need not worry about handling the RS-232 communications, which is taken care of by AUTODRV.EXE. 2. Demonstration Visual Basic Program -- 2WAYIF.MAK This program pops up a window and sends and receives commands to/from AUTODRV. It detects if the AUTODRV is running, and if not, runs it. By inspecting it and its operation, you can use it as the basis for writing programs which do not need to handle the RS-232 port directly. Running AUTODRV.EXE First, connect the 2WAYIF to the computer and to the 2 Way Powerline Interface and plug it into an electrical outlet. Run AUTODRV.EXE under Windows by clicking on its icon in the X-10 group or use the Program Manager. An icon appears on the screen. Click on it and a small window appears: ----------------------- | 2WAYIF | <-- Title Of Window ----------------------- | Menu | <-- Click Here To Bring Up A Menu Of Options ----------------------- | No Data | <-- These two lines show the ----------------------- latest data received by the | No Data | 2-Way Computer Interface ----------------------- | | | <-- Type desired commands here to send ----------------------- commands to the 2-Way Computer Interface When you click on the Menu button, the following window appears: ----------------------- | MENU | <-- Title Of Window ----------------------- | Run | <-- Click Here To Return To Run Window ----------------------- | Com = 1 | <-- Click Here To Select Com 1,2,3 or 4 ----------------------- | Minimize | <-- Click Here To Make This Run As An Icon ----------------------- | Exit | <-- Click Here To Terminate Program ----------------------- Select The COM Port After you have brought up the 2WAYIF window, if you are using a COM port other than the default COM1, click on the Menu button, then click on the Com button until the Com port you are using is selected. Then click on Run to return to the Communications Window. Note: This program may be called from the command line or from a SHELL statement in a Visual Basic program. When this is done, the COM port may be specified as a number from 1 to 4. For example, to start AUTODRV.EXE and have it use COM port 2, use the command line: AUTODRV.EXE 2 (To run AUTODRV invisibly, add the letter "i" to the command line.) Test Operation - Transmitting Using Keyboard Input Connect a lamp to a lamp module at HOUSE CODE B, UNIT CODE 1. Now turn it ON by putting the text cursor in the bottom text box (if not already there) and typing: B01 BON And the lamp should turn ON. Be careful to distinguish the zero (0) from the letter "oh" (O). If you type in an invalid code, such as BXN , the 2WAYIF will respond with: ?BXN There are 20 steps from full DIM to full BRIGHT. If you want to DIM your lamp to approximately half brightness, tell 2WAYIF you want to dim 10 steps by typing: R10 2WAYIF will respond with: >R10 Now dim the lamp by typing: B01 BDI and brighten the lamp by typing: BBR There was no need to type B01 again since B01 was already "selected" (and will stay selected until another HOUSE CODE plus UNIT CODE is sent -- (See the "What Is X-10" discussion above). - Receiving X-10 Signals From External Source Press buttons on an X-10 Mini Controller or other X-10 signal source and observe that the last two commands sent are shown in the two AUTODRV data windows. Exploring 2WAYIF.MAK First, connect the 2WAYIF to the computer and to the 2 Way Powerline Interface and plug it into an electrical outlet. Start Visual Basic and bring up the 2WAYIF.MAK project (normally found in the \VB\2WAYIF directory). This project has a single form with a label, a text box, and 3 option buttons. When this program is run, it first determines if the X-10 Communications Server, AUTODRV is already running. If it is not, it starts it up. The code is commented to explain how it works. Using the LinkItem and LinkTopic properties, it establishes a DDE link with AUTODRV. Now, whenever an X-10 command is read by 2WAYIF from the powerline, it appears as the caption of Label1. And, whenever the key is pressed after entering text into text box tbxUser, the text is sent via Label1 to AUTODRV.EXE which then sends it to over the RS-232 COM port and into the 2WAYIF. Similarly, data received by the 2WAYIF goes to AUTODRV.EXE, which then sends it to the caption of Label1 via the LinkNotify routine. Clicking on the Option Button labelled "A01 AON" turns ON a lamp connected to a module at HOUSE CODE A, UNITCODE 1, and clicking on the Option Button labelled "A01 AOF" would turn the lamp OFF. These Option Buttons simply put text into Label1 which then automatically sends the text to AUTODRV.EXE using the LinkExecute method. Clicking on the Option Button labelled "End Svr" shows how AUTODRV can be terminated from another Visual Basic program. This is done by sending the message "END" to AUTODRV.EXE. Upon receiving this message, that program will terminate. This causes an error, which is trapped by 2WAYIF in the code block starting at statement label Error1. Troubleshooting If you can't receive a "?" on a terminal program when you press the key as discussed under "terminal operation" above, check to make sure all the cable connections are firm -- the 2WAYIF must be plugged in to the computer (via an adapter cable, if necessary), the telehpone cord should be the one supplied with the unit, and must be plugged in at one end to the 2WAYIF and at the other to the 2-Way Powerline Interface (TW-523). And, the 2-Way Powerline Interface must be plugged in to the wall, its red indicator light showing ON, except when an X-10 signal is sent, at which time it blinks OFF for a short time. Make sure the settings of the terminal are 2400 baud, 8 bits, 1 stop bit, No Parity. The 2WAYIF is subject to all the potential problems that may occur when the powerline is used for communications. The transmitting strength of the 2-Way Powerline Interface (TW-523) is equal to the strength of a Mini Controller, and its receiving strength is equal to a lamp or appliance module. If signal strength is marginal, which may be due to long distances from transmitter to receiver, or by certain appliances which present heavy loads to the communications signal sent on the powerline, reliability can suffer. In addition, certain appliances may at certain times inject noise onto the powerline, hindering signal communications. Try moving modules around to improve reliability if necessary. Unplug appliances such as TV sets (even if they are off) one at a time, to see if the problem goes away. If an offending "noisy" appliance is found, install an X-10 noise filter on it. Other approaches include installing an X-10 signal bridge at or near the circuit breaker, which gives the communications signal an easy path from one leg of thepowerline circuit to the other leg. An X-10 signal amplifier may also be installed. Appendix 1 -- List of All 16 X-10 FUNCTION CODEs Code Function Comment ------- --------------- ----------------------------------------------------- A0 All Units Off L1 All Lights ON ON ON OF Off DI Dim BR Bright L0 All Lights Off Commercial modules do not usually respond to this code EC Extended Code Commercial modules do not usually respond to this code HR Hail Request Commerical modules do not usually respond to this code HA Hail Acknowledge Commercial modules do not usually respond to this code P0 Pre-Set Dim 0 Commercial modules do not usually respond to this code P1 Pre-Set Dim 1 Commercial modules do not usually respond to this code ED Extended Data Commercial modules do not usually respond to this code (Analog) Commercial modules do not usually respond to this code S1 Status=ON Commercial modules do not usually respond to this code S0 Status=OFF Commercial modules do not usually respond to this code SR Status Request Commercial modules do not usually respond to this code Appendix 2 -- 9-Pin to 25-Pin Adapter Wiring 9-Pin Female 25-Pin Male Pin Pin 1 -------------------------8 2 -------------------------3 3 -------------------------2 4 -------------------------20 5 -------------------------7 6 -------------------------6 7 -------------------------4 8 -------------------------5 9 -------------------------22