July 1993 X10 COMMANDER by Gregory MacKay What is it? X10 COMMANDER was created to allow owners of the X10(R) CP290 HOME CONTROL INTERFACE to program the 128 event capable interface or send direct commands through it to control lights, appliances, etc... _____________________________________________________________________________ COPYRIGHT NOTICE: This Software is protected by copyright law. It may not be copied or used for or in connection with any commercial purpose. Any other use is subject to acknowledgement of the author: Gregory MacKay 10 Cedar Road Gloucester, Ontario Canada, K1J 6L4 (613)746-8821 X10 COMMANDER is freely distributable provided the program and this documentation remain together and are not modified in any way. _____________________________________________________________________________ The program can be started through the CLI or the WORKBENCH. No parameters are required. The stack setting should not be a problem, but if you do have any then try increasing the stack. The CP290 interface must be connected through the serial port for the X10 COMMANER to work. If it is not connected then X10 COMMANDER will display a warning message and exit. If you don't have a cable, one can be made very easily as follows: *** SOLDERING REQUIRED TO MAKE CABLE *** Locate the connector type under SERIAL PORT in the Amiga User's Guide. Most Amigas use the DB25 male connector (standard RS232 serial connector). Locate the connector type in the PROGRAMMING GUIDE FOR ADVANCED PROGRAMMERS that came with the CP290 interface. The connector is a 5 pin DIN socket. Both these connectors can be purchased at most electronic stores. As for the cable, as long as it has at least three thin wires it should do. I used a regular telephone cable which has four wires in it. Connect the DB25 pin #2(transmit) to the 5 pin DIN socket pin #2(receive). Connect the DB25 pin #3(receive) to the 5 pin DIN socket pin #4(transmit). Connect the DB25 pin #7(ground) to the 5 pin DIN socket pin #3(ground). OR if you haven't purchased the CP290 interface yet, then I believe the one designated for the Apple Macintosh has a compatible cable(DB25 male). I haven't confirmed it though, so you had better double check at the store. OPERATION The X10 COMMANDER was designed to be as intuitive as possible. All actions are mouse driven. When X10 COMMANDER is started, the Base Housecode, current Time and Day will be uploaded to the program and displayed. Only one event will be active and the LOCATION text box will be activated for input. If the number of events exceeds ten, the scroll bar can be used to access the hidden events in the list. Command acknowledgements and errors are displayed in the MESSAGE BOX. The housecodes range from A through P and the unitcodes range from 1 through 16 and are used to select the module to control. The time can be set with two slider knobs, one for hours and the other for minutes. A box to the right of the slider gadgets contains the time values. Days (SUNDAY through SATURDAY) can be selected by clicking on the buttons. When using days with WEEKLY and SECURITY, don't forget to pick one or more days or the event will not function!. Modes (WEEKLY, SECURITY, TODAY, TOMORROW) can be cycled through by clicking on the button. (NORMAL, which is used in the programmers guide has been changed to WEEKLY for clarity). WEEKLY: will perform it's function on a weekly basis on the days selected. SECURITY: same as WEEKLY except it executes at a random time, from within one hour after the time specified. TODAY: will execute the event on that day only. Selecting days has no effect. TOMORROW: will execute the following day only. Selecting days has no effect. Functions (ON, OFF, DIM) can be cycled through by clicking on the button. ON: turns on a module. OFF: turns off a module. DIM: turns on a module at a specific dim level. (only lights can be dimmed) The DIM slider knob sets the dim intensity. 0(full dim) to 15 (full bright). NOTE: The dimming slider gadget in X10 COMMANDER works the opposite way than in the interface. Since it's easier to think of 0 being full dim and 15 being full bright, it was changed from 0 being full bright and 15 being full dim. * IMPORTANT * When issuing commands, the values used are taken from the event currently selected. Therefore, if you decide to use an event that contains valid data, then don't forget to return the data to its former values. The safest way to issue a command is to ADD an event, set the data to the desired values, execute the command and then DELETE the event. This way you don't interfere with events that contain valid data. Commands in X10 COMMANDER use only the data required for their execution. Most commands do not require any input. The following is a description of each command and the input required for proper execution: GET CLOCK AND HC: no input required This command will upload the Base Housecode that the interface was last set to, and will upload the current time and day from the interface. Both these values will be updated in the program's window. SET TIME AND DAY: Input: HOURS,MINUTES and ONE DAY ONLY To execute this command, use the slider knobs to set the HOURS and MINUTES and select which day (ONLY ONE) from the seven buttons at the bottom of the window. The buttons range from SUNDAY through SATURDAY and are toggle select, meaning the button will switch from selected to unselected with every click of the mouse. UPLOAD EVENTS: no input required This command will upload the events currently stored in the CP290 interface to the computer and will load a file which contains text descriptions of each event. This text file is created when the download command is executed and is neccessary since the CP290 interface has too little memory to store the descriptions. If it is the first time you use this program with the CP290 interface and the interface already contains events, then X10 COMMANDER will load the events and assign a name for each event. ie. EVENT 1, EVENT 2, EVENT 3... This command may take some time to complete depending on the number of events required to upload. DOWNLOAD EVENTS: no input required Will download all events in the list. When the download is complete, a file containing the LOCATION and DESCRIPTION text will be written to disk. The file is named 'X10Download_text' and will be used as input when the UPLOAD command is used. This command may take some time to complete depending on the number of events required to download. ADD EVENT: no input required Will add an event to the list. When an event is added, it is inserted at the currently selected event, pushing the selected and all subsequent events down by one. Using ADD EVENT and DEL EVENT it is possible to group events to your liking. DEL EVENT: no input required Will delete the event currently selected from the list. LOAD: no input required Will load events that were saved with the SAVE command. A requester will appear asking for the file to load. SAVE: no input required Will save all events currently listed to a file. A requester will appear asking for a file name under which the events will be saved. DIRECT COMMAND: Input: HOUSECODE, UNITCODE, FUNCTION This command allows house lights, appliances, etc. to be controlled at the click of a button (THIS BUTTON). Select the HOUSECODE and UNITCODE of the module you which to control, choose a FUNCTION (ON, OFF, or DIM) and click on the DIRECT COMMAND button. If DIM is selected then also select a DIM value. Values range from 0 (full dim) to 15 (full bright). The DIM function may take some time (about 5 secs), be patient. CHANGE HC: Input: HOUSECODE Will change the Base Housecode. The Base Housecode is used by the rocker keys on the interface. It is initially set to A when the interface is powered up. This command is a destructive one. When this command is executed the CP290 interface will erase all the events it contained. However, the list of events in the program will remain available so all that needs to be done is to re-download the events. SELF TEST: no input required This command will initiate the self test diagnostic routine of the interface which will check it's hardware and software(firmware). When the self test executes it writes test data destroying all events. Again, the list of events in the program will remain available so all that needs to be done is to re-download the events. Be patient, it may take about 10 seconds to complete the test. The response will be either 'Interface OK' or 'Interface fault' or will not respond at all, in which case you may have to reboot. If you receive the 'Interface fault' message or get no response, then it may be wise to return it to the store you bought it from as it might need to be repaired or replaced. COMPATIBILITY: X10 COMMANDER was designed to be compatible from OS 1.3 and up. I've tested it on my A1000 and my A4000 with no problems. Requesters will function according to which library resides (ASL,ARP,NONE). ASL library is the best of the bunch, while ARP is not quite as pretty and no requester library is of course an ugly affair, but manageable. TIPS: If you'll notice, there is no 'NEW' option to start a new list. I did this because the program starts with the list at 1 blank event and also because space for more buttons was getting tight. So, if you need to clear the list, either quit and restart the program or delete the events if there aren't too many. If for some reason the CP290 interface contains invalid data and you upload it, then you will need to clear the interface of this bad data. To do this choose 'CHANGE HC' or 'SELF TEST', if you choose 'CHANGE HC' make sure you pick the Base Housecode you want before executing this command. After doing this quit the program and restart it because the erroneous data will cause the program not to function properly. All communication from the computer to the CP290 interface and vice versa is synchronous. When a command is sent to the interface, the interface responds with an acknowledgement. In some rare cases that acknowledgement for some reason or other may not complete (It's never happened to me but I have simulated it). In any case, if this happens you will notice that the program is locked up. To clear up the problem, press one of the rocker keys on the interface which will cause it to send another acknowledgement and complete the program's command. You may get a 'serial error' message but at least your up and running again. All mouse button actions are buffered, meaning you can click on as many buttons as you like and they will execute in sequence, one after another. ACKNOWLEDGEMENTS: The code for X10 COMMANDER is all mine except for the file requesters which I got from the AmigaWorld Tech Journal "Easy File and Font Requesters" by Willy Langeveld in Volume 2, Number 2, April 1992 and support disk. I would like to thank Willy for his excellent article and code which I integrated into my program with no fuss at all. I would also like to thank AmigaWorld for publishing the article and for an outstanding Amiga Technical magazine which unfortunately is no longer being published. So, I hope this program will be useful to Amiga users who use the CP290 Home Control Interface. It's my little contribution to the Amiga Community and the Amiga computer. ENJOY! I can be reached on GENIE as 'G.MACKAY1'.